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>

1 files changed, 367 insertions, 0 deletions

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 therepository
+        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>