cgitrc.5.txt (view raw)
1CGITRC(5)
2========
3
4
5NAME
6----
7cgitrc - runtime configuration for cgit
8
9
10SYNOPSIS
11--------
12Cgitrc contains all runtime settings for cgit, including the list of git
13repositories, formatted as a line-separated list of NAME=VALUE pairs. Blank
14lines, and lines starting with '#', are ignored.
15
16
17LOCATION
18--------
19The default location of cgitrc, defined at compile time, is /etc/cgitrc. At
20runtime, cgit will consult the environment variable CGIT_CONFIG and, if
21defined, use its value instead.
22
23
24GLOBAL SETTINGS
25---------------
26about-filter::
27 Specifies a command which will be invoked to format the content of
28 about pages (both top-level and for each repository). The command will
29 get the content of the about-file on its STDIN, and the STDOUT from the
30 command will be included verbatim on the about page. Default value:
31 none.
32
33agefile::
34 Specifies a path, relative to each repository path, which can be used
35 to specify the date and time of the youngest commit in the repository.
36 The first line in the file is used as input to the "parse_date"
37 function in libgit. Recommended timestamp-format is "yyyy-mm-dd
38 hh:mm:ss". Default value: "info/web/last-modified".
39
40cache-root::
41 Path used to store the cgit cache entries. Default value:
42 "/var/cache/cgit".
43
44cache-dynamic-ttl::
45 Number which specifies the time-to-live, in minutes, for the cached
46 version of repository pages accessed without a fixed SHA1. Default
47 value: "5".
48
49cache-repo-ttl::
50 Number which specifies the time-to-live, in minutes, for the cached
51 version of the repository summary page. Default value: "5".
52
53cache-root-ttl::
54 Number which specifies the time-to-live, in minutes, for the cached
55 version of the repository index page. Default value: "5".
56
57cache-size::
58 The maximum number of entries in the cgit cache. Default value: "0"
59 (i.e. caching is disabled).
60
61cache-static-ttl::
62 Number which specifies the time-to-live, in minutes, for the cached
63 version of repository pages accessed with a fixed SHA1. Default value:
64 "5".
65
66clone-prefix::
67 Space-separated list of common prefixes which, when combined with a
68 repository url, generates valid clone urls for the repository. This
69 setting is only used if `repo.clone-url` is unspecified. Default value:
70 none.
71
72commit-filter::
73 Specifies a command which will be invoked to format commit messages.
74 The command will get the message on its STDIN, and the STDOUT from the
75 command will be included verbatim as the commit message, i.e. this can
76 be used to implement bugtracker integration. Default value: none.
77
78css::
79 Url which specifies the css document to include in all cgit pages.
80 Default value: "/cgit.css".
81
82embedded::
83 Flag which, when set to "1", will make cgit generate a html fragment
84 suitable for embedding in other html pages. Default value: none. See
85 also: "noheader".
86
87enable-index-links::
88 Flag which, when set to "1", will make cgit generate extra links for
89 each repo in the repository index (specifically, to the "summary",
90 "commit" and "tree" pages). Default value: "0".
91
92enable-log-filecount::
93 Flag which, when set to "1", will make cgit print the number of
94 modified files for each commit on the repository log page. Default
95 value: "0".
96
97enable-log-linecount::
98 Flag which, when set to "1", will make cgit print the number of added
99 and removed lines for each commit on the repository log page. Default
100 value: "0".
101
102favicon::
103 Url used as link to a shortcut icon for cgit. If specified, it is
104 suggested to use the value "/favicon.ico" since certain browsers will
105 ignore other values. Default value: none.
106
107footer::
108 The content of the file specified with this option will be included
109 verbatim at the bottom of all pages (i.e. it replaces the standard
110 "generated by..." message. Default value: none.
111
112head-include::
113 The content of the file specified with this option will be included
114 verbatim in the html HEAD section on all pages. Default value: none.
115
116header::
117 The content of the file specified with this option will be included
118 verbatim at the top of all pages. Default value: none.
119
120include::
121 Name of a configfile to include before the rest of the current config-
122 file is parsed. Default value: none.
123
124index-header::
125 The content of the file specified with this option will be included
126 verbatim above the repository index. This setting is deprecated, and
127 will not be supported by cgit-1.0 (use root-readme instead). Default
128 value: none.
129
130index-info::
131 The content of the file specified with this option will be included
132 verbatim below the heading on the repository index page. This setting
133 is deprecated, and will not be supported by cgit-1.0 (use root-desc
134 instead). Default value: none.
135
136local-time::
137 Flag which, if set to "1", makes cgit print commit and tag times in the
138 servers timezone. Default value: "0".
139
140logo::
141 Url which specifies the source of an image which will be used as a logo
142 on all cgit pages. Default value: "/cgit.png".
143
144logo-link::
145 Url loaded when clicking on the cgit logo image. If unspecified the
146 calculated url of the repository index page will be used. Default
147 value: none.
148
149max-commit-count::
150 Specifies the number of entries to list per page in "log" view. Default
151 value: "50".
152
153max-message-length::
154 Specifies the maximum number of commit message characters to display in
155 "log" view. Default value: "80".
156
157max-repo-count::
158 Specifies the number of entries to list per page on the repository
159 index page. Default value: "50".
160
161max-repodesc-length::
162 Specifies the maximum number of repo description characters to display
163 on the repository index page. Default value: "80".
164
165max-stats::
166 Set the default maximum statistics period. Valid values are "week",
167 "month", "quarter" and "year". If unspecified, statistics are
168 disabled. Default value: none. See also: "repo.max-stats".
169
170mimetype.<ext>::
171 Set the mimetype for the specified filename extension. This is used
172 by the `plain` command when returning blob content.
173
174module-link::
175 Text which will be used as the formatstring for a hyperlink when a
176 submodule is printed in a directory listing. The arguments for the
177 formatstring are the path and SHA1 of the submodule commit. Default
178 value: "./?repo=%s&page=commit&id=%s"
179
180nocache::
181 If set to the value "1" caching will be disabled. This settings is
182 deprecated, and will not be honored starting with cgit-1.0. Default
183 value: "0".
184
185noplainemail::
186 If set to "1" showing full author email adresses will be disabled.
187 Default value: "0".
188
189noheader::
190 Flag which, when set to "1", will make cgit omit the standard header
191 on all pages. Default value: none. See also: "embedded".
192
193renamelimit::
194 Maximum number of files to consider when detecting renames. The value
195 "-1" uses the compiletime value in git (for further info, look at
196 `man git-diff`). Default value: "-1".
197
198repo.group::
199 A value for the current repository group, which all repositories
200 specified after this setting will inherit. Default value: none.
201
202robots::
203 Text used as content for the "robots" meta-tag. Default value:
204 "index, nofollow".
205
206root-desc::
207 Text printed below the heading on the repository index page. Default
208 value: "a fast webinterface for the git dscm".
209
210root-readme::
211 The content of the file specified with this option will be included
212 verbatim below the "about" link on the repository index page. Default
213 value: none.
214
215root-title::
216 Text printed as heading on the repository index page. Default value:
217 "Git Repository Browser".
218
219snapshots::
220 Text which specifies the default set of snapshot formats generated by
221 cgit. The value is a space-separated list of zero or more of the
222 values "tar", "tar.gz", "tar.bz2" and "zip". Default value: none.
223
224source-filter::
225 Specifies a command which will be invoked to format plaintext blobs
226 in the tree view. The command will get the blob content on its STDIN
227 and the name of the blob as its only command line argument. The STDOUT
228 from the command will be included verbatim as the blob contents, i.e.
229 this can be used to implement e.g. syntax highlighting. Default value:
230 none.
231
232summary-branches::
233 Specifies the number of branches to display in the repository "summary"
234 view. Default value: "10".
235
236summary-log::
237 Specifies the number of log entries to display in the repository
238 "summary" view. Default value: "10".
239
240summary-tags::
241 Specifies the number of tags to display in the repository "summary"
242 view. Default value: "10".
243
244virtual-root::
245 Url which, if specified, will be used as root for all cgit links. It
246 will also cause cgit to generate 'virtual urls', i.e. urls like
247 '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
248 value: none.
249 NOTE: cgit has recently learned how to use PATH_INFO to achieve the
250 same kind of virtual urls, so this option will probably be deprecated.
251
252REPOSITORY SETTINGS
253-------------------
254repo.about-filter::
255 Override the default about-filter. Default value: <about-filter>.
256
257repo.clone-url::
258 A list of space-separated urls which can be used to clone this repo.
259 Default value: none.
260
261repo.commit-filter::
262 Override the default commit-filter. Default value: <commit-filter>.
263
264repo.defbranch::
265 The name of the default branch for this repository. If no such branch
266 exists in the repository, the first branch name (when sorted) is used
267 as default instead. Default value: "master".
268
269repo.desc::
270 The value to show as repository description. Default value: none.
271
272repo.enable-log-filecount::
273 A flag which can be used to disable the global setting
274 `enable-log-filecount'. Default value: none.
275
276repo.enable-log-linecount::
277 A flag which can be used to disable the global setting
278 `enable-log-linecount'. Default value: none.
279
280repo.max-stats::
281 Override the default maximum statistics period. Valid values are equal
282 to the values specified for the global "max-stats" setting. Default
283 value: none.
284
285repo.name::
286 The value to show as repository name. Default value: <repo.url>.
287
288repo.owner::
289 A value used to identify the owner of the repository. Default value:
290 none.
291
292repo.path::
293 An absolute path to the repository directory. For non-bare repositories
294 this is the .git-directory. Default value: none.
295
296repo.readme::
297 A path (relative to <repo.path>) which specifies a file to include
298 verbatim as the "About" page for this repo. Default value: none.
299
300repo.snapshots::
301 A mask of allowed snapshot-formats for this repo, restricted by the
302 "snapshots" global setting. Default value: <snapshots>.
303
304repo.source-filter::
305 Override the default source-filter. Default value: <source-filter>.
306
307repo.url::
308 The relative url used to access the repository. This must be the first
309 setting specified for each repo. Default value: none.
310
311
312EXAMPLE CGITRC FILE
313-------------------
314
315....
316# Enable caching of up to 1000 output entriess
317cache-size=1000
318
319
320# Specify some default clone prefixes
321clone-prefix=git://foobar.com ssh://foobar.com/pub/git http://foobar.com/git
322
323# Specify the css url
324css=/css/cgit.css
325
326
327# Show extra links for each repository on the index page
328enable-index-links=1
329
330
331# Show number of affected files per commit on the log pages
332enable-log-filecount=1
333
334
335# Show number of added/removed lines per commit on the log pages
336enable-log-linecount=1
337
338
339# Add a cgit favicon
340favicon=/favicon.ico
341
342
343# Use a custom logo
344logo=/img/mylogo.png
345
346
347# Enable statistics per week, month and quarter
348max-stats=quarter
349
350
351# Set the title and heading of the repository index page
352root-title=foobar.com git repositories
353
354
355# Set a subheading for the repository index page
356root-desc=tracking the foobar development
357
358
359# Include some more info about foobar.com on the index page
360root-readme=/var/www/htdocs/about.html
361
362
363# Allow download of tar.gz, tar.bz2 and zip-files
364snapshots=tar.gz tar.bz2 zip
365
366
367##
368## List of common mimetypes
369##
370
371mimetype.git=image/git
372mimetype.html=text/html
373mimetype.jpg=image/jpeg
374mimetype.jpeg=image/jpeg
375mimetype.pdf=application/pdf
376mimetype.png=image/png
377mimetype.svg=image/svg+xml
378
379
380##
381## List of repositories.
382## PS: Any repositories listed when repo.group is unset will not be
383## displayed under a group heading
384## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
385## and included like this:
386## include=/etc/cgitrepos
387##
388
389
390repo.url=foo
391repo.path=/pub/git/foo.git
392repo.desc=the master foo repository
393repo.owner=fooman@foobar.com
394repo.readme=info/web/about.html
395
396
397repo.url=bar
398repo.path=/pub/git/bar.git
399repo.desc=the bars for your foo
400repo.owner=barman@foobar.com
401repo.readme=info/web/about.html
402
403
404# The next repositories will be displayed under the 'extras' heading
405repo.group=extras
406
407
408repo.url=baz
409repo.path=/pub/git/baz.git
410repo.desc=a set of extensions for bar users
411
412repo.url=wiz
413repo.path=/pub/git/wiz.git
414repo.desc=the wizard of foo
415
416
417# Add some mirrored repositories
418repo.group=mirrors
419
420
421repo.url=git
422repo.path=/pub/git/git.git
423repo.desc=the dscm
424
425
426repo.url=linux
427repo.path=/pub/git/linux.git
428repo.desc=the kernel
429
430# Disable adhoc downloads of this repo
431repo.snapshots=0
432
433# Disable line-counts for this repo
434repo.enable-log-linecount=0
435
436# Restrict the max statistics period for this repo
437repo.max-stats=month
438....
439
440
441BUGS
442----
443Comments currently cannot appear on the same line as a setting; the comment
444will be included as part of the value. E.g. this line:
445
446 robots=index # allow indexing
447
448will generate the following html element:
449
450 <meta name='robots' content='index # allow indexing'/>
451
452
453
454AUTHOR
455------
456Lars Hjemli <hjemli@gmail.com>