\fR
block element\&. You can use it for longer description of a project, to provide links (for example to project\(cqs homepage), etc\&. This is recognized only if XSS prevention is off (\fB$prevent_xss\fR
is false, see
\fBgitweb.conf\fR(5)); a way to include a README safely when XSS prevention is on may be worked out in the future\&.
.RE
.PP
description (or \fBgitweb\&.description\fR)
.RS 4
Short (shortened to
\fB$projects_list_description_width\fR
in the projects list page, which is 25 characters by default; see
\fBgitweb.conf\fR(5)) single line description of a project (of a repository)\&. Plain text file; HTML will be escaped\&. By default set to
.sp
.if n \{\
.RS 4
.\}
.nf
Unnamed repository; edit this file to name it for gitweb\&.
.fi
.if n \{\
.RE
.\}
.sp
from the template during repository creation, usually installed in
\fB/usr/share/git\-core/templates/\fR\&. You can use the
\fBgitweb\&.description\fR
repo configuration variable, but the file takes precedence\&.
.RE
.PP
category (or \fBgitweb\&.category\fR)
.RS 4
Single line category of a project, used to group projects if
\fB$projects_list_group_categories\fR
is enabled\&. By default (file and configuration variable absent), uncategorized projects are put in the
\fB$project_list_default_category\fR
category\&. You can use the
\fBgitweb\&.category\fR
repo configuration variable, but the file takes precedence\&.
.sp
The configuration variables
\fB$projects_list_group_categories\fR
and
\fB$project_list_default_category\fR
are described in
\fBgitweb.conf\fR(5)
.RE
.PP
cloneurl (or multiple\-valued \fBgitweb\&.url\fR)
.RS 4
File with repository URL (used for clone and fetch), one per line\&. Displayed in the project summary page\&. You can use multiple\-valued
\fBgitweb\&.url\fR
repository configuration variable for that, but the file takes precedence\&.
.sp
This is per\-repository enhancement / version of global prefix\-based
\fB@git_base_url_list\fR
gitweb configuration variable (see
\fBgitweb.conf\fR(5))\&.
.RE
.PP
gitweb\&.owner
.RS 4
You can use the
\fBgitweb\&.owner\fR
repository configuration variable to set repository\(cqs owner\&. It is displayed in the project list and summary page\&.
.sp
If it\(cqs not set, filesystem directory\(cqs owner is used (via GECOS field, i\&.e\&. real name field from
\fBgetpwuid\fR(3)) if
\fB$projects_list\fR
is unset (gitweb scans
\fB$projectroot\fR
for repositories); if
\fB$projects_list\fR
points to file with list of repositories, then project owner defaults to value from this file for given repository\&.
.RE
.PP
various \fBgitweb\&.\fR* config variables (in config)
.RS 4
Read description of %feature hash for detailed list, and descriptions\&. See also "Configuring gitweb features" section in
\fBgitweb.conf\fR(5)
.RE
.SH "ACTIONS, AND URLS"
.sp
Gitweb can use path_info (component) based URLs, or it can pass all necessary information via query parameters\&. The typical gitweb URLs are broken down in to five components:
.sp
.if n \{\
.RS 4
.\}
.nf
\&.\&.\&./gitweb\&.cgi/
//:/?
.fi
.if n \{\
.RE
.\}
.sp
.PP
repo
.RS 4
The repository the action will be performed on\&.
.sp
All actions except for those that list all available projects, in whatever form, require this parameter\&.
.RE
.PP
action
.RS 4
The action that will be run\&. Defaults to
\fIprojects_list\fR
if repo is not set, and to
\fIsummary\fR
otherwise\&.
.RE
.PP
revision
.RS 4
Revision shown\&. Defaults to HEAD\&.
.RE
.PP
path
.RS 4
The path within the that the action is performed on, for those actions that require it\&.
.RE
.PP
arguments
.RS 4
Any arguments that control the behaviour of the action\&.
.RE
.sp
Some actions require or allow to specify two revisions, and sometimes even two pathnames\&. In most general form such path_info (component) based gitweb URL looks like this:
.sp
.if n \{\
.RS 4
.\}
.nf
\&.\&.\&./gitweb\&.cgi///:/\&.\&.:/?
.fi
.if n \{\
.RE
.\}
.sp
.sp
Each action is implemented as a subroutine, and must be present in %actions hash\&. Some actions are disabled by default, and must be turned on via feature mechanism\&. For example to enable \fIblame\fR view add the following to gitweb configuration file:
.sp
.if n \{\
.RS 4
.\}
.nf
$feature{\*(Aqblame\*(Aq}{\*(Aqdefault\*(Aq} = [1];
.fi
.if n \{\
.RE
.\}
.sp
.SS "Actions:"
.sp
The standard actions are:
.PP
project_list
.RS 4
Lists the available Git repositories\&. This is the default command if no repository is specified in the URL\&.
.RE
.PP
summary
.RS 4
Displays summary about given repository\&. This is the default command if no action is specified in URL, and only repository is specified\&.
.RE
.PP
heads, remotes
.RS 4
Lists all local or all remote\-tracking branches in given repository\&.
.sp
The latter is not available by default, unless configured\&.
.RE
.PP
tags
.RS 4
List all tags (lightweight and annotated) in given repository\&.
.RE
.PP
blob, tree
.RS 4
Shows the files and directories in a given repository path, at given revision\&. This is default command if no action is specified in the URL, and path is given\&.
.RE
.PP
blob_plain
.RS 4
Returns the raw data for the file in given repository, at given path and revision\&. Links to this action are marked
\fIraw\fR\&.
.RE
.PP
blobdiff
.RS 4
Shows the difference between two revisions of the same file\&.
.RE
.PP
blame, blame_incremental
.RS 4
Shows the blame (also called annotation) information for a file\&. On a per line basis it shows the revision in which that line was last changed and the user that committed the change\&. The incremental version (which if configured is used automatically when JavaScript is enabled) uses Ajax to incrementally add blame info to the contents of given file\&.
.sp
This action is disabled by default for performance reasons\&.
.RE
.PP
commit, commitdiff
.RS 4
Shows information about a specific commit in a repository\&. The
\fIcommit\fR
view shows information about commit in more detail, the
\fIcommitdiff\fR
action shows changeset for given commit\&.
.RE
.PP
patch
.RS 4
Returns the commit in plain text mail format, suitable for applying with
\fBgit-am\fR(1)\&.
.RE
.PP
tag
.RS 4
Display specific annotated tag (tag object)\&.
.RE
.PP
log, shortlog
.RS 4
Shows log information (commit message or just commit subject) for a given branch (starting from given revision)\&.
.sp
The
\fIshortlog\fR
view is more compact; it shows one commit per line\&.
.RE
.PP
history
.RS 4
Shows history of the file or directory in a given repository path, starting from given revision (defaults to HEAD, i\&.e\&. default branch)\&.
.sp
This view is similar to
\fIshortlog\fR
view\&.
.RE
.PP
rss, atom
.RS 4
Generates an RSS (or Atom) feed of changes to repository\&.
.RE
.SH "WEBSERVER CONFIGURATION"
.sp
This section explains how to configure some common webservers to run gitweb\&. In all cases, \fB/path/to/gitweb\fR in the examples is the directory you ran installed gitweb in, and contains \fBgitweb_config\&.perl\fR\&.
.sp
If you\(cqve configured a web server that isn\(cqt listed here for gitweb, please send in the instructions so they can be included in a future release\&.
.SS "Apache as CGI"
.sp
Apache must be configured to support CGI scripts in the directory in which gitweb is installed\&. Let\(cqs assume that it is \fB/var/www/cgi\-bin\fR directory\&.
.sp
.if n \{\
.RS 4
.\}
.nf
ScriptAlias /cgi\-bin/ "/var/www/cgi\-bin/"
Options Indexes FollowSymlinks ExecCGI
AllowOverride None
Order allow,deny
Allow from all
.fi
.if n \{\
.RE
.\}
.sp
.sp
With that configuration the full path to browse repositories would be:
.sp
.if n \{\
.RS 4
.\}
.nf
http://server/cgi\-bin/gitweb\&.cgi
.fi
.if n \{\
.RE
.\}
.SS "Apache with mod_perl, via ModPerl::Registry"
.sp
You can use mod_perl with gitweb\&. You must install Apache::Registry (for mod_perl 1\&.x) or ModPerl::Registry (for mod_perl 2\&.x) to enable this support\&.
.sp
Assuming that gitweb is installed to \fB/var/www/perl\fR, the following Apache configuration (for mod_perl 2\&.x) is suitable\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Alias /perl "/var/www/perl"
SetHandler perl\-script
PerlResponseHandler ModPerl::Registry
PerlOptions +ParseHeaders
Options Indexes FollowSymlinks +ExecCGI
AllowOverride None
Order allow,deny
Allow from all
.fi
.if n \{\
.RE
.\}
.sp
.sp
With that configuration the full path to browse repositories would be:
.sp
.if n \{\
.RS 4
.\}
.nf
http://server/perl/gitweb\&.cgi
.fi
.if n \{\
.RE
.\}
.SS "Apache with FastCGI"
.sp
Gitweb works with Apache and FastCGI\&. First you need to rename, copy or symlink gitweb\&.cgi to gitweb\&.fcgi\&. Let\(cqs assume that gitweb is installed in \fB/usr/share/gitweb\fR directory\&. The following Apache configuration is suitable (UNTESTED!)
.sp
.if n \{\
.RS 4
.\}
.nf
FastCgiServer /usr/share/gitweb/gitweb\&.cgi
ScriptAlias /gitweb /usr/share/gitweb/gitweb\&.cgi
Alias /gitweb/static /usr/share/gitweb/static
SetHandler default\-handler
.fi
.if n \{\
.RE
.\}
.sp
.sp
With that configuration the full path to browse repositories would be:
.sp
.if n \{\
.RS 4
.\}
.nf
http://server/gitweb
.fi
.if n \{\
.RE
.\}
.SH "ADVANCED WEB SERVER SETUP"
.sp
All of those examples use request rewriting, and need \fBmod_rewrite\fR (or equivalent; examples below are written for Apache)\&.
.SS "Single URL for gitweb and for fetching"
.sp
If you want to have one URL for both gitweb and your \fBhttp://\fR repositories, you can configure Apache like this:
.sp
.if n \{\
.RS 4
.\}
.nf
ServerName git\&.example\&.org
DocumentRoot /pub/git
SetEnv GITWEB_CONFIG /etc/gitweb\&.conf
# turning on mod rewrite
RewriteEngine on
# make the front page an internal rewrite to the gitweb script
RewriteRule ^/$ /cgi\-bin/gitweb\&.cgi
# make access for "dumb clients" work
RewriteRule ^/(\&.*\e\&.git/(?!/?(HEAD|info|objects|refs))\&.*)?$ \e
/cgi\-bin/gitweb\&.cgi%{REQUEST_URI} [L,PT]
.fi
.if n \{\
.RE
.\}
.sp
.sp
The above configuration expects your public repositories to live under \fB/pub/git\fR and will serve them as \fBhttp://git\&.domain\&.org/dir\-under\-pub\-git\fR, both as clonable Git URL and as browsable gitweb interface\&. If you then start your \fBgit-daemon\fR(1) with \fB\-\-base\-path=/pub/git\fR \fB\-\-export\-all\fR then you can even use the \fBgit://\fR URL with exactly the same path\&.
.sp
Setting the environment variable \fBGITWEB_CONFIG\fR will tell gitweb to use the named file (i\&.e\&. in this example \fB/etc/gitweb\&.conf\fR) as a configuration for gitweb\&. You don\(cqt really need it in above example; it is required only if your configuration file is in different place than built\-in (during compiling gitweb) \fIgitweb_config\&.perl\fR or \fB/etc/gitweb\&.conf\fR\&. See \fBgitweb.conf\fR(5) for details, especially information about precedence rules\&.
.sp
If you use the rewrite rules from the example you \fBmight\fR also need something like the following in your gitweb configuration file (\fB/etc/gitweb\&.conf\fR following example):
.sp
.if n \{\
.RS 4
.\}
.nf
@stylesheets = ("/some/absolute/path/gitweb\&.css");
$my_uri = "/";
$home_link = "/";
$per_request_config = 1;
.fi
.if n \{\
.RE
.\}
.sp
.sp
Nowadays though gitweb should create HTML base tag when needed (to set base URI for relative links), so it should work automatically\&.
.SS "Webserver configuration with multiple projects\*(Aq root"
.sp
If you want to use gitweb with several project roots you can edit your Apache virtual host and gitweb configuration files in the following way\&.
.sp
The virtual host configuration (in Apache configuration file) should look like this:
.sp
.if n \{\
.RS 4
.\}
.nf
ServerName git\&.example\&.org
DocumentRoot /pub/git
SetEnv GITWEB_CONFIG /etc/gitweb\&.conf
# turning on mod rewrite
RewriteEngine on
# make the front page an internal rewrite to the gitweb script
RewriteRule ^/$ /cgi\-bin/gitweb\&.cgi [QSA,L,PT]
# look for a public_git directory in unix users\*(Aq home
# http://git\&.example\&.org/~/
RewriteRule ^/\e~([^\e/]+)(/|/gitweb\&.cgi)?$ /cgi\-bin/gitweb\&.cgi \e
[QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
# http://git\&.example\&.org/+/
#RewriteRule ^/\e+([^\e/]+)(/|/gitweb\&.cgi)?$ /cgi\-bin/gitweb\&.cgi \e
[QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
# http://git\&.example\&.org/user//
#RewriteRule ^/user/([^\e/]+)/(gitweb\&.cgi)?$ /cgi\-bin/gitweb\&.cgi \e
[QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
# defined list of project roots
RewriteRule ^/scm(/|/gitweb\&.cgi)?$ /cgi\-bin/gitweb\&.cgi \e
[QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
RewriteRule ^/var(/|/gitweb\&.cgi)?$ /cgi\-bin/gitweb\&.cgi \e
[QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
# make access for "dumb clients" work
RewriteRule ^/(\&.*\e\&.git/(?!/?(HEAD|info|objects|refs))\&.*)?$ \e
/cgi\-bin/gitweb\&.cgi%{REQUEST_URI} [L,PT]
.fi
.if n \{\
.RE
.\}
.sp
.sp
Here actual project root is passed to gitweb via \fBGITWEB_PROJECT_ROOT\fR environment variable from a web server, so you need to put the following line in gitweb configuration file (\fB/etc/gitweb\&.conf\fR in above example):
.sp
.if n \{\
.RS 4
.\}
.nf
$projectroot = $ENV{\*(AqGITWEB_PROJECTROOT\*(Aq} || "/pub/git";
.fi
.if n \{\
.RE
.\}
.sp
.sp
\fBNote\fR that this requires to be set for each request, so either \fB$per_request_config\fR must be false, or the above must be put in code referenced by \fB$per_request_config\fR;
.sp
These configurations enable two things\&. First, each unix user (\fI\fR) of the server will be able to browse through gitweb Git repositories found in \fB~/public_git/\fR with the following url:
.sp
.if n \{\
.RS 4
.\}
.nf
http://git\&.example\&.org/~/
.fi
.if n \{\
.RE
.\}
.sp
If you do not want this feature on your server just remove the second rewrite rule\&.
.sp
If you already use \(oqmod_userdir` in your virtual host or you don\(cqt want to use the \*(Aq~\(cq as first character, just comment or remove the second rewrite rule, and uncomment one of the following according to what you want\&.
.sp
Second, repositories found in \fB/pub/scm/\fR and \fB/var/git/\fR will be accessible through \fBhttp://git\&.example\&.org/scm/\fR and \fBhttp://git\&.example\&.org/var/\fR\&. You can add as many project roots as you want by adding rewrite rules like the third and the fourth\&.
.SS "PATH_INFO usage"
.sp
If you enable PATH_INFO usage in gitweb by putting
.sp
.if n \{\
.RS 4
.\}
.nf
$feature{\*(Aqpathinfo\*(Aq}{\*(Aqdefault\*(Aq} = [1];
.fi
.if n \{\
.RE
.\}
.sp
.sp
in your gitweb configuration file, it is possible to set up your server so that it consumes and produces URLs in the form
.sp
.if n \{\
.RS 4
.\}
.nf
http://git\&.example\&.com/project\&.git/shortlog/sometag
.fi
.if n \{\
.RE
.\}
.sp
i\&.e\&. without \fIgitweb\&.cgi\fR part, by using a configuration such as the following\&. This configuration assumes that \fB/var/www/gitweb\fR is the DocumentRoot of your webserver, contains the gitweb\&.cgi script and complementary static files (stylesheet, favicon, JavaScript):
.sp
.if n \{\
.RS 4
.\}
.nf
ServerAlias git\&.example\&.com
DocumentRoot /var/www/gitweb
Options ExecCGI
AddHandler cgi\-script cgi
DirectoryIndex gitweb\&.cgi
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !\-f
RewriteCond %{REQUEST_FILENAME} !\-d
RewriteRule ^\&.* /gitweb\&.cgi/$0 [L,PT]
.fi
.if n \{\
.RE
.\}
.sp
.sp
The rewrite rule guarantees that existing static files will be properly served, whereas any other URL will be passed to gitweb as PATH_INFO parameter\&.
.sp
\fBNotice\fR that in this case you don\(cqt need special settings for \fB@stylesheets\fR, \fB$my_uri\fR and \fB$home_link\fR, but you lose "dumb client" access to your project \&.git dirs (described in "Single URL for gitweb and for fetching" section)\&. A possible workaround for the latter is the following: in your project root dir (e\&.g\&. \fB/pub/git\fR) have the projects named \fBwithout\fR a \&.git extension (e\&.g\&. \fB/pub/git/project\fR instead of \fB/pub/git/project\&.git\fR) and configure Apache as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
ServerAlias git\&.example\&.com
DocumentRoot /var/www/gitweb
AliasMatch ^(/\&.*?)(\e\&.git)(/\&.*)?$ /pub/git$1$3
Options ExecCGI
AddHandler cgi\-script cgi
DirectoryIndex gitweb\&.cgi
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !\-f
RewriteCond %{REQUEST_FILENAME} !\-d
RewriteRule ^\&.* /gitweb\&.cgi/$0 [L,PT]
.fi
.if n \{\
.RE
.\}
.sp
.sp
The additional AliasMatch makes it so that
.sp
.if n \{\
.RS 4
.\}
.nf
http://git\&.example\&.com/project\&.git
.fi
.if n \{\
.RE
.\}
.sp
will give raw access to the project\(cqs Git dir (so that the project can be cloned), while
.sp
.if n \{\
.RS 4
.\}
.nf
http://git\&.example\&.com/project
.fi
.if n \{\
.RE
.\}
.sp
will provide human\-friendly gitweb access\&.
.sp
This solution is not 100% bulletproof, in the sense that if some project has a named ref (branch, tag) starting with \fBgit/\fR, then paths such as
.sp
.if n \{\
.RS 4
.\}
.nf
http://git\&.example\&.com/project/command/abranch\&.\&.git/abranch
.fi
.if n \{\
.RE
.\}
.sp
will fail with a 404 error\&.
.SH "BUGS"
.sp
Please report any bugs or feature requests to \m[blue]\fBgit@vger\&.kernel\&.org\fR\m[]\&\s-2\u[1]\d\s+2, putting "gitweb" in the subject of email\&.
.SH "SEE ALSO"
.sp
\fBgitweb.conf\fR(5), \fBgit-instaweb\fR(1)
.sp
\fBgitweb/README\fR, \fBgitweb/INSTALL\fR
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite
.SH "NOTES"
.IP " 1." 4
git@vger.kernel.org
.RS 4
\%mailto:git@vger.kernel.org
.RE