1GIT web Interface (gitweb) Installation 2======================================= 3 4First you have to generate gitweb.cgi from gitweb.perl using 5"make gitweb", then "make install-gitweb" appropriate files 6(gitweb.cgi, gitweb.js, gitweb.css, git-logo.png and git-favicon.png) 7to their destination. For example if git was (or is) installed with 8/usr prefix and gitwebdir is /var/www/cgi-bin, you can do 9 10 $ make prefix=/usr gitweb ;# as yourself 11 # make gitwebdir=/var/www/cgi-bin install-gitweb ;# as root 12 13Alternatively you can use autoconf generated ./configure script to 14set up path to git binaries (via config.mak.autogen), so you can write 15instead 16 17 $ make configure ;# as yourself 18 $ ./configure --prefix=/usr ;# as yourself 19 $ make gitweb ;# as yourself 20 # make gitwebdir=/var/www/cgi-bin \ 21 install-gitweb ;# as root 22 23The above example assumes that your web server is configured to run 24[executable] files in /var/www/cgi-bin/ as server scripts (as CGI 25scripts). 26 27 28Build time configuration 29------------------------ 30 31See also "How to configure gitweb for your local system" section below. 32 33- There are many configuration variables which affect building of 34 gitweb.cgi; see "default configuration for gitweb" section in main 35 (top dir) Makefile, and instructions for building gitweb target. 36 37 One of the most important is where to find the git wrapper binary. Gitweb 38 tries to find the 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 the 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 searches 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. The 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 the object database, and does not 57 need a 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 repositories, you can make projectname.git a 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 JavaScript file, its favicon and logo with the GITWEB_CSS, GITWEB_JS 66 GITWEB_FAVICON and GITWEB_LOGO build configuration variables. By default 67 gitweb tries to find them in the same directory as gitweb.cgi script. 68 69- You can optionally generate minified versions of gitweb.js and gitweb.css 70 by defining the JSMIN and CSSMIN build configuration variables. By default 71 the non-minified versions will be used. NOTE: if you enable this option, 72 substitute gitweb.min.js and gitweb.min.css for all uses of gitweb.js and 73 gitweb.css in the help files. 74 75 76How to configure gitweb for your local system 77--------------------------------------------- 78 79You can specify the following configuration variables when building GIT: 80 81 * GIT_BINDIR 82 Points where to find the git executable. You should set it up to 83 the place where the git binary was installed (usually /usr/bin) if you 84 don't install git from sources together with gitweb. [Default: $(bindir)] 85 * GITWEB_SITENAME 86 Shown in the title of all generated pages, defaults to the server name 87 (SERVER_NAME CGI environment variable) if not set. [No default] 88 * GITWEB_PROJECTROOT 89 The root directory for all projects shown by gitweb. Must be set 90 correctly for gitweb to find repositories to display. See also 91 "Gitweb repositories" in the INSTALL file for gitweb. [Default: /pub/git] 92 * GITWEB_PROJECT_MAXDEPTH 93 The filesystem traversing limit for getting the project list; the number 94 is taken as depth relative to the projectroot. It is used when 95 GITWEB_LIST is a directory (or is not set; then project root is used). 96 This is meant to speed up project listing on large work trees by limiting 97 search depth. [Default: 2007] 98 * GITWEB_LIST 99 Points to a directory to scan for projects (defaults to project root 100 if not set / if empty) or to a file with explicit listing of projects 101 (together with projects' ownership). See "Generating projects list 102 using gitweb" in INSTALL file for gitweb to find out how to generate 103 such file from scan of a directory. [No default, which means use root 104 directory for projects] 105 * GITWEB_EXPORT_OK 106 Show repository only if this file exists (in repository). Only 107 effective if this variable evaluates to true. [No default / Not set] 108 * GITWEB_STRICT_EXPORT 109 Only allow viewing of repositories also shown on the overview page. 110 This for example makes GITWEB_EXPORT_OK to decide if repository is 111 available and not only if it is shown. If GITWEB_LIST points to 112 file with list of project, only those repositories listed would be 113 available for gitweb. [No default] 114 * GITWEB_HOMETEXT 115 Points to an .html file which is included on the gitweb project 116 overview page ('projects_list' view), if it exists. Relative to 117 gitweb.cgi script. [Default: indextext.html] 118 * GITWEB_SITE_HEADER 119 Filename of html text to include at top of each page. Relative to 120 gitweb.cgi script. [No default] 121 * GITWEB_SITE_FOOTER 122 Filename of html text to include at bottom of each page. Relative to 123 gitweb.cgi script. [No default] 124 * GITWEB_HOME_LINK_STR 125 String of the home link on top of all pages, leading to $home_link 126 (usually main gitweb page, which means projects list). Used as first 127 part of gitweb view "breadcrumb trail": <home> / <project> / <view>. 128 [Default: projects] 129 * GITWEB_SITENAME 130 Name of your site or organization to appear in page titles. Set it 131 to something descriptive for clearer bookmarks etc. If not set 132 (if empty) gitweb uses "$SERVER_NAME Git", or "Untitled Git" if 133 SERVER_NAME CGI environment variable is not set (e.g. if running 134 gitweb as standalone script). [No default] 135 * GITWEB_BASE_URL 136 Git base URLs used for URL to where fetch project from, i.e. full 137 URL is "$git_base_url/$project". Shown on projects summary page. 138 Repository URL for project can be also configured per repository; this 139 takes precedence over URLs composed from base URL and a project name. 140 Note that you can setup multiple base URLs (for example one for 141 git:// protocol access, another for http:// access) from the gitweb 142 config file. [No default] 143 * GITWEB_CSS 144 Points to the location where you put gitweb.css on your web server 145 (or to be more generic, the URI of gitweb stylesheet). Relative to the 146 base URI of gitweb. Note that you can setup multiple stylesheets from 147 the gitweb config file. [Default: static/gitweb.css (or 148 static/gitweb.min.css if the CSSMIN variable is defined / CSS minifier 149 is used)] 150 * GITWEB_JS 151 Points to the location where you put gitweb.js on your web server 152 (or to be more generic URI of JavaScript code used by gitweb). 153 Relative to base URI of gitweb. [Default: static/gitweb.js (or 154 static/gitweb.min.js if JSMIN build variable is defined / JavaScript 155 minifier is used)] 156 * CSSMIN, JSMIN 157 Invocation of a CSS minifier or a JavaScript minifier, respectively, 158 working as a filter (source on standard input, minified result on 159 standard output). If set, it is used to generate a minified version of 160 'static/gitweb.css' or 'static/gitweb.js', respectively. *Note* that 161 minified files would have *.min.css and *.min.js extension, which is 162 important if you also set GITWEB_CSS and/or GITWEB_JS. [No default] 163 * GITWEB_LOGO 164 Points to the location where you put git-logo.png on your web server 165 (or to be more generic URI of logo, 72x27 size, displayed in top right 166 corner of each gitweb page, and used as logo for Atom feed). Relative 167 to base URI of gitweb. [Default: static/git-logo.png] 168 * GITWEB_FAVICON 169 Points to the location where you put git-favicon.png on your web server 170 (or to be more generic URI of favicon, assumed to be image/png type; 171 web browsers that support favicons (website icons) may display them 172 in the browser's URL bar and next to site name in bookmarks). Relative 173 to base URI of gitweb. [Default: static/git-favicon.png] 174 * GITWEB_CONFIG 175 This Perl file will be loaded using 'do' and can be used to override any 176 of the options above as well as some other options -- see the "Runtime 177 gitweb configuration" section below, and top of 'gitweb.cgi' for their 178 full list and description. If the environment variable GITWEB_CONFIG 179 is set when gitweb.cgi is executed, then the file specified in the 180 environment variable will be loaded instead of the file specified 181 when gitweb.cgi was created. [Default: gitweb_config.perl] 182 * GITWEB_CONFIG_SYSTEM 183 This Perl file will be loaded using 'do' as a fallback if GITWEB_CONFIG 184 does not exist. If the environment variable GITWEB_CONFIG_SYSTEM is set 185 when gitweb.cgi is executed, then the file specified in the environment 186 variable will be loaded instead of the file specified when gitweb.cgi was 187 created. [Default: /etc/gitweb.conf] 188 * HIGHLIGHT_BIN 189 Path to the highlight executable to use (must be the one from 190 http://www.andre-simon.de due to assumptions about parameters and output). 191 Useful if highlight is not installed on your webserver's PATH. 192 [Default: highlight] 193 194Build example 195~~~~~~~~~~~~~ 196 197- To install gitweb to /var/www/cgi-bin/gitweb/, when git wrapper 198 is installed at /usr/local/bin/git, the repositories (projects) 199 we want to display are under /home/local/scm, and you do not use 200 minifiers, you can do 201 202 make GITWEB_PROJECTROOT="/home/local/scm" \ 203 GITWEB_JS="gitweb/static/gitweb.js" \ 204 GITWEB_CSS="gitweb/static/gitweb.css" \ 205 GITWEB_LOGO="gitweb/static/git-logo.png" \ 206 GITWEB_FAVICON="gitweb/static/git-favicon.png" \ 207 bindir=/usr/local/bin \ 208 gitweb 209 210 make gitwebdir=/var/www/cgi-bin/gitweb install-gitweb 211 212 213Gitweb config file 214------------------ 215 216See also "Runtime gitweb configuration" section in README file 217for gitweb (in gitweb/README). 218 219- You can configure gitweb further using the gitweb configuration file; 220 by default this is a file named gitweb_config.perl in the same place as 221 gitweb.cgi script. You can control the default place for the config file 222 using the GITWEB_CONFIG build configuration variable, and you can set it 223 using the GITWEB_CONFIG environment variable. If this file does not 224 exist, gitweb looks for a system-wide configuration file, normally 225 /etc/gitweb.conf. You can change the default using the 226 GITWEB_CONFIG_SYSTEM build configuration variable, and override it 227 through the GITWEB_CONFIG_SYSTEM environment variable. 228 229- The gitweb config file is a fragment of perl code. You can set variables 230 using "our $variable = value"; text from "#" character until the end 231 of a line is ignored. See perlsyn(1) for details. 232 233 See the top of gitweb.perl file for examples of customizable options. 234 235Config file example 236~~~~~~~~~~~~~~~~~~~ 237 238To enable blame, pickaxe search, and snapshot support, while allowing 239individual projects to turn them off, put the following in your 240GITWEB_CONFIG file: 241 242 $feature{'blame'}{'default'} = [1]; 243 $feature{'blame'}{'override'} = 1; 244 245 $feature{'pickaxe'}{'default'} = [1]; 246 $feature{'pickaxe'}{'override'} = 1; 247 248 $feature{'snapshot'}{'default'} = ['zip', 'tgz']; 249 $feature{'snapshot'}{'override'} = 1; 250 251If you allow overriding for the snapshot feature, you can specify which 252snapshot formats are globally disabled. You can also add any command line 253options you want (such as setting the compression level). For instance, 254you can disable Zip compressed snapshots and set GZip to run at level 6 by 255adding the following lines to your $GITWEB_CONFIG: 256 257 $known_snapshot_formats{'zip'}{'disabled'} = 1; 258 $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6']; 259 260 261Gitweb repositories 262------------------- 263 264- By default all git repositories under projectroot are visible and 265 available to gitweb. The list of projects is generated by default by 266 scanning the projectroot directory for git repositories (for object 267 databases to be more exact). 268 269 You can provide a pre-generated list of [visible] repositories, 270 together with information about their owners (the project ownership 271 defaults to the owner of the repository directory otherwise), by setting 272 the GITWEB_LIST build configuration variable (or the $projects_list 273 variable in the gitweb config file) to point to a plain file. 274 275 Each line of the projects list file should consist of the url-encoded path 276 to the project repository database (relative to projectroot), followed 277 by the url-encoded project owner on the same line (separated by a space). 278 Spaces in both project path and project owner have to be encoded as either 279 '%20' or '+'. 280 281 Other characters that have to be url-encoded, i.e. replaced by '%' 282 followed by two-digit character number in octal, are: other whitespace 283 characters (because they are field separator in a record), plus sign '+' 284 (because it can be used as replacement for spaces), and percent sign '%' 285 (which is used for encoding / escaping). 286 287 You can generate the projects list index file using the project_index 288 action (the 'TXT' link on projects list page) directly from gitweb. 289 290- By default, even if a project is not visible on projects list page, you 291 can view it nevertheless by hand-crafting a gitweb URL. You can set the 292 GITWEB_STRICT_EXPORT build configuration variable (or the $strict_export 293 variable in the gitweb config file) to only allow viewing of 294 repositories also shown on the overview page. 295 296- Alternatively, you can configure gitweb to only list and allow 297 viewing of the explicitly exported repositories, via the 298 GITWEB_EXPORT_OK build configuration variable (or the $export_ok 299 variable in gitweb config file). If it evaluates to true, gitweb 300 shows repositories only if this file exists in its object database 301 (if directory has the magic file named $export_ok). 302 303- Finally, it is possible to specify an arbitrary perl subroutine that 304 will be called for each project to determine if it can be exported. 305 The subroutine receives an absolute path to the project as its only 306 parameter. 307 308 For example, if you use mod_perl to run the script, and have dumb 309 http protocol authentication configured for your repositories, you 310 can use the following hook to allow access only if the user is 311 authorized to read the files: 312 313 $export_auth_hook = sub { 314 use Apache2::SubRequest (); 315 use Apache2::Const -compile => qw(HTTP_OK); 316 my $path = "$_[0]/HEAD"; 317 my $r = Apache2::RequestUtil->request; 318 my $sub = $r->lookup_file($path); 319 return $sub->filename eq $path 320 && $sub->status == Apache2::Const::HTTP_OK; 321 }; 322 323 324Generating projects list using gitweb 325~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 326 327We assume that GITWEB_CONFIG has its default Makefile value, namely 328gitweb_config.perl. Put the following in gitweb_make_index.perl file: 329 330 $GITWEB_CONFIG = "gitweb_config.perl"; 331 do $GITWEB_CONFIG if -e $GITWEB_CONFIG; 332 333 $projects_list = $projectroot; 334 335Then create the following script to get list of project in the format 336suitable for GITWEB_LIST build configuration variable (or 337$projects_list variable in gitweb config): 338 339 #!/bin/sh 340 341 export GITWEB_CONFIG="gitweb_make_index.perl" 342 export GATEWAY_INTERFACE="CGI/1.1" 343 export HTTP_ACCEPT="*/*" 344 export REQUEST_METHOD="GET" 345 export QUERY_STRING="a=project_index" 346 347 perl -- /var/www/cgi-bin/gitweb.cgi 348 349 350Requirements 351------------ 352 353 - Core git tools 354 - Perl 355 - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename. 356 - web server 357 358The following optional Perl modules are required for extra features 359 - Digest::MD5 - for gravatar support 360 - CGI::Fast and FCGI - for running gitweb as FastCGI script 361 - HTML::TagCloud - for fancy tag cloud in project list view 362 - HTTP::Date or Time::ParseDate - to support If-Modified-Since for feeds 363 364 365Example web server configuration 366~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 367 368See also "Webserver configuration" section in README file for gitweb 369(in gitweb/README). 370 371 372- Apache2, gitweb installed as CGI script, 373 under /var/www/cgi-bin/ 374 375 ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" 376 377 <Directory "/var/www/cgi-bin"> 378 Options Indexes FollowSymlinks ExecCGI 379 AllowOverride None 380 Order allow,deny 381 Allow from all 382 </Directory> 383 384- Apache2, gitweb installed as mod_perl legacy script, 385 under /var/www/perl/ 386 387 Alias /perl "/var/www/perl" 388 389 <Directory "/var/www/perl"> 390 SetHandler perl-script 391 PerlResponseHandler ModPerl::Registry 392 PerlOptions +ParseHeaders 393 Options Indexes FollowSymlinks +ExecCGI 394 AllowOverride None 395 Order allow,deny 396 Allow from all 397 </Directory>