gitphp/doc/README

Installing GitPHP

Minimum requirements:
git
Apache (or other php-compatible webserver)
PHP 5


To begin, you need to have your git repositories set up in a directory that the
webserver can access.  They can be in subdirectories within that, but you will
need a base directory to tell GitPHP where to look for repositories.  These
must be bare repositories - for those who don't know, the directory of source
code you have is your working copy, and the .git hidden directory inside of that
is the actual repository, which is what GitPHP reads.  There are files in here
like HEAD, COMMIT_EDITMSG, description, etc.

You can make a copy of your bare repository by running:

git clone --bare ~/myproject /gitprojects/myproject.git

Or, a new bare repository can be initialized with:

git init --bare /gitprojects/mybareproject.git

Once you have your projects in a directory, something like:

/gitprojects/project1.git
/gitprojects/project2.git
/gitprojects/subdir/project3.git

You can begin setting up GitPHP.  Put the GitPHP files in a place
readable by your webserver.  You will need to change the permissions of the
templates_c directory to be writable by your webserver.  This can be done
by either:

chown apache:apache templates_c
(assuming your webserver runs as user/group apache - this is the better way)

or:

chmod 777 templates_c

Then, you will need to set up your config file.  In the config directory,
copy the example config file, gitphp.conf.php.example, to gitphp.conf.php.

The only required setting is the 'projectroot' setting, which specifies
where your git repositories are - following the previous example, it would
be set up as "/gitprojects/".

All the available config options and their default settings are documented
in gitphp.conf.defaults.php.  If you want to change any of the settings,
just copy the config option from the defaults file to your normal config
and change the setting.  Some GitPHP features are disabled by default
since they require setting config options a certain way, so if you don't
look through the config file you won't get those features.

During upgrades, your existing config file will not be overwritten.  However
new options or features may be added to the defaults file, so you may want
to check for new options every now and then.

If you want to set up categories for your projects, or use a text file
with a list of projects, you need to set up the $git_projects array in
projects.conf.php.  Copy projects.conf.php.example to projects.conf.php
and edit it - the definition and structure of this is explained in
the config file.

If you want to edit the text header that appears above the project list on the
home page, create templates/hometext.tpl with your header content.


[Caching]

To turn on caching, set the 'cache' config item to true.  Gitphp will cache
every page's output, including plaintext output and binary output such as
blobs and snapshots, for the number of seconds specified in the
'cachelifetime' config key.  You will need to set the "cache" directory
writable by the server, as with the templates_c directory above.

Gitphp can also cache immutable objects from the git repository, by setting
'objectcache' to true.  These cached objects can be reused on multiple
pages.  The 'objectcachelifetime' config key controls how long they are
cached.  Since these objects don't ever change in the git repository, they
can be cached for significantly longer than templates can (or in theory,
forever).  This option can be used on its own, or in addition to the regular
template 'cache' option for the maximum benefit.  This option also requires
the "cache" directory writable by the server, as above.

The 'cacheexpire' key is recommended for most users.  With this option on,
gitphp will attempt to keep the cache in sync by automatically expiring any
cached pages that are older than the most recent commit, on any branch.
It is a slight performance hit to make this check, but the performance hit
is tiny compared to the gain you get from turning on caching.  It will
avoid situations where users are getting a cached version of a page that
isn't up to date and doesn't reflect the most recent commit, or worse,
pages that have been cached at different times and show data from both
before and after a commit (eg page 1 of the shortlog shows the most recent
commit but page 1 of the log was cached a while ago and doesn't show the
most recent commit).

However, if your project is so active that commits are constantly coming in
and invalidating the cache, rendering it useless, it would be better to
turn cache expiration off and just set a really short cache lifetime of
a few seconds.  In other words:

Most users:
* Set 'cache' to TRUE
* Set 'objectcache' to TRUE
* Set 'cacheexpire' to TRUE (this is the default)
* Set 'cachelifetime' high, 3600 seconds (1 hour) or more. (3600 is the default)
* Set 'objectcachelifetime' even higher, eg 86400 seconds or more.  (86400 is
  the default)

These are the defaults.

Extremely active projects, with commits every few seconds, or advanced
users that know exactly how often commits come in and want to save
the performance of the expiration check:
* Set 'cache' to TRUE
* Set 'objectcache' to TRUE
* Set 'cacheexpire' to FALSE
* Set 'cachelifetime' low, between 5-10 seconds.
* Set 'objectcachelifetime' high, 86400 seconds or more.  (86400 is the default)