Commit | Line | Data |
---|---|---|
0a8f4f00 | 1 | GIT web Interface |
128eead1 | 2 | ================= |
0a8f4f00 JH |
3 | |
4 | The one working on: | |
5 | http://www.kernel.org/git/ | |
6 | ||
175fb6c0 | 7 | From the git version 1.4.0 gitweb is bundled with git. |
0a8f4f00 | 8 | |
5d043a3d | 9 | |
128eead1 MW |
10 | How to configure gitweb for your local system |
11 | --------------------------------------------- | |
5d043a3d | 12 | |
61fd2552 JN |
13 | See also "Build time configuration" section in INSTALL |
14 | file for gitweb (in gitweb/INSTALL). | |
15 | ||
5d043a3d | 16 | You can specify the following configuration variables when building GIT: |
61fd2552 JN |
17 | * GIT_BINDIR |
18 | Points out where to find git executable. You should set up it to | |
19 | the place where git binary was installed (usually /usr/bin) if you | |
20 | don't install git from sources together with gitweb. [Default: $(bindir)] | |
5d043a3d | 21 | * GITWEB_SITENAME |
61fd2552 JN |
22 | Shown in the title of all generated pages, defaults to the server name |
23 | (SERVER_NAME CGI environment variable) if not set. [No default] | |
5d043a3d | 24 | * GITWEB_PROJECTROOT |
61fd2552 JN |
25 | The root directory for all projects shown by gitweb. Must be set |
26 | correctly for gitweb to find repositories to display. See also | |
27 | "Gitweb repositories" in INSTALL file for gitweb. [Default: /pub/git] | |
28 | * GITWEB_PROJECT_MAXDEPTH | |
29 | The filesystem traversing limit for getting projects list; the number | |
30 | is taken as depth relative to the projectroot. It is used when | |
31 | GITWEB_LIST is a directory (or is not set; then project root is used). | |
32 | Is is meant to speed up project listing on large work trees by limiting | |
33 | find depth. [Default: 2007] | |
5d043a3d | 34 | * GITWEB_LIST |
61fd2552 JN |
35 | Points to a directory to scan for projects (defaults to project root |
36 | if not set / if empty) or to a file with explicit listing of projects | |
37 | (together with projects' ownership). See "Generating projects list | |
38 | using gitweb" in INSTALL file for gitweb to find out how to generate | |
39 | such file from scan of a directory. [No default, which means use root | |
40 | directory for projects] | |
41 | * GITWEB_EXPORT_OK | |
42 | Show repository only if this file exists (in repository). Only | |
43 | effective if this variable evaluates to true. [No default / Not set] | |
44 | * GITWEB_STRICT_EXPORT | |
45 | Only allow viewing of repositories also shown on the overview page. | |
46 | This for example makes GITWEB_EXPORT_OK to decide if repository is | |
47 | available and not only if it is shown. If GITWEB_LIST points to | |
48 | file with list of project, only those repositories listed would be | |
49 | available for gitweb. [No default] | |
5d043a3d | 50 | * GITWEB_HOMETEXT |
61fd2552 JN |
51 | Points to an .html file which is included on the gitweb project |
52 | overview page ('projects_list' view), if it exists. Relative to | |
53 | gitweb.cgi script. [Default: indextext.html] | |
54 | * GITWEB_SITE_HEADER | |
55 | Filename of html text to include at top of each page. Relative to | |
56 | gitweb.cgi script. [No default] | |
57 | * GITWEB_SITE_FOOTER | |
58 | Filename of html text to include at bottom of each page. Relative to | |
59 | gitweb.cgi script. [No default] | |
60 | * GITWEB_HOME_LINK_STR | |
61 | String of the home link on top of all pages, leading to $home_link | |
62 | (usually main gitweb page, which means projects list). Used as first | |
63 | part of gitweb view "breadcrumb trail": <home> / <project> / <view>. | |
64 | [Default: projects] | |
65 | * GITWEB_SITENAME | |
66 | Name of your site or organization to appear in page titles. Set it | |
67 | to something descriptive for clearer bookmarks etc. If not set | |
68 | (if empty) gitweb uses "$SERVER_NAME Git", or "Untitled Git" if | |
69 | SERVER_NAME CGI environment variable is not set (e.g. if running | |
70 | gitweb as standalone script). [No default] | |
71 | * GITWEB_BASE_URL | |
72 | Git base URLs used for URL to where fetch project from, i.e. full | |
73 | URL is "$git_base_url/$project". Shown on projects summary page. | |
74 | Repository URL for project can be also configured per repository; this | |
75 | takes precendence over URL composed from base URL and project name. | |
76 | Note that you can setup multiple base URLs (for example one for | |
77 | git:// protocol access, one for http:// access) from gitweb config | |
78 | file. [No default] | |
5d043a3d | 79 | * GITWEB_CSS |
61fd2552 JN |
80 | Points to the location where you put gitweb.css on your web server |
81 | (or to be more generic URI of gitweb stylesheet). Relative to base | |
82 | URI of gitweb. Note that you can setup multiple stylesheets from | |
83 | gitweb config file. [Default: gitweb.css] | |
281f2f6b | 84 | * GITWEB_LOGO |
61fd2552 JN |
85 | Points to the location where you put git-logo.png on your web server |
86 | (or to be more generic URI of logo, 72x27 size, displayed in top right | |
87 | corner of each gitweb page, and used as logo for Atom feed). Relative | |
88 | to base URI of gitweb. [Default: git-logo.png] | |
89 | * GITWEB_FAVICON | |
90 | Points to the location where you put git-favicon.png on your web server | |
91 | (or to be more generic URI of favicon, assumed to be image/png type; | |
92 | web browsers that support favicons (website icons) may display them | |
93 | in the browser's URL bar and next to site name in bookmarks). Relative | |
94 | to base URI of gitweb. [Default: git-favicon.png] | |
bb55f77f | 95 | * GITWEB_CONFIG |
61fd2552 JN |
96 | This Perl file will be loaded using 'do' and can be used to override any |
97 | of the options above as well as some other options -- see the "Runtime | |
98 | gitweb configuration" section below, and top of 'gitweb.cgi' for their | |
99 | full list and description. If the environment variable GITWEB_CONFIG | |
100 | is set when gitweb.cgi is executed, then the file specified in the | |
101 | environment variable will be loaded instead of the file specified | |
102 | when gitweb.cgi was created. [Default: gitweb_config.perl] | |
5d043a3d | 103 | |
128eead1 | 104 | |
45a3b12c PB |
105 | Runtime gitweb configuration |
106 | ---------------------------- | |
107 | ||
108 | You can adjust gitweb behaviour using the file specified in `GITWEB_CONFIG` | |
109 | (defaults to 'gitweb_config.perl' in the same directory as the CGI). | |
45a3b12c | 110 | The most notable thing that is not configurable at compile time are the |
61fd2552 JN |
111 | optional features, stored in the '%features' variable. |
112 | ||
113 | Ultimate description on how to reconfigure the default features setting | |
114 | in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found | |
115 | as comments inside 'gitweb.cgi'. | |
116 | ||
117 | See also "Gitweb config file" (with example of gitweb config file), and | |
118 | "Gitweb repositories" sections in INSTALL file for gitweb. | |
119 | ||
120 | ||
121 | Gitweb config file is [fragment] of perl code. You can set variables | |
122 | using "our $variable = value"; text from "#" character until the end | |
123 | of a line is ignored. See perlsyn(1) man page for details. | |
124 | ||
125 | Below there is list of vaiables which you might want to set in gitweb config. | |
126 | See the top of 'gitweb.cgi' for the full list of variables and their | |
127 | descriptions. | |
128 | ||
129 | Gitweb config file variables | |
130 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
131 | ||
d661146a JN |
132 | You can set, among others, the following variables in gitweb config files |
133 | (with the exception of $projectroot and $projects_list this list does | |
134 | not include variables usually directly set during build): | |
61fd2552 JN |
135 | * $GIT |
136 | Cure git executable to use. By default set to "$GIT_BINDIR/git", which | |
137 | in turn is by default set to "$(bindir)/git". If you use git from binary | |
138 | package, set this to "/usr/bin/git". This can just be "git" if your | |
139 | webserver has a sensible PATH. If you have multiple git versions | |
d661146a | 140 | installed it can be used to choose which one to use. |
61fd2552 JN |
141 | * $version |
142 | Gitweb version, set automatically when creating gitweb.cgi from | |
143 | gitweb.perl. You might want to modify it if you are running modified | |
144 | gitweb. | |
d661146a JN |
145 | * $projectroot |
146 | Absolute filesystem path which will be prepended to project path; | |
147 | the path to repository is $projectroot/$project. Set to | |
148 | $GITWEB_PROJECTROOT during installation. This variable have to be | |
149 | set correctly for gitweb to find repositories. | |
150 | * $projects_list | |
151 | Source of projects list, either directory to scan, or text file | |
152 | with list of repositories (in the "<URI-encoded repository path> SPC | |
153 | <URI-encoded repository owner>" format). Set to $GITWEB_LIST | |
154 | during installation. If empty, $projectroot is used to scan for | |
155 | repositories. | |
61fd2552 JN |
156 | * $my_url, $my_uri |
157 | URL and absolute URL of gitweb script; you might need to set those | |
158 | variables if you are using 'pathinfo' feature: see also below. | |
159 | * $home_link | |
160 | Target of the home link on top of all pages (the first part of view | |
161 | "breadcrumbs"). By default set to absolute URI of a page; you might | |
162 | need to set it up to [base] gitweb URI if you use 'pathinfo' feature | |
163 | (alternative format of the URLs, with project name embedded directly | |
164 | in the path part of URL). | |
165 | * @stylesheets | |
166 | List of URIs of stylesheets (relative to base URI of a page). You | |
167 | might specify more than one stylesheet, for example use gitweb.css | |
168 | as base, with site specific modifications in separate stylesheet | |
169 | to make it easier to upgrade gitweb. You can add 'site' stylesheet | |
170 | for example by using | |
171 | push @stylesheets, "gitweb-site.css"; | |
172 | in gitweb config file. | |
173 | * $logo_url, $logo_label | |
174 | URI and label (title) of GIT logo link (or your site logo, if you choose | |
175 | to use different logo image). By default they point to git homepage; | |
176 | in the past they pointed to git documentation at www.kernel.org. | |
177 | * $projects_list_description_width | |
178 | The width (in characters) of the projects list "Description" column. | |
179 | Longer descriptions will be cut (trying to cut at word boundary); | |
180 | full description is available as 'title' attribute (usually shown on | |
181 | mouseover). By default set to 25, which might be too small if you | |
182 | use long project descriptions. | |
183 | * @git_base_url_list | |
184 | List of git base URLs used for URL to where fetch project from, shown | |
185 | in project summary page. Full URL is "$git_base_url/$project". | |
186 | You can setup multiple base URLs (for example one for git:// protocol | |
187 | access, and one for http:// "dumb" protocol access). Note that per | |
188 | repository configuration in 'cloneurl' file, or as values of gitweb.url | |
189 | project config. | |
190 | * $default_blob_plain_mimetype | |
191 | Default mimetype for blob_plain (raw) view, if mimetype checking | |
192 | doesn't result in some other type; by default 'text/plain'. | |
193 | * $default_text_plain_charset | |
194 | Default charset for text files. If not set, web serwer configuration | |
195 | would be used. | |
196 | * $mimetypes_file | |
197 | File to use for (filename extension based) guessing of MIME types before | |
198 | trying /etc/mime.types. Path, if relative, is taken currently as taken | |
199 | relative to current git repositoy. | |
200 | * $fallback_encoding | |
201 | Gitweb assumes this charset if line contains non-UTF-8 characters. | |
202 | Fallback decoding is used without error checking, so it can be even | |
203 | 'utf-8'. Value mist be valid encodig; see Encoding::Supported(3pm) man | |
204 | page for a list. By default 'latin1', aka. 'iso-8859-1'. | |
205 | * @diff_opts | |
206 | Rename detection options for git-diff and git-diff-tree. By default | |
207 | ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or | |
208 | set it to () if you don't want to have renames detection. | |
209 | ||
210 | Per-repository gitweb configuration | |
211 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
212 | ||
213 | You can also configure individual repositories shown in gitweb by creating | |
214 | file in the GIT_DIR of git repository, or by setting some repo configuration | |
215 | variable (in GIT_DIR/config). | |
216 | ||
217 | You can use the following files in repository: | |
218 | * README.html | |
219 | A .html file (HTML fragment) which is included on the gitweb project | |
220 | summary page inside <div> block element. You can use it for longer | |
221 | description of a project, to provide links for example to projects | |
222 | homepage, etc. | |
223 | * description (or gitweb.description) | |
224 | Short (shortened by default to 25 characters in the projects list page) | |
225 | single line description of a project (of a repository). Plain text file; | |
226 | HTML will be escaped. By default set to | |
227 | Unnamed repository; edit this file to name it for gitweb. | |
228 | from the template during creating repository. You can use | |
229 | gitweb.description repo configuration variable, but the file takes | |
230 | precendence. | |
231 | * cloneurl (or multiple-valued gitweb.url) | |
232 | File with repository URL (used for clone and fetch), one per line. | |
233 | Displayed in the project summary page. You can use multiple-valued | |
234 | gitweb.url repository configuration variable for that, but the file | |
235 | takes precendence. | |
b59012ef BR |
236 | * gitweb.owner |
237 | You can use the gitweb.owner repository configuration variable to set | |
238 | repository's owner. It is displayed in the project list and summary | |
239 | page. If it's not set, filesystem directory's owner is used. | |
61fd2552 JN |
240 | * various gitweb.* config variables (in config) |
241 | Read description of %feature hash for detailed list, and some | |
242 | descriptions. | |
45a3b12c PB |
243 | |
244 | ||
128eead1 MW |
245 | Webserver configuration |
246 | ----------------------- | |
247 | ||
248 | If you want to have one URL for both gitweb and your http:// | |
249 | repositories, you can configure apache like this: | |
250 | ||
251 | <VirtualHost www:80> | |
252 | ServerName git.domain.org | |
253 | DocumentRoot /pub/git | |
254 | RewriteEngine on | |
255 | RewriteRule ^/(.*\.git/(?!/?(info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] | |
604cb211 | 256 | SetEnv GITWEB_CONFIG /etc/gitweb.conf |
128eead1 MW |
257 | </VirtualHost> |
258 | ||
259 | The above configuration expects your public repositories to live under | |
260 | /pub/git and will serve them as http://git.domain.org/dir-under-pub-git, | |
261 | both as cloneable GIT URL and as browseable gitweb interface. | |
262 | If you then start your git-daemon with --base-path=/pub/git --export-all | |
263 | then you can even use the git:// URL with exactly the same path. | |
264 | ||
604cb211 AC |
265 | Setting the environment variable GITWEB_CONFIG will tell gitweb to use |
266 | the named file (i.e. in this example /etc/gitweb.conf) as a | |
267 | configuration for gitweb. Perl variables defined in here will | |
268 | override the defaults given at the head of the gitweb.perl (or | |
269 | gitweb.cgi). Look at the comments in that file for information on | |
270 | which variables and what they mean. | |
128eead1 MW |
271 | |
272 | ||
ee0d3234 | 273 | Originally written by: |
0a8f4f00 | 274 | Kay Sievers <kay.sievers@vrfy.org> |
ee0d3234 JH |
275 | |
276 | Any comment/question/concern to: | |
277 | Git mailing list <git@vger.kernel.org> |