gitweb: Describe projects_index format in more detail
Update and extend information about $projects_list file format in gitweb/README and in gitweb/INSTALL. Signed-off-by: Jakub Narebski <jnareb@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jakub Narebski committed
Jul 8, 2008 at 00:07 UTC
e67c9e3952a60dbf380cead5dae1d13fe9703f3c
2 files changed
+46
-6
gitweb/INSTALL
+6
@@ -144,6 +144,12 @@ Gitweb repositories
144
Spaces in both project path and project owner have to be encoded as either
145
'%20' or '+'.
146
147
+ Other characters that have to be url-encoded, i.e. replaced by '%'
148
+ followed by two-digit character number in octal, are: other whitespace
149
+ characters (because they are field separator in a record), plus sign '+'
150
+ (because it can be used as replacement for spaces), and percent sign '%'
151
+ (which is used for encoding / escaping).
152
+
153
You can generate the projects list index file using the project_index
154
action (the 'TXT' link on projects list page) directly from gitweb.
155
gitweb/README
+40
-6
@@ -156,10 +156,11 @@ not include variables usually directly set during build):
156
set correctly for gitweb to find repositories.
157
* $projects_list
158
Source of projects list, either directory to scan, or text file
159
- with list of repositories (in the "<URI-encoded repository path> SPC
160
- <URI-encoded repository owner>" format). Set to $GITWEB_LIST
161
- during installation. If empty, $projectroot is used to scan for
162
- repositories.
159
+ with list of repositories (in the "<URI-encoded repository path> SP
160
+ <URI-encoded repository owner>" line format; actually there can be
161
+ any sequence of whitespace in place of space (SP)). Set to
162
+ $GITWEB_LIST during installation. If empty, $projectroot is used
163
+ to scan for repositories.
164
* $my_url, $my_uri
165
URL and absolute URL of gitweb script; you might need to set those
166
variables if you are using 'pathinfo' feature: see also below.
@@ -214,6 +215,39 @@ not include variables usually directly set during build):
215
('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or
216
set it to () if you don't want to have renames detection.
217
218
+
219
+Projects list file format
220
+~~~~~~~~~~~~~~~~~~~~~~~~~
221
+
222
+Instead of having gitweb find repositories by scanning filesystem starting
223
+from $projectroot (or $projects_list, if it points to directory), you can
224
+provide list of projects by setting $projects_list to a text file with list
225
+of projects (and some additional info). This file uses the following
226
+format:
227
+
228
+One record (for project / repository) per line, whitespace separated fields;
229
+does not support (at least for now) lines continuation (newline escaping).
230
+Leading and trailing whitespace are ignored, any run of whitespace can be
231
+used as field separator (rules for Perl's "split(' ', $line)"). Keyed by
232
+the first field, which is project name, i.e. path to repository GIT_DIR
233
+relative to $projectroot. Fields use modified URI encoding, defined in
234
+RFC 3986, section 2.1 (Percent-Encoding), or rather "Query string encoding"
235
+(see http://en.wikipedia.org/wiki/Query_string#URL_encoding), the difference
236
+being that SP (' ') can be encoded as '+' (and therefore '+' has to be also
237
+percent-encoded). Reserved characters are: '%' (used for encoding), '+'
238
+(can be used to encode SPACE), all whitespace characters as defined in Perl,
239
+including SP, TAB and LF, (used to separate fields in a record).
240
+
241
+Currently list of fields is
242
+ * <repository path> - path to repository GIT_DIR, relative to $projectroot
243
+ * <repository owner> - displayed as repository owner, preferably full name,
244
+ or email, or both
245
+
246
+You can additionally use $projects_list file to limit which repositories
247
+are visible, and together with $strict_export to limit access to
248
+repositories (see "Gitweb repositories" section in gitweb/INSTALL).
249
+
250
+
251
Per-repository gitweb configuration
252
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
253
@@ -225,8 +259,8 @@ You can use the following files in repository:
259
* README.html
260
A .html file (HTML fragment) which is included on the gitweb project
261
summary page inside <div> block element. You can use it for longer
228
- description of a project, to provide links for example to projects
229
- homepage, etc.
262
+ description of a project, to provide links (for example to project's
263
+ homepage), etc.
264
* description (or gitweb.description)
265
Short (shortened by default to 25 characters in the projects list page)
266
single line description of a project (of a repository). Plain text file;