mirror of
https://github.com/git/git
synced 2024-08-25 02:35:46 +00:00
![Ævar Arnfjörð Bjarmason](/assets/img/avatar_default.png)
Since myd48b284183
("perl: bump the required Perl version to 5.8 from 5.6.[21]", 2010-09-24), we've depended on 5.8, so there's no reason to conditionally require Digest::MD5 anymore. It was released with perl v5.7.3[1] The initial introduction of the dependency ine9fdd74e53
("gitweb: (gr)avatar support", 2009-06-30) says as much, this also undoes part of the later2e9c8789b7
("gitweb: Mention optional Perl modules in INSTALL", 2011-02-04) since gitweb will always be run on at least 5.8, so there's no need to mention Digest::MD5 as a required module in the documentation, let's instead say that we require perl 5.8. 1. $ corelist Digest::MD5 Data for 2015-02-14 Digest::MD5 was first released with perl v5.7.3 Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
329 lines
14 KiB
Plaintext
329 lines
14 KiB
Plaintext
GIT web Interface (gitweb) Installation
|
|
=======================================
|
|
|
|
First you have to generate gitweb.cgi from gitweb.perl using
|
|
"make gitweb", then "make install-gitweb" appropriate files
|
|
(gitweb.cgi, gitweb.js, gitweb.css, git-logo.png and git-favicon.png)
|
|
to their destination. For example if git was (or is) installed with
|
|
/usr prefix and gitwebdir is /var/www/cgi-bin, you can do
|
|
|
|
$ make prefix=/usr gitweb ;# as yourself
|
|
# make gitwebdir=/var/www/cgi-bin install-gitweb ;# 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 ;# as yourself
|
|
# make gitwebdir=/var/www/cgi-bin \
|
|
install-gitweb ;# 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).
|
|
|
|
|
|
Requirements
|
|
------------
|
|
|
|
- Core git tools
|
|
- Perl 5.8
|
|
- Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename.
|
|
- web server
|
|
|
|
The following optional Perl modules are required for extra features
|
|
- 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
|
|
------------------------
|
|
|
|
See also "How to configure gitweb for your local system" section below.
|
|
|
|
- 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 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 JavaScript file, its favicon and logo with the GITWEB_CSS, GITWEB_JS
|
|
GITWEB_FAVICON and GITWEB_LOGO build configuration variables. By default
|
|
gitweb tries to find them in the same directory as gitweb.cgi script.
|
|
|
|
- You can optionally generate minified versions of gitweb.js and gitweb.css
|
|
by defining the JSMIN and CSSMIN build configuration variables. By default
|
|
the non-minified versions will be used. NOTE: if you enable this option,
|
|
substitute gitweb.min.js and gitweb.min.css for all uses of gitweb.js and
|
|
gitweb.css in the help files.
|
|
|
|
|
|
How to configure gitweb for your local system
|
|
---------------------------------------------
|
|
|
|
You can specify the following configuration variables when building GIT:
|
|
|
|
* GIT_BINDIR
|
|
Points where to find the git executable. You should set it up to
|
|
the place where the git binary was installed (usually /usr/bin) if you
|
|
don't install git from sources together with gitweb. [Default: $(bindir)]
|
|
* GITWEB_SITENAME
|
|
Shown in the title of all generated pages, defaults to the server name
|
|
(SERVER_NAME CGI environment variable) if not set. [No default]
|
|
* GITWEB_PROJECTROOT
|
|
The root directory for all projects shown by gitweb. Must be set
|
|
correctly for gitweb to find repositories to display. See also
|
|
"Gitweb repositories" in the INSTALL file for gitweb. [Default: /pub/git]
|
|
* GITWEB_PROJECT_MAXDEPTH
|
|
The filesystem traversing limit for getting the project list; the number
|
|
is taken as depth relative to the projectroot. It is used when
|
|
GITWEB_LIST is a directory (or is not set; then project root is used).
|
|
This is meant to speed up project listing on large work trees by limiting
|
|
search depth. [Default: 2007]
|
|
* GITWEB_LIST
|
|
Points to a directory to scan for projects (defaults to project root
|
|
if not set / if empty) or to a file with explicit listing of projects
|
|
(together with projects' ownership). See "Generating projects list
|
|
using gitweb" in INSTALL file for gitweb to find out how to generate
|
|
such file from scan of a directory. [No default, which means use root
|
|
directory for projects]
|
|
* GITWEB_EXPORT_OK
|
|
Show repository only if this file exists (in repository). Only
|
|
effective if this variable evaluates to true. [No default / Not set]
|
|
* GITWEB_STRICT_EXPORT
|
|
Only allow viewing of repositories also shown on the overview page.
|
|
This for example makes GITWEB_EXPORT_OK to 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. [No default]
|
|
* GITWEB_HOMETEXT
|
|
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]
|
|
* GITWEB_SITE_FOOTER
|
|
Filename of html text to include at bottom of each page. Relative to
|
|
gitweb.cgi script. [No default]
|
|
* GITWEB_HOME_LINK_STR
|
|
String of the home link on top of all pages, leading to $home_link
|
|
(usually main gitweb page, which means projects list). Used as first
|
|
part of gitweb view "breadcrumb trail": <home> / <project> / <view>.
|
|
[Default: projects]
|
|
* GITWEB_SITENAME
|
|
Name of your site or organization to appear in page titles. Set it
|
|
to something descriptive for clearer bookmarks etc. If not set
|
|
(if empty) gitweb uses "$SERVER_NAME Git", or "Untitled Git" if
|
|
SERVER_NAME CGI environment variable is not set (e.g. if running
|
|
gitweb as standalone script). [No default]
|
|
* GITWEB_BASE_URL
|
|
Git base URLs used for URL to where fetch project from, i.e. full
|
|
URL is "$git_base_url/$project". Shown on projects summary page.
|
|
Repository URL for project can be also configured per repository; this
|
|
takes precedence over URLs composed from base URL and a project name.
|
|
Note that you can setup multiple base URLs (for example one for
|
|
git:// protocol access, another for http:// access) from the gitweb
|
|
config file. [No default]
|
|
* GITWEB_CSS
|
|
Points to the location where you put gitweb.css on your web server
|
|
(or to be more generic, the URI of gitweb stylesheet). Relative to the
|
|
base URI of gitweb. Note that you can setup multiple stylesheets from
|
|
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
|
|
corner of each gitweb page, and used as logo for Atom feed). Relative
|
|
to base URI of gitweb. [Default: static/git-logo.png]
|
|
* GITWEB_FAVICON
|
|
Points to the location where you put git-favicon.png on your web server
|
|
(or to be more generic URI of favicon, assumed to be image/png type;
|
|
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_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
|
|
gitweb configuration" section below, and top of 'gitweb.cgi' for their
|
|
full list and description. If the environment variable GITWEB_CONFIG
|
|
is set when gitweb.cgi is executed, then the file specified in the
|
|
environment variable will be loaded instead of the file specified
|
|
when gitweb.cgi was created. [Default: gitweb_config.perl]
|
|
* GITWEB_CONFIG_SYSTEM
|
|
This Perl file will be loaded using 'do' as a fallback if GITWEB_CONFIG
|
|
does not exist. If the environment variable GITWEB_CONFIG_SYSTEM is set
|
|
when gitweb.cgi is executed, then the file specified in the environment
|
|
variable will be loaded instead of the file specified when gitweb.cgi was
|
|
created. [Default: /etc/gitweb.conf]
|
|
* 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]
|
|
|
|
Build example
|
|
~~~~~~~~~~~~~
|
|
|
|
- To install gitweb to /var/www/cgi-bin/gitweb/, when git wrapper
|
|
is installed at /usr/local/bin/git, the repositories (projects)
|
|
we want to display are under /home/local/scm, and you do not use
|
|
minifiers, you can do
|
|
|
|
make GITWEB_PROJECTROOT="/home/local/scm" \
|
|
GITWEB_JS="gitweb/static/gitweb.js" \
|
|
GITWEB_CSS="gitweb/static/gitweb.css" \
|
|
GITWEB_LOGO="gitweb/static/git-logo.png" \
|
|
GITWEB_FAVICON="gitweb/static/git-favicon.png" \
|
|
bindir=/usr/local/bin \
|
|
gitweb
|
|
|
|
make gitwebdir=/var/www/cgi-bin/gitweb install-gitweb
|
|
|
|
|
|
Gitweb config file
|
|
------------------
|
|
|
|
See also "Runtime gitweb configuration" section in README file
|
|
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
|
|
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.
|
|
|
|
Note that the GITWEB_CONFIG_SYSTEM system-wide configuration file is
|
|
only used for instances that lack per-instance configuration file.
|
|
You can use GITWEB_CONFIG_COMMON common system-wide configuration
|
|
file (normally /etc/gitweb-common.conf) to keep common default
|
|
settings that apply to all instances. 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.
|
|
|
|
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;
|
|
|
|
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 to run at level 6 by
|
|
adding the following lines to your $GITWEB_CONFIG:
|
|
|
|
$known_snapshot_formats{'zip'}{'disabled'} = 1;
|
|
$known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
|
|
|
|
|
|
Gitweb repositories
|
|
-------------------
|
|
|
|
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" and "Advanced web server setup" sections
|
|
in gitweb(1) manpage.
|
|
|
|
|
|
- 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>
|