diff --git a/gitweb/README b/gitweb/README
index 825162a0b6dce8c354de67a30abfbad94d29fdde..6c2c8e12598ca9ba17e7cc3d74812a8b7883d59a 100644 (file)
--- a/gitweb/README
+++ b/gitweb/README
web browsers that support favicons (website icons) may display them
in the browser's URL bar and next to site name in bookmarks). Relative
to base URI of gitweb. [Default: git-favicon.png]
+ * GITWEB_JS
+ Points to the localtion where you put gitweb.js on your web server
+ (or to be more generic URI of JavaScript code used by gitweb).
+ Relative to base URI of gitweb. [Default: gitweb.js (or gitweb.min.js
+ if JSMIN build variable is defined / JavaScript minifier is used)]
* GITWEB_CONFIG
This Perl file will be loaded using 'do' and can be used to override any
of the options above as well as some other options -- see the "Runtime
$GITWEB_LIST during installation. If empty, $projectroot is used
to scan for repositories.
* $my_url, $my_uri
- URL and absolute URL of gitweb script; you might need to set those
- variables if you are using 'pathinfo' feature: see also below.
+ Full URL and absolute URL of gitweb script;
+ in earlier versions of gitweb you might have need to set those
+ variables, now there should be no need to do it.
+ * $base_url
+ Base URL for relative URLs in pages generated by gitweb,
+ (e.g. $logo, $favicon, @stylesheets if they are relative URLs),
+ needed and used only for URLs with nonempty PATH_INFO via
+ <base href="$base_url">. Usually gitweb sets its value correctly,
+ and there is no need to set this variable, e.g. to $my_uri or "/".
* $home_link
Target of the home link on top of all pages (the first part of view
- "breadcrumbs"). By default set to absolute URI of a page; you might
- need to set it up to [base] gitweb URI if you use 'pathinfo' feature
- (alternative format of the URLs, with project name embedded directly
- in the path part of URL).
+ "breadcrumbs"). By default set to absolute URI of a page ($my_uri).
* @stylesheets
List of URIs of stylesheets (relative to base URI of a page). You
might specify more than one stylesheet, for example use gitweb.css
* $fallback_encoding
Gitweb assumes this charset if line contains non-UTF-8 characters.
Fallback decoding is used without error checking, so it can be even
- 'utf-8'. Value mist be valid encodig; see Encoding::Supported(3pm) man
+ 'utf-8'. Value must be valid encoding; see Encoding::Supported(3pm) man
page for a list. By default 'latin1', aka. 'iso-8859-1'.
* @diff_opts
Rename detection options for git-diff and git-diff-tree. By default
('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or
set it to () if you don't want to have renames detection.
+ * $prevent_xss
+ If true, some gitweb features are disabled to prevent content in
+ repositories from launching cross-site scripting (XSS) attacks. Set this
+ to true if you don't trust the content of your repositories. The default
+ is false.
+ * $maxload
+ Used to set the maximum load that we will still respond to gitweb queries.
+ If server load exceed this value then return "503 Service Unavaliable" error.
+ Server load is taken to be 0 if gitweb cannot determine its value. Set it to
+ undefined value to turn it off. The default is 300.
Projects list file format
A .html file (HTML fragment) which is included on the gitweb project
summary page inside <div> block element. You can use it for longer
description of a project, to provide links (for example to project's
- homepage), etc.
+ homepage), etc. This is recognized only if XSS prevention is off
+ ($prevent_xss is false); a way to include a readme safely when XSS
+ prevention is on may be worked out in the future.
* description (or gitweb.description)
Short (shortened by default to 25 characters in the projects list page)
single line description of a project (of a repository). Plain text file;
$home_link = "/";
+PATH_INFO usage
+-----------------------
+If you enable PATH_INFO usage in gitweb by putting
+
+ $feature{'pathinfo'}{'default'} = [1];
+
+in your gitweb.conf, it is possible to set up your server so that it
+consumes and produces URLs in the form
+
+http://git.example.com/project.git/shortlog/sometag
+
+by using a configuration such as the following, that assumes that
+/var/www/gitweb is the DocumentRoot of your webserver, and that it
+contains the gitweb.cgi script and complementary static files
+(stylesheet, favicon):
+
+<VirtualHost *:80>
+ ServerAlias git.example.com
+
+ DocumentRoot /var/www/gitweb
+
+ <Directory /var/www/gitweb>
+ Options ExecCGI
+ AddHandler cgi-script cgi
+
+ DirectoryIndex gitweb.cgi
+
+ RewriteEngine On
+ RewriteCond %{REQUEST_FILENAME} !-f
+ RewriteCond %{REQUEST_FILENAME} !-d
+ RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
+ </Directory>
+</VirtualHost>
+
+The rewrite rule guarantees that existing static files will be properly
+served, whereas any other URL will be passed to gitweb as PATH_INFO
+parameter.
+
+Notice that in this case you don't need special settings for
+@stylesheets, $my_uri and $home_link, but you lose "dumb client" access
+to your project .git dirs. A possible workaround for the latter is the
+following: in your project root dir (e.g. /pub/git) have the projects
+named without a .git extension (e.g. /pub/git/project instead of
+/pub/git/project.git) and configure Apache as follows:
+
+<VirtualHost *:80>
+ ServerAlias git.example.com
+
+ DocumentRoot /var/www/gitweb
+
+ AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
+ <Directory /var/www/gitweb>
+ Options ExecCGI
+ AddHandler cgi-script cgi
+
+ DirectoryIndex gitweb.cgi
+
+ RewriteEngine On
+ RewriteCond %{REQUEST_FILENAME} !-f
+ RewriteCond %{REQUEST_FILENAME} !-d
+ RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
+ </Directory>
+</VirtualHost>
+
+The additional AliasMatch makes it so that
+
+http://git.example.com/project.git
+
+will give raw access to the project's git dir (so that the project can
+be cloned), while
+
+http://git.example.com/project
+
+will provide human-friendly gitweb access.
+
+This solution is not 100% bulletproof, in the sense that if some project
+has a named ref (branch, tag) starting with 'git/', then paths such as
+
+http://git.example.com/project/command/abranch..git/abranch
+
+will fail with a 404 error.
+
+
+
Originally written by:
Kay Sievers <kay.sievers@vrfy.org>