Commit | Line | Data |
---|---|---|
cd67c8e0 JN |
1 | GIT web Interface (gitweb) Installation |
2 | ======================================= | |
3 | ||
4 | First you have to generate gitweb.cgi from gitweb.perl using | |
18d05328 PKS |
5 | "make gitweb", then "make install-gitweb" appropriate files |
6 | (gitweb.cgi, gitweb.js, gitweb.css, git-logo.png and git-favicon.png) | |
7 | to their destination. For example if git was (or is) installed with | |
8 | /usr prefix and gitwebdir is /var/www/cgi-bin, you can do | |
cd67c8e0 | 9 | |
152d9434 JN |
10 | $ make prefix=/usr gitweb ;# as yourself |
11 | # make gitwebdir=/var/www/cgi-bin install-gitweb ;# as root | |
cd67c8e0 JN |
12 | |
13 | Alternatively you can use autoconf generated ./configure script to | |
14 | set up path to git binaries (via config.mak.autogen), so you can write | |
15 | instead | |
16 | ||
17 | $ make configure ;# as yourself | |
18 | $ ./configure --prefix=/usr ;# as yourself | |
e3918594 | 19 | $ make gitweb ;# as yourself |
152d9434 JN |
20 | # make gitwebdir=/var/www/cgi-bin \ |
21 | install-gitweb ;# as root | |
cd67c8e0 JN |
22 | |
23 | The above example assumes that your web server is configured to run | |
24 | [executable] files in /var/www/cgi-bin/ as server scripts (as CGI | |
25 | scripts). | |
26 | ||
27 | ||
80b4dfee JN |
28 | Requirements |
29 | ------------ | |
30 | ||
31 | - Core git tools | |
7d5b30e0 | 32 | - Perl 5.8 |
80b4dfee JN |
33 | - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename. |
34 | - web server | |
35 | ||
36 | The following optional Perl modules are required for extra features | |
80b4dfee JN |
37 | - CGI::Fast and FCGI - for running gitweb as FastCGI script |
38 | - HTML::TagCloud - for fancy tag cloud in project list view | |
39 | - HTTP::Date or Time::ParseDate - to support If-Modified-Since for feeds | |
40 | ||
41 | ||
cd67c8e0 JN |
42 | Build time configuration |
43 | ------------------------ | |
44 | ||
cee694d0 | 45 | See also "How to configure gitweb for your local system" section below. |
cd67c8e0 | 46 | |
eae7a759 | 47 | - There are many configuration variables which affect building of |
cd67c8e0 | 48 | gitweb.cgi; see "default configuration for gitweb" section in main |
e3918594 | 49 | (top dir) Makefile, and instructions for building gitweb target. |
cd67c8e0 | 50 | |
eae7a759 RGS |
51 | One of the most important is where to find the git wrapper binary. Gitweb |
52 | tries to find the git wrapper at $(bindir)/git, so you have to set $bindir | |
cd67c8e0 | 53 | when building gitweb.cgi, or $prefix from which $bindir is derived. If |
eae7a759 | 54 | you build and install gitweb together with the rest of the git suite, |
cd67c8e0 JN |
55 | there should be no problems. Otherwise, if git was for example |
56 | installed from a binary package, you have to set $prefix (or $bindir) | |
57 | accordingly. | |
58 | ||
59 | - Another important issue is where are git repositories you want to make | |
eae7a759 | 60 | available to gitweb. By default gitweb searches for repositories under |
cd67c8e0 JN |
61 | /pub/git; if you want to have projects somewhere else, like /home/git, |
62 | use GITWEB_PROJECTROOT build configuration variable. | |
63 | ||
64 | By default all git repositories under projectroot are visible and | |
eae7a759 | 65 | available to gitweb. The list of projects is generated by default by |
cd67c8e0 JN |
66 | scanning the projectroot directory for git repositories. This can be |
67 | changed (configured) as described in "Gitweb repositories" section | |
68 | below. | |
69 | ||
eae7a759 RGS |
70 | Note that gitweb deals directly with the object database, and does not |
71 | need a working directory; the name of the project is the name of its | |
cd67c8e0 JN |
72 | repository object database, usually projectname.git for bare |
73 | repositories. If you want to provide gitweb access to non-bare (live) | |
eae7a759 | 74 | repositories, you can make projectname.git a symbolic link under |
cd67c8e0 JN |
75 | projectroot linking to projectname/.git (but it is just |
76 | a suggestion). | |
77 | ||
78 | - You can control where gitweb tries to find its main CSS style file, | |
a8ab675f MR |
79 | its JavaScript file, its favicon and logo with the GITWEB_CSS, GITWEB_JS |
80 | GITWEB_FAVICON and GITWEB_LOGO build configuration variables. By default | |
81 | gitweb tries to find them in the same directory as gitweb.cgi script. | |
cd67c8e0 | 82 | |
a8ab675f MR |
83 | - You can optionally generate minified versions of gitweb.js and gitweb.css |
84 | by defining the JSMIN and CSSMIN build configuration variables. By default | |
85 | the non-minified versions will be used. NOTE: if you enable this option, | |
86 | substitute gitweb.min.js and gitweb.min.css for all uses of gitweb.js and | |
87 | gitweb.css in the help files. | |
0e6ce213 | 88 | |
cee694d0 JN |
89 | |
90 | How to configure gitweb for your local system | |
91 | --------------------------------------------- | |
92 | ||
93 | You can specify the following configuration variables when building GIT: | |
94 | ||
95 | * GIT_BINDIR | |
96 | Points where to find the git executable. You should set it up to | |
97 | the place where the git binary was installed (usually /usr/bin) if you | |
98 | don't install git from sources together with gitweb. [Default: $(bindir)] | |
99 | * GITWEB_SITENAME | |
100 | Shown in the title of all generated pages, defaults to the server name | |
101 | (SERVER_NAME CGI environment variable) if not set. [No default] | |
102 | * GITWEB_PROJECTROOT | |
103 | The root directory for all projects shown by gitweb. Must be set | |
104 | correctly for gitweb to find repositories to display. See also | |
105 | "Gitweb repositories" in the INSTALL file for gitweb. [Default: /pub/git] | |
106 | * GITWEB_PROJECT_MAXDEPTH | |
107 | The filesystem traversing limit for getting the project list; the number | |
108 | is taken as depth relative to the projectroot. It is used when | |
109 | GITWEB_LIST is a directory (or is not set; then project root is used). | |
110 | This is meant to speed up project listing on large work trees by limiting | |
111 | search depth. [Default: 2007] | |
112 | * GITWEB_LIST | |
113 | Points to a directory to scan for projects (defaults to project root | |
114 | if not set / if empty) or to a file with explicit listing of projects | |
115 | (together with projects' ownership). See "Generating projects list | |
116 | using gitweb" in INSTALL file for gitweb to find out how to generate | |
117 | such file from scan of a directory. [No default, which means use root | |
118 | directory for projects] | |
119 | * GITWEB_EXPORT_OK | |
120 | Show repository only if this file exists (in repository). Only | |
121 | effective if this variable evaluates to true. [No default / Not set] | |
122 | * GITWEB_STRICT_EXPORT | |
123 | Only allow viewing of repositories also shown on the overview page. | |
124 | This for example makes GITWEB_EXPORT_OK to decide if repository is | |
125 | available and not only if it is shown. If GITWEB_LIST points to | |
126 | file with list of project, only those repositories listed would be | |
127 | available for gitweb. [No default] | |
128 | * GITWEB_HOMETEXT | |
129 | Points to an .html file which is included on the gitweb project | |
130 | overview page ('projects_list' view), if it exists. Relative to | |
131 | gitweb.cgi script. [Default: indextext.html] | |
c1355b7f LH |
132 | * GITWEB_SITE_HTML_HEAD_STRING |
133 | html snippet to include in the <head> section of each page. [No default] | |
cee694d0 JN |
134 | * GITWEB_SITE_HEADER |
135 | Filename of html text to include at top of each page. Relative to | |
136 | gitweb.cgi script. [No default] | |
137 | * GITWEB_SITE_FOOTER | |
138 | Filename of html text to include at bottom of each page. Relative to | |
139 | gitweb.cgi script. [No default] | |
140 | * GITWEB_HOME_LINK_STR | |
141 | String of the home link on top of all pages, leading to $home_link | |
142 | (usually main gitweb page, which means projects list). Used as first | |
143 | part of gitweb view "breadcrumb trail": <home> / <project> / <view>. | |
144 | [Default: projects] | |
145 | * GITWEB_SITENAME | |
146 | Name of your site or organization to appear in page titles. Set it | |
147 | to something descriptive for clearer bookmarks etc. If not set | |
148 | (if empty) gitweb uses "$SERVER_NAME Git", or "Untitled Git" if | |
149 | SERVER_NAME CGI environment variable is not set (e.g. if running | |
150 | gitweb as standalone script). [No default] | |
151 | * GITWEB_BASE_URL | |
152 | Git base URLs used for URL to where fetch project from, i.e. full | |
153 | URL is "$git_base_url/$project". Shown on projects summary page. | |
154 | Repository URL for project can be also configured per repository; this | |
155 | takes precedence over URLs composed from base URL and a project name. | |
156 | Note that you can setup multiple base URLs (for example one for | |
157 | git:// protocol access, another for http:// access) from the gitweb | |
158 | config file. [No default] | |
159 | * GITWEB_CSS | |
160 | Points to the location where you put gitweb.css on your web server | |
161 | (or to be more generic, the URI of gitweb stylesheet). Relative to the | |
162 | base URI of gitweb. Note that you can setup multiple stylesheets from | |
163 | the gitweb config file. [Default: static/gitweb.css (or | |
164 | static/gitweb.min.css if the CSSMIN variable is defined / CSS minifier | |
165 | is used)] | |
560869e3 JN |
166 | * GITWEB_JS |
167 | Points to the location where you put gitweb.js on your web server | |
168 | (or to be more generic URI of JavaScript code used by gitweb). | |
169 | Relative to base URI of gitweb. [Default: static/gitweb.js (or | |
170 | static/gitweb.min.js if JSMIN build variable is defined / JavaScript | |
171 | minifier is used)] | |
172 | * CSSMIN, JSMIN | |
173 | Invocation of a CSS minifier or a JavaScript minifier, respectively, | |
174 | working as a filter (source on standard input, minified result on | |
175 | standard output). If set, it is used to generate a minified version of | |
176 | 'static/gitweb.css' or 'static/gitweb.js', respectively. *Note* that | |
177 | minified files would have *.min.css and *.min.js extension, which is | |
178 | important if you also set GITWEB_CSS and/or GITWEB_JS. [No default] | |
cee694d0 JN |
179 | * GITWEB_LOGO |
180 | Points to the location where you put git-logo.png on your web server | |
181 | (or to be more generic URI of logo, 72x27 size, displayed in top right | |
182 | corner of each gitweb page, and used as logo for Atom feed). Relative | |
183 | to base URI of gitweb. [Default: static/git-logo.png] | |
184 | * GITWEB_FAVICON | |
185 | Points to the location where you put git-favicon.png on your web server | |
186 | (or to be more generic URI of favicon, assumed to be image/png type; | |
187 | web browsers that support favicons (website icons) may display them | |
188 | in the browser's URL bar and next to site name in bookmarks). Relative | |
189 | to base URI of gitweb. [Default: static/git-favicon.png] | |
cee694d0 JN |
190 | * GITWEB_CONFIG |
191 | This Perl file will be loaded using 'do' and can be used to override any | |
192 | of the options above as well as some other options -- see the "Runtime | |
193 | gitweb configuration" section below, and top of 'gitweb.cgi' for their | |
194 | full list and description. If the environment variable GITWEB_CONFIG | |
195 | is set when gitweb.cgi is executed, then the file specified in the | |
196 | environment variable will be loaded instead of the file specified | |
197 | when gitweb.cgi was created. [Default: gitweb_config.perl] | |
198 | * GITWEB_CONFIG_SYSTEM | |
199 | This Perl file will be loaded using 'do' as a fallback if GITWEB_CONFIG | |
200 | does not exist. If the environment variable GITWEB_CONFIG_SYSTEM is set | |
201 | when gitweb.cgi is executed, then the file specified in the environment | |
202 | variable will be loaded instead of the file specified when gitweb.cgi was | |
203 | created. [Default: /etc/gitweb.conf] | |
204 | * HIGHLIGHT_BIN | |
205 | Path to the highlight executable to use (must be the one from | |
206 | http://www.andre-simon.de due to assumptions about parameters and output). | |
207 | Useful if highlight is not installed on your webserver's PATH. | |
208 | [Default: highlight] | |
209 | ||
cd67c8e0 JN |
210 | Build example |
211 | ~~~~~~~~~~~~~ | |
212 | ||
8515392f JN |
213 | - To install gitweb to /var/www/cgi-bin/gitweb/, when git wrapper |
214 | is installed at /usr/local/bin/git, the repositories (projects) | |
215 | we want to display are under /home/local/scm, and you do not use | |
216 | minifiers, you can do | |
cd67c8e0 JN |
217 | |
218 | make GITWEB_PROJECTROOT="/home/local/scm" \ | |
18d05328 PKS |
219 | GITWEB_JS="gitweb/static/gitweb.js" \ |
220 | GITWEB_CSS="gitweb/static/gitweb.css" \ | |
221 | GITWEB_LOGO="gitweb/static/git-logo.png" \ | |
222 | GITWEB_FAVICON="gitweb/static/git-favicon.png" \ | |
cd67c8e0 | 223 | bindir=/usr/local/bin \ |
e3918594 | 224 | gitweb |
cd67c8e0 | 225 | |
18d05328 | 226 | make gitwebdir=/var/www/cgi-bin/gitweb install-gitweb |
cd67c8e0 JN |
227 | |
228 | ||
229 | Gitweb config file | |
230 | ------------------ | |
231 | ||
232 | See also "Runtime gitweb configuration" section in README file | |
07ea4df2 | 233 | for gitweb (in gitweb/README), and gitweb.conf(5) manpage. |
cd67c8e0 | 234 | |
131d6afc | 235 | - You can configure gitweb further using the per-instance gitweb configuration file; |
eae7a759 RGS |
236 | by default this is a file named gitweb_config.perl in the same place as |
237 | gitweb.cgi script. You can control the default place for the config file | |
238 | using the GITWEB_CONFIG build configuration variable, and you can set it | |
239 | using the GITWEB_CONFIG environment variable. If this file does not | |
17a8b250 GP |
240 | exist, gitweb looks for a system-wide configuration file, normally |
241 | /etc/gitweb.conf. You can change the default using the | |
242 | GITWEB_CONFIG_SYSTEM build configuration variable, and override it | |
eae7a759 | 243 | through the GITWEB_CONFIG_SYSTEM environment variable. |
cd67c8e0 | 244 | |
0d2f7d1c JN |
245 | Note that the GITWEB_CONFIG_SYSTEM system-wide configuration file is |
246 | only used for instances that lack per-instance configuration file. | |
247 | You can use GITWEB_CONFIG_COMMON common system-wide configuration | |
248 | file (normally /etc/gitweb-common.conf) to keep common default | |
249 | settings that apply to all instances. Settings from per-instance or | |
131d6afc JN |
250 | system-wide configuration file override those from common system-wide |
251 | configuration file. | |
252 | ||
eae7a759 | 253 | - The gitweb config file is a fragment of perl code. You can set variables |
cd67c8e0 JN |
254 | using "our $variable = value"; text from "#" character until the end |
255 | of a line is ignored. See perlsyn(1) for details. | |
256 | ||
257 | See the top of gitweb.perl file for examples of customizable options. | |
258 | ||
52c813f2 JN |
259 | Config file example |
260 | ~~~~~~~~~~~~~~~~~~~ | |
cd67c8e0 | 261 | |
52c813f2 JN |
262 | To enable blame, pickaxe search, and snapshot support, while allowing |
263 | individual projects to turn them off, put the following in your | |
264 | GITWEB_CONFIG file: | |
265 | ||
266 | $feature{'blame'}{'default'} = [1]; | |
267 | $feature{'blame'}{'override'} = 1; | |
268 | ||
269 | $feature{'pickaxe'}{'default'} = [1]; | |
270 | $feature{'pickaxe'}{'override'} = 1; | |
271 | ||
1e3a2eb6 | 272 | $feature{'snapshot'}{'default'} = ['zip', 'tgz']; |
52c813f2 JN |
273 | $feature{'snapshot'}{'override'} = 1; |
274 | ||
b4c07792 MR |
275 | If you allow overriding for the snapshot feature, you can specify which |
276 | snapshot formats are globally disabled. You can also add any command line | |
277 | options you want (such as setting the compression level). For instance, | |
278 | you can disable Zip compressed snapshots and set GZip to run at level 6 by | |
279 | adding the following lines to your $GITWEB_CONFIG: | |
280 | ||
281 | $known_snapshot_formats{'zip'}{'disabled'} = 1; | |
282 | $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6']; | |
283 | ||
52c813f2 JN |
284 | |
285 | Gitweb repositories | |
286 | ------------------- | |
cd67c8e0 | 287 | |
07ea4df2 JN |
288 | By default gitweb shows all git repositories under single common repository |
289 | root on a local filesystem; see description of GITWEB_PROJECTROOT build-time | |
290 | configuration variable above (and also of GITWEB_LIST). | |
291 | ||
292 | More advanced usage, like limiting access or visibility of repositories and | |
293 | managing multiple roots are described on gitweb manpage. | |
52c813f2 | 294 | |
cd67c8e0 | 295 | |
cd67c8e0 JN |
296 | Example web server configuration |
297 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
298 | ||
07ea4df2 JN |
299 | See also "Webserver configuration" and "Advanced web server setup" sections |
300 | in gitweb(1) manpage. | |
cd67c8e0 JN |
301 | |
302 | ||
303 | - Apache2, gitweb installed as CGI script, | |
304 | under /var/www/cgi-bin/ | |
305 | ||
306 | ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" | |
307 | ||
308 | <Directory "/var/www/cgi-bin"> | |
309 | Options Indexes FollowSymlinks ExecCGI | |
310 | AllowOverride None | |
311 | Order allow,deny | |
312 | Allow from all | |
313 | </Directory> | |
314 | ||
315 | - Apache2, gitweb installed as mod_perl legacy script, | |
316 | under /var/www/perl/ | |
317 | ||
318 | Alias /perl "/var/www/perl" | |
319 | ||
320 | <Directory "/var/www/perl"> | |
321 | SetHandler perl-script | |
322 | PerlResponseHandler ModPerl::Registry | |
323 | PerlOptions +ParseHeaders | |
324 | Options Indexes FollowSymlinks +ExecCGI | |
325 | AllowOverride None | |
326 | Order allow,deny | |
327 | Allow from all | |
328 | </Directory> |