development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-08-28 20:20:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'jn/gitweb-manpages'

Browse source 
* jn/gitweb-manpages:
  gitweb: Add gitweb manpages to 'gitweb' package in git.spec
  Documentation: Add gitweb config variables to git-config(1)
  Documentation: Link to gitweb(1) and gitweb.conf(5) in other manpages
  gitweb: Add gitweb(1) manpage for gitweb itself
  gitweb: Add gitweb.conf(5) manpage for gitweb configuration files
This commit is contained in:
Junio C Hamano 2011-10-18 21:59:11 -07:00
parent 578183bcb0 55752fa861
commit 380f26c29b
9 changed files with 1648 additions and 478 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
Documentation/Makefile
View file

@ -1,9 +1,9 @@
MAN1_TXT= \
$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
$(wildcard git-*.txt)) \
gitk.txt git.txt
gitk.txt gitweb.txt git.txt
MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
gitrepository-layout.txt
gitrepository-layout.txt gitweb.conf.txt
MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt

17
Documentation/config.txt
View file

@ -1071,6 +1071,23 @@ All gitcvs variables except for 'gitcvs.usecrlfattr' and
is one of "ext" and "pserver") to make them apply only for the given
access method.
gitweb.category::
gitweb.description::
gitweb.owner::
gitweb.url::
See linkgit:gitweb[1] for description.
gitweb.avatar::
gitweb.blame::
gitweb.grep::
gitweb.highlight::
gitweb.patches::
gitweb.pickaxe::
gitweb.remote_heads::
gitweb.showsizes::
gitweb.snapshot::
See linkgit:gitweb.conf[5] for description.
grep.lineNumber::
If set to true, enable '-n' option by default.

4
Documentation/git-instaweb.txt
View file

@ -84,6 +84,10 @@ If the configuration variable 'instaweb.browser' is not set,
'web.browser' will be used instead if it is defined. See
linkgit:git-web{litdd}browse[1] for more information about this.
SEE ALSO
--------
linkgit:gitweb[1]
GIT
---
Part of the linkgit:git[1] suite

884
Documentation/gitweb.conf.txt Normal file
View file

@ -0,0 +1,884 @@
gitweb.conf(5)
==============
NAME
----
gitweb.conf - Gitweb (git web interface) configuration file
SYNOPSIS
--------
/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl
DESCRIPTION
-----------
The gitweb CGI script for viewing Git repositories over the web uses a
perl script fragment as its configuration file. You can set variables
using "`our $variable = value`"; text from a "#" character until the
end of a line is ignored. See *perlsyn*(1) for details.
An example:
# gitweb configuration file for http://git.example.org
#
our $projectroot = "/srv/git"; # FHS recommendation
our $site_name = 'Example.org >> Repos';
The configuration file is used to override the default settings that
were built into gitweb at the time the 'gitweb.cgi' script was generated.
While one could just alter the configuration settings in the gitweb
CGI itself, those changes would be lost upon upgrade. Configuration
settings might also be placed into a file in the same directory as the
CGI script with the default name 'gitweb_config.perl' -- allowing
one to have multiple gitweb instances with different configurations by
the use of symlinks.
Note that some configuration can be controlled on per-repository rather than
gitweb-wide basis: see "Per-repository gitweb configuration" subsection on
linkgit:gitweb[1] manpage.
DISCUSSION
----------
Gitweb reads configuration data from the following sources in the
following order:
* built-in values (some set during build stage),
* common system-wide configuration file (defaults to
'/etc/gitweb-common.conf'),
* either per-instance configuration file (defaults to 'gitweb_config.perl'
in the same directory as the installed gitweb), or if it does not exists
then fallback system-wide configuration file (defaults to '/etc/gitweb.conf').
Values obtained in later configuration files override values obtained earlier
in the above sequence.
Locations of the common system-wide configuration file, the fallback
system-wide configuration file and the per-instance configuration file
are defined at compile time using build-time Makefile configuration
variables, respectively `GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM`
and `GITWEB_CONFIG`.
You can also override locations of gitweb configuration files during
runtime by setting the following environment variables:
`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG`
to a non-empty value.
The syntax of the configuration files is that of Perl, since these files are
handled by sourcing them as fragments of Perl code (the language that
gitweb itself is written in). Variables are typically set using the
`our` qualifier (as in "`our $variable = <value>;`") to avoid syntax
errors if a new version of gitweb no longer uses a variable and therefore
stops declaring it.
You can include other configuration file using read_config_file()
subroutine. For example, one might want to put gitweb configuration
related to access control for viewing repositories via Gitolite (one
of git repository management tools) in a separate file, e.g. in
'/etc/gitweb-gitolite.conf'. To include it, put
--------------------------------------------------
read_config_file("/etc/gitweb-gitolite.conf");
--------------------------------------------------
somewhere in gitweb configuration file used, e.g. in per-installation
gitweb configuration file. Note that read_config_file() checks itself
that the file it reads exists, and does nothing if it is not found.
It also handles errors in included file.
The default configuration with no configuration file at all may work
perfectly well for some installations. Still, a configuration file is
useful for customizing or tweaking the behavior of gitweb in many ways, and
some optional features will not be present unless explicitly enabled using
the configurable `%features` variable (see also "Configuring gitweb
features" section below).
CONFIGURATION VARIABLES
-----------------------
Some configuration variables have their default values (embedded in the CGI
script) set during building gitweb -- if that is the case, this fact is put
in their description. See gitweb's 'INSTALL' file for instructions on building
and installing gitweb.
Location of repositories
~~~~~~~~~~~~~~~~~~~~~~~~
The configuration variables described below control how gitweb finds
git repositories, and how repositories are displayed and accessed.
See also "Repositories" and later subsections in linkgit:gitweb[1] manpage.
$projectroot::
Absolute filesystem path which will be prepended to project path;
the path to repository is `$projectroot/$project`. Set to
`$GITWEB_PROJECTROOT` during installation. This variable has to be
set correctly for gitweb to find repositories.
+
For example, if `$projectroot` is set to "/srv/git" by putting the following
in gitweb config file:
+
----------------------------------------------------------------------------
our $projectroot = "/srv/git";
----------------------------------------------------------------------------
+
then
+
------------------------------------------------
http://git.example.com/gitweb.cgi?p=foo/bar.git
------------------------------------------------
+
and its path_info based equivalent
+
------------------------------------------------
http://git.example.com/gitweb.cgi/foo/bar.git
------------------------------------------------
+
will map to the path '/srv/git/foo/bar.git' on the filesystem.
$projects_list::
Name of a plain text file listing projects, or a name of directory
to be scanned for projects.
+
Project list files should list one project per line, with each line
having the following format
+
-----------------------------------------------------------------------------
<URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
-----------------------------------------------------------------------------
+
The default value of this variable is determined by the `GITWEB_LIST`
makefile variable at installation time. If this variable is empty, gitweb
will fall back to scanning the `$projectroot` directory for repositories.
$project_maxdepth::
If `$projects_list` variable is unset, gitweb will recursively
scan filesystem for git repositories. The `$project_maxdepth`
is used to limit traversing depth, relative to `$projectroot`
(starting point); it means that directories which are further
from `$projectroot` than `$project_maxdepth` will be skipped.
+
It is purely performance optimization, originally intended for MacOS X,
where recursive directory traversal is slow. Gitweb follows symbolic
links, but it detects cycles, ignoring any duplicate files and directories.
+
The default value of this variable is determined by the build-time
configuration variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to
2007.
$export_ok::
Show repository only if this file exists (in repository). Only
effective if this variable evaluates to true. Can be set when
building gitweb by setting `GITWEB_EXPORT_OK`. This path is
relative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok',
unless started with `--export-all`. By default this variable is
not set, which means that this feature is turned off.
$export_auth_hook::
Function used to determine which repositories should be shown.
This subroutine should take one parameter, the full path to
a project, and if it returns true, that project will be included
in the projects list and can be accessed through gitweb as long
as it fulfills the other requirements described by $export_ok,
$projects_list, and $projects_maxdepth. Example:
+
----------------------------------------------------------------------------
our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };
----------------------------------------------------------------------------
+
though the above might be done by using `$export_ok` instead
+
----------------------------------------------------------------------------
our $export_ok = "git-daemon-export-ok";
----------------------------------------------------------------------------
+
If not set (default), it means that this feature is disabled.
+
See also more involved example in "Controlling access to git repositories"
subsection on linkgit:gitweb[1] manpage.
$strict_export::
Only allow viewing of repositories also shown on the overview page.
This for example makes `$gitweb_export_ok` file 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. Can be set during building gitweb via
`GITWEB_STRICT_EXPORT`. By default this variable is not set, which
means that you can directly access those repositories that are hidden
from projects list page (e.g. the are not listed in the $projects_list
file).
Finding files
~~~~~~~~~~~~~
The following configuration variables tell gitweb where to find files.
The values of these variables are paths on the filesystem.
$GIT::
Core 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 installed
from a binary package, you should usually set this to "/usr/bin/git".
This can just be "git" if your web server has a sensible PATH; from
security point of view it is better to use absolute path to git binary.
If you have multiple git versions installed it can be used to choose
which one to use. Must be (correctly) set for gitweb to be able to
work.
$mimetypes_file::
File to use for (filename extension based) guessing of MIME types before
trying '/etc/mime.types'. *NOTE* that this path, if relative, is taken
as relative to the current git repository, not to CGI script. If unset,
only '/etc/mime.types' is used (if present on filesystem). If no mimetypes
file is found, mimetype guessing based on extension of file is disabled.
Unset by default.
$highlight_bin::
Path to the highlight executable to use (it must be the one from
http://www.andre-simon.de[] due to assumptions about parameters and output).
By default set to 'highlight'; set it to full path to highlight
executable if it is not installed on your web server's PATH.
Note that 'highlight' feature must be set for gitweb to actually
use syntax hightlighting.
+
*NOTE*: if you want to add support for new file type (supported by
"highlight" but not used by gitweb), you need to modify `%highlight_ext`
or `%highlight_basename`, depending on whether you detect type of file
based on extension (for example "sh") or on its basename (for example
"Makefile"). The keys of these hashes are extension and basename,
respectively, and value for given key is name of syntax to be passed via
`--syntax <syntax>` to highlighter.
+
For example if repositories you are hosting use "phtml" extension for
PHP files, and you want to have correct syntax-highlighting for those
files, you can add the following to gitweb configuration:
+
---------------------------------------------------------
our %highlight_ext;
$highlight_ext{'phtml'} = 'php';
---------------------------------------------------------
Links and their targets
~~~~~~~~~~~~~~~~~~~~~~~
The configuration variables described below configure some of gitweb links:
their target and their look (text or image), and where to find page
prerequisites (stylesheet, favicon, images, scripts). Usually they are left
at their default values, with the possible exception of `@stylesheets`
variable.
@stylesheets::
List of URIs of stylesheets (relative to the base URI of a page). You
might specify more than one stylesheet, for example to use "gitweb.css"
as base with site specific modifications in a separate stylesheet
to make it easier to upgrade gitweb. For example, you can add
a `site` stylesheet by putting
+
----------------------------------------------------------------------------
push @stylesheets, "gitweb-site.css";
----------------------------------------------------------------------------
+
in the gitweb config file. Those values that are relative paths are
relative to base URI of gitweb.
+
This list should contain the URI of gitweb's standard stylesheet. The default
URI of gitweb stylesheet can be set at build time using the `GITWEB_CSS`
makefile variable. Its default value is 'static/gitweb.css'
(or 'static/gitweb.min.css' if the `CSSMIN` variable is defined,
i.e. if CSS minifier is used during build).
+
*Note*: there is also a legacy `$stylesheet` configuration variable, which was
used by older gitweb. If `$stylesheet` variable is defined, only CSS stylesheet
given by this variable is used by gitweb.
$logo::
Points to the location where you put 'git-logo.png' on your web
server, or to be more the generic URI of logo, 72x27 size). This image
is displayed in the top right corner of each gitweb page and used as
a logo for the Atom feed. Relative to the base URI of gitweb (as a path).
Can be adjusted when building gitweb using `GITWEB_LOGO` variable
By default set to 'static/git-logo.png'.
$favicon::
Points to the location where you put 'git-favicon.png' on your web
server, or to be more the generic URI of favicon, which will be served
as "image/png" type. Web browsers that support favicons (website icons)
may display them in the browser's URL bar and next to the site name in
bookmarks. Relative to the base URI of gitweb. Can be adjusted at
build time using `GITWEB_FAVICON` variable.
By default set to 'static/git-favicon.png'.
$javascript::
Points to the location where you put 'gitweb.js' on your web server,
or to be more generic the URI of JavaScript code used by gitweb.
Relative to the base URI of gitweb. Can be set at build time using
the `GITWEB_JS` build-time configuration variable.
+
The default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if
the `JSMIN` build variable was defined, i.e. if JavaScript minifier was used
at build time. *Note* that this single file is generated from multiple
individual JavaScript "modules".
$home_link::
Target of the home link on the top of all pages (the first part of view
"breadcrumbs"). By default it is set to the absolute URI of a current page
(to the value of `$my_uri` variable, or to "/" if `$my_uri` is undefined
or is an empty string).
$home_link_str::
Label for the "home link" at the top of all pages, leading to `$home_link`
(usually the main gitweb page, which contains the projects list). It is
used as the first component of gitweb's "breadcrumb trail":
`<home link> / <project> / <action>`. Can be set at build time using
the `GITWEB_HOME_LINK_STR` variable. By default it is set to "projects",
as this link leads to the list of projects. Other popular choice it to
set it to the name of site.
$logo_url::
$logo_label::
URI and label (title) for the Git logo link (or your site logo,
if you chose to use different logo image). By default, these both
refer to git homepage, http://git-scm.com[]; in the past, they pointed
to git documentation at http://www.kernel.org[].
Changing gitweb's look
~~~~~~~~~~~~~~~~~~~~~~
You can adjust how pages generated by gitweb look using the variables described
below. You can change the site name, add common headers and footers for all
pages, and add a description of this gitweb installation on its main page
(which is the projects list page), etc.
$site_name::
Name of your site or organization, to appear in page titles. Set it
to something descriptive for clearer bookmarks etc. If this variable
is not set or is, then gitweb uses the value of the `SERVER_NAME`
CGI environment variable, setting site name to "$SERVER_NAME Git",
or "Untitled Git" if this variable is not set (e.g. if running gitweb
as standalone script).
+
Can be set using the `GITWEB_SITENAME` at build time. Unset by default.
$site_header::
Name of a file with HTML to be included at the top of each page.
Relative to the directory containing the 'gitweb.cgi' script.
Can be set using `GITWEB_SITE_HEADER` at build time. No default
value.
$site_footer::
Name of a file with HTML to be included at the bottom of each page.
Relative to the directory containing the 'gitweb.cgi' script.
Can be set using `GITWEB_SITE_FOOTER` at build time. No default
value.
$home_text::
Name of a HTML file which, if it exists, is included on the
gitweb projects overview page ("projects_list" view). Relative to
the directory containing the gitweb.cgi script. Default value
can be adjusted during build time using `GITWEB_HOMETEXT` variable.
By default set to 'indextext.html'.
$projects_list_description_width::
The width (in characters) of the "Description" column of the projects list.
Longer descriptions will be truncated (trying to cut at word boundary);
the full description is available in the 'title' attribute (usually shown on
mouseover). The default is 25, which might be too small if you
use long project descriptions.
$default_projects_order::
Default value of ordering of projects on projects list page, which
means the ordering used if you don't explicitly sort projects list
(if there is no "o" CGI query parameter in the URL). Valid values
are "none" (unsorted), "project" (projects are by project name,
i.e. path to repository relative to `$projectroot`), "descr"
(project description), "owner", and "age" (by date of most current
commit).
+
Default value is "project". Unknown value means unsorted.
Changing gitweb's behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~
These configuration variables control _internal_ gitweb behavior.
$default_blob_plain_mimetype::
Default mimetype for the blob_plain (raw) view, if mimetype checking
doesn't result in some other type; by default "text/plain".
Gitweb guesses mimetype of a file to display based on extension
of its filename, using `$mimetypes_file` (if set and file exists)
and '/etc/mime.types' files (see *mime.types*(5) manpage; only
filename extension rules are supported by gitweb).
$default_text_plain_charset::
Default charset for text files. If this is not set, the web server
configuration will be used. Unset by default.
$fallback_encoding::
Gitweb assumes this charset when a line contains non-UTF-8 characters.
The fallback decoding is used without error checking, so it can be even
"utf-8". The value must be a valid encoding; see the *Encoding::Supported*(3pm)
man page for a list. The default is "latin1", aka. "iso-8859-1".
@diff_opts::
Rename detection options for git-diff and git-diff-tree. The default is
(\'-M'); set it to (\'-C') or (\'-C', \'-C') to also detect copies,
or set it to () i.e. empty list if you don't want to have renames
detection.
+
*Note* that rename and especially copy detection can be quite
CPU-intensive. Note also that non git tools can have problems with
patches generated with options mentioned above, especially when they
involve file copies (\'-C') or criss-cross renames (\'-B').
Some optional features and policies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most of features are configured via `%feature` hash; however some of extra
gitweb features can be turned on and configured using variables described
below. This list beside configuration variables that control how gitweb
looks does contain variables configuring administrative side of gitweb
(e.g. cross-site scripting prevention; admittedly this as side effect
affects how "summary" pages look like, or load limiting).
@git_base_url_list::
List of git base URLs. These URLs are used to generate URLs
describing from where to fetch a project, which are shown on
project summary page. The full fetch URL is "`$git_base_url/$project`",
for each element of this list. You can set up multiple base URLs
(for example one for `git://` protocol, and one for `http://`
protocol).
+
Note that per repository configuration can be set in '$GIT_DIR/cloneurl'
file, or as values of multi-value `gitweb.url` configuration variable in
project config. Per-repository configuration takes precedence over value
composed from `@git_base_url_list` elements and project name.
+
You can setup one single value (single entry/item in this list) at build
time by setting the `GITWEB_BASE_URL` built-time configuration variable.
By default it is set to (), i.e. an empty list. This means that gitweb
would not try to create project URL (to fetch) from project name.
$projects_list_group_categories::
Whether to enables the grouping of projects by category on the project
list page. The category of a project is determined by the
`$GIT_DIR/category` file or the `gitweb.category` variable in each
repository's configuration. Disabled by default (set to 0).
$project_list_default_category::
Default category for projects for which none is specified. If this is
set to the empty string, such projects will remain uncategorized and
listed at the top, above categorized projects. Used only if project
categories are enabled, which means if `$projects_list_group_categories`
is true. By default set to "" (empty string).
$prevent_xss::
If true, some gitweb features are disabled to prevent content in
repositories from launching cross-site scripting (XSS) attacks. Set this
to true if you don't trust the content of your repositories.
False by default (set to 0).
$maxload::
Used to set the maximum load that we will still respond to gitweb queries.
If the server load exceeds this value then gitweb will return
"503 Service Unavailable" error. The server load is taken to be 0
if gitweb cannot determine its value. Currently it works only on Linux,
where it uses '/proc/loadavg'; the load there is the number of active
tasks on the system -- processes that are actually running -- averaged
over the last minute.
+
Set `$maxload` to undefined value (`undef`) to turn this feature off.
The default value is 300.
$per_request_config::
If this is set to code reference, it will be run once for each request.
You can set parts of configuration that change per session this way.
For example, one might use the following code in a gitweb configuration
file
+
--------------------------------------------------------------------------------
our $per_request_config = sub {
$ENV{GL_USER} = $cgi->remote_user || "gitweb";
};
--------------------------------------------------------------------------------
+
If `$per_request_config` is not a code reference, it is interpreted as boolean
value. If it is true gitweb will process config files once per request,
and if it is false gitweb will process config files only once, each time it
is executed. True by default (set to 1).
+
*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default
values before every request, so if you want to change them, be sure to set
this variable to true or a code reference effecting the desired changes.
+
This variable matters only when using persistent web environments that
serve multiple requests using single gitweb instance, like mod_perl,
FastCGI or Plackup.
Other variables
~~~~~~~~~~~~~~~
Usually you should not need to change (adjust) any of configuration
variables described below; they should be automatically set by gitweb to
correct value.
$version::
Gitweb version, set automatically when creating gitweb.cgi from
gitweb.perl. You might want to modify it if you are running modified
gitweb, for example
+
---------------------------------------------------
our $version .= " with caching";
---------------------------------------------------
+
if you run modified version of gitweb with caching support. This variable
is purely informational, used e.g. in the "generator" meta header in HTML
header.
$my_url::
$my_uri::
Full URL and absolute URL of the gitweb script;
in earlier versions of gitweb you might have need to set those
variables, but now there should be no need to do it. See
`$per_request_config` if you need to set them still.
$base_url::
Base URL for relative URLs in pages generated by gitweb,
(e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs),
needed and used '<base href="$base_url">' only for URLs with nonempty
PATH_INFO. Usually gitweb sets its value correctly,
and there is no need to set this variable, e.g. to $my_uri or "/".
See `$per_request_config` if you need to override it anyway.
CONFIGURING GITWEB FEATURES
---------------------------
Many gitweb features can be enabled (or disabled) and configured using the
`%feature` hash. Names of gitweb features are keys of this hash.
Each `%feature` hash element is a hash reference and has the following
structure:
----------------------------------------------------------------------
"<feature_name>" => {
"sub" => <feature-sub (subroutine)>,
"override" => <allow-override (boolean)>,
"default" => [ <options>... ]
},
----------------------------------------------------------------------
Some features cannot be overridden per project. For those
features the structure of appropriate `%feature` hash element has a simpler
form:
----------------------------------------------------------------------
"<feature_name>" => {
"override" => 0,
"default" => [ <options>... ]
},
----------------------------------------------------------------------
As one can see it lacks the \'sub' element.
The meaning of each part of feature configuration is described
below:
default::
List (array reference) of feature parameters (if there are any),
used also to toggle (enable or disable) given feature.
+
Note that it is currently *always* an array reference, even if
feature doesn't accept any configuration parameters, and \'default'
is used only to turn it on or off. In such case you turn feature on
by setting this element to `[1]`, and torn it off by setting it to
`[0]`. See also the passage about the "blame" feature in the "Examples"
section.
+
To disable features that accept parameters (are configurable), you
need to set this element to empty list i.e. `[]`.
override::
If this field has a true value then the given feature is
overriddable, which means that it can be configured
(or enabled/disabled) on a per-repository basis.
+
Usually given "<feature>" is configurable via the `gitweb.<feature>`
config variable in the per-repository git configuration file.
+
*Note* that no feature is overriddable by default.
sub::
Internal detail of implementation. What is important is that
if this field is not present then per-repository override for
given feature is not supported.
+
You wouldn't need to ever change it in gitweb config file.
Features in `%feature`
~~~~~~~~~~~~~~~~~~~~~~
The gitweb features that are configurable via `%feature` hash are listed
below. This should be a complete list, but ultimately the authoritative
and complete list is in gitweb.cgi source code, with features described
in the comments.
blame::
Enable the "blame" and "blame_incremental" blob views, showing for
each line the last commit that modified it; see linkgit:git-blame[1].
This can be very CPU-intensive and is therefore disabled by default.
+
This feature can be configured on a per-repository basis via
repository's `gitweb.blame` configuration variable (boolean).
snapshot::
Enable and configure the "snapshot" action, which allows user to
download a compressed archive of any tree or commit, as produced
by linkgit:git-archive[1] and possibly additionally compressed.
This can potentially generate high traffic if you have large project.
+
The value of \'default' is a list of names of snapshot formats,
defined in `%known_snapshot_formats` hash, that you wish to offer.
Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz
compressed tar archive) and "zip"; please consult gitweb sources for
a definitive list. By default only "tgz" is offered.
+
This feature can be configured on a per-repository basis via
repository's `gitweb.blame` configuration variable, which contains
a comma separated list of formats or "none" to disable snapshots.
Unknown values are ignored.
grep::
Enable grep search, which lists the files in currently selected
tree (directory) containing the given string; see linkgit:git-grep[1].
This can be potentially CPU-intensive, of course. Enabled by default.
+
This feature can be configured on a per-repository basis via
repository's `gitweb.grep` configuration variable (boolean).
pickaxe::
Enable the so called pickaxe search, which will list the commits
that introduced or removed a given string in a file. This can be
practical and quite faster alternative to "blame" action, but it is
still potentially CPU-intensive. Enabled by default.
+
The pickaxe search is described in linkgit:git-log[1] (the
description of `-S<string>` option, which refers to pickaxe entry in
linkgit:gitdiffcore[7] for more details).
+
This feature can be configured on a per-repository basis by setting
repository's `gitweb.pickaxe` configuration variable (boolean).
show-sizes::
Enable showing size of blobs (ordinary files) in a "tree" view, in a
separate column, similar to what `ls -l` does; see description of
`-l` option in linkgit:git-ls-tree[1] manpage. This costs a bit of
I/O. Enabled by default.
+
This feature can be configured on a per-repository basis via
repository's `gitweb.showsizes` configuration variable (boolean).
patches::
Enable and configure "patches" view, which displays list of commits in email
(plain text) output format; see also linkgit:git-format-patch[1].
The value is the maximum number of patches in a patchset generated
in "patches" view. Set the 'default' field to a list containing single
item of or to an empty list to disable patch view, or to a list
containing a single negative number to remove any limit.
Default value is 16.
+
This feature can be configured on a per-repository basis via
repository's `gitweb.patches` configuration variable (integer).
avatar::
Avatar support. When this feature is enabled, views such as
"shortlog" or "commit" will display an avatar associated with
the email of each committer and author.
+
Currently available providers are *"gravatar"* and *"picon"*.
Only one provider at a time can be selected ('default' is one element list).
If an unknown provider is specified, the feature is disabled.
*Note* that some providers might require extra Perl packages to be
installed; see 'gitweb/INSTALL' for more details.
+
This feature can be configured on a per-repository basis via
repository's `gitweb.avatar` configuration variable.
+
See also `%avatar_size` with pixel sizes for icons and avatars
("default" is used for one-line like "log" and "shortlog", "double"
is used for two-line like "commit", "commitdiff" or "tag"). If the
default font sizes or lineheights are changed (e.g. via adding extra
CSS stylesheet in `@stylesheets`), it may be appropriate to change
these values.
highlight::
Server-side syntax highlight support in "blob" view. It requires
`$highlight_bin` program to be available (see the description of
this variable in the "Configuration variables" section above),
and therefore is disabled by default.
+
This feature can be configured on a per-repository basis via
repository's `gitweb.highlight` configuration variable (boolean).
remote_heads::
Enable displaying remote heads (remote-tracking branches) in the "heads"
list. In most cases the list of remote-tracking branches is an
unnecessary internal private detail, and this feature is therefore
disabled by default. linkgit:git-instaweb[1], which is usually used
to browse local repositories, enables and uses this feature.
+
This feature can be configured on a per-repository basis via
repository's `gitweb.remote_heads` configuration variable (boolean).
The remaining features cannot be overridden on a per project basis.
search::
Enable text search, which will list the commits which match author,
committer or commit text to a given string; see the description of
`--author`, `--committer` and `--grep` options in linkgit:git-log[1]
manpage. Enabled by default.
+
Project specific override is not supported.
forks::
If this feature is enabled, gitweb considers projects in
subdirectories of project root (basename) to be forks of existing
projects. For each project `$projname.git`, projects in the
`$projname/` directory and its subdirectories will not be
shown in the main projects list. Instead, a \'+' mark is shown
next to `$projname`, which links to a "forks" view that lists all
the forks (all projects in `$projname/` subdirectory). Additionally
a "forks" view for a project is linked from project summary page.
+
If the project list is taken from a file (`$projects_list` points to a
file), forks are only recognized if they are listed after the main project
in that file.
+
Project specific override is not supported.
actions::
Insert custom links to the action bar of all project pages. This
allows you to link to third-party scripts integrating into gitweb.
+
The "default" value consists of a list of triplets in the form
`("<label>", "<link>", "<position>")` where "position" is the label
after which to insert the link, "link" is a format string where `%n`
expands to the project name, `%f` to the project path within the
filesystem (i.e. "$projectroot/$project"), `%h` to the current hash
(\'h' gitweb parameter) and `%b` to the current hash base
(\'hb' gitweb parameter); `%%` expands to \'%'.
+
For example, at the time this page was written, the http://repo.or.cz[]
git hosting site set it to the following to enable graphical log
(using the third party tool *git-browser*):
+
----------------------------------------------------------------------
$feature{'actions'}{'default'} =
[ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
----------------------------------------------------------------------
+
This adds a link titled "graphiclog" after the "summary" link, leading to
`git-browser` script, passing `r=<project>` as a query parameter.
+
Project specific override is not supported.
timed::
Enable displaying how much time and how many git commands it took to
generate and display each page in the page footer (at the bottom of
page). For example the footer might contain: "This page took 6.53325
seconds and 13 git commands to generate." Disabled by default.
+
Project specific override is not supported.
javascript-timezone::
Enable and configure the ability to change a common timezone for dates
in gitweb output via JavaScript. Dates in gitweb output include
authordate and committerdate in "commit", "commitdiff" and "log"
views, and taggerdate in "tag" view. Enabled by default.
+
The value is a list of three values: a default timezone (for if the client
hasn't selected some other timezone and saved it in a cookie), a name of cookie
where to store selected timezone, and a CSS class used to mark up
dates for manipulation. If you want to turn this feature off, set "default"
to empty list: `[]`.
+
Typical gitweb config files will only change starting (default) timezone,
and leave other elements at their default values:
+
---------------------------------------------------------------------------
$feature{'javascript-timezone'}{'default'}[0] = "utc";
---------------------------------------------------------------------------
+
The example configuration presented here is guaranteed to be backwards
and forward compatible.
+
Timezone values can be "local" (for local timezone that browser uses), "utc"
(what gitweb uses when JavaScript or this feature is disabled), or numerical
timezones in the form of "+/-HHMM", such as "+0200".
+
Project specific override is not supported.
EXAMPLES
--------
To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and
"zip" snapshots), while allowing individual projects to turn them off, put
the following in your GITWEB_CONFIG file:
$feature{'blame'}{'default'} = [1];
$feature{'blame'}{'override'} = 1;
$feature{'pickaxe'}{'default'} = [1];
$feature{'pickaxe'}{'override'} = 1;
$feature{'snapshot'}{'default'} = ['zip', 'tgz'];
$feature{'snapshot'}{'override'} = 1;
If you allow overriding for the snapshot feature, you can specify which
snapshot formats are globally disabled. You can also add any command line
options you want (such as setting the compression level). For instance, you
can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by
adding the following lines to your gitweb configuration file:
$known_snapshot_formats{'zip'}{'disabled'} = 1;
$known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
ENVIRONMENT
-----------
The location of per-instance and system-wide configuration files can be
overridden using the following environment variables:
GITWEB_CONFIG::
Sets location of per-instance configuration file.
GITWEB_CONFIG_SYSTEM::
Sets location of fallback system-wide configuration file.
This file is read only if per-instance one does not exist.
GITWEB_CONFIG_COMMON::
Sets location of common system-wide configuration file.
FILES
-----
gitweb_config.perl::
This is default name of per-instance configuration file. The
format of this file is described above.
/etc/gitweb.conf::
This is default name of fallback system-wide configuration
file. This file is used only if per-instance configuration
variable is not found.
/etc/gitweb-common.conf::
This is default name of common system-wide configuration
file.
SEE ALSO
--------
linkgit:gitweb[1], linkgit:git-instaweb[1]
'gitweb/README', 'gitweb/INSTALL'
GIT
---
Part of the linkgit:git[1] suite

704
Documentation/gitweb.txt Normal file
View file

@ -0,0 +1,704 @@
gitweb(1)
=========
NAME
----
gitweb - Git web interface (web frontend to Git repositories)
SYNOPSIS
--------
To get started with gitweb, run linkgit:git-instaweb[1] from a git repository.
This would configure and start your web server, and run web browser pointing to
gitweb.
DESCRIPTION
-----------
Gitweb provides a web interface to git repositories. It's features include:
* Viewing multiple Git repositories with common root.
* Browsing every revision of the repository.
* Viewing the contents of files in the repository at any revision.
* Viewing the revision log of branches, history of files and directories,
see what was changed when, by who.
* Viewing the blame/annotation details of any file (if enabled).
* Generating RSS and Atom feeds of commits, for any branch.
The feeds are auto-discoverable in modern web browsers.
* Viewing everything that was changed in a revision, and step through
revisions one at a time, viewing the history of the repository.
* Finding commits which commit messages matches given search term.
See http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb[] or
http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code,
browsed using gitweb itself.
CONFIGURATION
-------------
Various aspects of gitweb's behavior can be controlled through the configuration
file 'gitweb_config.perl' or '/etc/gitweb.conf'. See the linkgit:gitweb.conf[5]
for details.
Repositories
~~~~~~~~~~~~
Gitweb can show information from one or more Git repositories. These
repositories have to be all on local filesystem, and have to share common
repository root, i.e. be all under a single parent repository (but see also
"Advanced web server setup" section, "Webserver configuration with multiple
projects' root" subsection).
-----------------------------------------------------------------------
our $projectroot = '/path/to/parent/directory';
-----------------------------------------------------------------------
The default value for `$projectroot` is '/pub/git'. You can change it during
building gitweb via `GITWEB_PROJECTROOT` build configuration variable.
By default all git repositories under `$projectroot` are visible and available
to gitweb. The list of projects is generated by default by scanning the
`$projectroot` directory for git repositories (for object databases to be
more exact; gitweb is not interested in a working area, and is best suited
to showing "bare" repositories).
The name of repository in gitweb is path to it's `$GIT_DIR` (it's object
database) relative to `$projectroot`. Therefore the repository $repo can be
found at "$projectroot/$repo".
Projects list file format
~~~~~~~~~~~~~~~~~~~~~~~~~
Instead of having gitweb find repositories by scanning filesystem
starting from $projectroot, you can provide a pre-generated list of
visible projects by setting `$projects_list` to point to a plain text
file with a list of projects (with some additional info).
This file uses the following format:
* One record (for project / repository) per line; does not support line
continuation (newline escaping).
* Leading and trailing whitespace are ignored.
* Whitespace separated fields; any run of whitespace can be used as field
separator (rules for Perl's "`split(" ", $line)`").
* Fields use modified URI encoding, defined in RFC 3986, section 2.1
(Percent-Encoding), or rather "Query string encoding" (see
link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference
being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be
also percent-encoded).
+
Reserved characters are: "%" (used for encoding), "{plus}" (can be used to
encode SPACE), all whitespace characters as defined in Perl, including SP,
TAB and LF, (used to separate fields in a record).
* Currently recognized fields are:
<repository path>::
path to repository GIT_DIR, relative to `$projectroot`
<repository owner>::
displayed as repository owner, preferably full name, or email,
or both
You can generate the projects list index file using the project_index action
(the 'TXT' link on projects list page) directly from gitweb; see also
"Generating projects list using gitweb" section below.
Example contents:
-----------------------------------------------------------------------
foo.git Joe+R+Hacker+<joe@example.com>
foo/bar.git O+W+Ner+<owner@example.org>
-----------------------------------------------------------------------
By default this file controls only which projects are *visible* on projects
list page (note that entries that do not point to correctly recognized git
repositories won't be displayed by gitweb). Even if a project is not
visible on projects list page, you can view it nevertheless by hand-crafting
a gitweb URL. By setting `$strict_export` configuration variable (see
linkgit:gitweb.conf[5]) to true value you can allow viewing only of
repositories also shown on the overview page (i.e. only projects explicitly
listed in projects list file will be accessible).
Generating projects list using gitweb
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We assume that GITWEB_CONFIG has its default Makefile value, namely
'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file:
----------------------------------------------------------------------------
read_config_file("gitweb_config.perl");
$projects_list = $projectroot;
----------------------------------------------------------------------------
Then create the following script to get list of project in the format
suitable for GITWEB_LIST build configuration variable (or
`$projects_list` variable in gitweb config):
----------------------------------------------------------------------------
#!/bin/sh
export GITWEB_CONFIG="gitweb_make_index.perl"
export GATEWAY_INTERFACE="CGI/1.1"
export HTTP_ACCEPT="*/*"
export REQUEST_METHOD="GET"
export QUERY_STRING="a=project_index"
perl -- /var/www/cgi-bin/gitweb.cgi
----------------------------------------------------------------------------
Run this script and save its output to a file. This file could then be used
as projects list file, which means that you can set `$projects_list` to its
filename.
Controlling access to git repositories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default all git repositories under `$projectroot` are visible and
available to gitweb. You can however configure how gitweb controls access
to repositories.
* As described in "Projects list file format" section, you can control which
projects are *visible* by selectively including repositories in projects
list file, and setting `$projects_list` gitweb configuration variable to
point to it. With `$strict_export` set, projects list file can be used to
control which repositories are *available* as well.
* You can configure gitweb to only list and allow viewing of the explicitly
exported repositories, via `$export_ok` variable in gitweb config file; see
linkgit:gitweb.conf[5] manpage. If it evaluates to true, gitweb shows
repositories only if this file named by `$export_ok` exists in its object
database (if directory has the magic file named `$export_ok`).
+
For example linkgit:git-daemon[1] by default (unless `--export-all` option
is used) allows pulling only for those repositories that have
'git-daemon-export-ok' file. Adding
+
--------------------------------------------------------------------------
our $export_ok = "git-daemon-export-ok";
--------------------------------------------------------------------------
+
makes gitweb show and allow access only to those repositories that can be
fetched from via `git://` protocol.
* Finally, it is possible to specify an arbitrary perl subroutine that will
be called for each repository to determine if it can be exported. The
subroutine receives an absolute path to the project (repository) as its only
parameter (i.e. "$projectroot/$project").
+
For example, if you use mod_perl to run the script, and have dumb
HTTP protocol authentication configured for your repositories, you
can use the following hook to allow access only if the user is
authorized to read the files:
+
--------------------------------------------------------------------------
$export_auth_hook = sub {
use Apache2::SubRequest ();
use Apache2::Const -compile => qw(HTTP_OK);
my $path = "$_[0]/HEAD";
my $r = Apache2::RequestUtil->request;
my $sub = $r->lookup_file($path);
return $sub->filename eq $path
&& $sub->status == Apache2::Const::HTTP_OK;
};
--------------------------------------------------------------------------
Per-repository gitweb configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can 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', see linkgit:git-config[1]).
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 `<div>` block element. You can use it for longer
description of a project, to provide links (for example to project's
homepage), etc. This is recognized only if XSS prevention is off
(`$prevent_xss` is false, see linkgit:gitweb.conf[5]); a way to include
a README safely when XSS prevention is on may be worked out in the
future.
description (or `gitweb.description`)::
Short (shortened to `$projects_list_description_width` in the projects
list page, which is 25 characters by default; see
linkgit:gitweb.conf[5]) 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 repository creation, usually installed in
'/usr/share/git-core/templates/'. You can use the `gitweb.description` repo
configuration variable, but the file takes precedence.
category (or `gitweb.category`)::
Singe line category of a project, used to group projects if
`$projects_list_group_categories` is enabled. By default (file and
configuration variable absent), uncategorized projects are put in the
`$project_list_default_category` category. You can use the
`gitweb.category` repo configuration variable, but the file takes
precedence.
+
The configuration variables `$projects_list_group_categories` and
`$project_list_default_category` are described in linkgit:gitweb.conf[5]
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 precedence.
+
This is per-repository enhancement / version of global prefix-based
`@git_base_url_list` gitweb configuration variable (see
linkgit:gitweb.conf[5]).
gitweb.owner::
You can use the `gitweb.owner` repository configuration variable to set
repository's owner. It is displayed in the project list and summary
page.
+
If it's not set, filesystem directory's owner is used (via GECOS field,
i.e. real name field from *getpwuid*(3)) if `$projects_list` is unset
(gitweb scans `$projectroot` for repositories); if `$projects_list`
points to file with list of repositories, then project owner defaults to
value from this file for given repository.
various `gitweb.*` config variables (in config)::
Read description of `%feature` hash for detailed list, and descriptions.
See also "Configuring gitweb features" section in linkgit:gitweb.conf[5]
ACTIONS, AND URLS
-----------------
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:
-----------------------------------------------------------------------
.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments>
-----------------------------------------------------------------------
repo::
The repository the action will be performed on.
+
All actions except for those that list all available projects,
in whatever form, require this parameter.
action::
The action that will be run. Defaults to 'projects_list' if repo
is not set, and to 'summary' otherwise.
revision::
Revision shown. Defaults to HEAD.
path::
The path within the <repository> that the action is performed on,
for those actions that require it.
arguments::
Any arguments that control the behaviour of the action.
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:
-----------------------------------------------------------------------
.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments>
-----------------------------------------------------------------------
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 'blame' view add the following to gitweb
configuration file:
-----------------------------------------------------------------------
$feature{'blame'}{'default'} = [1];
-----------------------------------------------------------------------
Actions:
~~~~~~~~
The standard actions are:
project_list::
Lists the available Git repositories. This is the default command if no
repository is specified in the URL.
summary::
Displays summary about given repository. This is the default command if
no action is specified in URL, and only repository is specified.
heads::
remotes::
Lists all local or all remote-tracking branches in given repository.
+
The latter is not available by default, unless configured.
tags::
List all tags (lightweight and annotated) in given repository.
blob::
tree::
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.
blob_plain::
Returns the raw data for the file in given repository, at given path and
revision. Links to this action are marked 'raw'.
blobdiff::
Shows the difference between two revisions of the same file.
blame::
blame_incremental::
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.
+
This action is disabled by default for performance reasons.
commit::
commitdiff::
Shows information about a specific commit in a repository. The 'commit'
view shows information about commit in more detail, the 'commitdiff'
action shows changeset for given commit.
patch::
Returns the commit in plain text mail format, suitable for applying with
linkgit:git-am[1].
tag::
Display specific annotated tag (tag object).
log::
shortlog::
Shows log information (commit message or just commit subject) for a
given branch (starting from given revision).
+
The 'shortlog' view is more compact; it shows one commit per line.
history::
Shows history of the file or directory in a given repository path,
starting from given revision (defaults to HEAD, i.e. default branch).
+
This view is similar to 'shortlog' view.
rss::
atom::
Generates an RSS (or Atom) feed of changes to repository.
WEBSERVER CONFIGURATION
-----------------------
This section explains how to configure some common webservers to run gitweb. In
all cases, `/path/to/gitweb` in the examples is the directory you ran installed
gitweb in, and contains `gitweb_config.perl`.
If you've configured a web server that isn't listed here for gitweb, please send
in the instructions so they can be included in a future release.
Apache as CGI
~~~~~~~~~~~~~
Apache must be configured to support CGI scripts in the directory in
which gitweb is installed. Let's assume that it is '/var/www/cgi-bin'
directory.
-----------------------------------------------------------------------
ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"
<Directory "/var/www/cgi-bin">
Options Indexes FollowSymlinks ExecCGI
AllowOverride None
Order allow,deny
Allow from all
</Directory>
-----------------------------------------------------------------------
With that configuration the full path to browse repositories would be:
http://server/cgi-bin/gitweb.cgi
Apache with mod_perl, via ModPerl::Registry
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
Assuming that gitweb is installed to '/var/www/perl', the following
Apache configuration (for mod_perl 2.x) is suitable.
-----------------------------------------------------------------------
Alias /perl "/var/www/perl"
<Directory "/var/www/perl">
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
PerlOptions +ParseHeaders
Options Indexes FollowSymlinks +ExecCGI
AllowOverride None
Order allow,deny
Allow from all
</Directory>
-----------------------------------------------------------------------
With that configuration the full path to browse repositories would be:
http://server/perl/gitweb.cgi
Apache with FastCGI
~~~~~~~~~~~~~~~~~~~
Gitweb works with Apache and FastCGI. First you need to rename, copy
or symlink gitweb.cgi to gitweb.fcgi. Let's assume that gitweb is
installed in '/usr/share/gitweb' directory. The following Apache
configuration is suitable (UNTESTED!)
-----------------------------------------------------------------------
FastCgiServer /usr/share/gitweb/gitweb.cgi
ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi
Alias /gitweb/static /usr/share/gitweb/static
<Directory /usr/share/gitweb/static>
SetHandler default-handler
</Directory>
-----------------------------------------------------------------------
With that configuration the full path to browse repositories would be:
http://server/gitweb
ADVANCED WEB SERVER SETUP
-------------------------
All of those examples use request rewriting, and need `mod_rewrite`
(or equivalent; examples below are written for Apache).
Single URL for gitweb and for fetching
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to have one URL for both gitweb and your `http://`
repositories, you can configure Apache like this:
-----------------------------------------------------------------------
<VirtualHost *:80>
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 ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \
/cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT]
</VirtualHost>
-----------------------------------------------------------------------
The above configuration expects your public repositories to live under
'/pub/git' and will serve them as `http://git.domain.org/dir-under-pub-git`,
both as cloneable GIT URL and as browseable gitweb interface. If you then
start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all`
then you can even use the `git://` URL with exactly the same path.
Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the
named file (i.e. in this example '/etc/gitweb.conf') as a configuration for
gitweb. You don't really need it in above example; it is required only if
your configuration file is in different place than built-in (during
compiling gitweb) 'gitweb_config.perl' or '/etc/gitweb.conf'. See
linkgit:gitweb.conf[5] for details, especially information about precedence
rules.
If you use the rewrite rules from the example you *might* also need
something like the following in your gitweb configuration file
('/etc/gitweb.conf' following example):
----------------------------------------------------------------------------
@stylesheets = ("/some/absolute/path/gitweb.css");
$my_uri = "/";
$home_link = "/";
$per_request_config = 1;
----------------------------------------------------------------------------
Nowadays though gitweb should create HTML base tag when needed (to set base
URI for relative links), so it should work automatically.
Webserver configuration with multiple projects' root
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
The virtual host configuration (in Apache configuration file) should look
like this:
--------------------------------------------------------------------------
<VirtualHost *:80>
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 folder in unix users' home
# http://git.example.org/~<user>/
RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
[QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
# http://git.example.org/+<user>/
#RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
[QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
# http://git.example.org/user/<user>/
#RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
[QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
# defined list of project roots
RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
[QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
[QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
# make access for "dumb clients" work
RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \
/cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT]
</VirtualHost>
--------------------------------------------------------------------------
Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT`
environment variable from a web server, so you need to put the following
line in gitweb configuration file ('/etc/gitweb.conf' in above example):
--------------------------------------------------------------------------
$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
--------------------------------------------------------------------------
*Note* that this requires to be set for each request, so either
`$per_request_config` must be false, or the above must be put in code
referenced by `$per_request_config`;
These configurations enable two things. First, each unix user (`<user>`) of
the server will be able to browse through gitweb git repositories found in
'~/public_git/' with the following url:
http://git.example.org/~<user>/
If you do not want this feature on your server just remove the second
rewrite rule.
If you already use `mod_userdir` in your virtual host or you don't want to
use the \'~' as first character, just comment or remove the second rewrite
rule, and uncomment one of the following according to what you want.
Second, repositories found in '/pub/scm/' and '/var/git/' will be accessible
through `http://git.example.org/scm/` and `http://git.example.org/var/`.
You can add as many project roots as you want by adding rewrite rules like
the third and the fourth.
PATH_INFO usage
~~~~~~~~~~~~~~~
If you enable PATH_INFO usage in gitweb by putting
----------------------------------------------------------------------------
$feature{'pathinfo'}{'default'} = [1];
----------------------------------------------------------------------------
in your gitweb configuration file, it is possible to set up your server so
that it consumes and produces URLs in the form
http://git.example.com/project.git/shortlog/sometag
i.e. without 'gitweb.cgi' part, by using a configuration such as the
following. This configuration assumes that '/var/www/gitweb' is the
DocumentRoot of your webserver, contains the gitweb.cgi script and
complementary static files (stylesheet, favicon, JavaScript):
----------------------------------------------------------------------------
<VirtualHost *:80>
ServerAlias git.example.com
DocumentRoot /var/www/gitweb
<Directory /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]
</Directory>
</VirtualHost>
----------------------------------------------------------------------------
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.
*Notice* that in this case you don't need special settings for
`@stylesheets`, `$my_uri` and `$home_link`, 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. '/pub/git') have the projects
named *without* a .git extension (e.g. '/pub/git/project' instead of
'/pub/git/project.git') and configure Apache as follows:
----------------------------------------------------------------------------
<VirtualHost *:80>
ServerAlias git.example.com
DocumentRoot /var/www/gitweb
AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
<Directory /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]
</Directory>
</VirtualHost>
----------------------------------------------------------------------------
The additional AliasMatch makes it so that
http://git.example.com/project.git
will give raw access to the project's git dir (so that the project can be
cloned), while
http://git.example.com/project
will provide human-friendly gitweb access.
This solution is not 100% bulletproof, in the sense that if some project has
a named ref (branch, tag) starting with 'git/', then paths such as
http://git.example.com/project/command/abranch..git/abranch
will fail with a 404 error.
BUGS
----
Please report any bugs or feature requests to git@vger.kernel.org,
putting "gitweb" in the subject of email.
SEE ALSO
--------
linkgit:gitweb.conf[5], linkgit:git-instaweb[1]
'gitweb/README', 'gitweb/INSTALL'
GIT
---
Part of the linkgit:git[1] suite

1
command-list.txt
View file

@ -130,5 +130,6 @@ git-upload-pack synchelpers
git-var plumbinginterrogators
git-verify-pack plumbinginterrogators
git-verify-tag ancillaryinterrogators
gitweb ancillaryinterrogators
git-whatchanged ancillaryinterrogators
git-write-tree plumbingmanipulators

7
git.spec.in
View file

@ -199,7 +199,11 @@ rm -rf $RPM_BUILD_ROOT
%files -n gitweb
%defattr(-,root,root)
%doc gitweb/README gitweb/INSTALL Documentation/*gitweb*.txt
%{_datadir}/gitweb
%{!?_without_docs: %{_mandir}/man1/*gitweb*.1*}
%{!?_without_docs: %{_mandir}/man5/*gitweb*.5*}
%{!?_without_docs: %doc Documentation/*gitweb*.html }
%files -n perl-Git -f perl-files
%defattr(-,root,root)
@ -208,6 +212,9 @@ rm -rf $RPM_BUILD_ROOT
# No files for you!
%changelog
* Sun Sep 18 2011 Jakub Narebski <jnareb@gmail.com>
- Add gitweb manpages to 'gitweb' subpackage
* Wed Jun 30 2010 Junio C Hamano <gitster@pobox.com>
- Add 'gitweb' subpackage.

94
gitweb/INSTALL
View file

@ -229,7 +229,7 @@ Gitweb config file
------------------
See also "Runtime gitweb configuration" section in README file
for gitweb (in gitweb/README).
for gitweb (in gitweb/README), and gitweb.conf(5) manpage.
- You can configure gitweb further using the per-instance gitweb configuration file;
by default this is a file named gitweb_config.perl in the same place as
@ -287,97 +287,19 @@ adding the following lines to your $GITWEB_CONFIG:
Gitweb repositories
-------------------
- By default all git repositories under projectroot are visible and
available to gitweb. The list of projects is generated by default by
scanning the projectroot directory for git repositories (for object
databases to be more exact).
By default gitweb shows all git repositories under single common repository
root on a local filesystem; see description of GITWEB_PROJECTROOT build-time
configuration variable above (and also of GITWEB_LIST).
You can provide a pre-generated list of [visible] repositories,
together with information about their owners (the project ownership
defaults to the owner of the repository directory otherwise), by setting
the GITWEB_LIST build configuration variable (or the $projects_list
variable in the gitweb config file) to point to a plain file.
Each line of the projects list file should consist of the url-encoded path
to the project repository database (relative to projectroot), followed
by the url-encoded project owner on the same line (separated by a space).
Spaces in both project path and project owner have to be encoded as either
'%20' or '+'.
Other characters that have to be url-encoded, i.e. replaced by '%'
followed by two-digit character number in octal, are: other whitespace
characters (because they are field separator in a record), plus sign '+'
(because it can be used as replacement for spaces), and percent sign '%'
(which is used for encoding / escaping).
You can generate the projects list index file using the project_index
action (the 'TXT' link on projects list page) directly from gitweb.
- By default, even if a project is not visible on projects list page, you
can view it nevertheless by hand-crafting a gitweb URL. You can set the
GITWEB_STRICT_EXPORT build configuration variable (or the $strict_export
variable in the gitweb config file) to only allow viewing of
repositories also shown on the overview page.
- Alternatively, you can configure gitweb to only list and allow
viewing of the explicitly exported repositories, via the
GITWEB_EXPORT_OK build configuration variable (or the $export_ok
variable in gitweb config file). If it evaluates to true, gitweb
shows repositories only if this file exists in its object database
(if directory has the magic file named $export_ok).
- Finally, it is possible to specify an arbitrary perl subroutine that
will be called for each project to determine if it can be exported.
The subroutine receives an absolute path to the project as its only
parameter.
For example, if you use mod_perl to run the script, and have dumb
http protocol authentication configured for your repositories, you
can use the following hook to allow access only if the user is
authorized to read the files:
$export_auth_hook = sub {
use Apache2::SubRequest ();
use Apache2::Const -compile => qw(HTTP_OK);
my $path = "$_[0]/HEAD";
my $r = Apache2::RequestUtil->request;
my $sub = $r->lookup_file($path);
return $sub->filename eq $path
&& $sub->status == Apache2::Const::HTTP_OK;
};
Generating projects list using gitweb
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We assume that GITWEB_CONFIG has its default Makefile value, namely
gitweb_config.perl. Put the following in gitweb_make_index.perl file:
$GITWEB_CONFIG = "gitweb_config.perl";
do $GITWEB_CONFIG if -e $GITWEB_CONFIG;
$projects_list = $projectroot;
Then create the following script to get list of project in the format
suitable for GITWEB_LIST build configuration variable (or
$projects_list variable in gitweb config):
#!/bin/sh
export GITWEB_CONFIG="gitweb_make_index.perl"
export GATEWAY_INTERFACE="CGI/1.1"
export HTTP_ACCEPT="*/*"
export REQUEST_METHOD="GET"
export QUERY_STRING="a=project_index"
perl -- /var/www/cgi-bin/gitweb.cgi
More advanced usage, like limiting access or visibility of repositories and
managing multiple roots are described on gitweb manpage.
Example web server configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See also "Webserver configuration" section in README file for gitweb
(in gitweb/README).
See also "Webserver configuration" and "Advanced web server setup" sections
in gitweb(1) manpage.
- Apache2, gitweb installed as CGI script,

411
gitweb/README
View file

@ -7,9 +7,18 @@ The one working on:
From the git version 1.4.0 gitweb is bundled with git.
Build time gitweb configuration
-------------------------------
There are many configuration variables which affect building gitweb (among
others creating gitweb.cgi out of gitweb.perl by replacing placeholders such
as `++GIT_BINDIR++` by their build-time values).
Building and installing gitweb is described in gitweb's INSTALL file
(in 'gitweb/INSTALL').
Runtime gitweb configuration
----------------------------
Gitweb obtains configuration data from the following sources in the
following order:
@ -41,400 +50,22 @@ 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 the "Gitweb config file" (with an example of config file), and
the "Gitweb repositories" sections in INSTALL file for gitweb.
See also gitweb.conf(5) manpage.
The gitweb config file is a 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 is the list of variables 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
(with the exception of $projectroot and $projects_list this list does
not include variables usually directly set during build):
* $GIT
Core 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 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.
* $projectroot
Absolute filesystem path which will be prepended to project path;
the path to repository is $projectroot/$project. Set to
$GITWEB_PROJECTROOT during installation. This variable have to be
set correctly for gitweb to find repositories.
* $projects_list
Source of projects list, either directory to scan, or text file
with list of repositories (in the "<URI-encoded repository path> SP
<URI-encoded repository owner>" line format; actually there can be
any sequence of whitespace in place of space (SP)). Set to
$GITWEB_LIST during installation. If empty, $projectroot is used
to scan for repositories.
* $my_url, $my_uri
Full URL and absolute URL of gitweb script;
in earlier versions of gitweb you might have need to set those
variables, now there should be no need to do it. See
$per_request_config if you need to set them still.
* $base_url
Base URL for relative URLs in pages generated by gitweb,
(e.g. $logo, $favicon, @stylesheets if they are relative URLs),
needed and used only for URLs with nonempty PATH_INFO via
<base href="$base_url">. Usually gitweb sets its value correctly,
and there is no need to set this variable, e.g. to $my_uri or "/".
See $per_request_config if you need to set it anyway.
* $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 ($my_uri).
* @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 the 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.
* $projects_list_group_categories
Enables the grouping of projects by category on the project list page.
The category of a project is determined by the $GIT_DIR/category
file or the 'gitweb.category' variable in its repository configuration.
Disabled by default.
* $project_list_default_category
Default category for projects for which none is specified. If set
to the empty string, such projects will remain uncategorized and
listed at the top, above categorized projects.
* @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 server 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
relative to the current git repository.
* $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 must be valid encoding; 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.
* $prevent_xss
If true, some gitweb features are disabled to prevent content in
repositories from launching cross-site scripting (XSS) attacks. Set this
to true if you don't trust the content of your repositories. The default
is false.
* $maxload
Used to set the maximum load that we will still respond to gitweb queries.
If server load exceed this value then return "503 Service Unavailable" error.
Server load is taken to be 0 if gitweb cannot determine its value. Set it to
undefined value to turn it off. The default is 300.
* $highlight_bin
Path to the highlight executable to use (must be the one from
http://www.andre-simon.de due to assumptions about parameters and output).
Useful if highlight is not installed on your webserver's PATH.
[Default: highlight]
* $per_request_config
If set to code reference, it would be run once per each request. You can
set parts of configuration that change per session, e.g. by setting it to
sub { $ENV{GL_USER} = $cgi->remote_user || "gitweb"; }
Otherwise it is treated as boolean value: if true gitweb would process
config file once per request, if false it would process config file only
once. Note: $my_url, $my_uri, and $base_url are overwritten with
their default values before every request, so if you want to change
them, be sure to set this variable to true or a code reference effecting
the desired changes. The default is true.
Projects list file format
~~~~~~~~~~~~~~~~~~~~~~~~~
Instead of having gitweb find repositories by scanning filesystem starting
from $projectroot (or $projects_list, if it points to directory), you can
provide list of projects by setting $projects_list to a text file with list
of projects (and some additional info). This file uses the following
format:
One record (for project / repository) per line, whitespace separated fields;
does not support (at least for now) lines continuation (newline escaping).
Leading and trailing whitespace are ignored, any run of whitespace can be
used as field separator (rules for Perl's "split(' ', $line)"). Keyed by
the first field, which is project name, i.e. path to repository GIT_DIR
relative to $projectroot. Fields use modified URI encoding, defined in
RFC 3986, section 2.1 (Percent-Encoding), or rather "Query string encoding"
(see http://en.wikipedia.org/wiki/Query_string#URL_encoding), the difference
being that SP (' ') can be encoded as '+' (and therefore '+' has to be also
percent-encoded). Reserved characters are: '%' (used for encoding), '+'
(can be used to encode SPACE), all whitespace characters as defined in Perl,
including SP, TAB and LF, (used to separate fields in a record).
Currently list of fields is
* <repository path> - path to repository GIT_DIR, relative to $projectroot
* <repository owner> - displayed as repository owner, preferably full name,
or email, or both
You can additionally use $projects_list file to limit which repositories
are visible, and together with $strict_export to limit access to
repositories (see "Gitweb repositories" section in gitweb/INSTALL).
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 <div> block element. You can use it for longer
description of a project, to provide links (for example to project's
homepage), etc. This is recognized only if XSS prevention is off
($prevent_xss is false); a way to include a readme safely when XSS
prevention is on may be worked out in the future.
* 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 repository creation. You can use the
gitweb.description repo configuration variable, but the file takes
precedence.
* category (or gitweb.category)
Singe line category of a project, used to group projects if
$projects_list_group_categories is enabled. By default (file and
configuration variable absent), uncategorized projects are put in
the $project_list_default_category category. You can use the
gitweb.category repo configuration variable, but the file takes
precedence.
* 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 precedence.
* gitweb.owner
You can use the gitweb.owner repository configuration variable to set
repository's owner. It is displayed in the project list and summary
page. If it's not set, filesystem directory's owner is used
(via GECOS field / real name field from getpwiud(3)).
* various gitweb.* config variables (in config)
Read description of %feature hash for detailed list, and some
descriptions.
Webserver configuration
-----------------------
If you want to have one URL for both gitweb and your http://
repositories, you can configure apache like this:
<VirtualHost *:80>
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 ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT]
</VirtualHost>
The above configuration expects your public repositories to live under
/pub/git and will serve them as http://git.domain.org/dir-under-pub-git,
both as cloneable GIT URL and as browseable gitweb interface.
If you then start your git-daemon with --base-path=/pub/git --export-all
then you can even use the git:// URL with exactly the same path.
Setting the environment variable GITWEB_CONFIG will tell gitweb to use
the named file (i.e. in this example /etc/gitweb.conf) as a
configuration for gitweb. Perl variables defined in here will
override the defaults given at the head of the gitweb.perl (or
gitweb.cgi). Look at the comments in that file for information on
which variables and what they mean.
If you use the rewrite rules from the example you'll likely also need
something like the following in your gitweb.conf (or gitweb_config.perl) file:
@stylesheets = ("/some/absolute/path/gitweb.css");
$my_uri = "/";
$home_link = "/";
Webserver configuration with multiple projects' root
----------------------------------------------------
If you want to use gitweb with several project roots you can edit your apache
virtual host and gitweb.conf configuration files like this :
virtual host configuration :
<VirtualHost *:80>
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 folder in unix users' home
# http://git.example.org/~<user>/
RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
# http://git.example.org/+<user>/
#RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
# http://git.example.org/user/<user>/
#RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
# defined list of project roots
RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
# make access for "dumb clients" work
RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT]
</VirtualHost>
gitweb.conf configuration :
$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
These configurations enable two things. First, each unix user (<user>) of the
server will be able to browse through gitweb git repositories found in
~/public_git/ with the following url : http://git.example.org/~<user>/
If you do not want this feature on your server just remove the second rewrite rule.
If you already use mod_userdir in your virtual host or you don't want to use
the '~' as first character just comment or remove the second rewrite rule and
uncomment one of the following according to what you want.
Second, repositories found in /pub/scm/ and /var/git/ will be accesible
through http://git.example.org/scm/ and http://git.example.org/var/.
You can add as many project roots as you want by adding rewrite rules like the
third and the fourth.
PATH_INFO usage
-----------------------
If you enable PATH_INFO usage in gitweb by putting
$feature{'pathinfo'}{'default'} = [1];
in your gitweb.conf, it is possible to set up your server so that it
consumes and produces URLs in the form
http://git.example.com/project.git/shortlog/sometag
by using a configuration such as the following, that assumes that
/var/www/gitweb is the DocumentRoot of your webserver, and that it
contains the gitweb.cgi script and complementary static files
(stylesheet, favicon):
<VirtualHost *:80>
ServerAlias git.example.com
DocumentRoot /var/www/gitweb
<Directory /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]
</Directory>
</VirtualHost>
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.
Notice that in this case you don't need special settings for
@stylesheets, $my_uri and $home_link, but you lose "dumb client" access
to your project .git dirs. A possible workaround for the latter is the
following: in your project root dir (e.g. /pub/git) have the projects
named without a .git extension (e.g. /pub/git/project instead of
/pub/git/project.git) and configure Apache as follows:
<VirtualHost *:80>
ServerAlias git.example.com
DocumentRoot /var/www/gitweb
AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
<Directory /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]
</Directory>
</VirtualHost>
The additional AliasMatch makes it so that
http://git.example.com/project.git
will give raw access to the project's git dir (so that the project can
be cloned), while
http://git.example.com/project
will provide human-friendly gitweb access.
This solution is not 100% bulletproof, in the sense that if some project
has a named ref (branch, tag) starting with 'git/', then paths such as
http://git.example.com/project/command/abranch..git/abranch
will fail with a 404 error.
Web server configuration
------------------------
Gitweb can be run as CGI script, as legacy mod_perl application (using
ModPerl::Registry), and as FastCGI script. You can find some simple examples
in "Example web server configuration" section in INSTALL file for gitweb (in
gitweb/INSTALL).
See "Webserver configuration" and "Advanced web server setup" sections in
gitweb(1) manpage.
AUTHORS
-------
Originally written by:
Kay Sievers <kay.sievers@vrfy.org>