17a8b25005
From a distribution point of view, configuration files for applications should reside in /etc/. On the other hand it's convenient for multiple instances of gitweb (e.g. virtual web servers on a single machine) to have a per-instance configuration file, just as gitweb currently supports through the file gitweb_config.perl next to the cgi. To support both at runtime, this commit introduces GITWEB_CONFIG_SYSTEM as a system-wide configuration file which will be used as a fallback if the config file sprecified throug GITWEB_CONFIG does not exist. See also http://bugs.debian.org/450592 Signed-off-by: Gerrit Pape <pape@smarden.org> Acked-by: Jakub Narebski <jnareb@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
230 lines
8.2 KiB
Plaintext
230 lines
8.2 KiB
Plaintext
GIT web Interface (gitweb) Installation
|
|
=======================================
|
|
|
|
First you have to generate gitweb.cgi from gitweb.perl using
|
|
"make gitweb/gitweb.cgi", then copy appropriate files (gitweb.cgi,
|
|
gitweb.css, git-logo.png and git-favicon.png) to their destination.
|
|
For example if git was (or is) installed with /usr prefix, you can do
|
|
|
|
$ make prefix=/usr gitweb/gitweb.cgi ;# as yourself
|
|
# cp gitweb/git* /var/www/cgi-bin/ ;# as root
|
|
|
|
Alternatively you can use autoconf generated ./configure script to
|
|
set up path to git binaries (via config.mak.autogen), so you can write
|
|
instead
|
|
|
|
$ make configure ;# as yourself
|
|
$ ./configure --prefix=/usr ;# as yourself
|
|
$ make gitweb/gitweb.cgi ;# as yourself
|
|
# cp gitweb/git* /var/www/cgi-bin/ ;# as root
|
|
|
|
The above example assumes that your web server is configured to run
|
|
[executable] files in /var/www/cgi-bin/ as server scripts (as CGI
|
|
scripts).
|
|
|
|
|
|
Build time configuration
|
|
------------------------
|
|
|
|
See also "How to configure gitweb for your local system" in README
|
|
file for gitweb (in gitweb/README).
|
|
|
|
- There are many configuration variables which affects building of
|
|
gitweb.cgi; see "default configuration for gitweb" section in main
|
|
(top dir) Makefile, and instructions for building gitweb/gitweb.cgi
|
|
target.
|
|
|
|
One of most important is where to find git wrapper binary. Gitweb
|
|
tries to find git wrapper at $(bindir)/git, so you have to set $bindir
|
|
when building gitweb.cgi, or $prefix from which $bindir is derived. If
|
|
you build and install gitweb together with the rest of git suite,
|
|
there should be no problems. Otherwise, if git was for example
|
|
installed from a binary package, you have to set $prefix (or $bindir)
|
|
accordingly.
|
|
|
|
- Another important issue is where are git repositories you want to make
|
|
available to gitweb. By default gitweb search for repositories under
|
|
/pub/git; if you want to have projects somewhere else, like /home/git,
|
|
use GITWEB_PROJECTROOT build configuration variable.
|
|
|
|
By default all git repositories under projectroot are visible and
|
|
available to gitweb. List of projects is generated by default by
|
|
scanning the projectroot directory for git repositories. This can be
|
|
changed (configured) as described in "Gitweb repositories" section
|
|
below.
|
|
|
|
Note that gitweb deals directly with object database, and does not
|
|
need working directory; the name of the project is the name of its
|
|
repository object database, usually projectname.git for bare
|
|
repositories. If you want to provide gitweb access to non-bare (live)
|
|
repository, you can make projectname.git symbolic link under
|
|
projectroot linking to projectname/.git (but it is just
|
|
a suggestion).
|
|
|
|
- You can control where gitweb tries to find its main CSS style file,
|
|
its favicon and logo with GITWEB_CSS, GITWEB_FAVICON and GITWEB_LOGO
|
|
build configuration variables. By default gitweb tries to find them
|
|
in the same directory as gitweb.cgi script.
|
|
|
|
Build example
|
|
~~~~~~~~~~~~~
|
|
|
|
- To install gitweb to /var/www/cgi-bin/gitweb/ when git wrapper
|
|
is installed at /usr/local/bin/git and the repositories (projects)
|
|
we want to display are under /home/local/scm, you can do
|
|
|
|
make GITWEB_PROJECTROOT="/home/local/scm" \
|
|
GITWEB_CSS="/gitweb/gitweb.css" \
|
|
GITWEB_LOGO="/gitweb/git-logo.png" \
|
|
GITWEB_FAVICON="/gitweb/git-favicon.png" \
|
|
bindir=/usr/local/bin \
|
|
gitweb/gitweb.cgi
|
|
|
|
cp -fv ~/git/gitweb/gitweb.{cgi,css} \
|
|
~/git/gitweb/git-{favicon,logo}.png \
|
|
/var/www/cgi-bin/gitweb/
|
|
|
|
|
|
Gitweb config file
|
|
------------------
|
|
|
|
See also "Runtime gitweb configuration" section in README file
|
|
for gitweb (in gitweb/README).
|
|
|
|
- You can configure gitweb further using gitweb configuration file;
|
|
by default it is file named gitweb_config.perl in the same place as
|
|
gitweb.cgi script. You can control default place for config file
|
|
using GITWEB_CONFIG build configuration variable, and you can set it
|
|
using GITWEB_CONFIG environmental variable. If this file does not
|
|
exist, gitweb looks for a system-wide configuration file, normally
|
|
/etc/gitweb.conf. You can change the default using the
|
|
GITWEB_CONFIG_SYSTEM build configuration variable, and override it
|
|
through GITWEB_CONFIG_SYSTEM environmental variable.
|
|
|
|
- Gitweb config file is [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.
|
|
|
|
See the top of gitweb.perl file for examples of customizable options.
|
|
|
|
Config file example
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
To enable blame, pickaxe search, and snapshot support, 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;
|
|
|
|
|
|
Gitweb repositories
|
|
-------------------
|
|
|
|
- By default all git repositories under projectroot are visible and
|
|
available to gitweb. 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 pre-generated list of [visible] repositories,
|
|
together with information about their owners (the project ownership
|
|
is taken from owner of repository directory otherwise), by setting
|
|
GITWEB_LIST build configuration variable (or $projects_list variable
|
|
in gitweb config file) to point to a plain file.
|
|
|
|
Each line of projects list file should consist of url-encoded path
|
|
to project repository database (relative to projectroot) separated
|
|
by space from url-encoded project owner; spaces in both project path
|
|
and project owner have to be encoded as either '%20' or '+'.
|
|
|
|
You can generate projects list index file using project_index action
|
|
(the 'TXT' link on projects list page) directly from gitweb.
|
|
|
|
- By default even if project is not visible on projects list page, you
|
|
can view it nevertheless by hand-crafting gitweb URL. You can set
|
|
GITWEB_STRICT_EXPORT build configuration variable (or $strict_export
|
|
variable in 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
|
|
GITWEB_EXPORT_OK build configuration variable (or $export_ok
|
|
variable in gitweb config file). If it evaluates to true, gitweb
|
|
show repository only if this file exists in its object database
|
|
(if directory has the magic file $export_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
|
|
------------
|
|
|
|
- Core git tools
|
|
- Perl
|
|
- Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename.
|
|
- web server
|
|
|
|
|
|
Example web server configuration
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
See also "Webserver configuration" section in README file for gitweb
|
|
(in gitweb/README).
|
|
|
|
|
|
- Apache2, gitweb installed as CGI script,
|
|
under /var/www/cgi-bin/
|
|
|
|
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>
|
|
|
|
- Apache2, gitweb installed as mod_perl legacy script,
|
|
under /var/www/perl/
|
|
|
|
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>
|