gitweb / READMEon commit Sync with 1.7.6.2 (48f36dc)
   1GIT web Interface
   2=================
   3
   4The one working on:
   5  http://git.kernel.org/
   6
   7From the git version 1.4.0 gitweb is bundled with git.
   8
   9
  10Runtime gitweb configuration
  11----------------------------
  12
  13Gitweb obtains configuration data from the following sources in the
  14following order:
  15
  161. built-in values (some set during build stage),
  172. common system-wide configuration file (`GITWEB_CONFIG_COMMON`,
  18   defaults to '/etc/gitweb-common.conf'),
  193. either per-instance configuration file (`GITWEB_CONFIG`, defaults to
  20   'gitweb_config.perl' in the same directory as the installed gitweb),
  21   or if it does not exists then system-wide configuration file
  22   (`GITWEB_CONFIG_SYSTEM`, defaults to '/etc/gitweb.conf').
  23
  24Values obtained in later configuration files override values obtained earlier
  25in above sequence.
  26
  27You can read defaults in system-wide GITWEB_CONFIG_SYSTEM from GITWEB_CONFIG
  28by adding
  29
  30  read_config_file($GITWEB_CONFIG_SYSTEM);
  31
  32at very beginning of per-instance GITWEB_CONFIG file.  In this case
  33settings in said per-instance file will override settings from
  34system-wide configuration file.  Note that read_config_file checks
  35itself that the $GITWEB_CONFIG_SYSTEM file exists.
  36
  37The most notable thing that is not configurable at compile time are the
  38optional features, stored in the '%features' variable.
  39
  40Ultimate description on how to reconfigure the default features setting
  41in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found
  42as comments inside 'gitweb.cgi'.
  43
  44See also the "Gitweb config file" (with an example of config file), and
  45the "Gitweb repositories" sections in INSTALL file for gitweb.
  46
  47
  48The gitweb config file is a fragment of perl code. You can set variables
  49using "our $variable = value"; text from "#" character until the end
  50of a line is ignored. See perlsyn(1) man page for details.
  51
  52Below is the list of variables which you might want to set in gitweb config.
  53See the top of 'gitweb.cgi' for the full list of variables and their
  54descriptions.
  55
  56Gitweb config file variables
  57~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  58
  59You can set, among others, the following variables in gitweb config files
  60(with the exception of $projectroot and $projects_list this list does
  61not include variables usually directly set during build):
  62 * $GIT
  63   Core git executable to use.  By default set to "$GIT_BINDIR/git", which
  64   in turn is by default set to "$(bindir)/git".  If you use git from binary
  65   package, set this to "/usr/bin/git".  This can just be "git" if your
  66   webserver has a sensible PATH.  If you have multiple git versions
  67   installed it can be used to choose which one to use.
  68 * $version
  69   Gitweb version, set automatically when creating gitweb.cgi from
  70   gitweb.perl. You might want to modify it if you are running modified
  71   gitweb.
  72 * $projectroot
  73   Absolute filesystem path which will be prepended to project path;
  74   the path to repository is $projectroot/$project.  Set to
  75   $GITWEB_PROJECTROOT during installation.  This variable have to be
  76   set correctly for gitweb to find repositories.
  77 * $projects_list
  78   Source of projects list, either directory to scan, or text file
  79   with list of repositories (in the "<URI-encoded repository path> SP
  80   <URI-encoded repository owner>" line format; actually there can be
  81   any sequence of whitespace in place of space (SP)).  Set to
  82   $GITWEB_LIST during installation.  If empty, $projectroot is used
  83   to scan for repositories.
  84 * $my_url, $my_uri
  85   Full URL and absolute URL of gitweb script;
  86   in earlier versions of gitweb you might have need to set those
  87   variables, now there should be no need to do it.  See
  88   $per_request_config if you need to set them still.
  89 * $base_url
  90   Base URL for relative URLs in pages generated by gitweb,
  91   (e.g. $logo, $favicon, @stylesheets if they are relative URLs),
  92   needed and used only for URLs with nonempty PATH_INFO via
  93   <base href="$base_url">.  Usually gitweb sets its value correctly,
  94   and there is no need to set this variable, e.g. to $my_uri or "/".
  95   See $per_request_config if you need to set it anyway.
  96 * $home_link
  97   Target of the home link on top of all pages (the first part of view
  98   "breadcrumbs").  By default set to absolute URI of a page ($my_uri).
  99 * @stylesheets
 100   List of URIs of stylesheets (relative to base URI of a page). You
 101   might specify more than one stylesheet, for example use gitweb.css
 102   as base, with site specific modifications in separate stylesheet
 103   to make it easier to upgrade gitweb. You can add 'site' stylesheet
 104   for example by using
 105      push @stylesheets, "gitweb-site.css";
 106   in the gitweb config file.
 107 * $logo_url, $logo_label
 108   URI and label (title) of GIT logo link (or your site logo, if you choose
 109   to use different logo image). By default they point to git homepage;
 110   in the past they pointed to git documentation at www.kernel.org.
 111 * $projects_list_description_width
 112   The width (in characters) of the projects list "Description" column.
 113   Longer descriptions will be cut (trying to cut at word boundary);
 114   full description is available as 'title' attribute (usually shown on
 115   mouseover).  By default set to 25, which might be too small if you
 116   use long project descriptions.
 117 * $projects_list_group_categories
 118   Enables the grouping of projects by category on the project list page.
 119   The category of a project is determined by the $GIT_DIR/category
 120   file or the 'gitweb.category' variable in its repository configuration.
 121   Disabled by default.
 122 * $project_list_default_category
 123   Default category for projects for which none is specified.  If set
 124   to the empty string, such projects will remain uncategorized and
 125   listed at the top, above categorized projects.
 126 * @git_base_url_list
 127   List of git base URLs used for URL to where fetch project from, shown
 128   in project summary page.  Full URL is "$git_base_url/$project".
 129   You can setup multiple base URLs (for example one for  git:// protocol
 130   access, and one for http:// "dumb" protocol access).  Note that per
 131   repository configuration in 'cloneurl' file, or as values of gitweb.url
 132   project config.
 133 * $default_blob_plain_mimetype
 134   Default mimetype for blob_plain (raw) view, if mimetype checking
 135   doesn't result in some other type; by default 'text/plain'.
 136 * $default_text_plain_charset
 137   Default charset for text files. If not set, web server configuration
 138   would be used.
 139 * $mimetypes_file
 140   File to use for (filename extension based) guessing of MIME types before
 141   trying /etc/mime.types. Path, if relative, is taken currently as
 142   relative to the current git repository.
 143 * $fallback_encoding
 144   Gitweb assumes this charset if line contains non-UTF-8 characters.
 145   Fallback decoding is used without error checking, so it can be even
 146   'utf-8'. Value must be valid encoding; see Encoding::Supported(3pm) man
 147   page for a list.   By default 'latin1', aka. 'iso-8859-1'.
 148 * @diff_opts
 149   Rename detection options for git-diff and git-diff-tree. By default
 150   ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or
 151   set it to () if you don't want to have renames detection.
 152 * $prevent_xss
 153   If true, some gitweb features are disabled to prevent content in
 154   repositories from launching cross-site scripting (XSS) attacks.  Set this
 155   to true if you don't trust the content of your repositories. The default
 156   is false.
 157 * $maxload
 158   Used to set the maximum load that we will still respond to gitweb queries.
 159   If server load exceed this value then return "503 Service Unavailable" error.
 160   Server load is taken to be 0 if gitweb cannot determine its value.  Set it to
 161   undefined value to turn it off.  The default is 300.
 162 * $highlight_bin
 163   Path to the highlight executable to use (must be the one from
 164   http://www.andre-simon.de due to assumptions about parameters and output).
 165   Useful if highlight is not installed on your webserver's PATH.
 166   [Default: highlight]
 167 * $per_request_config
 168   If set to code reference, it would be run once per each request.  You can
 169   set parts of configuration that change per session, e.g. by setting it to
 170     sub { $ENV{GL_USER} = $cgi->remote_user || "gitweb"; }
 171   Otherwise it is treated as boolean value: if true gitweb would process
 172   config file once per request, if false it would process config file only
 173   once.  Note: $my_url, $my_uri, and $base_url are overwritten with
 174   their default values before every request, so if you want to change
 175   them, be sure to set this variable to true or a code reference effecting
 176   the desired changes.  The default is true.
 177
 178Projects list file format
 179~~~~~~~~~~~~~~~~~~~~~~~~~
 180
 181Instead of having gitweb find repositories by scanning filesystem starting
 182from $projectroot (or $projects_list, if it points to directory), you can
 183provide list of projects by setting $projects_list to a text file with list
 184of projects (and some additional info).  This file uses the following
 185format:
 186
 187One record (for project / repository) per line, whitespace separated fields;
 188does not support (at least for now) lines continuation (newline escaping).
 189Leading and trailing whitespace are ignored, any run of whitespace can be
 190used as field separator (rules for Perl's "split(' ', $line)").  Keyed by
 191the first field, which is project name, i.e. path to repository GIT_DIR
 192relative to $projectroot.  Fields use modified URI encoding, defined in
 193RFC 3986, section 2.1 (Percent-Encoding), or rather "Query string encoding"
 194(see http://en.wikipedia.org/wiki/Query_string#URL_encoding), the difference
 195being that SP (' ') can be encoded as '+' (and therefore '+' has to be also
 196percent-encoded).  Reserved characters are: '%' (used for encoding), '+'
 197(can be used to encode SPACE), all whitespace characters as defined in Perl,
 198including SP, TAB and LF, (used to separate fields in a record).
 199
 200Currently list of fields is
 201 * <repository path>  - path to repository GIT_DIR, relative to $projectroot
 202 * <repository owner> - displayed as repository owner, preferably full name,
 203                        or email, or both
 204
 205You can additionally use $projects_list file to limit which repositories
 206are visible, and together with $strict_export to limit access to
 207repositories (see "Gitweb repositories" section in gitweb/INSTALL).
 208
 209
 210Per-repository gitweb configuration
 211~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 212
 213You can also configure individual repositories shown in gitweb by creating
 214file in the GIT_DIR of git repository, or by setting some repo configuration
 215variable (in GIT_DIR/config).
 216
 217You can use the following files in repository:
 218 * README.html
 219   A .html file (HTML fragment) which is included on the gitweb project
 220   summary page inside <div> block element. You can use it for longer
 221   description of a project, to provide links (for example to project's
 222   homepage), etc. This is recognized only if XSS prevention is off
 223   ($prevent_xss is false); a way to include a readme safely when XSS
 224   prevention is on may be worked out in the future.
 225 * description (or gitweb.description)
 226   Short (shortened by default to 25 characters in the projects list page)
 227   single line description of a project (of a repository). Plain text file;
 228   HTML will be escaped. By default set to
 229     Unnamed repository; edit this file to name it for gitweb.
 230   from the template during repository creation. You can use the
 231   gitweb.description repo configuration variable, but the file takes
 232   precedence.
 233 * category (or gitweb.category)
 234   Singe line category of a project, used to group projects if
 235   $projects_list_group_categories is enabled. By default (file and
 236   configuration variable absent), uncategorized projects are put in
 237   the $project_list_default_category category. You can use the
 238   gitweb.category repo configuration variable, but the file takes
 239   precedence.
 240 * cloneurl (or multiple-valued gitweb.url)
 241   File with repository URL (used for clone and fetch), one per line.
 242   Displayed in the project summary page. You can use multiple-valued
 243   gitweb.url repository configuration variable for that, but the file
 244   takes precedence.
 245 * gitweb.owner
 246   You can use the gitweb.owner repository configuration variable to set
 247   repository's owner. It is displayed in the project list and summary
 248   page. If it's not set, filesystem directory's owner is used
 249   (via GECOS field / real name field from getpwiud(3)).
 250 * various gitweb.* config variables (in config)
 251   Read description of %feature hash for detailed list, and some
 252   descriptions.
 253
 254
 255Webserver configuration
 256-----------------------
 257
 258If you want to have one URL for both gitweb and your http://
 259repositories, you can configure apache like this:
 260
 261<VirtualHost *:80>
 262    ServerName          git.example.org
 263    DocumentRoot        /pub/git
 264    SetEnv                      GITWEB_CONFIG   /etc/gitweb.conf
 265
 266    # turning on mod rewrite
 267    RewriteEngine on
 268
 269    # make the front page an internal rewrite to the gitweb script
 270    RewriteRule ^/$  /cgi-bin/gitweb.cgi
 271
 272    # make access for "dumb clients" work
 273    RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]
 274</VirtualHost>
 275
 276The above configuration expects your public repositories to live under
 277/pub/git and will serve them as http://git.domain.org/dir-under-pub-git,
 278both as cloneable GIT URL and as browseable gitweb interface.
 279If you then start your git-daemon with --base-path=/pub/git --export-all
 280then you can even use the git:// URL with exactly the same path.
 281
 282Setting the environment variable GITWEB_CONFIG will tell gitweb to use
 283the named file (i.e. in this example /etc/gitweb.conf) as a
 284configuration for gitweb.  Perl variables defined in here will
 285override the defaults given at the head of the gitweb.perl (or
 286gitweb.cgi).  Look at the comments in that file for information on
 287which variables and what they mean.
 288
 289If you use the rewrite rules from the example you'll likely also need
 290something like the following in your gitweb.conf (or gitweb_config.perl) file:
 291
 292  @stylesheets = ("/some/absolute/path/gitweb.css");
 293  $my_uri = "/";
 294  $home_link = "/";
 295
 296
 297Webserver configuration with multiple projects' root
 298----------------------------------------------------
 299
 300If you want to use gitweb with several project roots you can edit your apache
 301virtual host and gitweb.conf configuration files like this :
 302
 303virtual host configuration :
 304
 305<VirtualHost *:80>
 306    ServerName                  git.example.org
 307    DocumentRoot                /pub/git
 308    SetEnv                              GITWEB_CONFIG   /etc/gitweb.conf
 309
 310    # turning on mod rewrite
 311    RewriteEngine on
 312
 313    # make the front page an internal rewrite to the gitweb script
 314    RewriteRule ^/$             /cgi-bin/gitweb.cgi [QSA,L,PT]
 315
 316    # look for a public_git folder in unix users' home
 317    # http://git.example.org/~<user>/
 318    RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$   /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
 319
 320    # http://git.example.org/+<user>/
 321    #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$  /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
 322
 323    # http://git.example.org/user/<user>/
 324    #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
 325
 326    # defined list of project roots
 327    RewriteRule ^/scm(/|/gitweb.cgi)?$          /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
 328    RewriteRule ^/var(/|/gitweb.cgi)?$          /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
 329
 330    # make access for "dumb clients" work
 331    RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]
 332</VirtualHost>
 333
 334gitweb.conf configuration :
 335
 336$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
 337
 338These configurations enable two things. First, each unix user (<user>) of the
 339server will be able to browse through gitweb git repositories found in
 340~/public_git/ with the following url : http://git.example.org/~<user>/
 341
 342If you do not want this feature on your server just remove the second rewrite rule.
 343
 344If you already use mod_userdir in your virtual host or you don't want to use
 345the '~' as first character just comment or remove the second rewrite rule and
 346uncomment one of the following according to what you want.
 347
 348Second, repositories found in /pub/scm/ and /var/git/ will be accesible
 349through http://git.example.org/scm/ and http://git.example.org/var/.
 350You can add as many project roots as you want by adding rewrite rules like the
 351third and the fourth.
 352
 353
 354PATH_INFO usage
 355-----------------------
 356If you enable PATH_INFO usage in gitweb by putting
 357
 358   $feature{'pathinfo'}{'default'} = [1];
 359
 360in your gitweb.conf, it is possible to set up your server so that it
 361consumes and produces URLs in the form
 362
 363http://git.example.com/project.git/shortlog/sometag
 364
 365by using a configuration such as the following, that assumes that
 366/var/www/gitweb is the DocumentRoot of your webserver, and that it
 367contains the gitweb.cgi script and complementary static files
 368(stylesheet, favicon):
 369
 370<VirtualHost *:80>
 371        ServerAlias git.example.com
 372
 373        DocumentRoot /var/www/gitweb
 374
 375        <Directory /var/www/gitweb>
 376                Options ExecCGI
 377                AddHandler cgi-script cgi
 378
 379                DirectoryIndex gitweb.cgi
 380
 381                RewriteEngine On
 382                RewriteCond %{REQUEST_FILENAME} !-f
 383                RewriteCond %{REQUEST_FILENAME} !-d
 384                RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
 385        </Directory>
 386</VirtualHost>
 387
 388The rewrite rule guarantees that existing static files will be properly
 389served, whereas any other URL will be passed to gitweb as PATH_INFO
 390parameter.
 391
 392Notice that in this case you don't need special settings for
 393@stylesheets, $my_uri and $home_link, but you lose "dumb client" access
 394to your project .git dirs. A possible workaround for the latter is the
 395following: in your project root dir (e.g. /pub/git) have the projects
 396named without a .git extension (e.g. /pub/git/project instead of
 397/pub/git/project.git) and configure Apache as follows:
 398
 399<VirtualHost *:80>
 400        ServerAlias git.example.com
 401
 402        DocumentRoot /var/www/gitweb
 403
 404        AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
 405        <Directory /var/www/gitweb>
 406                Options ExecCGI
 407                AddHandler cgi-script cgi
 408
 409                DirectoryIndex gitweb.cgi
 410
 411                RewriteEngine On
 412                RewriteCond %{REQUEST_FILENAME} !-f
 413                RewriteCond %{REQUEST_FILENAME} !-d
 414                RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
 415        </Directory>
 416</VirtualHost>
 417
 418The additional AliasMatch makes it so that
 419
 420http://git.example.com/project.git
 421
 422will give raw access to the project's git dir (so that the project can
 423be cloned), while
 424
 425http://git.example.com/project
 426
 427will provide human-friendly gitweb access.
 428
 429This solution is not 100% bulletproof, in the sense that if some project
 430has a named ref (branch, tag) starting with 'git/', then paths such as
 431
 432http://git.example.com/project/command/abranch..git/abranch
 433
 434will fail with a 404 error.
 435
 436
 437
 438Originally written by:
 439  Kay Sievers <kay.sievers@vrfy.org>
 440
 441Any comment/question/concern to:
 442  Git mailing list <git@vger.kernel.org>