gitweb / INSTALLon commit Merge branch 'maint' (12d6697)
   1GIT web Interface (gitweb) Installation
   2=======================================
   3
   4First you have to generate gitweb.cgi from gitweb.perl using
   5"make gitweb/gitweb.cgi", then copy appropriate files (gitweb.cgi,
   6gitweb.css, git-logo.png and git-favicon.png) to their destination.
   7For example if git was (or is) installed with /usr prefix, you can do
   8
   9        $ make prefix=/usr gitweb/gitweb.cgi  ;# as yourself
  10        # cp gitweb/git* /var/www/cgi-bin/    ;# as root
  11
  12Alternatively you can use autoconf generated ./configure script to
  13set up path to git binaries (via config.mak.autogen), so you can write
  14instead
  15
  16        $ make configure                     ;# as yourself
  17        $ ./configure --prefix=/usr          ;# as yourself
  18        $ make gitweb/gitweb.cgi             ;# as yourself
  19        # cp gitweb/git* /var/www/cgi-bin/   ;# as root
  20
  21The above example assumes that your web server is configured to run
  22[executable] files in /var/www/cgi-bin/ as server scripts (as CGI
  23scripts).
  24
  25
  26Build time configuration
  27------------------------
  28
  29See also "How to configure gitweb for your local system" in README
  30file for gitweb (in gitweb/README).
  31
  32- There are many configuration variables which affects building of
  33  gitweb.cgi; see "default configuration for gitweb" section in main
  34  (top dir) Makefile, and instructions for building gitweb/gitweb.cgi
  35  target.
  36
  37  One of most important is where to find git wrapper binary. Gitweb
  38  tries to find git wrapper at $(bindir)/git, so you have to set $bindir
  39  when building gitweb.cgi, or $prefix from which $bindir is derived. If
  40  you build and install gitweb together with the rest of git suite,
  41  there should be no problems. Otherwise, if git was for example
  42  installed from a binary package, you have to set $prefix (or $bindir)
  43  accordingly.
  44
  45- Another important issue is where are git repositories you want to make
  46  available to gitweb. By default gitweb search for repositories under
  47  /pub/git; if you want to have projects somewhere else, like /home/git,
  48  use GITWEB_PROJECTROOT build configuration variable.
  49
  50  By default all git repositories under projectroot are visible and
  51  available to gitweb. List of projects is generated by default by
  52  scanning the projectroot directory for git repositories. This can be
  53  changed (configured) as described in "Gitweb repositories" section
  54  below.
  55
  56  Note that gitweb deals directly with object database, and does not
  57  need working directory; the name of the project is the name of its
  58  repository object database, usually projectname.git for bare
  59  repositories. If you want to provide gitweb access to non-bare (live)
  60  repository, you can make projectname.git symbolic link under
  61  projectroot linking to projectname/.git (but it is just
  62  a suggestion).
  63
  64- You can control where gitweb tries to find its main CSS style file,
  65  its favicon and logo with GITWEB_CSS, GITWEB_FAVICON and GITWEB_LOGO
  66  build configuration variables. By default gitweb tries to find them
  67  in the same directory as gitweb.cgi script.
  68
  69Build example
  70~~~~~~~~~~~~~
  71
  72- To install gitweb to /var/www/cgi-bin/gitweb/ when git wrapper
  73  is installed at /usr/local/bin/git and the repositories (projects)
  74  we want to display are under /home/local/scm, you can do
  75
  76        make GITWEB_PROJECTROOT="/home/local/scm" \
  77             GITWEB_CSS="/gitweb/gitweb.css" \
  78             GITWEB_LOGO="/gitweb/git-logo.png" \
  79             GITWEB_FAVICON="/gitweb/git-favicon.png" \
  80             bindir=/usr/local/bin \
  81             gitweb/gitweb.cgi
  82
  83        cp -fv ~/git/gitweb/gitweb.{cgi,css} \
  84               ~/git/gitweb/git-{favicon,logo}.png \
  85             /var/www/cgi-bin/gitweb/
  86
  87
  88Gitweb config file
  89------------------
  90
  91See also "Runtime gitweb configuration" section in README file
  92for gitweb (in gitweb/README).
  93
  94- You can configure gitweb further using gitweb configuration file;
  95  by default it is file named gitweb_config.perl in the same place as
  96  gitweb.cgi script. You can control default place for config file
  97  using GITWEB_CONFIG build configuration variable, and you can set it
  98  using GITWEB_CONFIG environmental variable.
  99
 100- Gitweb config file is [fragment] of perl code. You can set variables
 101  using "our $variable = value"; text from "#" character until the end
 102  of a line is ignored. See perlsyn(1) for details.
 103
 104  See the top of gitweb.perl file for examples of customizable options.
 105
 106
 107Gitweb repositories:
 108--------------------
 109
 110- By default all git repositories under projectroot are visible and
 111  available to gitweb. List of projects is generated by default by
 112  scanning the projectroot directory for git repositories (for object
 113  databases to be more exact).
 114
 115  You can provide pre-generated list of [visible] repositories,
 116  together with information about their owners (the project ownership
 117  is taken from owner of repository directory otherwise), by setting
 118  GITWEB_LIST build configuration variable (or $projects_list variable
 119  in gitweb config file) to point to a plain file.
 120
 121  Each line of projects list file should consist of url-encoded path
 122  to project repository database (relative to projectroot) separated
 123  by space from url-encoded project owner; spaces in both project path
 124  and project owner have to be encoded as either '%20' or '+'.
 125
 126  You can generate projects list index file using project_index action
 127  (the 'TXT' link on projects list page) directly from gitweb.
 128
 129- By default even if project is not visible on projects list page, you
 130  can view it nevertheless by hand-crafting gitweb URL. You can set
 131  GITWEB_STRICT_EXPORT build configuration variable (or $strict_export
 132  variable in gitweb config file) to only allow viewing of
 133  repositories also shown on the overview page.
 134
 135- Alternatively, you can configure gitweb to only list and allow
 136  viewing of the explicitly exported repositories, via
 137  GITWEB_EXPORT_OK build configuration variable (or $export_ok
 138  variable in gitweb config file). If it evaluates to true, gitweb
 139  show repository only if this file exists in its object database
 140  (if directory has the magic file $export_ok).
 141
 142
 143Requirements
 144------------
 145
 146 - Core git tools
 147 - Perl
 148 - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename.
 149 - web server
 150
 151
 152Example web server configuration
 153~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 154
 155See also "Webserver configuration" section in README file for gitweb
 156(in gitweb/README).
 157
 158
 159- Apache2, gitweb installed as CGI script,
 160  under /var/www/cgi-bin/
 161
 162        ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"
 163
 164        <Directory "/var/www/cgi-bin">
 165            Options Indexes FollowSymlinks ExecCGI
 166            AllowOverride None
 167            Order allow,deny
 168            Allow from all
 169        </Directory>
 170
 171- Apache2, gitweb installed as mod_perl legacy script,
 172  under /var/www/perl/
 173
 174        Alias /perl "/var/www/perl"
 175
 176        <Directory "/var/www/perl">
 177            SetHandler perl-script
 178            PerlResponseHandler ModPerl::Registry
 179            PerlOptions +ParseHeaders
 180            Options Indexes FollowSymlinks +ExecCGI
 181            AllowOverride None
 182            Order allow,deny
 183            Allow from all
 184        </Directory>