scripts).
+Requirements
+------------
+
+ - Core git tools
+ - Perl
+ - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename.
+ - web server
+
+The following optional Perl modules are required for extra features
+ - Digest::MD5 - for gravatar support
+ - CGI::Fast and FCGI - for running gitweb as FastCGI script
+ - HTML::TagCloud - for fancy tag cloud in project list view
+ - HTTP::Date or Time::ParseDate - to support If-Modified-Since for feeds
+
+
Build time configuration
------------------------
Points to an .html file which is included on the gitweb project
overview page ('projects_list' view), if it exists. Relative to
gitweb.cgi script. [Default: indextext.html]
+ * GITWEB_SITE_HTML_HEAD_STRING
+ html snippet to include in the <head> section of each page. [No default]
* GITWEB_SITE_HEADER
Filename of html text to include at top of each page. Relative to
gitweb.cgi script. [No default]
the gitweb config file. [Default: static/gitweb.css (or
static/gitweb.min.css if the CSSMIN variable is defined / CSS minifier
is used)]
+ * GITWEB_JS
+ Points to the location where you put gitweb.js on your web server
+ (or to be more generic URI of JavaScript code used by gitweb).
+ Relative to base URI of gitweb. [Default: static/gitweb.js (or
+ static/gitweb.min.js if JSMIN build variable is defined / JavaScript
+ minifier is used)]
+ * CSSMIN, JSMIN
+ Invocation of a CSS minifier or a JavaScript minifier, respectively,
+ working as a filter (source on standard input, minified result on
+ standard output). If set, it is used to generate a minified version of
+ 'static/gitweb.css' or 'static/gitweb.js', respectively. *Note* that
+ minified files would have *.min.css and *.min.js extension, which is
+ important if you also set GITWEB_CSS and/or GITWEB_JS. [No default]
* GITWEB_LOGO
Points to the location where you put git-logo.png on your web server
(or to be more generic URI of logo, 72x27 size, displayed in top right
web browsers that support favicons (website icons) may display them
in the browser's URL bar and next to site name in bookmarks). Relative
to base URI of gitweb. [Default: static/git-favicon.png]
- * GITWEB_JS
- Points to the location where you put gitweb.js on your web server
- (or to be more generic URI of JavaScript code used by gitweb).
- Relative to base URI of gitweb. [Default: static/gitweb.js (or
- static/gitweb.min.js if JSMIN build variable is defined / JavaScript
- minifier is used)]
* GITWEB_CONFIG
This Perl file will be loaded using 'do' and can be used to override any
of the options above as well as some other options -- see the "Runtime
------------------
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 gitweb configuration file;
+- 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
gitweb.cgi script. You can control the default place for the config file
using the GITWEB_CONFIG build configuration variable, and you can set it
GITWEB_CONFIG_SYSTEM build configuration variable, and override it
through the GITWEB_CONFIG_SYSTEM environment variable.
+ Note that if per-instance configuration file exists, then system-wide
+ configuration is _not used at all_. This is quite untypical and suprising
+ behavior. On the other hand changing current behavior would break backwards
+ compatibility and can lead to unexpected changes in gitweb behavior.
+ Therefore gitweb also looks for common system-wide configuration file,
+ normally /etc/gitweb-common.conf (set during build time using build time
+ configuration variable GITWEB_CONFIG_COMMON, set it at runtime using
+ environment variable with the same name). Settings from per-instance or
+ system-wide configuration file override those from common system-wide
+ configuration file.
+
- 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) for details.
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
- 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
-
-
-Requirements
-------------
+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).
- - Core git tools
- - Perl
- - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename.
- - web server
-
-The following optional Perl modules are required for extra features
- - Digest::MD5 - for gravatar support
- - CGI::Fast and FCGI - for running gitweb as FastCGI script
- - HTML::TagCloud - for fancy tag cloud in project list view
- - HTTP::Date or Time::ParseDate - to support If-Modified-Since for feeds
+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,