You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
257 lines
9.4 KiB
257 lines
9.4 KiB
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 affect 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 the most important is where to find the git wrapper binary. Gitweb |
|
tries to find the 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 the 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 searches 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. The 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 the object database, and does not |
|
need a 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) |
|
repositories, you can make projectname.git a 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 the 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 the 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 |
|
using the GITWEB_CONFIG environment 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 the GITWEB_CONFIG_SYSTEM environment variable. |
|
|
|
- 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. |
|
|
|
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. 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 |
|
------------ |
|
|
|
- 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>
|
|
|