@matheusbsbs / matheus-bagliano / commits / cd67c8e0bc
Fork 0

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>