| 1 | gitweb(1) |
| 2 | ========= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | gitweb - Git web interface (web frontend to Git repositories) |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | To get started with gitweb, run linkgit:git-instaweb[1] from a Git repository. |
| 11 | This will configure and start your web server, and run a web browser pointing to |
| 12 | gitweb. |
| 13 | |
| 14 | |
| 15 | DESCRIPTION |
| 16 | ----------- |
| 17 | Gitweb provides a web interface to Git repositories. Its features include: |
| 18 | |
| 19 | * Viewing multiple Git repositories with common root. |
| 20 | * Browsing every revision of the repository. |
| 21 | * Viewing the contents of files in the repository at any revision. |
| 22 | * Viewing the revision log of branches, history of files and directories, |
| 23 | seeing what was changed, when, and by whom. |
| 24 | * Viewing the blame/annotation details of any file (if enabled). |
| 25 | * Generating RSS and Atom feeds of commits, for any branch. |
| 26 | The feeds are auto-discoverable in modern web browsers. |
| 27 | * Viewing everything that was changed in a revision, and stepping through |
| 28 | revisions one at a time, viewing the history of the repository. |
| 29 | * Finding commits whose commit messages match a given search term. |
| 30 | |
| 31 | See https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, |
| 32 | browsed using gitweb itself. |
| 33 | |
| 34 | |
| 35 | CONFIGURATION |
| 36 | ------------- |
| 37 | Various aspects of gitweb's behavior can be controlled through the configuration |
| 38 | file `gitweb_config.perl` or `/etc/gitweb.conf`. See the linkgit:gitweb.conf[5] |
| 39 | for details. |
| 40 | |
| 41 | Repositories |
| 42 | ~~~~~~~~~~~~ |
| 43 | Gitweb can show information from one or more Git repositories. These |
| 44 | repositories have to be all on local filesystem, and have to share a common |
| 45 | repository root, i.e. be all under a single parent repository (but see also |
| 46 | the "Advanced web server setup" section, "Webserver configuration with multiple |
| 47 | projects' root" subsection). |
| 48 | |
| 49 | ----------------------------------------------------------------------- |
| 50 | our $projectroot = '/path/to/parent/directory'; |
| 51 | ----------------------------------------------------------------------- |
| 52 | |
| 53 | The default value for `$projectroot` is `/pub/git`. You can change it during |
| 54 | building gitweb via the `GITWEB_PROJECTROOT` build configuration variable. |
| 55 | |
| 56 | By default all Git repositories under `$projectroot` are visible and available |
| 57 | to gitweb. The list of projects is generated by default by scanning the |
| 58 | `$projectroot` directory for Git repositories (for object databases to be |
| 59 | more exact; gitweb is not interested in a working area, and is best suited |
| 60 | to showing "bare" repositories). |
| 61 | |
| 62 | The name of the repository in gitweb is the path to its `$GIT_DIR` (its object |
| 63 | database) relative to `$projectroot`. Therefore the repository $repo can be |
| 64 | found at "$projectroot/$repo". |
| 65 | |
| 66 | |
| 67 | Projects list file format |
| 68 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 69 | Instead of having gitweb find repositories by scanning the filesystem |
| 70 | starting from $projectroot, you can provide a pre-generated list of |
| 71 | visible projects by setting `$projects_list` to point to a plain text |
| 72 | file with a list of projects (with some additional info). |
| 73 | |
| 74 | This file uses the following format: |
| 75 | |
| 76 | * One record (for project / repository) per line; does not support line |
| 77 | continuation (newline escaping). |
| 78 | |
| 79 | * Leading and trailing whitespace are ignored. |
| 80 | |
| 81 | * Whitespace separated fields; any run of whitespace can be used as field |
| 82 | separator (rules for Perl's "`split(" ", $line)`"). |
| 83 | |
| 84 | * Fields use modified URI encoding, defined in RFC 3986, section 2.1 |
| 85 | (Percent-Encoding), or rather "Query string encoding" (see |
| 86 | https://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference |
| 87 | being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be |
| 88 | also percent-encoded). |
| 89 | + |
| 90 | Reserved characters are: "%" (used for encoding), "{plus}" (can be used to |
| 91 | encode SPACE), all whitespace characters as defined in Perl, including SP, |
| 92 | TAB and LF, (used to separate fields in a record). |
| 93 | |
| 94 | * Currently recognized fields are: |
| 95 | <repository path>:: |
| 96 | path to repository GIT_DIR, relative to `$projectroot` |
| 97 | <repository owner>:: |
| 98 | displayed as repository owner, preferably full name, or email, |
| 99 | or both |
| 100 | |
| 101 | You can generate the projects list index file using the project_index action |
| 102 | (the 'TXT' link on projects list page) directly from gitweb; see also |
| 103 | "Generating projects list using gitweb" section below. |
| 104 | |
| 105 | Example contents: |
| 106 | |
| 107 | ----------------------------------------------------------------------- |
| 108 | foo.git Joe+R+Hacker+<joe@example.com> |
| 109 | foo/bar.git O+W+Ner+<owner@example.org> |
| 110 | ----------------------------------------------------------------------- |
| 111 | |
| 112 | |
| 113 | By default this file controls only which projects are *visible* on projects |
| 114 | list page (note that entries that do not point to correctly recognized Git |
| 115 | repositories won't be displayed by gitweb). Even if a project is not |
| 116 | visible on projects list page, you can view it nevertheless by hand-crafting |
| 117 | a gitweb URL. By setting `$strict_export` configuration variable (see |
| 118 | linkgit:gitweb.conf[5]) to true value you can allow viewing only of |
| 119 | repositories also shown on the overview page (i.e. only projects explicitly |
| 120 | listed in projects list file will be accessible). |
| 121 | |
| 122 | |
| 123 | Generating projects list using gitweb |
| 124 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 125 | |
| 126 | We assume that GITWEB_CONFIG has its default Makefile value, namely |
| 127 | 'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file: |
| 128 | |
| 129 | ---------------------------------------------------------------------------- |
| 130 | read_config_file("gitweb_config.perl"); |
| 131 | $projects_list = $projectroot; |
| 132 | ---------------------------------------------------------------------------- |
| 133 | |
| 134 | Then create the following script to get list of project in the format |
| 135 | suitable for GITWEB_LIST build configuration variable (or |
| 136 | `$projects_list` variable in gitweb config): |
| 137 | |
| 138 | ---------------------------------------------------------------------------- |
| 139 | #!/bin/sh |
| 140 | |
| 141 | export GITWEB_CONFIG="gitweb_make_index.perl" |
| 142 | export GATEWAY_INTERFACE="CGI/1.1" |
| 143 | export HTTP_ACCEPT="*/*" |
| 144 | export REQUEST_METHOD="GET" |
| 145 | export QUERY_STRING="a=project_index" |
| 146 | |
| 147 | perl -- /var/www/cgi-bin/gitweb.cgi |
| 148 | ---------------------------------------------------------------------------- |
| 149 | |
| 150 | Run this script and save its output to a file. This file could then be used |
| 151 | as projects list file, which means that you can set `$projects_list` to its |
| 152 | filename. |
| 153 | |
| 154 | |
| 155 | Controlling access to Git repositories |
| 156 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 157 | By default all Git repositories under `$projectroot` are visible and |
| 158 | available to gitweb. You can however configure how gitweb controls access |
| 159 | to repositories. |
| 160 | |
| 161 | * As described in "Projects list file format" section, you can control which |
| 162 | projects are *visible* by selectively including repositories in projects |
| 163 | list file, and setting `$projects_list` gitweb configuration variable to |
| 164 | point to it. With `$strict_export` set, projects list file can be used to |
| 165 | control which repositories are *available* as well. |
| 166 | |
| 167 | * You can configure gitweb to only list and allow viewing of the explicitly |
| 168 | exported repositories, via `$export_ok` variable in gitweb config file; see |
| 169 | linkgit:gitweb.conf[5] manpage. If it evaluates to true, gitweb shows |
| 170 | repositories only if this file named by `$export_ok` exists in its object |
| 171 | database (if directory has the magic file named `$export_ok`). |
| 172 | + |
| 173 | For example linkgit:git-daemon[1] by default (unless `--export-all` option |
| 174 | is used) allows pulling only for those repositories that have |
| 175 | 'git-daemon-export-ok' file. Adding |
| 176 | + |
| 177 | -------------------------------------------------------------------------- |
| 178 | our $export_ok = "git-daemon-export-ok"; |
| 179 | -------------------------------------------------------------------------- |
| 180 | + |
| 181 | makes gitweb show and allow access only to those repositories that can be |
| 182 | fetched from via `git://` protocol. |
| 183 | |
| 184 | * Finally, it is possible to specify an arbitrary perl subroutine that will |
| 185 | be called for each repository to determine if it can be exported. The |
| 186 | subroutine receives an absolute path to the project (repository) as its only |
| 187 | parameter (i.e. "$projectroot/$project"). |
| 188 | + |
| 189 | For example, if you use mod_perl to run the script, and have dumb |
| 190 | HTTP protocol authentication configured for your repositories, you |
| 191 | can use the following hook to allow access only if the user is |
| 192 | authorized to read the files: |
| 193 | + |
| 194 | -------------------------------------------------------------------------- |
| 195 | $export_auth_hook = sub { |
| 196 | use Apache2::SubRequest (); |
| 197 | use Apache2::Const -compile => qw(HTTP_OK); |
| 198 | my $path = "$_[0]/HEAD"; |
| 199 | my $r = Apache2::RequestUtil->request; |
| 200 | my $sub = $r->lookup_file($path); |
| 201 | return $sub->filename eq $path |
| 202 | && $sub->status == Apache2::Const::HTTP_OK; |
| 203 | }; |
| 204 | -------------------------------------------------------------------------- |
| 205 | |
| 206 | |
| 207 | Per-repository gitweb configuration |
| 208 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 209 | You can configure individual repositories shown in gitweb by creating file |
| 210 | in the `GIT_DIR` of Git repository, or by setting some repo configuration |
| 211 | variable (in `GIT_DIR/config`, see linkgit:git-config[1]). |
| 212 | |
| 213 | You can use the following files in repository: |
| 214 | |
| 215 | README.html:: |
| 216 | A html file (HTML fragment) which is included on the gitweb project |
| 217 | "summary" page inside `<div>` block element. You can use it for longer |
| 218 | description of a project, to provide links (for example to project's |
| 219 | homepage), etc. This is recognized only if XSS prevention is off |
| 220 | (`$prevent_xss` is false, see linkgit:gitweb.conf[5]); a way to include |
| 221 | a README safely when XSS prevention is on may be worked out in the |
| 222 | future. |
| 223 | |
| 224 | description (or `gitweb.description`):: |
| 225 | Short (shortened to `$projects_list_description_width` in the projects |
| 226 | list page, which is 25 characters by default; see |
| 227 | linkgit:gitweb.conf[5]) single line description of a project (of a |
| 228 | repository). Plain text file; HTML will be escaped. By default set to |
| 229 | + |
| 230 | ------------------------------------------------------------------------------- |
| 231 | Unnamed repository; edit this file to name it for gitweb. |
| 232 | ------------------------------------------------------------------------------- |
| 233 | + |
| 234 | from the template during repository creation, usually installed in |
| 235 | `/usr/share/git-core/templates/`. You can use the `gitweb.description` repo |
| 236 | configuration variable, but the file takes precedence. |
| 237 | |
| 238 | category (or `gitweb.category`):: |
| 239 | Single line category of a project, used to group projects if |
| 240 | `$projects_list_group_categories` is enabled. By default (file and |
| 241 | configuration variable absent), uncategorized projects are put in the |
| 242 | `$project_list_default_category` category. You can use the |
| 243 | `gitweb.category` repo configuration variable, but the file takes |
| 244 | precedence. |
| 245 | + |
| 246 | The configuration variables `$projects_list_group_categories` and |
| 247 | `$project_list_default_category` are described in linkgit:gitweb.conf[5] |
| 248 | |
| 249 | cloneurl (or multiple-valued `gitweb.url`):: |
| 250 | File with repository URL (used for clone and fetch), one per line. |
| 251 | Displayed in the project summary page. You can use multiple-valued |
| 252 | `gitweb.url` repository configuration variable for that, but the file |
| 253 | takes precedence. |
| 254 | + |
| 255 | This is per-repository enhancement / version of global prefix-based |
| 256 | `@git_base_url_list` gitweb configuration variable (see |
| 257 | linkgit:gitweb.conf[5]). |
| 258 | |
| 259 | gitweb.owner:: |
| 260 | You can use the `gitweb.owner` repository configuration variable to set |
| 261 | repository's owner. It is displayed in the project list and summary |
| 262 | page. |
| 263 | + |
| 264 | If it's not set, filesystem directory's owner is used (via GECOS field, |
| 265 | i.e. real name field from *getpwuid*(3)) if `$projects_list` is unset |
| 266 | (gitweb scans `$projectroot` for repositories); if `$projects_list` |
| 267 | points to file with list of repositories, then project owner defaults to |
| 268 | value from this file for given repository. |
| 269 | |
| 270 | various `gitweb.*` config variables (in config):: |
| 271 | Read description of `%feature` hash for detailed list, and descriptions. |
| 272 | See also "Configuring gitweb features" section in linkgit:gitweb.conf[5] |
| 273 | |
| 274 | |
| 275 | ACTIONS, AND URLS |
| 276 | ----------------- |
| 277 | Gitweb can use path_info (component) based URLs, or it can pass all necessary |
| 278 | information via query parameters. The typical gitweb URLs are broken down in to |
| 279 | five components: |
| 280 | |
| 281 | ----------------------------------------------------------------------- |
| 282 | .../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments> |
| 283 | ----------------------------------------------------------------------- |
| 284 | |
| 285 | repo:: |
| 286 | The repository the action will be performed on. |
| 287 | + |
| 288 | All actions except for those that list all available projects, |
| 289 | in whatever form, require this parameter. |
| 290 | |
| 291 | action:: |
| 292 | The action that will be run. Defaults to 'projects_list' if repo |
| 293 | is not set, and to 'summary' otherwise. |
| 294 | |
| 295 | revision:: |
| 296 | Revision shown. Defaults to HEAD. |
| 297 | |
| 298 | path:: |
| 299 | The path within the <repository> that the action is performed on, |
| 300 | for those actions that require it. |
| 301 | |
| 302 | arguments:: |
| 303 | Any arguments that control the behaviour of the action. |
| 304 | |
| 305 | Some actions require or allow to specify two revisions, and sometimes even two |
| 306 | pathnames. In most general form such path_info (component) based gitweb URL |
| 307 | looks like this: |
| 308 | |
| 309 | ----------------------------------------------------------------------- |
| 310 | .../gitweb.cgi/<repo>/<action>/<revision-from>:/<path-from>..<revision-to>:/<path-to>?<arguments> |
| 311 | ----------------------------------------------------------------------- |
| 312 | |
| 313 | |
| 314 | Each action is implemented as a subroutine, and must be present in %actions |
| 315 | hash. Some actions are disabled by default, and must be turned on via feature |
| 316 | mechanism. For example to enable 'blame' view add the following to gitweb |
| 317 | configuration file: |
| 318 | |
| 319 | ----------------------------------------------------------------------- |
| 320 | $feature{'blame'}{'default'} = [1]; |
| 321 | ----------------------------------------------------------------------- |
| 322 | |
| 323 | |
| 324 | Actions: |
| 325 | ~~~~~~~~ |
| 326 | The standard actions are: |
| 327 | |
| 328 | project_list:: |
| 329 | Lists the available Git repositories. This is the default command if no |
| 330 | repository is specified in the URL. |
| 331 | |
| 332 | summary:: |
| 333 | Displays summary about given repository. This is the default command if |
| 334 | no action is specified in URL, and only repository is specified. |
| 335 | |
| 336 | heads:: |
| 337 | remotes:: |
| 338 | Lists all local or all remote-tracking branches in given repository. |
| 339 | + |
| 340 | The latter is not available by default, unless configured. |
| 341 | |
| 342 | tags:: |
| 343 | List all tags (lightweight and annotated) in given repository. |
| 344 | |
| 345 | blob:: |
| 346 | tree:: |
| 347 | Shows the files and directories in a given repository path, at given |
| 348 | revision. This is default command if no action is specified in the URL, |
| 349 | and path is given. |
| 350 | |
| 351 | blob_plain:: |
| 352 | Returns the raw data for the file in given repository, at given path and |
| 353 | revision. Links to this action are marked 'raw'. |
| 354 | |
| 355 | blobdiff:: |
| 356 | Shows the difference between two revisions of the same file. |
| 357 | |
| 358 | blame:: |
| 359 | blame_incremental:: |
| 360 | Shows the blame (also called annotation) information for a file. On a |
| 361 | per line basis it shows the revision in which that line was last changed |
| 362 | and the user that committed the change. The incremental version (which |
| 363 | if configured is used automatically when JavaScript is enabled) uses |
| 364 | Ajax to incrementally add blame info to the contents of given file. |
| 365 | + |
| 366 | This action is disabled by default for performance reasons. |
| 367 | |
| 368 | commit:: |
| 369 | commitdiff:: |
| 370 | Shows information about a specific commit in a repository. The 'commit' |
| 371 | view shows information about commit in more detail, the 'commitdiff' |
| 372 | action shows changeset for given commit. |
| 373 | |
| 374 | patch:: |
| 375 | Returns the commit in plain text mail format, suitable for applying with |
| 376 | linkgit:git-am[1]. |
| 377 | |
| 378 | tag:: |
| 379 | Display specific annotated tag (tag object). |
| 380 | |
| 381 | log:: |
| 382 | shortlog:: |
| 383 | Shows log information (commit message or just commit subject) for a |
| 384 | given branch (starting from given revision). |
| 385 | + |
| 386 | The 'shortlog' view is more compact; it shows one commit per line. |
| 387 | |
| 388 | history:: |
| 389 | Shows history of the file or directory in a given repository path, |
| 390 | starting from given revision (defaults to HEAD, i.e. default branch). |
| 391 | + |
| 392 | This view is similar to 'shortlog' view. |
| 393 | |
| 394 | rss:: |
| 395 | atom:: |
| 396 | Generates an RSS (or Atom) feed of changes to repository. |
| 397 | |
| 398 | |
| 399 | WEBSERVER CONFIGURATION |
| 400 | ----------------------- |
| 401 | This section explains how to configure some common webservers to run gitweb. In |
| 402 | all cases, `/path/to/gitweb` in the examples is the directory you ran installed |
| 403 | gitweb in, and contains `gitweb_config.perl`. |
| 404 | |
| 405 | If you've configured a web server that isn't listed here for gitweb, please send |
| 406 | in the instructions so they can be included in a future release. |
| 407 | |
| 408 | Apache as CGI |
| 409 | ~~~~~~~~~~~~~ |
| 410 | Apache must be configured to support CGI scripts in the directory in |
| 411 | which gitweb is installed. Let's assume that it is `/var/www/cgi-bin` |
| 412 | directory. |
| 413 | |
| 414 | ----------------------------------------------------------------------- |
| 415 | ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" |
| 416 | |
| 417 | <Directory "/var/www/cgi-bin"> |
| 418 | Options Indexes FollowSymlinks ExecCGI |
| 419 | AllowOverride None |
| 420 | Order allow,deny |
| 421 | Allow from all |
| 422 | </Directory> |
| 423 | ----------------------------------------------------------------------- |
| 424 | |
| 425 | With that configuration the full path to browse repositories would be: |
| 426 | |
| 427 | http://server/cgi-bin/gitweb.cgi |
| 428 | |
| 429 | Apache with mod_perl, via ModPerl::Registry |
| 430 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 431 | You can use mod_perl with gitweb. You must install Apache::Registry |
| 432 | (for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable |
| 433 | this support. |
| 434 | |
| 435 | Assuming that gitweb is installed to `/var/www/perl`, the following |
| 436 | Apache configuration (for mod_perl 2.x) is suitable. |
| 437 | |
| 438 | ----------------------------------------------------------------------- |
| 439 | Alias /perl "/var/www/perl" |
| 440 | |
| 441 | <Directory "/var/www/perl"> |
| 442 | SetHandler perl-script |
| 443 | PerlResponseHandler ModPerl::Registry |
| 444 | PerlOptions +ParseHeaders |
| 445 | Options Indexes FollowSymlinks +ExecCGI |
| 446 | AllowOverride None |
| 447 | Order allow,deny |
| 448 | Allow from all |
| 449 | </Directory> |
| 450 | ----------------------------------------------------------------------- |
| 451 | |
| 452 | With that configuration the full path to browse repositories would be: |
| 453 | |
| 454 | http://server/perl/gitweb.cgi |
| 455 | |
| 456 | Apache with FastCGI |
| 457 | ~~~~~~~~~~~~~~~~~~~ |
| 458 | Gitweb works with Apache and FastCGI. First you need to rename, copy |
| 459 | or symlink gitweb.cgi to gitweb.fcgi. Let's assume that gitweb is |
| 460 | installed in `/usr/share/gitweb` directory. The following Apache |
| 461 | configuration is suitable (UNTESTED!) |
| 462 | |
| 463 | ----------------------------------------------------------------------- |
| 464 | FastCgiServer /usr/share/gitweb/gitweb.cgi |
| 465 | ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi |
| 466 | |
| 467 | Alias /gitweb/static /usr/share/gitweb/static |
| 468 | <Directory /usr/share/gitweb/static> |
| 469 | SetHandler default-handler |
| 470 | </Directory> |
| 471 | ----------------------------------------------------------------------- |
| 472 | |
| 473 | With that configuration the full path to browse repositories would be: |
| 474 | |
| 475 | http://server/gitweb |
| 476 | |
| 477 | |
| 478 | ADVANCED WEB SERVER SETUP |
| 479 | ------------------------- |
| 480 | All of those examples use request rewriting, and need `mod_rewrite` |
| 481 | (or equivalent; examples below are written for Apache). |
| 482 | |
| 483 | Single URL for gitweb and for fetching |
| 484 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 485 | If you want to have one URL for both gitweb and your `http://` |
| 486 | repositories, you can configure Apache like this: |
| 487 | |
| 488 | ----------------------------------------------------------------------- |
| 489 | <VirtualHost *:80> |
| 490 | ServerName git.example.org |
| 491 | DocumentRoot /pub/git |
| 492 | SetEnv GITWEB_CONFIG /etc/gitweb.conf |
| 493 | |
| 494 | # turning on mod rewrite |
| 495 | RewriteEngine on |
| 496 | |
| 497 | # make the front page an internal rewrite to the gitweb script |
| 498 | RewriteRule ^/$ /cgi-bin/gitweb.cgi |
| 499 | |
| 500 | # make access for "dumb clients" work |
| 501 | RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ |
| 502 | /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] |
| 503 | </VirtualHost> |
| 504 | ----------------------------------------------------------------------- |
| 505 | |
| 506 | The above configuration expects your public repositories to live under |
| 507 | `/pub/git` and will serve them as `http://git.domain.org/dir-under-pub-git`, |
| 508 | both as clonable Git URL and as browsable gitweb interface. If you then |
| 509 | start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all` |
| 510 | then you can even use the `git://` URL with exactly the same path. |
| 511 | |
| 512 | Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the |
| 513 | named file (i.e. in this example `/etc/gitweb.conf`) as a configuration for |
| 514 | gitweb. You don't really need it in above example; it is required only if |
| 515 | your configuration file is in different place than built-in (during |
| 516 | compiling gitweb) 'gitweb_config.perl' or `/etc/gitweb.conf`. See |
| 517 | linkgit:gitweb.conf[5] for details, especially information about precedence |
| 518 | rules. |
| 519 | |
| 520 | If you use the rewrite rules from the example you *might* also need |
| 521 | something like the following in your gitweb configuration file |
| 522 | (`/etc/gitweb.conf` following example): |
| 523 | |
| 524 | ---------------------------------------------------------------------------- |
| 525 | @stylesheets = ("/some/absolute/path/gitweb.css"); |
| 526 | $my_uri = "/"; |
| 527 | $home_link = "/"; |
| 528 | $per_request_config = 1; |
| 529 | ---------------------------------------------------------------------------- |
| 530 | |
| 531 | Nowadays though gitweb should create HTML base tag when needed (to set base |
| 532 | URI for relative links), so it should work automatically. |
| 533 | |
| 534 | |
| 535 | Webserver configuration with multiple projects' root |
| 536 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 537 | If you want to use gitweb with several project roots you can edit your |
| 538 | Apache virtual host and gitweb configuration files in the following way. |
| 539 | |
| 540 | The virtual host configuration (in Apache configuration file) should look |
| 541 | like this: |
| 542 | |
| 543 | -------------------------------------------------------------------------- |
| 544 | <VirtualHost *:80> |
| 545 | ServerName git.example.org |
| 546 | DocumentRoot /pub/git |
| 547 | SetEnv GITWEB_CONFIG /etc/gitweb.conf |
| 548 | |
| 549 | # turning on mod rewrite |
| 550 | RewriteEngine on |
| 551 | |
| 552 | # make the front page an internal rewrite to the gitweb script |
| 553 | RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT] |
| 554 | |
| 555 | # look for a public_git directory in unix users' home |
| 556 | # http://git.example.org/~<user>/ |
| 557 | RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ |
| 558 | [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] |
| 559 | |
| 560 | # http://git.example.org/+<user>/ |
| 561 | #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ |
| 562 | [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] |
| 563 | |
| 564 | # http://git.example.org/user/<user>/ |
| 565 | #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ |
| 566 | [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] |
| 567 | |
| 568 | # defined list of project roots |
| 569 | RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ |
| 570 | [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT] |
| 571 | RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ |
| 572 | [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT] |
| 573 | |
| 574 | # make access for "dumb clients" work |
| 575 | RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ |
| 576 | /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] |
| 577 | </VirtualHost> |
| 578 | -------------------------------------------------------------------------- |
| 579 | |
| 580 | Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT` |
| 581 | environment variable from a web server, so you need to put the following |
| 582 | line in gitweb configuration file (`/etc/gitweb.conf` in above example): |
| 583 | |
| 584 | -------------------------------------------------------------------------- |
| 585 | $projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git"; |
| 586 | -------------------------------------------------------------------------- |
| 587 | |
| 588 | *Note* that this requires to be set for each request, so either |
| 589 | `$per_request_config` must be false, or the above must be put in code |
| 590 | referenced by `$per_request_config`; |
| 591 | |
| 592 | These configurations enable two things. First, each unix user (`<user>`) of |
| 593 | the server will be able to browse through gitweb Git repositories found in |
| 594 | `~/public_git/` with the following url: |
| 595 | |
| 596 | http://git.example.org/~<user>/ |
| 597 | |
| 598 | If you do not want this feature on your server just remove the second |
| 599 | rewrite rule. |
| 600 | |
| 601 | If you already use `mod_userdir` in your virtual host or you don't want to |
| 602 | use the \'~' as first character, just comment or remove the second rewrite |
| 603 | rule, and uncomment one of the following according to what you want. |
| 604 | |
| 605 | Second, repositories found in `/pub/scm/` and `/var/git/` will be accessible |
| 606 | through `http://git.example.org/scm/` and `http://git.example.org/var/`. |
| 607 | You can add as many project roots as you want by adding rewrite rules like |
| 608 | the third and the fourth. |
| 609 | |
| 610 | |
| 611 | PATH_INFO usage |
| 612 | ~~~~~~~~~~~~~~~ |
| 613 | If you enable PATH_INFO usage in gitweb by putting |
| 614 | |
| 615 | ---------------------------------------------------------------------------- |
| 616 | $feature{'pathinfo'}{'default'} = [1]; |
| 617 | ---------------------------------------------------------------------------- |
| 618 | |
| 619 | in your gitweb configuration file, it is possible to set up your server so |
| 620 | that it consumes and produces URLs in the form |
| 621 | |
| 622 | http://git.example.com/project.git/shortlog/sometag |
| 623 | |
| 624 | i.e. without 'gitweb.cgi' part, by using a configuration such as the |
| 625 | following. This configuration assumes that `/var/www/gitweb` is the |
| 626 | DocumentRoot of your webserver, contains the gitweb.cgi script and |
| 627 | complementary static files (stylesheet, favicon, JavaScript): |
| 628 | |
| 629 | ---------------------------------------------------------------------------- |
| 630 | <VirtualHost *:80> |
| 631 | ServerAlias git.example.com |
| 632 | |
| 633 | DocumentRoot /var/www/gitweb |
| 634 | |
| 635 | <Directory /var/www/gitweb> |
| 636 | Options ExecCGI |
| 637 | AddHandler cgi-script cgi |
| 638 | |
| 639 | DirectoryIndex gitweb.cgi |
| 640 | |
| 641 | RewriteEngine On |
| 642 | RewriteCond %{REQUEST_FILENAME} !-f |
| 643 | RewriteCond %{REQUEST_FILENAME} !-d |
| 644 | RewriteRule ^.* /gitweb.cgi/$0 [L,PT] |
| 645 | </Directory> |
| 646 | </VirtualHost> |
| 647 | ---------------------------------------------------------------------------- |
| 648 | |
| 649 | The rewrite rule guarantees that existing static files will be properly |
| 650 | served, whereas any other URL will be passed to gitweb as PATH_INFO |
| 651 | parameter. |
| 652 | |
| 653 | *Notice* that in this case you don't need special settings for |
| 654 | `@stylesheets`, `$my_uri` and `$home_link`, but you lose "dumb client" |
| 655 | access to your project .git dirs (described in "Single URL for gitweb and |
| 656 | for fetching" section). A possible workaround for the latter is the |
| 657 | following: in your project root dir (e.g. `/pub/git`) have the projects |
| 658 | named *without* a .git extension (e.g. `/pub/git/project` instead of |
| 659 | `/pub/git/project.git`) and configure Apache as follows: |
| 660 | |
| 661 | ---------------------------------------------------------------------------- |
| 662 | <VirtualHost *:80> |
| 663 | ServerAlias git.example.com |
| 664 | |
| 665 | DocumentRoot /var/www/gitweb |
| 666 | |
| 667 | AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3 |
| 668 | <Directory /var/www/gitweb> |
| 669 | Options ExecCGI |
| 670 | AddHandler cgi-script cgi |
| 671 | |
| 672 | DirectoryIndex gitweb.cgi |
| 673 | |
| 674 | RewriteEngine On |
| 675 | RewriteCond %{REQUEST_FILENAME} !-f |
| 676 | RewriteCond %{REQUEST_FILENAME} !-d |
| 677 | RewriteRule ^.* /gitweb.cgi/$0 [L,PT] |
| 678 | </Directory> |
| 679 | </VirtualHost> |
| 680 | ---------------------------------------------------------------------------- |
| 681 | |
| 682 | The additional AliasMatch makes it so that |
| 683 | |
| 684 | http://git.example.com/project.git |
| 685 | |
| 686 | will give raw access to the project's Git dir (so that the project can be |
| 687 | cloned), while |
| 688 | |
| 689 | http://git.example.com/project |
| 690 | |
| 691 | will provide human-friendly gitweb access. |
| 692 | |
| 693 | This solution is not 100% bulletproof, in the sense that if some project has |
| 694 | a named ref (branch, tag) starting with `git/`, then paths such as |
| 695 | |
| 696 | http://git.example.com/project/command/abranch..git/abranch |
| 697 | |
| 698 | will fail with a 404 error. |
| 699 | |
| 700 | |
| 701 | BUGS |
| 702 | ---- |
| 703 | Please report any bugs or feature requests to git@vger.kernel.org, |
| 704 | putting "gitweb" in the subject of email. |
| 705 | |
| 706 | SEE ALSO |
| 707 | -------- |
| 708 | linkgit:gitweb.conf[5], linkgit:git-instaweb[1] |
| 709 | |
| 710 | `gitweb/README`, `gitweb/INSTALL` |
| 711 | |
| 712 | GIT |
| 713 | --- |
| 714 | Part of the linkgit:git[1] suite |