summaryrefslogtreecommitdiffabout
authorLars Hjemli <hjemli@gmail.com>2008-10-05 16:55:49 (UTC)
committer Lars Hjemli <hjemli@gmail.com>2008-10-05 16:55:49 (UTC)
commitdf46123b0e55027bc39403df285851d37f25a473 (patch) (side-by-side diff)
tree0aa2dcc29d332e7bf5153405552d483d9a3c3d68
parentc6bea0375aa7898ea3229483741944303740801e (diff)
downloadcgit-df46123b0e55027bc39403df285851d37f25a473.zip
cgit-df46123b0e55027bc39403df285851d37f25a473.tar.gz
cgit-df46123b0e55027bc39403df285851d37f25a473.tar.bz2
Replace cgitrc with cgitrc.5.txt
The new file describes all cgitrc options in a more structured manner then the cgitrc example file and it might also work as the source for a cgitrc man page. Signed-off-by: Lars Hjemli <hjemli@gmail.com>
Diffstat (more/less context) (show whitespace changes)
-rw-r--r--cgitrc202
-rw-r--r--cgitrc.5.txt367
2 files changed, 367 insertions, 202 deletions
diff --git a/cgitrc b/cgitrc
deleted file mode 100644
index 6a79c43..0000000
--- a/cgitrc
+++ b/dev/null
@@ -1,202 +0,0 @@
-##
-## cgitrc: template for /etc/cgitrc
-##
-
-
-## Uncomment and set to 1 to deactivate caching of generated pages. Mostly
-## usefull for testing.
-#nocache=0
-
-
-## This variable can be used to override the default value for "robots"
-## meta-tag. If unset, the meta-tag isn't generated.
-#robots=index, nofollow
-
-
-## Set allowed snapshot types by default. Can be overridden per repo
-# can be any combination of zip/tar.gz/tar.bz2/tar
-#snapshots=0
-
-
-## Enable/disable extra links to summary/log/tree per repo on index page
-#enable-index-links=0
-
-
-## Enable/disable display of 'number of files changed' in log view
-#enable-log-filecount=0
-
-
-## Enable/disable display of 'number of lines changed' in log view
-#enable-log-linecount=0
-
-
-## Enable/disable display of HEAD shortlog in summary view. Set it to maximum
-## number of commits that should be displayed
-#summary-log=0
-
-
-## Restrict the number of branches printed in summary view. Set to 0 to
-## print all branches.
-#summary-branches=0
-
-
-## Restrict the number of tags printed in summary view. Set to 0 to
-## print all tags.
-#summary-tags=0
-
-## Enable/disable display of localtime vs. GMT. Set to 1 for localtime.
-#local-time=0
-
-## The "Idle" column on the repository index page can read a timestamp
-## from the specified agefile (if this file cannot be found, the mtime
-## of HEAD is used).
-## The cgit repo on hjemli.net uses the the following command in it's
-## post-receive hook to update the age-file:
-## git-for-each-ref --format="%(committerdate)" --sort=-committerdate \
-## --count=1 > $GIT_DIR/info/web/last-modifie
-##
-#agefile=info/web/last-modified
-
-
-## Git detects renames, but with a limit on the number of files to
-## consider. This option can be used to specify another limit (or -1 to
-## use the default limit).
-##
-#renamelimit=-1
-
-
-## Specify a root for virtual urls. This makes cgit generate urls like
-##
-## http://localhost/git/repo/log/?h=branch
-##
-## instead of
-##
-## http://localhost/cgit/cgit.cgi?url=repo/log&h=branch
-##
-## For this to work with apache, a rewrite rule must be added to httpd.conf,
-## possibly looking something like this:
-##
-## RewriteRule ^/git/(.*)$ /cgit/cgit.cgi?url=$1 [L,QSA]
-##
-## For this to work with lighttpd, the rewrite rule should look more like this:
-##
-## url.rewrite = (
-## "^/git/([^?/]+/[^?]*)?(?:\?(.*))?$" => "/cgit.cgi?url=$1&$2"
-## )
-##
-## This setting is disabled by default.
-#virtual-root=/git
-
-
-## Set the title printed on the root page
-#root-title=Git repository browser
-
-
-## Set the description printed on the root page
-#root-desc=a fast web interface for the git dscm
-
-
-## If specified, the file at this path will be included as HTML in the
-## sidebar on the repository index page
-#index-info=
-
-
-## If specified, the file at this path will be included as HTML above
-## the repository index
-#index-header=
-
-
-## Link to css file
-#css=/cgit/cgit.css
-
-## Link to favicon
-#favicon=/favicon.ico
-
-## Link to logo file
-#logo=/cgit/git-logo.png
-
-
-## Url loaded when clicking the logo
-#logo-link=http://www.kernel.org/pub/software/scm/git/docs/
-
-
-## Url loaded when clicking a submodule link
-#module-link=./?repo=%s&page=commit&id=%s
-
-
-## Shared prefix which, when combined with repo url, becomes the url used
-## to clone the repo
-#clone-prefix=
-
-
-## Number of chars shown of repo description (in repolist view)
-#max-repodesc-length=60
-
-
-## Number of chars shown of commit subject message (in log view)
-#max-message-length=60
-
-
-## Number of commits per page in log view
-#max-commit-count=50
-
-
-## Root of cached output
-#cache-root=/var/cache/cgit
-
-
-## Include another config-file
-#include=/var/cgit/repolist
-
-##
-## Time-To-Live settings: specifies how long (in minutes) different pages
-## should be cached (0 for instant expiration, -1 for immortal pages)
-##
-
-## ttl for root page
-#cache-root-ttl=5
-
-## ttl for repo summary page
-#cache-repo-ttl=5
-
-## ttl for other dynamic pages
-#cache-dynamic-ttl=5
-
-## ttl for static pages (addressed by SHA-1)
-#cache-static-ttl=-1
-
-
-
-## Example repository entry. Required values are repo.url and repo.path (each
-## repository section must start with repo.url).
-#repo.url=cgit
-#repo.name=cgit
-#repo.desc=the caching cgi for git
-#repo.path=/pub/git/cgit ## this is the path to $GIT_DIR
-#repo.owner=Lars Hjemli
-#repo.defbranch=master ## define a default branch
-#repo.snapshots=tar.bz2 ## override a sitewide snapshot-setting
-#repo.enable-log-filecount=0 ## override the default filecount setting
-#repo.enable-log-linecount=0 ## override the default linecount setting
-#repo.module-link=/git/%s/commit/?id=%s ## override the standard module-link
-#repo.readme=info/web/readme ## specify a file to include on summary page
-#repo.clone-url=git://hjemli.net/pub/git/cgit
-
-## Additional repositories grouped under "mirrors"
-#repo.group=mirrors
-
-#repo.url=git
-#repo.path=/pub/git/git
-#repo.clone-url=git://hjemli.net/pub/git/git
-#
-#repo.url=linux
-#repo.path=/pub/git/linux
-
-## A group of private repositories (with a working directory)
-#repo.group=private
-
-#repo.url=larsh/cgit
-#repo.path=/home/larsh/src/cgit/.git
-
-#repo.url=larsh/git
-#repo.path=/home/larsh/src/git/.git
diff --git a/cgitrc.5.txt b/cgitrc.5.txt
new file mode 100644
index 0000000..7887b02
--- a/dev/null
+++ b/cgitrc.5.txt
@@ -0,0 +1,367 @@
+CGITRC
+======
+
+
+NAME
+----
+ cgitrc - runtime configuration for cgit
+
+
+DESCRIPTION
+-----------
+Cgitrc contains all runtime settings for cgit, including the list of git
+repositories, formatted as a line-separated list of NAME=VALUE pairs. Blank
+lines, and lines starting with '#', are ignored.
+
+
+GLOBAL SETTINGS
+---------------
+agefile
+ Specifies a path, relative to each repository path, which can be used
+ to specify the date and time of the youngest commit in the repository.
+ The first line in the file is used as input to the "parse_date"
+ function in libgit. Recommended timestamp-format is "yyyy-mm-dd
+ hh:mm:ss". Default value: "info/web/last-modified".
+
+cache-root
+ Path used to store the cgit cache entries. Default value:
+ "/var/cache/cgit".
+
+cache-dynamic-ttl
+ Number which specifies the time-to-live, in minutes, for the cached
+ version of repository pages accessed without a fixed SHA1. Default
+ value: "5".
+
+cache-repo-ttl
+ Number which specifies the time-to-live, in minutes, for the cached
+ version of the repository summary page. Default value: "5".
+
+cache-root-ttl
+ Number which specifies the time-to-live, in minutes, for the cached
+ version of the repository index page. Default value: "5".
+
+cache-size
+ The maximum number of entries in the cgit cache. Default value: "0"
+ (i.e. caching is disabled).
+
+cache-static-ttl
+ Number which specifies the time-to-live, in minutes, for the cached
+ version of repository pages accessed with a fixed SHA1. Default value:
+ "5".
+
+clone-prefix
+ Space-separated list of common prefixes which, when combined with a
+ repository url, generates valid clone urls for the repository. This
+ setting is only used if `repo.clone-url` is unspecified. Default value:
+ none.
+
+css
+ Url which specifies the css document to include in all cgit pages.
+ Default value: "/cgit.css".
+
+enable-index-links
+ Flag which, when set to "1", will make cgit generate extra links for
+ each repo in the repository index (specifically, to the "summary",
+ "commit" and "tree" pages). Default value: "0".
+
+enable-log-filecount
+ Flag which, when set to "1", will make cgit print the number of
+ modified files for each commit on the repository log page. Default
+ value: "0".
+
+enable-log-linecount
+ Flag which, when set to "1", will make cgit print the number of added
+ and removed lines for each commit on the repository log page. Default
+ value: "0".
+
+favicon
+ Url used as link to a shortcut icon for cgit. If specified, it is
+ suggested to use the value "/favicon.ico" since certain browsers will
+ ignore other values. Default value: none.
+
+footer
+ The content of the file specified with this option will be included
+ verbatim at the bottom of all pages (i.e. it replaces the standard
+ "generated by..." message. Default value: none.
+
+include
+ Name of a configfile to include before the rest of the current config-
+ file is parsed. Default value: none.
+
+index-header
+ The content of the file specified with this option will be included
+ verbatim above the repository index. This setting is deprecated, and
+ will not be supported by cgit-1.0 (use root-readme instead). Default
+ value: none.
+
+index-info
+ The content of the file specified with this option will be included
+ verbatim below the heading on the repository index page. This setting
+ is deprecated, and will not be supported by cgit-1.0 (use root-desc
+ instead). Default value: none.
+
+local-time
+ Flag which, if set to "1", makes cgit print commit and tag times in the
+ servers timezone. Default value: "0".
+
+logo
+ Url which specifies the source of an image which will be used as a logo
+ on all cgit pages.
+
+logo-link
+ Url loaded when clicking on the cgit logo image. If unspecified the
+ calculated url of the repository index page will be used. Default
+ value: none.
+
+max-commit-count
+ Specifies the number of entries to list per page in "log" view. Default
+ value: "50".
+
+max-message-length
+ Specifies the maximum number of commit message characters to display in
+ "log" view. Default value: "80".
+
+max-repo-count
+ Specifies the number of entries to list per page on the repository
+ index page. Default value: "50".
+
+max-repodesc-length
+ Specifies the maximum number of repo description characters to display
+ on the repository index page. Default value: "80".
+
+module-link
+ Text which will be used as the formatstring for a hyperlink when a
+ submodule is printed in a directory listing. The arguments for the
+ formatstring are the path and SHA1 of the submodule commit. Default
+ value: "./?repo=%s&page=commit&id=%s"
+
+nocache
+ If set to the value "1" caching will be disabled. This settings is
+ deprecated, and will not be honored starting with cgit-1.0. Default
+ value: "0".
+
+renamelimit
+ Maximum number of files to consider when detecting renames. The value
+ "-1" uses the compiletime value in git (for further info, look at
+ `man git-diff`). Default value: "-1".
+
+repo.group
+ A value for the current repository group, which all repositories
+ specified after this setting will inherit. Default value: none.
+
+robots
+ Text used as content for the "robots" meta-tag. Default value:
+ "index, nofollow".
+
+root-desc
+ Text printed below the heading on the repository index page. Default
+ value: "a fast webinterface for the git dscm".
+
+root-readme:
+ The content of the file specified with this option will be included
+ verbatim below the "about" link on the repository index page. Default
+ value: none.
+
+root-title
+ Text printed as heading on the repository index page. Default value:
+ "Git Repository Browser".
+
+snapshots
+ Text which specifies the default (and allowed) set of snapshot formats
+ supported by cgit. The value is a space-separated list of zero or more
+ of the following values:
+ "tar" uncompressed tar-file
+ "tar.gz" gzip-compressed tar-file
+ "tar.bz2" bzip-compressed tar-file
+ "zip" zip-file
+ Default value: none.
+
+summary-branches
+ Specifies the number of branches to display in the repository "summary"
+ view. Default value: "10".
+
+summary-log
+ Specifies the number of log entries to display in the repository
+ "summary" view. Default value: "10".
+
+summary-tags
+ Specifies the number of tags to display in the repository "summary"
+ view. Default value: "10".
+
+virtual-root
+ Url which, if specified, will be used as root for all cgit links. It
+ will also cause cgit to generate 'virtual urls', i.e. urls like
+ '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
+ value: none.
+ NOTE: cgit has recently learned how to use PATH_INFO to achieve the
+ same kind of virtual urls, so this option will probably be deprecated.
+
+REPOSITORY SETTINGS
+-------------------
+repo.clone-url
+ A list of space-separated urls which can be used to clone this repo.
+ Default value: none.
+
+repo.defbranch
+ The name of the default branch for this repository. If no such branch
+ exists in the repository, the first branch name (when sorted) is used
+ as default instead. Default value: "master".
+
+repo.desc
+ The value to show as repository description. Default value: none.
+
+repo.enable-log-filecount
+ A flag which can be used to disable the global setting
+ `enable-log-filecount'. Default value: none.
+
+repo.enable-log-linecount
+ A flag which can be used to disable the global setting
+ `enable-log-linecount'. Default value: none.
+
+repo.name
+ The value to show as repository name. Default value: <repo.url>.
+
+repo.owner
+ A value used to identify the owner of the repository. Default value:
+ none.
+
+repo.path
+ An absolute path to the repository directory. For non-bare repositories
+ this is the .git-directory. Default value: none.
+
+repo.readme
+ A path (relative to <repo.path>) which specifies a file to include
+ verbatim as the "About" page for this repo. Default value: none.
+
+repo.snapshots
+ A mask of allowed snapshot-formats for this repo, restricted by the
+ "snapshots" global setting. Default value: <snapshots>.
+
+repo.url
+ The relative url used to access the repository. This must be the first
+ setting specified for each repo. Default value: none.
+
+
+EXAMPLE CGITRC FILE
+-------------------
+
+# Enable caching of up to 1000 output entriess
+cache-size=1000
+
+
+# Specify some default clone prefixes
+clone-prefix=git://foobar.com ssh://foobar.com/pub/git http://foobar.com/git
+
+# Specify the css url
+css=/css/cgit.css
+
+
+# Show extra links for each repository on the index page
+enable-index-links=1
+
+
+# Show number of affected files per commit on the log pages
+enable-log-filecount=1
+
+
+# Show number of added/removed lines per commit on the log pages
+enable-log-linecount=1
+
+
+# Add a cgit favicon
+favicon=/favicon.ico
+
+
+# Use a custom logo
+logo=/img/mylogo.png
+
+
+# Set the title and heading of the repository index page
+root-title=foobar.com git repositories
+
+
+# Set a subheading for the repository index page
+root-desc=tracking the foobar development
+
+
+# Include some more info about foobar.com on the index page
+root-readme=/var/www/htdocs/about.html
+
+
+# Allow download of tar.gz, tar.bz and zip-files
+snapshots=tar.gz tar.bz zip
+
+
+##
+## List of repositories.
+## PS: Any repositories listed when repo.group is unset will not be
+## displayed under a group heading
+## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
+## and included like this:
+## include=/etc/cgitrepos
+##
+
+
+repo.url=foo
+repo.path=/pub/git/foo.git
+repo.desc=the master foo repository
+repo.owner=fooman@foobar.com
+repo.readme=info/web/about.html
+
+
+repo.url=bar
+repo.path=/pub/git/bar.git
+repo.desc=the bars for your foo
+repo.owner=barman@foobar.com
+repo.readme=info/web/about.html
+
+
+# The next repositories will be displayed under the 'extras' heading
+repo.group=extras
+
+
+repo.url=baz
+repo.path=/pub/git/baz.git
+repo.desc=a set of extensions for bar users
+
+repo.url=wiz
+repo.path=/pub/git/wiz.git
+repo.desc=the wizard of foo
+
+
+# Add some mirrored repositories
+repo.group=mirrors
+
+
+repo.url=git
+repo.path=/pub/git/git.git
+repo.desc=the dscm
+
+
+repo.url=linux
+repo.path=/pub/git/linux.git
+repo.desc=the kernel
+
+# Disable adhoc downloads of this repo
+repo.snapshots=0
+
+# Disable line-counts for this repo
+repo.enable-log-linecount=0
+
+
+BUGS
+----
+Comments currently cannot appear on the same line as a setting; the comment
+will be included as part of the value. E.g. this line:
+
+ robots=index # allow indexing
+
+will generate the following html element:
+
+ <meta name='robots' content='index # allow indexing'/>
+
+
+
+AUTHOR
+------
+Lars Hjemli <hjemli@gmail.com>