gitweb: Update and improve gitweb/README file

Update list of build configuration variables, add references
to gitweb/INSTALL, add description of runtime and per-repository
runtime configuration.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 197 insertions, 18 deletions

diff --git a/gitweb/README b/gitweb/README
index 7186cede2f..b28f59f574 100644
--- a/gitweb/README
+++ b/gitweb/README
@@ -10,28 +10,96 @@ From the git version 1.4.0 gitweb is bundled with git.
 How to configure gitweb for your local system
 ---------------------------------------------
 
+See also "Build time configuration" section in INSTALL
+file for gitweb (in gitweb/INSTALL).
+
 You can specify the following configuration variables when building GIT:
+ * GIT_BINDIR
+   Points out where to find git executable.  You should set up it to
+   the place where git binary was installed (usually /usr/bin) if you
+   don't install git from sources together with gitweb.  [Default: $(bindir)]
  * GITWEB_SITENAME
-   Shown in the title of all generated pages, defaults to the servers name.
+   Shown in the title of all generated pages, defaults to the server name
+   (SERVER_NAME CGI environment variable) if not set. [No default]
  * GITWEB_PROJECTROOT
-   The root directory for all projects shown by gitweb.
+   The root directory for all projects shown by gitweb. Must be set
+   correctly for gitweb to find repositories to display.  See also
+   "Gitweb repositories" in INSTALL file for gitweb.  [Default: /pub/git]
+ * GITWEB_PROJECT_MAXDEPTH
+   The filesystem traversing limit for getting projects list; the number
+   is taken as depth relative to the projectroot.  It is used when
+   GITWEB_LIST is a directory (or is not set; then project root is used).
+   Is is meant to speed up project listing on large work trees by limiting
+   find depth.  [Default: 2007]
  * GITWEB_LIST
-   points to a directory to scan for projects (defaults to project root)
-   or to a file for explicit listing of projects.
+   Points to a directory to scan for projects (defaults to project root
+   if not set / if empty) or to a file with explicit listing of projects
+   (together with projects' ownership). See "Generating projects list
+   using gitweb" in INSTALL file for gitweb to find out how to generate
+   such file from scan of a directory. [No default, which means use root
+   directory for projects]
+ * GITWEB_EXPORT_OK
+   Show repository only if this file exists (in repository).  Only
+   effective if this variable evaluates to true.  [No default / Not set]
+ * GITWEB_STRICT_EXPORT
+   Only allow viewing of repositories also shown on the overview page.
+   This for example makes GITWEB_EXPORT_OK to decide if repository is
+   available and not only if it is shown.  If GITWEB_LIST points to
+   file with list of project, only those repositories listed would be
+   available for gitweb.  [No default]
  * GITWEB_HOMETEXT
-   points to an .html file which is included on the gitweb project
-   overview page.
+   Points to an .html file which is included on the gitweb project
+   overview page ('projects_list' view), if it exists.  Relative to
+   gitweb.cgi script.  [Default: indextext.html]
+ * GITWEB_SITE_HEADER
+   Filename of html text to include at top of each page.  Relative to
+   gitweb.cgi script.  [No default]
+ * GITWEB_SITE_FOOTER
+   Filename of html text to include at bottom of each page.  Relative to
+   gitweb.cgi script.  [No default]
+ * GITWEB_HOME_LINK_STR
+   String of the home link on top of all pages, leading to $home_link
+   (usually main gitweb page, which means projects list).  Used as first
+   part of gitweb view "breadcrumb trail": <home> / <project> / <view>.
+   [Default: projects]
+ * GITWEB_SITENAME
+   Name of your site or organization to appear in page titles.  Set it
+   to something descriptive for clearer bookmarks etc.  If not set
+   (if empty) gitweb uses "$SERVER_NAME Git", or "Untitled Git" if
+   SERVER_NAME CGI environment variable is not set (e.g. if running
+   gitweb as standalone script).  [No default]
+ * GITWEB_BASE_URL
+   Git base URLs used for URL to where fetch project from, i.e. full
+   URL is "$git_base_url/$project".  Shown on projects summary page.
+   Repository URL for project can be also configured per repository; this
+   takes precendence over URL composed from base URL and project name.
+   Note that you can setup multiple base URLs (for example one for
+   git:// protocol access, one for http:// access) from gitweb config
+   file.  [No default]
  * GITWEB_CSS
-   Points to the location where you put gitweb.css on your web server.
+   Points to the location where you put gitweb.css on your web server
+   (or to be more generic URI of gitweb stylesheet).  Relative to base
+   URI of gitweb.  Note that you can setup multiple stylesheets from
+   gitweb config file.  [Default: gitweb.css]
  * GITWEB_LOGO
-   Points to the location where you put git-logo.png on your web server.
+   Points to the location where you put git-logo.png on your web server
+   (or to be more generic URI of logo, 72x27 size, displayed in top right
+   corner of each gitweb page, and used as logo for Atom feed).  Relative
+   to base URI of gitweb.  [Default: git-logo.png]
+ * GITWEB_FAVICON
+   Points to the location where you put git-favicon.png on your web server
+   (or to be more generic URI of favicon, assumed to be image/png type;
+   web browsers that support favicons (website icons) may display them
+   in the browser's URL bar and next to site name in bookmarks).  Relative
+   to base URI of gitweb.  [Default: git-favicon.png]
  * GITWEB_CONFIG
-   This file will be loaded using 'require' and can be used to override any
-   of the options above as well as some other options - see the top of
-   'gitweb.cgi' for their full list and description.  If the environment
-   $GITWEB_CONFIG is set when gitweb.cgi is executed the file in the
-   environment variable will be loaded instead of the file
-   specified when gitweb.cgi was created.
+   This Perl file will be loaded using 'do' and can be used to override any
+   of the options above as well as some other options -- see the "Runtime
+   gitweb configuration" section below, and top of 'gitweb.cgi' for their
+   full list and description.  If the environment variable GITWEB_CONFIG
+   is set when gitweb.cgi is executed, then the file specified in the
+   environment variable will be loaded instead of the file specified
+   when gitweb.cgi was created.  [Default: gitweb_config.perl]
 
 
 Runtime gitweb configuration
@@ -39,11 +107,122 @@ Runtime gitweb configuration
 
 You can adjust gitweb behaviour using the file specified in `GITWEB_CONFIG`
 (defaults to 'gitweb_config.perl' in the same directory as the CGI).
-See the top of 'gitweb.cgi' for the list of variables and some description.
 The most notable thing that is not configurable at compile time are the
-optional features, stored in the '%features' variable. You can find further
-description on how to reconfigure the default features setting in your
-`GITWEB_CONFIG` or per-project in `project.git/config` inside 'gitweb.cgi'.
+optional features, stored in the '%features' variable.
+
+Ultimate description on how to reconfigure the default features setting
+in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found
+as comments inside 'gitweb.cgi'.
+
+See also "Gitweb config file" (with example of gitweb config file), and
+"Gitweb repositories" sections in INSTALL file for gitweb.
+
+
+Gitweb config file is [fragment] of perl code. You can set variables
+using "our $variable = value"; text from "#" character until the end
+of a line is ignored. See perlsyn(1) man page for details.
+
+Below there is list of vaiables which you might want to set in gitweb config.
+See the top of 'gitweb.cgi' for the full list of variables and their
+descriptions.
+
+Gitweb config file variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can set, among others,  the following variables in gitweb config files:
+ * $GIT
+   Cure git executable to use.  By default set to "$GIT_BINDIR/git", which
+   in turn is by default set to "$(bindir)/git".  If you use git from binary
+   package, set this to "/usr/bin/git".  This can just be "git" if your
+   webserver has a sensible PATH.  If you have multiple git versions
+   installed it is / can be used to choose which one to use.
+ * $version
+   Gitweb version, set automatically when creating gitweb.cgi from
+   gitweb.perl. You might want to modify it if you are running modified
+   gitweb.
+ * $my_url, $my_uri
+   URL and absolute URL of gitweb script; you might need to set those
+   variables if you are using 'pathinfo' feature: see also below.
+ * $home_link
+   Target of the home link on top of all pages (the first part of view
+   "breadcrumbs").  By default set to absolute URI of a page; you might
+   need to set it up to [base] gitweb URI if you use 'pathinfo' feature
+   (alternative format of the URLs, with project name embedded directly
+   in the path part of URL).
+ * @stylesheets
+   List of URIs of stylesheets (relative to base URI of a page). You
+   might specify more than one stylesheet, for example use gitweb.css
+   as base, with site specific modifications in separate stylesheet
+   to make it easier to upgrade gitweb. You can add 'site' stylesheet
+   for example by using
+      push @stylesheets, "gitweb-site.css";
+   in gitweb config file.
+ * $logo_url, $logo_label
+   URI and label (title) of GIT logo link (or your site logo, if you choose
+   to use different logo image). By default they point to git homepage;
+   in the past they pointed to git documentation at www.kernel.org.
+ * $projects_list_description_width
+   The width (in characters) of the projects list "Description" column.
+   Longer descriptions will be cut (trying to cut at word boundary);
+   full description is available as 'title' attribute (usually shown on
+   mouseover).  By default set to 25, which might be too small if you
+   use long project descriptions.
+ * @git_base_url_list
+   List of git base URLs used for URL to where fetch project from, shown
+   in project summary page.  Full URL is "$git_base_url/$project".
+   You can setup multiple base URLs (for example one for  git:// protocol
+   access, and one for http:// "dumb" protocol access).  Note that per
+   repository configuration in 'cloneurl' file, or as values of gitweb.url
+   project config.
+ * $default_blob_plain_mimetype
+   Default mimetype for blob_plain (raw) view, if mimetype checking
+   doesn't result in some other type; by default 'text/plain'.
+ * $default_text_plain_charset
+   Default charset for text files. If not set, web serwer configuration
+   would be used.
+ * $mimetypes_file
+   File to use for (filename extension based) guessing of MIME types before
+   trying /etc/mime.types. Path, if relative, is taken currently as taken
+   relative to current git repositoy.
+ * $fallback_encoding
+   Gitweb assumes this charset if line contains non-UTF-8 characters.
+   Fallback decoding is used without error checking, so it can be even
+   'utf-8'. Value mist be valid encodig; see Encoding::Supported(3pm) man
+   page for a list.   By default 'latin1', aka. 'iso-8859-1'.
+ * @diff_opts
+   Rename detection options for git-diff and git-diff-tree. By default
+   ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or
+   set it to () if you don't want to have renames detection.
+
+Per-repository gitweb configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also configure individual repositories shown in gitweb by creating
+file in the GIT_DIR of git repository, or by setting some repo configuration
+variable (in GIT_DIR/config).
+
+You can use the following files in repository:
+ * README.html
+   A .html file (HTML fragment) which is included on the gitweb project
+   summary page inside <div> block element. You can use it for longer
+   description of a project, to provide links for example to projects
+   homepage, etc.
+ * description (or gitweb.description)
+   Short (shortened by default to 25 characters in the projects list page)
+   single line description of a project (of a repository). Plain text file;
+   HTML will be escaped. By default set to
+     Unnamed repository; edit this file to name it for gitweb.
+   from the template during creating repository. You can use
+   gitweb.description repo configuration variable, but the file takes
+   precendence.
+ * cloneurl (or multiple-valued gitweb.url)
+   File with repository URL (used for clone and fetch), one per line.
+   Displayed in the project summary page. You can use multiple-valued
+   gitweb.url repository configuration variable for that, but the file
+   takes precendence.
+ * various gitweb.* config variables (in config)
+   Read description of %feature hash for detailed list, and some
+   descriptions.
 
 
 Webserver configuration