From 61fd2552d89a15b005d36bab99e7172e1c85878b Mon Sep 17 00:00:00 2001 From: Jakub Narebski Date: Mon, 3 Dec 2007 00:22:02 +0100 Subject: 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 Signed-off-by: Junio C Hamano --- gitweb/README | 215 +++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file 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": / / . + [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
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 -- cgit v1.2.3