diff options
Diffstat (limited to 'gitweb/INSTALL')
| -rw-r--r-- | gitweb/INSTALL | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/gitweb/INSTALL b/gitweb/INSTALL new file mode 100644 index 0000000000..b76a0cffff --- /dev/null +++ b/gitweb/INSTALL @@ -0,0 +1,266 @@ +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; + +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 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> |