gitweb: Add some installation notes in gitweb/INSTALL
Add some installation and configuration notes for gitweb in gitweb/INSTALL. Make use of filling gitweb configuration by Makefile. It does not cover (yet?) all the configuration variables and options. Some of contents duplicates information in gitweb/README file (it is referred from gitweb/INSTALL). Signed-off-by: Jakub Narebski <jnareb@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
Jakub Narebski committed
Mar 24, 2007 at 20:59 UTC
cd67c8e0bc6f61ffccc12d1775bc1a200df5fe85
1 file changed
+184
gitweb/INSTALL
new
+184
@@ -0,0 +1,184 @@
1
+GIT web Interface (gitweb) Installation
2
+=======================================
3
+
4
+First you have to generate gitweb.cgi from gitweb.perl using
5
+"make gitweb/gitweb.cgi", then copy appropriate files (gitweb.cgi,
6
+gitweb.css, git-logo.png and git-favicon.png) to their destination.
7
+For 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
+
12
+Alternatively you can use autoconf generated ./configure script to
13
+set up path to git binaries (via config.mak.autogen), so you can write
14
+instead
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
+
21
+The above example assumes that your web server is configured to run
22
+[executable] files in /var/www/cgi-bin/ as server scripts (as CGI
23
+scripts).
24
+
25
+
26
+Build time configuration
27
+------------------------
28
+
29
+See also "How to configure gitweb for your local system" in README
30
+file 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
+
69
+Build 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
+
88
+Gitweb config file
89
+------------------
90
+
91
+See also "Runtime gitweb configuration" section in README file
92
+for 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
+
107
+Gitweb 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
+
143
+Requirements
144
+------------
145
+
146
+ - Core git tools
147
+ - Perl
148
+ - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename.
149
+ - web server
150
+
151
+
152
+Example web server configuration
153
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
154
+
155
+See 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>