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