gitweb/README

   1 GIT web Interface
   2 =================
   3
   4 The one working on:
   5   http://git.kernel.org/
   6
   7 From the git version 1.4.0 gitweb is bundled with git.
   8
   9
  10 Runtime gitweb configuration
  11 ----------------------------
  12
  13 Gitweb obtains configuration data from the following sources in the
  14 following order:
  15
  16 1. built-in values (some set during build stage),
  17 2. common system-wide configuration file (`GITWEB_CONFIG_COMMON`,
  18    defaults to '/etc/gitweb-common.conf'),
  19 3. 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
  24 Values obtained in later configuration files override values obtained earlier
  25 in above sequence.
  26
  27 You can read defaults in system-wide GITWEB_CONFIG_SYSTEM from GITWEB_CONFIG
  28 by adding
  29
  30   read_config_file($GITWEB_CONFIG_SYSTEM);
  31
  32 at very beginning of per-instance GITWEB_CONFIG file.  In this case
  33 settings in said per-instance file will override settings from
  34 system-wide configuration file.  Note that read_config_file checks
  35 itself that the $GITWEB_CONFIG_SYSTEM file exists.
  36
  37 The most notable thing that is not configurable at compile time are the
  38 optional features, stored in the '%features' variable.
  39
  40 Ultimate description on how to reconfigure the default features setting
  41 in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found
  42 as comments inside 'gitweb.cgi'.
  43
  44 See also gitweb.conf(5) manpage.
  45
  46
  47 Projects list file format
  48 ~~~~~~~~~~~~~~~~~~~~~~~~~
  49
  50 Instead of having gitweb find repositories by scanning filesystem starting
  51 from $projectroot (or $projects_list, if it points to directory), you can
  52 provide list of projects by setting $projects_list to a text file with list
  53 of projects (and some additional info).  This file uses the following
  54 format:
  55
  56 One record (for project / repository) per line, whitespace separated fields;
  57 does not support (at least for now) lines continuation (newline escaping).
  58 Leading and trailing whitespace are ignored, any run of whitespace can be
  59 used as field separator (rules for Perl's "split(' ', $line)").  Keyed by
  60 the first field, which is project name, i.e. path to repository GIT_DIR
  61 relative to $projectroot.  Fields use modified URI encoding, defined in
  62 RFC 3986, section 2.1 (Percent-Encoding), or rather "Query string encoding"
  63 (see http://en.wikipedia.org/wiki/Query_string#URL_encoding), the difference
  64 being that SP (' ') can be encoded as '+' (and therefore '+' has to be also
  65 percent-encoded).  Reserved characters are: '%' (used for encoding), '+'
  66 (can be used to encode SPACE), all whitespace characters as defined in Perl,
  67 including SP, TAB and LF, (used to separate fields in a record).
  68
  69 Currently list of fields is
  70  * <repository path>  - path to repository GIT_DIR, relative to $projectroot
  71  * <repository owner> - displayed as repository owner, preferably full name,
  72                         or email, or both
  73
  74 You can additionally use $projects_list file to limit which repositories
  75 are visible, and together with $strict_export to limit access to
  76 repositories (see "Gitweb repositories" section in gitweb/INSTALL).
  77
  78
  79 Per-repository gitweb configuration
  80 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  81
  82 You can also configure individual repositories shown in gitweb by creating
  83 file in the GIT_DIR of git repository, or by setting some repo configuration
  84 variable (in GIT_DIR/config).
  85
  86 You can use the following files in repository:
  87  * README.html
  88    A .html file (HTML fragment) which is included on the gitweb project
  89    summary page inside <div> block element. You can use it for longer
  90    description of a project, to provide links (for example to project's
  91    homepage), etc. This is recognized only if XSS prevention is off
  92    ($prevent_xss is false); a way to include a readme safely when XSS
  93    prevention is on may be worked out in the future.
  94  * description (or gitweb.description)
  95    Short (shortened by default to 25 characters in the projects list page)
  96    single line description of a project (of a repository). Plain text file;
  97    HTML will be escaped. By default set to
  98      Unnamed repository; edit this file to name it for gitweb.
  99    from the template during repository creation. You can use the
 100    gitweb.description repo configuration variable, but the file takes
 101    precedence.
 102  * category (or gitweb.category)
 103    Singe line category of a project, used to group projects if
 104    $projects_list_group_categories is enabled. By default (file and
 105    configuration variable absent), uncategorized projects are put in
 106    the $project_list_default_category category. You can use the
 107    gitweb.category repo configuration variable, but the file takes
 108    precedence.
 109  * cloneurl (or multiple-valued gitweb.url)
 110    File with repository URL (used for clone and fetch), one per line.
 111    Displayed in the project summary page. You can use multiple-valued
 112    gitweb.url repository configuration variable for that, but the file
 113    takes precedence.
 114  * gitweb.owner
 115    You can use the gitweb.owner repository configuration variable to set
 116    repository's owner. It is displayed in the project list and summary
 117    page. If it's not set, filesystem directory's owner is used
 118    (via GECOS field / real name field from getpwiud(3)).
 119  * various gitweb.* config variables (in config)
 120    Read description of %feature hash for detailed list, and some
 121    descriptions.
 122
 123
 124 Webserver configuration
 125 -----------------------
 126
 127 If you want to have one URL for both gitweb and your http://
 128 repositories, you can configure apache like this:
 129
 130 <VirtualHost *:80>
 131     ServerName          git.example.org
 132     DocumentRoot        /pub/git
 133     SetEnv                      GITWEB_CONFIG   /etc/gitweb.conf
 134
 135     # turning on mod rewrite
 136     RewriteEngine on
 137
 138     # make the front page an internal rewrite to the gitweb script
 139     RewriteRule ^/$  /cgi-bin/gitweb.cgi
 140
 141     # make access for "dumb clients" work
 142     RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]
 143 </VirtualHost>
 144
 145 The above configuration expects your public repositories to live under
 146 /pub/git and will serve them as http://git.domain.org/dir-under-pub-git,
 147 both as cloneable GIT URL and as browseable gitweb interface.
 148 If you then start your git-daemon with --base-path=/pub/git --export-all
 149 then you can even use the git:// URL with exactly the same path.
 150
 151 Setting the environment variable GITWEB_CONFIG will tell gitweb to use
 152 the named file (i.e. in this example /etc/gitweb.conf) as a
 153 configuration for gitweb.  Perl variables defined in here will
 154 override the defaults given at the head of the gitweb.perl (or
 155 gitweb.cgi).  Look at the comments in that file for information on
 156 which variables and what they mean.
 157
 158 If you use the rewrite rules from the example you'll likely also need
 159 something like the following in your gitweb.conf (or gitweb_config.perl) file:
 160
 161   @stylesheets = ("/some/absolute/path/gitweb.css");
 162   $my_uri = "/";
 163   $home_link = "/";
 164
 165
 166 Webserver configuration with multiple projects' root
 167 ----------------------------------------------------
 168
 169 If you want to use gitweb with several project roots you can edit your apache
 170 virtual host and gitweb.conf configuration files like this :
 171
 172 virtual host configuration :
 173
 174 <VirtualHost *:80>
 175     ServerName                  git.example.org
 176     DocumentRoot                /pub/git
 177     SetEnv                              GITWEB_CONFIG   /etc/gitweb.conf
 178
 179     # turning on mod rewrite
 180     RewriteEngine on
 181
 182     # make the front page an internal rewrite to the gitweb script
 183     RewriteRule ^/$             /cgi-bin/gitweb.cgi [QSA,L,PT]
 184
 185     # look for a public_git folder in unix users' home
 186     # http://git.example.org/~<user>/
 187     RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$   /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
 188
 189     # http://git.example.org/+<user>/
 190     #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$  /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
 191
 192     # http://git.example.org/user/<user>/
 193     #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
 194
 195     # defined list of project roots
 196     RewriteRule ^/scm(/|/gitweb.cgi)?$          /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
 197     RewriteRule ^/var(/|/gitweb.cgi)?$          /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
 198
 199     # make access for "dumb clients" work
 200     RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]
 201 </VirtualHost>
 202
 203 gitweb.conf configuration :
 204
 205 $projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
 206
 207 These configurations enable two things. First, each unix user (<user>) of the
 208 server will be able to browse through gitweb git repositories found in
 209 ~/public_git/ with the following url : http://git.example.org/~<user>/
 210
 211 If you do not want this feature on your server just remove the second rewrite rule.
 212
 213 If you already use mod_userdir in your virtual host or you don't want to use
 214 the '~' as first character just comment or remove the second rewrite rule and
 215 uncomment one of the following according to what you want.
 216
 217 Second, repositories found in /pub/scm/ and /var/git/ will be accesible
 218 through http://git.example.org/scm/ and http://git.example.org/var/.
 219 You can add as many project roots as you want by adding rewrite rules like the
 220 third and the fourth.
 221
 222
 223 PATH_INFO usage
 224 -----------------------
 225 If you enable PATH_INFO usage in gitweb by putting
 226
 227    $feature{'pathinfo'}{'default'} = [1];
 228
 229 in your gitweb.conf, it is possible to set up your server so that it
 230 consumes and produces URLs in the form
 231
 232 http://git.example.com/project.git/shortlog/sometag
 233
 234 by using a configuration such as the following, that assumes that
 235 /var/www/gitweb is the DocumentRoot of your webserver, and that it
 236 contains the gitweb.cgi script and complementary static files
 237 (stylesheet, favicon):
 238
 239 <VirtualHost *:80>
 240         ServerAlias git.example.com
 241
 242         DocumentRoot /var/www/gitweb
 243
 244         <Directory /var/www/gitweb>
 245                 Options ExecCGI
 246                 AddHandler cgi-script cgi
 247
 248                 DirectoryIndex gitweb.cgi
 249
 250                 RewriteEngine On
 251                 RewriteCond %{REQUEST_FILENAME} !-f
 252                 RewriteCond %{REQUEST_FILENAME} !-d
 253                 RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
 254         </Directory>
 255 </VirtualHost>
 256
 257 The rewrite rule guarantees that existing static files will be properly
 258 served, whereas any other URL will be passed to gitweb as PATH_INFO
 259 parameter.
 260
 261 Notice that in this case you don't need special settings for
 262 @stylesheets, $my_uri and $home_link, but you lose "dumb client" access
 263 to your project .git dirs. A possible workaround for the latter is the
 264 following: in your project root dir (e.g. /pub/git) have the projects
 265 named without a .git extension (e.g. /pub/git/project instead of
 266 /pub/git/project.git) and configure Apache as follows:
 267
 268 <VirtualHost *:80>
 269         ServerAlias git.example.com
 270
 271         DocumentRoot /var/www/gitweb
 272
 273         AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
 274         <Directory /var/www/gitweb>
 275                 Options ExecCGI
 276                 AddHandler cgi-script cgi
 277
 278                 DirectoryIndex gitweb.cgi
 279
 280                 RewriteEngine On
 281                 RewriteCond %{REQUEST_FILENAME} !-f
 282                 RewriteCond %{REQUEST_FILENAME} !-d
 283                 RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
 284         </Directory>
 285 </VirtualHost>
 286
 287 The additional AliasMatch makes it so that
 288
 289 http://git.example.com/project.git
 290
 291 will give raw access to the project's git dir (so that the project can
 292 be cloned), while
 293
 294 http://git.example.com/project
 295
 296 will provide human-friendly gitweb access.
 297
 298 This solution is not 100% bulletproof, in the sense that if some project
 299 has a named ref (branch, tag) starting with 'git/', then paths such as
 300
 301 http://git.example.com/project/command/abranch..git/abranch
 302
 303 will fail with a 404 error.
 304
 305
 306
 307 Originally written by:
 308   Kay Sievers <kay.sievers@vrfy.org>
 309
 310 Any comment/question/concern to:
 311   Git mailing list <git@vger.kernel.org>