1cgit - CGI for Git
 2==================
 3
 4This is an attempt to create a fast web interface for the Git SCM, using a
 5built-in cache to decrease server I/O pressure.
 6
 7Installation
 8------------
 9
10Building cgit involves building a proper version of Git. How to do this
11depends on how you obtained the cgit sources:
12
13a) If you're working in a cloned cgit repository, you first need to
14initialize and update the Git submodule:
15
16    $ git submodule init     # register the Git submodule in .git/config
17    $ $EDITOR .git/config    # if you want to specify a different url for git
18    $ git submodule update   # clone/fetch and checkout correct git version
19
20b) If you're building from a cgit tarball, you can download a proper git
21version like this:
22
23    $ make get-git
24
25When either a) or b) has been performed, you can build and install cgit like
26this:
27
28    $ make
29    $ sudo make install
30
31This will install `cgit.cgi` and `cgit.css` into `/var/www/htdocs/cgit`. You
32can configure this location (and a few other things) by providing a `cgit.conf`
33file (see the Makefile for details).
34
35If you'd like to compile without Lua support, you may use:
36
37    $ make NO_LUA=1
38
39And if you'd like to specify a Lua implementation, you may use:
40
41    $ make LUA_PKGCONFIG=lua5.1
42
43If this is not specified, the Lua implementation will be auto-detected,
44preferring LuaJIT if many are present. Acceptable values are generally "lua",
45"luajit", "lua5.1", and "lua5.2".
46
47
48Dependencies
49------------
50
51* libzip
52* libcrypto (OpenSSL)
53* libssl (OpenSSL)
54* optional: luajit or lua, most reliably used when pkg-config is available
55
56Apache configuration
57--------------------
58
59A new `Directory` section must probably be added for cgit, possibly something
60like this:
61
62    <Directory "/var/www/htdocs/cgit/">
63        AllowOverride None
64        Options +ExecCGI
65        Order allow,deny
66        Allow from all
67    </Directory>
68
69
70Runtime configuration
71---------------------
72
73The file `/etc/cgitrc` is read by cgit before handling a request. In addition
74to runtime parameters, this file may also contain a list of repositories
75displayed by cgit (see `cgitrc.5.txt` for further details).
76
77The cache
78---------
79
80When cgit is invoked it looks for a cache file matching the request and
81returns it to the client. If no such cache file exists (or if it has expired),
82the content for the request is written into the proper cache file before the
83file is returned.
84
85If the cache file has expired but cgit is unable to obtain a lock for it, the
86stale cache file is returned to the client. This is done to favour page
87throughput over page freshness.
88
89The generated content contains the complete response to the client, including
90the HTTP headers `Modified` and `Expires`.
91
92Online presence
93---------------
94
95* The cgit homepage is hosted by cgit at <http://git.zx2c4.com/cgit/about/>
96
97* Patches, bug reports, discussions and support should go to the cgit
98  mailing list: <cgit@lists.zx2c4.com>. To sign up, visit 
99  <http://lists.zx2c4.com/mailman/listinfo/cgit>