1
  2                       cgit - cgi for git
  3
  4
  5This is an attempt to create a fast web interface for the git scm, using a
  6builtin cache to decrease server io-pressure.
  7
  8
  9Installation
 10
 11Building cgit involves building a proper version of git. How to do this
 12depends on how you obtained the cgit sources:
 13
 14a) If you're working in a cloned cgit repository, you first need to
 15initialize and update the git submodule:
 16
 17  $ git submodule init     # register the git submodule in .git/config
 18  $ $EDITOR .git/config    # if you want to specify a different url for git
 19  $ git submodule update   # clone/fetch and checkout correct git version
 20
 21b) If you're building from a cgit tarball, you can download a proper git
 22version like this:
 23
 24  $ make get-git
 25
 26
 27When either a) or b) has been performed, you can build and install cgit like
 28this:
 29
 30  $ make
 31  $ sudo make install
 32
 33This will install cgit.cgi and cgit.css into "/var/www/htdocs/cgit". You can
 34configure this location (and a few other things) by providing a "cgit.conf"
 35file (see the Makefile for details).
 36
 37
 38Dependencies:
 39  -git 1.5.3
 40  -zip lib
 41  -crypto lib
 42  -openssl lib
 43
 44
 45Apache configuration
 46
 47A new Directory-section must probably be added for cgit, possibly something
 48like this:
 49
 50  <Directory "/var/www/htdocs/cgit/">
 51      AllowOverride None
 52      Options +ExecCGI
 53      Order allow,deny
 54      Allow from all
 55  </Directory>
 56
 57
 58Runtime configuration
 59
 60The file /etc/cgitrc is read by cgit before handling a request. In addition
 61to runtime parameters, this file also contains a list of the repositories
 62displayed by cgit.
 63
 64A template cgitrc is shipped with the sources, and all parameters and default
 65values are documented in this file.
 66
 67
 68The cache
 69
 70When cgit is invoked it looks for a cachefile matching the request and
 71returns it to the client. If no such cachefile exist (or if it has expired),
 72the content for the request is written into the proper cachefile before the
 73file is returned.
 74
 75If the cachefile has expired but cgit is unable to obtain a lock for it, the
 76stale cachefile is returned to the client. This is done to favour page
 77throughput over page freshness.
 78
 79The generated content contains the complete response to the client, including
 80the http-headers "Modified" and "Expires".
 81
 82
 83The missing features
 84
 85* Submodule links in the directory listing page have a fixed format per
 86  repository. This should probably be extended to a generic map between
 87  submodule path and url.
 88
 89* Branch- and tag-lists in the summary page can get very long, they should
 90  probably only show something like the ten "latest modified" branches and
 91  a similar number of "most recent" tags.
 92
 93* There should be a new page for browsing refs/heads and refs/tags, with links
 94  from the summary page whenever the branch/tag lists overflow.
 95
 96* The log-page should have more/better search options (author, committer,
 97  pickaxe, paths) and possibly support arbitrary revision specifiers.
 98
 99* A set of test-scripts is required before cgit-1.0 can be released.
100
101Patches/bugreports/suggestions/comments are always welcome, please feel free
102to contact the author: hjemli@gmail.com