| 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 |
| - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename. |
| - web server |
| |
| The following optional Perl modules are required for extra features |
| - Digest::MD5 - for gravatar support |
| - 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 if per-instance configuration file exists, then system-wide |
| configuration is _not used at all_. This is quite untypical and suprising |
| behavior. On the other hand changing current behavior would break backwards |
| compatibility and can lead to unexpected changes in gitweb behavior. |
| Therefore gitweb also looks for common system-wide configuration file, |
| normally /etc/gitweb-common.conf (set during build time using build time |
| configuration variable GITWEB_CONFIG_COMMON, set it at runtime using |
| environment variable with the same name). 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> |