Commit 07ea4df2 authored by Jakub Narębski's avatar Jakub Narębski Committed by Junio C Hamano

gitweb: Add gitweb(1) manpage for gitweb itself

Most of what is in gitweb.txt it has been pulled directly from the
README and INSTALL files of gitweb.

Current version is somewhat based on structure of SVN::Web manpage
(one of web interfaces for Subversion).

gitweb.conf(5) i.e. gitweb configuration manpage now refers to
appropriate sections in gitweb(1).  gitweb/README now refers to
gitweb/INSTALL and gitweb(1) manpage.  gitweb/INSTALL now refers to
gitweb.conf(5) and gitweb(1).
Inspired-by: default avatarDrew Northup <[email protected]>
Signed-off-by: Jakub Narębski's avatarJakub Narebski <[email protected]>
Signed-off-by: default avatarJunio C Hamano <[email protected]>
parent 6d3902b0
$(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 gitweb.conf.txt
MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
......@@ -35,6 +35,10 @@ 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.
......@@ -109,6 +113,8 @@ 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.
Absolute filesystem path which will be prepended to project path;
the path to repository is `$projectroot/$project`. Set to
......@@ -193,6 +199,9 @@ 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.
Only allow viewing of repositories also shown on the overview page.
This diff is collapsed.
......@@ -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).
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
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";
$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):
export GITWEB_CONFIG="gitweb_make_index.perl"
export HTTP_ACCEPT="*/*"
export QUERY_STRING="a=project_index"
perl -- /var/www/cgi-bin/gitweb.cgi
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).
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,
This diff is collapsed.
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment