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