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 (and allowed) set of snapshot formats
221 supported by cgit. The value is a space-separated list of zero or more
222 of the following values:
223 "tar" uncompressed tar-file
224 "tar.gz" gzip-compressed tar-file
225 "tar.bz2" bzip-compressed tar-file
226 "zip" zip-file
227 Default value: none.
228
229source-filter::
230 Specifies a command which will be invoked to format plaintext blobs
231 in the tree view. The command will get the blob content on its STDIN
232 and the name of the blob as its only command line argument. The STDOUT
233 from the command will be included verbatim as the blob contents, i.e.
234 this can be used to implement e.g. syntax highlighting. Default value:
235 none.
236
237summary-branches::
238 Specifies the number of branches to display in the repository "summary"
239 view. Default value: "10".
240
241summary-log::
242 Specifies the number of log entries to display in the repository
243 "summary" view. Default value: "10".
244
245summary-tags::
246 Specifies the number of tags to display in the repository "summary"
247 view. Default value: "10".
248
249virtual-root::
250 Url which, if specified, will be used as root for all cgit links. It
251 will also cause cgit to generate 'virtual urls', i.e. urls like
252 '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
253 value: none.
254 NOTE: cgit has recently learned how to use PATH_INFO to achieve the
255 same kind of virtual urls, so this option will probably be deprecated.
256
257REPOSITORY SETTINGS
258-------------------
259repo.about-filter::
260 Override the default about-filter. Default value: <about-filter>.
261
262repo.clone-url::
263 A list of space-separated urls which can be used to clone this repo.
264 Default value: none.
265
266repo.commit-filter::
267 Override the default commit-filter. Default value: <commit-filter>.
268
269repo.defbranch::
270 The name of the default branch for this repository. If no such branch
271 exists in the repository, the first branch name (when sorted) is used
272 as default instead. Default value: "master".
273
274repo.desc::
275 The value to show as repository description. Default value: none.
276
277repo.enable-log-filecount::
278 A flag which can be used to disable the global setting
279 `enable-log-filecount'. Default value: none.
280
281repo.enable-log-linecount::
282 A flag which can be used to disable the global setting
283 `enable-log-linecount'. Default value: none.
284
285repo.max-stats::
286 Override the default maximum statistics period. Valid values are equal
287 to the values specified for the global "max-stats" setting. Default
288 value: none.
289
290repo.name::
291 The value to show as repository name. Default value: <repo.url>.
292
293repo.owner::
294 A value used to identify the owner of the repository. Default value:
295 none.
296
297repo.path::
298 An absolute path to the repository directory. For non-bare repositories
299 this is the .git-directory. Default value: none.
300
301repo.readme::
302 A path (relative to <repo.path>) which specifies a file to include
303 verbatim as the "About" page for this repo. Default value: none.
304
305repo.snapshots::
306 A mask of allowed snapshot-formats for this repo, restricted by the
307 "snapshots" global setting. Default value: <snapshots>.
308
309repo.source-filter::
310 Override the default source-filter. Default value: <source-filter>.
311
312repo.url::
313 The relative url used to access the repository. This must be the first
314 setting specified for each repo. Default value: none.
315
316
317EXAMPLE CGITRC FILE
318-------------------
319
320....
321# Enable caching of up to 1000 output entriess
322cache-size=1000
323
324
325# Specify some default clone prefixes
326clone-prefix=git://foobar.com ssh://foobar.com/pub/git http://foobar.com/git
327
328# Specify the css url
329css=/css/cgit.css
330
331
332# Show extra links for each repository on the index page
333enable-index-links=1
334
335
336# Show number of affected files per commit on the log pages
337enable-log-filecount=1
338
339
340# Show number of added/removed lines per commit on the log pages
341enable-log-linecount=1
342
343
344# Add a cgit favicon
345favicon=/favicon.ico
346
347
348# Use a custom logo
349logo=/img/mylogo.png
350
351
352# Enable statistics per week, month and quarter
353max-stats=quarter
354
355
356# Set the title and heading of the repository index page
357root-title=foobar.com git repositories
358
359
360# Set a subheading for the repository index page
361root-desc=tracking the foobar development
362
363
364# Include some more info about foobar.com on the index page
365root-readme=/var/www/htdocs/about.html
366
367
368# Allow download of tar.gz, tar.bz2 and zip-files
369snapshots=tar.gz tar.bz2 zip
370
371
372##
373## List of common mimetypes
374##
375
376mimetype.git=image/git
377mimetype.html=text/html
378mimetype.jpg=image/jpeg
379mimetype.jpeg=image/jpeg
380mimetype.pdf=application/pdf
381mimetype.png=image/png
382mimetype.svg=image/svg+xml
383
384
385##
386## List of repositories.
387## PS: Any repositories listed when repo.group is unset will not be
388## displayed under a group heading
389## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
390## and included like this:
391## include=/etc/cgitrepos
392##
393
394
395repo.url=foo
396repo.path=/pub/git/foo.git
397repo.desc=the master foo repository
398repo.owner=fooman@foobar.com
399repo.readme=info/web/about.html
400
401
402repo.url=bar
403repo.path=/pub/git/bar.git
404repo.desc=the bars for your foo
405repo.owner=barman@foobar.com
406repo.readme=info/web/about.html
407
408
409# The next repositories will be displayed under the 'extras' heading
410repo.group=extras
411
412
413repo.url=baz
414repo.path=/pub/git/baz.git
415repo.desc=a set of extensions for bar users
416
417repo.url=wiz
418repo.path=/pub/git/wiz.git
419repo.desc=the wizard of foo
420
421
422# Add some mirrored repositories
423repo.group=mirrors
424
425
426repo.url=git
427repo.path=/pub/git/git.git
428repo.desc=the dscm
429
430
431repo.url=linux
432repo.path=/pub/git/linux.git
433repo.desc=the kernel
434
435# Disable adhoc downloads of this repo
436repo.snapshots=0
437
438# Disable line-counts for this repo
439repo.enable-log-linecount=0
440
441# Restrict the max statistics period for this repo
442repo.max-stats=month
443....
444
445
446BUGS
447----
448Comments currently cannot appear on the same line as a setting; the comment
449will be included as part of the value. E.g. this line:
450
451 robots=index # allow indexing
452
453will generate the following html element:
454
455 <meta name='robots' content='index # allow indexing'/>
456
457
458
459AUTHOR
460------
461Lars Hjemli <hjemli@gmail.com>