@matheusbsbs / matheus-bagliano / commits / 61fd2552d8
Fork 0

gitweb: Update and improve gitweb/README file

Update list of build configuration variables, add references to gitweb/INSTALL, add description of runtime and per-repository runtime configuration. Signed-off-by: Jakub Narebski <jnareb@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Jakub Narebski committed Dec 3, 2007 at 00:22 UTC 61fd2552d89a15b005d36bab99e7172e1c85878b
1 file changed +197 -18
gitweb/README
+197 -18
@@ -10,28 +10,96 @@ From the git version 1.4.0 gitweb is bundled with git.
10 How to configure gitweb for your local system
11 ---------------------------------------------
12
13 +See also "Build time configuration" section in INSTALL
14 +file for gitweb (in gitweb/INSTALL).
15 +
16 You can specify the following configuration variables when building GIT:
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)]
21 * GITWEB_SITENAME
15 - Shown in the title of all generated pages, defaults to the servers name.
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]
24 * GITWEB_PROJECTROOT
17 - The root directory for all projects shown by gitweb.
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]
34 * GITWEB_LIST
19 - points to a directory to scan for projects (defaults to project root)
20 - or to a file for explicit listing of projects.
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]
50 * GITWEB_HOMETEXT
22 - points to an .html file which is included on the gitweb project
23 - overview page.
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]
79 * GITWEB_CSS
25 - Points to the location where you put gitweb.css on your web server.
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]
84 * GITWEB_LOGO
27 - Points to the location where you put git-logo.png on your web server.
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]
95 * GITWEB_CONFIG
29 - This file will be loaded using 'require' and can be used to override any
30 - of the options above as well as some other options - see the top of
31 - 'gitweb.cgi' for their full list and description. If the environment
32 - $GITWEB_CONFIG is set when gitweb.cgi is executed the file in the
33 - environment variable will be loaded instead of the file
34 - specified when gitweb.cgi was created.
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]
103
104
105 Runtime gitweb configuration
@@ -39,11 +107,122 @@ Runtime gitweb configuration
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).
42 -See the top of 'gitweb.cgi' for the list of variables and some description.
110 The most notable thing that is not configurable at compile time are the
44 -optional features, stored in the '%features' variable. You can find further
45 -description on how to reconfigure the default features setting in your
46 -`GITWEB_CONFIG` or per-project in `project.git/config` inside 'gitweb.cgi'.
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 +
132 +You can set, among others, the following variables in gitweb config files:
133 + * $GIT
134 + Cure git executable to use. By default set to "$GIT_BINDIR/git", which
135 + in turn is by default set to "$(bindir)/git". If you use git from binary
136 + package, set this to "/usr/bin/git". This can just be "git" if your
137 + webserver has a sensible PATH. If you have multiple git versions
138 + installed it is / can be used to choose which one to use.
139 + * $version
140 + Gitweb version, set automatically when creating gitweb.cgi from
141 + gitweb.perl. You might want to modify it if you are running modified
142 + gitweb.
143 + * $my_url, $my_uri
144 + URL and absolute URL of gitweb script; you might need to set those
145 + variables if you are using 'pathinfo' feature: see also below.
146 + * $home_link
147 + Target of the home link on top of all pages (the first part of view
148 + "breadcrumbs"). By default set to absolute URI of a page; you might
149 + need to set it up to [base] gitweb URI if you use 'pathinfo' feature
150 + (alternative format of the URLs, with project name embedded directly
151 + in the path part of URL).
152 + * @stylesheets
153 + List of URIs of stylesheets (relative to base URI of a page). You
154 + might specify more than one stylesheet, for example use gitweb.css
155 + as base, with site specific modifications in separate stylesheet
156 + to make it easier to upgrade gitweb. You can add 'site' stylesheet
157 + for example by using
158 + push @stylesheets, "gitweb-site.css";
159 + in gitweb config file.
160 + * $logo_url, $logo_label
161 + URI and label (title) of GIT logo link (or your site logo, if you choose
162 + to use different logo image). By default they point to git homepage;
163 + in the past they pointed to git documentation at www.kernel.org.
164 + * $projects_list_description_width
165 + The width (in characters) of the projects list "Description" column.
166 + Longer descriptions will be cut (trying to cut at word boundary);
167 + full description is available as 'title' attribute (usually shown on
168 + mouseover). By default set to 25, which might be too small if you
169 + use long project descriptions.
170 + * @git_base_url_list
171 + List of git base URLs used for URL to where fetch project from, shown
172 + in project summary page. Full URL is "$git_base_url/$project".
173 + You can setup multiple base URLs (for example one for git:// protocol
174 + access, and one for http:// "dumb" protocol access). Note that per
175 + repository configuration in 'cloneurl' file, or as values of gitweb.url
176 + project config.
177 + * $default_blob_plain_mimetype
178 + Default mimetype for blob_plain (raw) view, if mimetype checking
179 + doesn't result in some other type; by default 'text/plain'.
180 + * $default_text_plain_charset
181 + Default charset for text files. If not set, web serwer configuration
182 + would be used.
183 + * $mimetypes_file
184 + File to use for (filename extension based) guessing of MIME types before
185 + trying /etc/mime.types. Path, if relative, is taken currently as taken
186 + relative to current git repositoy.
187 + * $fallback_encoding
188 + Gitweb assumes this charset if line contains non-UTF-8 characters.
189 + Fallback decoding is used without error checking, so it can be even
190 + 'utf-8'. Value mist be valid encodig; see Encoding::Supported(3pm) man
191 + page for a list. By default 'latin1', aka. 'iso-8859-1'.
192 + * @diff_opts
193 + Rename detection options for git-diff and git-diff-tree. By default
194 + ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or
195 + set it to () if you don't want to have renames detection.
196 +
197 +Per-repository gitweb configuration
198 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199 +
200 +You can also configure individual repositories shown in gitweb by creating
201 +file in the GIT_DIR of git repository, or by setting some repo configuration
202 +variable (in GIT_DIR/config).
203 +
204 +You can use the following files in repository:
205 + * README.html
206 + A .html file (HTML fragment) which is included on the gitweb project
207 + summary page inside <div> block element. You can use it for longer
208 + description of a project, to provide links for example to projects
209 + homepage, etc.
210 + * description (or gitweb.description)
211 + Short (shortened by default to 25 characters in the projects list page)
212 + single line description of a project (of a repository). Plain text file;
213 + HTML will be escaped. By default set to
214 + Unnamed repository; edit this file to name it for gitweb.
215 + from the template during creating repository. You can use
216 + gitweb.description repo configuration variable, but the file takes
217 + precendence.
218 + * cloneurl (or multiple-valued gitweb.url)
219 + File with repository URL (used for clone and fetch), one per line.
220 + Displayed in the project summary page. You can use multiple-valued
221 + gitweb.url repository configuration variable for that, but the file
222 + takes precendence.
223 + * various gitweb.* config variables (in config)
224 + Read description of %feature hash for detailed list, and some
225 + descriptions.
226
227
228 Webserver configuration