{"thread":{"id":"28634","subject":"[PATCHv5/RFC 0/6] Moving gitweb documentation to manpages","startedAt":"2011-10-08T18:31:57Z","lastAt":"2011-10-11T18:16:09Z","messageCount":22,"participants":["Jakub Narebski","Junio C Hamano","Jonathan Nieder","Drew Northup"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"177241","messageId":"1318098723-12813-1-git-send-email-jnareb@gmail.com","threadId":"28634","inReplyTo":null,"subject":"[PATCHv5/RFC 0/6] Moving gitweb documentation to manpages","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-10-08T18:31:57Z","receivedAt":"2011-10-08T18:31:57Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"The original patch adding manpage for /etc/gitweb.conf was sent by\nDrew Northup (as can be seen from shortlog); I have added manpage for\ngitweb itself, inspired by his patch. Unfortunately Drew doesn't\ncurrently have time to work on this patch (patch series), so that is\nwhy it is me resending this series (again).\n\nCompared to previous version\n\n \"[PATCH/RFCv4 0/4] Moving gitweb documentation to manpages\"\n http://thread.gmane.org/gmane.comp.version-control.git/181605\n\nit has much improved gitweb.conf.txt manpage, and \"Documentation:\nPreparation for gitweb manpages\" commit message, thanks to feedback\nprovided by Jonathan Nieder.\n\nNew in this series are patches 4 and 5, which add links to the newly\ncreated gitweb documentation and gitweb config variables from other\nmanpages, respectively.\n\nNote that only \"Documentation: Preparation for gitweb manpages\" (which\nis not strictly necessary) and \"gitweb: Add manpage for gitweb\" (which\ndidn't get as much review as \"gitweb: Add manpage for gitweb\nconfiguration files\" are still marked as RFC.\n\nI have checked that RPM generation of 'gitweb' package works correctly\nwrt. gitweb documentation.\n\nTable of contents:\n~~~~~~~~~~~~~~~~~~\n [PATCHv5/RFC 1/6] Documentation: Preparation for gitweb manpages\n [PATCHv5 2/6] gitweb: Add manpage for gitweb configuration files\n [PATCHv5/RFC 3/6] gitweb: Add manpage for gitweb\n [PATCHv5 4/6] Documentation: Link to gitweb(1) and \n gitweb.conf(5) in other manpages\n [PATCHv5 5/6] Documentation: Add gitweb config variables to\n git-config(1)\n [PATCHv5 6/6] gitweb: Add gitweb manpages to 'gitweb' package in\n git.spec.in\n\nShortlog:\n~~~~~~~~~\nDrew Northup (1):\n gitweb: Add manpage for gitweb configuration files\n\nJakub Narebski (5):\n Documentation: Preparation for gitweb manpages\n gitweb: Add manpage for gitweb\n Documentation: Link to gitweb(1) and gitweb.conf(5) in other manpages\n Documentation: Add gitweb config variables to git-config(1)\n gitweb: Add gitweb manpages to 'gitweb' package in git.spec\n\nDiffstat:\n~~~~~~~~~\n Documentation/Makefile | 7 +-\n Documentation/config.txt | 17 +\n Documentation/git-instaweb.txt | 4 +\n Documentation/gitweb.conf.txt | 875 ++++++++++++++++++++++++++++++++++++++++\n Documentation/gitweb.txt | 703 ++++++++++++++++++++++++++++++++\n command-list.txt | 1 +\n git.spec.in | 7 +\n gitweb/INSTALL | 94 +----\n gitweb/Makefile | 7 +-\n gitweb/README | 411 +------------------\n 10 files changed, 1647 insertions(+), 479 deletions(-)\n create mode 100644 Documentation/gitweb.conf.txt\n create mode 100644 Documentation/gitweb.txt\n\n-- \n1.7.6\n"},{"id":"177242","messageId":"1318098723-12813-2-git-send-email-jnareb@gmail.com","threadId":"28634","inReplyTo":"1318098723-12813-1-git-send-email-jnareb@gmail.com","subject":"[PATCHv5/RFC 1/6] Documentation: Preparation for gitweb manpages","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-10-08T18:31:58Z","receivedAt":"2011-10-08T18:31:58Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Gitweb documentation currently consists of gitweb/README, gitweb/INSTALL\nand comments in gitweb source code. This is harder to find, use and\nbrowse than manpages (\"man gitweb\" or \"git help gitweb\") and HTML\ndocumentation (\"git help --web gitweb\").\n\nThe goal of the next two commits is to move documentation out of\ngitweb/README to gitweb.txt and gitweb.conf.txt manpages, reducing its\nsize 10x from around 500 to around 50 lines (two pages), and to move\ninformation not related directly to building and installing gitweb out\nof gitweb/INSTALL.\n\nThe idea is to have the gitweb manpage sources reside in AsciiDoc\nformat in the Documentation/ directory, like for gitk and git-gui.\nThis means that building git documentation (with \"make doc\") would\nalso build gitweb manpages.\n\nAn alternate solution would be to have gitweb documentation in the\ngitweb/ directory, perhaps in POD format (see perlpod(1)).\n\n\nThis patch adds infrastructure for easy generation of only\ngitweb-related manpages. It adds a currently empty 'gitweb-doc'\ntarget to Documentation/Makefile, and a 'doc' proxy target to\ngitweb/Makefile.\n\nThis way to build only gitweb documentation in both 'man' and 'html'\nformats one can use\n\n make -C gitweb doc\n\nor\n\n cd gitweb; make doc\n\nThis somewhat follows the idea of 'full-svn-test' and 'gitweb-test' in\nt/Makefile. Note also that with alternate solution, where source of\ngitweb manpages would reside in the gitweb/ directory, \"make doc\"\nwould invoke \"make -C gitweb doc\" to generate formatted docs.\n\nThe gitweb.conf(5) and gitweb(1) manpages will be added in subsequent\ncommits.\n\n[Commit message improved with help of Jonathan Nieder]\n\nSigned-off-by: Jakub Narebski \n---\nThis commit is not strictly necessary: it only adds \"doc\" target to\ngitweb/Makefile, and \"gitweb-doc\" target to Documentation/Makefile;\nneither is run when e.g. generating RPM.\n\nThey are here because they would be here if documentation source was\nkept along with gitweb script in the 'gitweb/' subdirectory, and to\nmake it easier and faster to test the changes.\n\n Documentation/Makefile | 3 +++\n gitweb/Makefile | 7 ++++++-\n 2 files changed, 9 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 6346a75..44be67b 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -170,6 +170,9 @@ info: git.info gitman.info\n \n pdf: user-manual.pdf\n \n+GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7))\n+gitweb-doc: $(GITWEB_DOC)\n+\n install: install-man\n \n install-man: man\ndiff --git a/gitweb/Makefile b/gitweb/Makefile\nindex 1c85b5f..3014d80 100644\n--- a/gitweb/Makefile\n+++ b/gitweb/Makefile\n@@ -174,6 +174,11 @@ test-installed:\n \tGITWEB_TEST_INSTALLED='$(DESTDIR_SQ)$(gitwebdir_SQ)' \\\n \t\t$(MAKE) -C ../t gitweb-test\n \n+### Documentation\n+\n+doc:\n+\t$(MAKE) -C ../Documentation gitweb-doc\n+\n ### Installation rules\n \n install: all\n@@ -187,5 +192,5 @@ install: all\n clean:\n \t$(RM) gitweb.cgi static/gitweb.min.js static/gitweb.min.css GITWEB-BUILD-OPTIONS\n \n-.PHONY: all clean install test test-installed .FORCE-GIT-VERSION-FILE FORCE\n+.PHONY: all clean install test test-installed doc .FORCE-GIT-VERSION-FILE FORCE\n \n-- \n1.7.6\n"},{"id":"177243","messageId":"1318098723-12813-3-git-send-email-jnareb@gmail.com","threadId":"28634","inReplyTo":"1318098723-12813-1-git-send-email-jnareb@gmail.com","subject":"[PATCHv5 2/6] gitweb: Add manpage for gitweb configuration files","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-10-08T18:31:59Z","receivedAt":"2011-10-08T18:31:59Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"From: Drew Northup \n\nMuch of what is in gitweb.conf.txt has been pulled directly from the\nREADME file of gitweb. The manpage was supplemented with description\nof missing gitweb config variables, and with description of gitweb's\n%features.\n\nThere remains a bit of redundancy, which should be reduced if\npossible... but I think some of duplication of information is\ninevitable.\n\n[jn: Improved, extended, removed duplicate info from README]\n\nSigned-off-by: Drew Northup \nSigned-off-by: Jakub Narebski \nHelped-by: Jonathan Nieder \n---\nI refer to my reply to Jonathan Nieder in\n\n Re: [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation)\n http://thread.gmane.org/gmane.comp.version-control.git/181605/focus=181896\n\nfor description of changes (and to parent post).\n\nThanks a lot to Jonathan Nieder.\n\n Documentation/Makefile | 2 +-\n Documentation/gitweb.conf.txt | 866 +++++++++++++++++++++++++++++++++++++++++\n gitweb/README | 133 +-------\n 3 files changed, 868 insertions(+), 133 deletions(-)\n create mode 100644 Documentation/gitweb.conf.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 44be67b..6d71943 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -3,7 +3,7 @@ MAN1_TXT= \\\n \t\t$(wildcard git-*.txt)) \\\n \tgitk.txt git.txt\n MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \\\n-\tgitrepository-layout.txt\n+\tgitrepository-layout.txt gitweb.conf.txt\n MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \\\n \tgitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \\\n \tgitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt\ndiff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt\nnew file mode 100644\nindex 0000000..31eb527\n--- /dev/null\n+++ b/Documentation/gitweb.conf.txt\n@@ -0,0 +1,866 @@\n+gitweb.conf(5)\n+==============\n+\n+NAME\n+----\n+gitweb.conf - Gitweb (git web interface) configuration file\n+\n+SYNOPSIS\n+--------\n+/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl\n+\n+DESCRIPTION\n+-----------\n+\n+The gitweb CGI script for viewing Git repositories over the web uses a\n+perl script fragment as its configuration file. You can set variables\n+using \"`our $variable = value`\"; text from a \"#\" character until the\n+end of a line is ignored. See *perlsyn*(1) for details.\n+\n+An example:\n+\n+ # gitweb configuration file for http://git.example.org\n+ #\n+ our $projectroot = \"/srv/git\"; # FHS recommendation\n+ our $site_name = 'Example.org >> Repos';\n+\n+\n+The configuration file is used to override the default settings that\n+were built into gitweb at the time the 'gitweb.cgi' script was generated.\n+\n+While one could just alter the configuration settings in the gitweb\n+CGI itself, those changes would be lost upon upgrade. Configuration\n+settings might also be placed into a file in the same directory as the\n+CGI script with the default name 'gitweb_config.perl' -- allowing\n+one to have multiple gitweb instances with different configurations by\n+the use of symlinks.\n+\n+\n+DISCUSSION\n+----------\n+Gitweb reads configuration data from the following sources in the\n+following order:\n+\n+ * built-in values (some set during build stage),\n+\n+ * common system-wide configuration file (defaults to\n+ '/etc/gitweb-common.conf'),\n+\n+ * either per-instance configuration file (defaults to 'gitweb_config.perl'\n+ in the same directory as the installed gitweb), or if it does not exists\n+ then fallback system-wide configuration file (defaults to '/etc/gitweb.conf').\n+\n+Values obtained in later configuration files override values obtained earlier\n+in the above sequence.\n+\n+Locations of the common system-wide configuration file, the fallback\n+system-wide configuration file and the per-instance configuration file\n+are defined at compile time using build-time Makefile configuration\n+variables, respectively `GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM`\n+and `GITWEB_CONFIG`.\n+\n+You can also override locations of gitweb configuration files during\n+runtime by setting the following environment variables:\n+`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG`\n+to a non-empty value.\n+\n+\n+The syntax of the configuration files is that of Perl, since these files are\n+handled by sourcing them as fragments of Perl code (the language that\n+gitweb itself is written in). Variables are typically set using the\n+`our` qualifier (as in \"`our $variable = ;`\") to avoid syntax\n+errors if a new version of gitweb no longer uses a variable and therefore\n+stops declaring it.\n+\n+You can include other configuration file using read_config_file()\n+subroutine. For example, one might want to put gitweb configuration\n+related to access control for viewing repositories via Gitolite (one\n+of git repository management tools) in a separate file, e.g. in\n+'/etc/gitweb-gitolite.conf'. To include it, put\n+\n+--------------------------------------------------\n+read_config_file(\"/etc/gitweb-gitolite.conf\");\n+--------------------------------------------------\n+\n+somewhere in gitweb configuration file used, e.g. in per-installation\n+gitweb configuration file. Note that read_config_file() checks itself\n+that the file it reads exists, and does nothing if it is not found.\n+It also handles errors in included file.\n+\n+\n+The default configuration with no configuration file at all may work\n+perfectly well for some installations. Still, a configuration file is\n+useful for customizing or tweaking the behavior of gitweb in many ways, and\n+some optional features will not be present unless explicitly enabled using\n+the configurable `%features` variable (see also \"Configuring gitweb\n+features\" section below).\n+\n+\n+CONFIGURATION VARIABLES\n+-----------------------\n+Some configuration variables have their default values (embedded in the CGI\n+script) set during building gitweb -- if that is the case, this fact is put\n+in their description. See gitweb's 'INSTALL' file for instructions on building\n+and installing gitweb.\n+\n+\n+Location of repositories\n+~~~~~~~~~~~~~~~~~~~~~~~~\n+The configuration variables described below control how gitweb finds\n+git repositories, and how repositories are displayed and accessed.\n+\n+$projectroot::\n+\tAbsolute filesystem path which will be prepended to project path;\n+\tthe path to repository is `$projectroot/$project`. Set to\n+\t`$GITWEB_PROJECTROOT` during installation. This variable has to be\n+\tset correctly for gitweb to find repositories.\n++\n+For example, if `$projectroot` is set to \"/srv/git\" by putting the following\n+in gitweb config file:\n++\n+----------------------------------------------------------------------------\n+our $projectroot = \"/srv/git\";\n+----------------------------------------------------------------------------\n++\n+then\n++\n+------------------------------------------------\n+http://git.example.com/gitweb.cgi?p=foo/bar.git\n+------------------------------------------------\n++\n+and its path_info based equivalent\n++\n+------------------------------------------------\n+http://git.example.com/gitweb.cgi/foo/bar.git\n+------------------------------------------------\n++\n+will map to the path '/srv/git/foo/bar.git' on the filesystem.\n+\n+$projects_list::\n+\tName of a plain text file listing projects, or a name of directory\n+\tto be scanned for projects.\n++\n+Project list files should list one project per line, with each line\n+having the following format\n++\n+-----------------------------------------------------------------------------\n+ SP \n+-----------------------------------------------------------------------------\n++\n+The default value of this variable is determined by the `GITWEB_LIST`\n+makefile variable at installation time. If this variable is empty, gitweb\n+will fall back to scanning the `$projectroot` directory for repositories.\n+\n+$project_maxdepth::\n+\tIf `$projects_list` variable is unset, gitweb will recursively\n+\tscan filesystem for git repositories. The `$project_maxdepth`\n+\tis used to limit traversing depth, relative to `$projectroot`\n+\t(starting point); it means that directories which are further\n+\tfrom `$projectroot` than `$project_maxdepth` will be skipped.\n++\n+It is purely performance optimization, originally intended for MacOS X,\n+where recursive directory traversal is slow. Gitweb follows symbolic\n+links, but it detects cycles, ignoring any duplicate files and directories.\n++\n+The default value of this variable is determined by the build-time\n+configuration variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to\n+2007.\n+\n+$export_ok::\n+\tShow repository only if this file exists (in repository). Only\n+\teffective if this variable evaluates to true. Can be set when\n+\tbuilding gitweb by setting `GITWEB_EXPORT_OK`. This path is\n+\trelative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok',\n+\tunless started with `--export-all`. [No default / Not set\n+\t(this feature is turned off)]\n+\n+$export_auth_hook::\n+\tFunction used to determine which repositories should be shown.\n+\tThis subroutine should take one parameter, the full path to\n+\ta project, and if it returns true, that project will be included\n+\tin the projects list and can be accessed through gitweb as long\n+\tas it fulfills the other requirements described by $export_ok,\n+\t$projects_list, and $projects_maxdepth. Example:\n++\n+----------------------------------------------------------------------------\n+our $export_auth_hook = sub { return -e \"$_[0]/git-daemon-export-ok\"; };\n+----------------------------------------------------------------------------\n++\n+though the above might be done by using `$export_ok` instead\n++\n+----------------------------------------------------------------------------\n+our $export_ok = \"git-daemon-export-ok\";\n+----------------------------------------------------------------------------\n++\n+If not set (default), it means that this feature is disabled.\n+\n+$strict_export::\n+\tOnly allow viewing of repositories also shown on the overview page.\n+\tThis for example makes `$gitweb_export_ok` file decide if repository is\n+\tavailable and not only if it is shown. If `$gitweb_list` points to\n+\tfile with list of project, only those repositories listed would be\n+\tavailable for gitweb. Can be set during building gitweb via\n+\t`GITWEB_STRICT_EXPORT`. [No default / Not set (you can access\n+\trepositories hidden from projects list page)]\n+\n+\n+Finding files\n+~~~~~~~~~~~~~\n+The following configuration variables tell gitweb where to find files.\n+The values of these variables are paths on the filesystem.\n+\n+$GIT::\n+\tCore git executable to use. By default set to `$GIT_BINDIR/git`, which\n+\tin turn is by default set to `$(bindir)/git`. If you use git installed\n+\tfrom a binary package, you should usually set this to \"/usr/bin/git\".\n+\tThis can just be \"git\" if your web server has a sensible PATH; from\n+\tsecurity point of view it is better to use absolute path to git binary.\n+\tIf you have multiple git versions installed it can be used to choose\n+\twhich one to use. Must be (correctly) set for gitweb to be able to\n+\twork.\n+\n+$mimetypes_file::\n+\tFile to use for (filename extension based) guessing of MIME types before\n+\ttrying '/etc/mime.types'. *NOTE* that this path, if relative, is taken\n+\tas relative to the current git repository, not to CGI script. If unset,\n+\tonly '/etc/mime.types' is used (if present on filesystem). If no mimetypes\n+\tfile is found, mimetype guessing based on extension of file is disabled.\n+\t[Unset by default]\n+\n+$highlight_bin::\n+\tPath to the highlight executable to use (it must be the one from\n+\thttp://www.andre-simon.de due to assumptions about parameters and output).\n+\tUseful if 'highlight' is not installed on your web server's PATH.\n+\t[Default: 'highlight']\n++\n+*NOTE*: if you want to add support for new file type (supported by\n+\"highlight\" but not used by gitweb), you need to modify `%highlight_ext`\n+or `%highlight_basename`, depending on whether you detect type of file\n+based on extension (for example \"sh\") or on its basename (for example\n+\"Makefile\"). The keys of these hashes are extension and basename,\n+respectively, and value for given key is name of syntax to be passed via\n+`--syntax ` to highlighter.\n++\n+For example if repositories you are hosting use \"phtml\" extension for\n+PHP files, and you want to have correct syntax-highlighting for those\n+files, you can add the following to gitweb configuration:\n++\n+---------------------------------------------------------\n+our %highlight_ext;\n+$highlight_ext{'phtml'} = 'php';\n+---------------------------------------------------------\n+\n+\n+Links and their targets\n+~~~~~~~~~~~~~~~~~~~~~~~\n+The configuration variables described below configure some of gitweb links:\n+their target and their look (text or image), and where to find page\n+prerequisites (stylesheet, favicon, images, scripts). Usually they are left\n+at their default values, with the possible exception of `@stylesheets`\n+variable.\n+\n+@stylesheets::\n+\tList of URIs of stylesheets (relative to the base URI of a page). You\n+\tmight specify more than one stylesheet, for example to use \"gitweb.css\"\n+\tas base with site specific modifications in a separate stylesheet\n+\tto make it easier to upgrade gitweb. For example, you can add\n+\ta `site` stylesheet by putting\n++\n+----------------------------------------------------------------------------\n+push @stylesheets, \"gitweb-site.css\";\n+----------------------------------------------------------------------------\n++\n+in the gitweb config file. Those values that are relative paths are\n+relative to base URI of gitweb.\n++\n+This list should contain the URI of gitweb's standard stylesheet. The default\n+URI of gitweb stylesheet can be set at build time using the `GITWEB_CSS`\n+makefile variable. Its default value is 'static/gitweb.css'\n+(or 'static/gitweb.min.css' if the `CSSMIN` variable is defined,\n+i.e. if CSS minifier is used during build).\n++\n+*Note*: there is also a legacy `$stylesheet` configuration variable, which was\n+used by older gitweb. If `$stylesheet` variable is defined, only CSS stylesheet\n+given by this variable is used by gitweb.\n+\n+$logo::\n+\tPoints to the location where you put 'git-logo.png' on your web\n+\tserver, or to be more the generic URI of logo, 72x27 size). This image\n+\tis displayed in the top right corner of each gitweb page and used as\n+\ta logo for the Atom feed. Relative to the base URI of gitweb (as a path).\n+\tCan be adjusted when building gitweb using `GITWEB_LOGO` variable\n+\t[Default: 'static/git-logo.png']\n+\n+$favicon::\n+\tPoints to the location where you put 'git-favicon.png' on your web\n+\tserver, or to be more the generic URI of favicon, which will be served\n+\tas \"image/png\" type. Web browsers that support favicons (website icons)\n+\tmay display them in the browser's URL bar and next to the site name in\n+\tbookmarks. Relative to the base URI of gitweb. Can be adjusted at\n+\tbuild time using `GITWEB_FAVICON` variable.\n+\t[Default: 'static/git-favicon.png']\n+\n+$javascript::\n+\tPoints to the location where you put 'gitweb.js' on your web server,\n+\tor to be more generic the URI of JavaScript code used by gitweb.\n+\tRelative to the base URI of gitweb. Can be set at build time using\n+\tthe `GITWEB_JS` build-time configuration variable.\n++\n+The default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if\n+the `JSMIN` build variable was defined, i.e. if JavaScript minifier was used\n+at build time. *Note* that this single file is generated from multiple\n+individual JavaScript \"modules\".\n+\n+$home_link::\n+\tTarget of the home link on the top of all pages (the first part of view\n+\t\"breadcrumbs\"). By default it is set to the absolute URI of a current page\n+\t(to the value of `$my_uri` variable, or to \"/\" if `$my_uri` is undefined\n+\tor is an empty string).\n+\n+$home_link_str::\n+\tLabel for the \"home link\" at the top of all pages, leading to `$home_link`\n+\t(usually the main gitweb page, which contains the projects list). It is\n+\tused as the first component of gitweb's \"breadcrumb trail\":\n+\t` / / `. Can be set at build time using\n+\tthe `GITWEB_HOME_LINK_STR` variable. [Default: \"projects\"]\n+\n+$logo_url::\n+$logo_label::\n+\tURI and label (title) for the Git logo link (or your site logo,\n+\tif you chose to use different logo image). By default, these both\n+\trefer to git homepage; in the past, they pointed to git documentation\n+\tat http://www.kernel.org[].\n+\n+\n+Changing gitweb's look\n+~~~~~~~~~~~~~~~~~~~~~~\n+You can adjust how pages generated by gitweb look using the variables described\n+below. You can change the site name, add common headers and footers for all\n+pages, and add a description of this gitweb installation on its main page\n+(which is the projects list page), etc.\n+\n+$site_name::\n+\tName of your site or organization, to appear in page titles. Set it\n+\tto something descriptive for clearer bookmarks etc. If this variable\n+\tis not set or is, then gitweb uses the value of the `SERVER_NAME`\n+\tCGI environment variable, setting site name to \"$SERVER_NAME Git\",\n+\tor \"Untitled Git\" if this variable is not set (e.g. if running gitweb\n+\tas standalone script).\n++\n+Can be set using the `GITWEB_SITENAME` at build time. [No default]\n+\n+$site_header::\n+\tName of a file with HTML to be included at the top of each page.\n+\tRelative to the directory containing the 'gitweb.cgi' script.\n+\tCan be set using `GITWEB_SITE_HEADER` at build time. [No default]\n+\n+$site_footer::\n+\tName of a file with HTML to be included at the bottom of each page.\n+\tRelative to the directory containing the 'gitweb.cgi' script.\n+\tCan be set using `GITWEB_SITE_FOOTER` at build time. [No default]\n+\n+$home_text::\n+\tName of a HTML file which, if it exists, is included on the\n+\tgitweb projects overview page (\"projects_list\" view). Relative to\n+\tthe directory containing the gitweb.cgi script. Default value\n+\tcan be adjusted during build time using `GITWEB_HOMETEXT` variable.\n+\t[Default: 'indextext.html']\n+\n+$projects_list_description_width::\n+\tThe width (in characters) of the \"Description\" column of the projects list.\n+\tLonger descriptions will be truncated (trying to cut at word boundary);\n+\tthe full description is available in the 'title' attribute (usually shown on\n+\tmouseover). The default is 25, which might be too small if you\n+\tuse long project descriptions.\n+\n+$default_projects_order::\n+\tDefault value of ordering of projects on projects list page, which\n+\tmeans the ordering used if you don't explicitly sort projects list\n+\t(if there is no \"o\" CGI query parameter in the URL). Valid values\n+\tare \"none\" (unsorted), \"project\" (projects are by project name,\n+\ti.e. path to repository relative to `$projectroot`), \"descr\"\n+\t(project description), \"owner\", and \"age\" (by date of most current\n+\tcommit).\n++\n+Default value is \"project\". Unknown value means unsorted.\n+\n+\n+Changing gitweb's behavior\n+~~~~~~~~~~~~~~~~~~~~~~~~~~\n+These configuration variables control _internal_ gitweb behavior.\n+\n+$default_blob_plain_mimetype::\n+\tDefault mimetype for the blob_plain (raw) view, if mimetype checking\n+\tdoesn't result in some other type; by default \"text/plain\".\n+\tGitweb guesses mimetype of a file to display based on extension\n+\tof its filename, using `$mimetypes_file` (if set and file exists)\n+\tand '/etc/mime.types' files (see *mime.types*(5) manpage; only\n+\tfilename extension rules are supported by gitweb).\n+\n+$default_text_plain_charset::\n+\tDefault charset for text files. If this is not set, the web server\n+\tconfiguration will be used. Unset by default.\n+\n+$fallback_encoding::\n+\tGitweb assumes this charset when a line contains non-UTF-8 characters.\n+\tThe fallback decoding is used without error checking, so it can be even\n+\t\"utf-8\". The value must be a valid encoding; see the *Encoding::Supported*(3pm)\n+\tman page for a list. The default is \"latin1\", aka. \"iso-8859-1\".\n+\n+@diff_opts::\n+\tRename detection options for git-diff and git-diff-tree. The default is\n+\t(\\'-M'); set it to (\\'-C') or (\\'-C', \\'-C') to also detect copies,\n+\tor set it to () i.e. empty list if you don't want to have renames\n+\tdetection.\n++\n+*Note* that rename and especially copy detection can be quite\n+CPU-intensive. Note also that non git tools can have problems with\n+patches generated with options mentioned above, especially when they\n+involve file copies (\\'-C') or criss-cross renames (\\'-B').\n+\n+\n+Some optional features and policies\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+Most of features are configured via `%feature` hash; however some of extra\n+gitweb features can be turned on and configured using variables described\n+below. This list beside configuration variables that control how gitweb\n+looks does contain variables configuring administrative side of gitweb\n+(e.g. cross-site scripting prevention; admittedly this as side effect\n+affects how \"summary\" pages look like, or load limiting).\n+\n+@git_base_url_list::\n+\tList of git base URLs. These URLs are used to generate URLs\n+\tdescribing from where to fetch a project, which are shown on\n+\tproject summary page. The full fetch URL is \"`$git_base_url/$project`\",\n+\tfor each element of this list. You can set up multiple base URLs\n+\t(for example one for `git://` protocol, and one for `http://`\n+\tprotocol).\n++\n+Note that per repository configuration can be set in '$GIT_DIR/cloneurl'\n+file, or as values of multi-value `gitweb.url` configuration variable in\n+project config. Per-repository configuration takes precedence over value\n+composed from `@git_base_url_list` elements and project name.\n++\n+You can setup one single value (single entry/item in this list) at build\n+time by setting the `GITWEB_BASE_URL` built-time configuration variable.\n+[Default: (), i.e. empty list]\n+\n+$projects_list_group_categories::\n+\tWhether to enables the grouping of projects by category on the project\n+\tlist page. The category of a project is determined by the\n+\t`$GIT_DIR/category` file or the `gitweb.category` variable in each\n+\trepository's configuration. [Disabled by default].\n+\n+$project_list_default_category::\n+\tDefault category for projects for which none is specified. If this is\n+\tset to the empty string, such projects will remain uncategorized and\n+\tlisted at the top, above categorized projects. Used only if project\n+\tcategories are enabled, which means if `$projects_list_group_categories`\n+\tis true. [Default: \"\" (empty string)]\n+\n+$prevent_xss::\n+\tIf true, some gitweb features are disabled to prevent content in\n+\trepositories from launching cross-site scripting (XSS) attacks. Set this\n+\tto true if you don't trust the content of your repositories.\n+\t[Default: false].\n+\n+$maxload::\n+\tUsed to set the maximum load that we will still respond to gitweb queries.\n+\tIf the server load exceeds this value then gitweb will return\n+\t\"503 Service Unavailable\" error. The server load is taken to be 0\n+\tif gitweb cannot determine its value. Currently it works only on Linux,\n+\twhere it uses '/proc/loadavg'; the load there is the number of active\n+\ttasks on the system -- processes that are actually running -- averaged\n+\tover the last minute.\n++\n+Set `$maxload` to undefined value (`undef`) to turn this feature off.\n+[Default: 300]\n+\n+$per_request_config::\n+\tIf this is set to code reference, it will be run once for each request.\n+\tYou can\tset parts of configuration that change per session this way.\n+\tFor example, one might use the following code in a gitweb configuration\n+\tfile\n++\n+--------------------------------------------------------------------------------\n+our $per_request_config = sub {\n+\t$ENV{GL_USER} = $cgi->remote_user || \"gitweb\";\n+};\n+--------------------------------------------------------------------------------\n++\n+If `$per_request_config` is not a code reference, it is interpreted as boolean\n+value. If it is true gitweb will process config files once per request,\n+and if it is false gitweb will process config files only once, each time it\n+is executed. [Default: true]\n++\n+*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default\n+values before every request, so if you want to change them, be sure to set\n+this variable to true or a code reference effecting the desired changes.\n++\n+This variable matters only when using persistent web environments that\n+serve multiple requests using single gitweb instance, like mod_perl,\n+FastCGI or Plackup.\n+\n+\n+Other variables\n+~~~~~~~~~~~~~~~\n+Usually you should not need to change (adjust) any of configuration\n+variables described below; they should be automatically set by gitweb to\n+correct value.\n+\n+\n+$version::\n+\tGitweb version, set automatically when creating gitweb.cgi from\n+\tgitweb.perl. You might want to modify it if you are running modified\n+\tgitweb, for example\n++\n+---------------------------------------------------\n+our $version .= \" with caching\";\n+---------------------------------------------------\n++\n+if you run modified version of gitweb with caching support. This variable\n+is purely informational, used e.g. in the \"generator\" meta header in HTML\n+header.\n+\n+$my_url::\n+$my_uri::\n+\tFull URL and absolute URL of the gitweb script;\n+\tin earlier versions of gitweb you might have need to set those\n+\tvariables, but now there should be no need to do it. See\n+\t`$per_request_config` if you need to set them still.\n+\n+$base_url::\n+\tBase URL for relative URLs in pages generated by gitweb,\n+\t(e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs),\n+\tneeded and used '' only for URLs with nonempty\n+\tPATH_INFO. Usually gitweb sets its value correctly,\n+\tand there is no need to set this variable, e.g. to $my_uri or \"/\".\n+\tSee `$per_request_config` if you need to override it anyway.\n+\n+\n+CONFIGURING GITWEB FEATURES\n+---------------------------\n+Many gitweb features can be enabled (or disabled) and configured using the\n+`%feature` hash. Names of gitweb features are keys of this hash.\n+\n+Each `%feature` hash element is a hash reference and has the following\n+structure:\n+----------------------------------------------------------------------\n+\"\" => {\n+\t\"sub\" => ,\n+\t\"override\" => ,\n+\t\"default\" => [ ... ]\n+},\n+----------------------------------------------------------------------\n+Some features cannot be overridden per project. For those\n+features the structure of appropriate `%feature` hash element has a simpler\n+form:\n+----------------------------------------------------------------------\n+\"\" => {\n+\t\"override\" => 0,\n+\t\"default\" => [ ... ]\n+},\n+----------------------------------------------------------------------\n+As one can see it lacks the \\'sub' element.\n+\n+The meaning of each part of feature configuration is described\n+below:\n+\n+default::\n+\tList (array reference) of feature parameters (if there are any),\n+\tused also to toggle (enable or disable) given feature.\n++\n+Note that it is currently *always* an array reference, even if\n+feature doesn't accept any configuration parameters, and \\'default'\n+is used only to turn it on or off. In such case you turn feature on\n+by setting this element to `[1]`, and torn it off by setting it to\n+`[0]`. See also the passage about the \"blame\" feature in the \"Examples\"\n+section.\n++\n+To disable features that accept parameters (are configurable), you\n+need to set this element to empty list i.e. `[]`.\n+\n+override::\n+\tIf this field has a true value then the given feature is\n+\toverriddable, which means that it can be configured\n+\t(or enabled/disabled) on a per-repository basis.\n++\n+Usually given \"\" is configurable via the `gitweb.`\n+config variable in the per-repository git configuration file.\n++\n+*Note* that no feature is overriddable by default.\n+\n+sub::\n+\tInternal detail of implementation. What is important is that\n+\tif this field is not present then per-repository override for\n+\tgiven feature is not supported.\n++\n+You wouldn't need to ever change it in gitweb config file.\n+\n+\n+Features in `%feature`\n+~~~~~~~~~~~~~~~~~~~~~~\n+The gitweb features that are configurable via `%feature` hash are listed\n+below. This should be a complete list, but ultimately the authoritative\n+and complete list is in gitweb.cgi source code, with features described\n+in the comments.\n+\n+blame::\n+\tEnable the \"blame\" and \"blame_incremental\" blob views, showing for\n+\teach line the last commit that modified it; see linkgit:git-blame[1].\n+\tThis can be very CPU-intensive and is therefore disabled by default.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.blame` configuration variable (boolean).\n+\n+snapshot::\n+\tEnable and configure the \"snapshot\" action, which allows user to\n+\tdownload a compressed archive of any tree or commit, as produced\n+\tby linkgit:git-archive[1] and possibly additionally compressed.\n+\tThis can potentially generate high traffic if you have large project.\n++\n+The value of \\'default' is a list of names of snapshot formats,\n+defined in `%known_snapshot_formats` hash, that you wish to offer.\n+Supported formats include \"tgz\", \"tbz2\", \"txz\" (gzip/bzip2/xz\n+compressed tar archive) and \"zip\"; please consult gitweb sources for\n+a definitive list. By default only \"tgz\" is offered.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.blame` configuration variable, which contains\n+a comma separated list of formats or \"none\" to disable snapshots.\n+Unknown values are ignored.\n+\n+grep::\n+\tEnable grep search, which lists the files in currently selected\n+\ttree (directory) containing the given string; see linkgit:git-grep[1].\n+\tThis can be potentially CPU-intensive, of course. Enabled by default.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.grep` configuration variable (boolean).\n+\n+pickaxe::\n+\tEnable the so called pickaxe search, which will list the commits\n+\tthat introduced or removed a given string in a file. This can be\n+\tpractical and quite faster alternative to \"blame\" action, but it is\n+\tstill potentially CPU-intensive. Enabled by default.\n++\n+The pickaxe search is described in linkgit:git-log[1] (the\n+description of `-S` option, which refers to pickaxe entry in\n+linkgit:gitdiffcore[7] for more details).\n++\n+This feature can be configured on a per-repository basis by setting\n+repository's `gitweb.pickaxe` configuration variable (boolean).\n+\n+show-sizes::\n+\tEnable showing size of blobs (ordinary files) in a \"tree\" view, in a\n+\tseparate column, similar to what `ls -l` does; see description of\n+\t`-l` option in linkgit:git-ls-tree[1] manpage. This costs a bit of\n+\tI/O. Enabled by default.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.showsizes` configuration variable (boolean).\n+\n+patches::\n+\tEnable and configure \"patches\" view, which displays list of commits in email\n+\t(plain text) output format; see also linkgit:git-format-patch[1].\n+\tThe value is the maximum number of patches in a patchset generated\n+\tin \"patches\" view. Set the 'default' field to a list containing single\n+\titem of or to an empty list to disable patch view, or to a list\n+\tcontaining a single negative number to remove any limit.\n+\tDefault value is 16.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.patches` configuration variable (integer).\n+\n+avatar::\n+\tAvatar support. When this feature is enabled, views such as\n+\t\"shortlog\" or \"commit\" will display an avatar associated with\n+\tthe email of each committer and author.\n++\n+Currently available providers are *\"gravatar\"* and *\"picon\"*.\n+Only one provider at a time can be selected ('default' is one element list).\n+If an unknown provider is specified, the feature is disabled.\n+*Note* that some providers might require extra Perl packages to be\n+installed; see 'gitweb/INSTALL' for more details.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.avatar` configuration variable.\n++\n+See also `%avatar_size` with pixel sizes for icons and avatars\n+(\"default\" is used for one-line like \"log\" and \"shortlog\", \"double\"\n+is used for two-line like \"commit\", \"commitdiff\" or \"tag\"). If the\n+default font sizes or lineheights are changed (e.g. via adding extra\n+CSS stylesheet in `@stylesheets`), it may be appropriate to change\n+these values.\n+\n+highlight::\n+\tServer-side syntax highlight support in \"blob\" view. It requires\n+\t`$highlight_bin` program to be available (see the description of\n+\tthis variable in the \"Configuration variables\" section above),\n+\tand therefore is disabled by default.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.highlight` configuration variable (boolean).\n+\n+remote_heads::\n+\tEnable displaying remote heads (remote-tracking branches) in the \"heads\"\n+\tlist. In most cases the list of remote-tracking branches is an\n+\tunnecessary internal private detail, and this feature is therefore\n+\tdisabled by default. linkgit:git-instaweb[1], which is usually used\n+\tto browse local repositories, enables and uses this feature.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.remote_heads` configuration variable (boolean).\n+\n+\n+The remaining features cannot be overridden on a per project basis.\n+\n+search::\n+\tEnable text search, which will list the commits which match author,\n+\tcommitter or commit text to a given string; see the description of\n+\t`--author`, `--committer` and `--grep` options in linkgit:git-log[1]\n+\tmanpage. Enabled by default.\n++\n+Project specific override is not supported.\n+\n+forks::\n+\tIf this feature is enabled, gitweb considers projects in\n+\tsubdirectories of project root (basename) to be forks of existing\n+\tprojects. For each project `$projname.git`, projects in the\n+\t`$projname/` directory and its subdirectories will not be\n+\tshown in the main projects list. Instead, a \\'+' mark is shown\n+\tnext to `$projname`, which links to a \"forks\" view that lists all\n+\tthe forks (all projects in `$projname/` subdirectory). Additionally\n+\ta \"forks\" view for a project is linked from project summary page.\n++\n+If the project list is taken from a file (`$projects_list` points to a\n+file), forks are only recognized if they are listed after the main project\n+in that file.\n++\n+Project specific override is not supported.\n+\n+actions::\n+\tInsert custom links to the action bar of all project pages. This\n+\tallows you to link to third-party scripts integrating into gitweb.\n++\n+The \"default\" value consists of a list of triplets in the form\n+`(\"