X-Git-Url: https://git.ladys.computer/Gitweb/blobdiff_plain/e0e04ea69032b5f12107bda0cd9c34a1822f0c51600cdee2d3800d26e4968193..d2594424606cf21ec26a59ae0abd639990d598e3da2c1133dc24de3f857b6187:/README?ds=sidebyside diff --git a/README b/README index 2dbacc6..6b89a66 100644 --- a/README +++ b/README @@ -2,7 +2,7 @@ GIT web Interface ================= The one working on: - http://www.kernel.org/git/ + http://git.kernel.org/ From the git version 1.4.0 gitweb is bundled with git. @@ -10,13 +10,13 @@ From the git version 1.4.0 gitweb is bundled with git. How to configure gitweb for your local system --------------------------------------------- -See also "Build time configuration" section in INSTALL +See also the "Build time configuration" section in the INSTALL file for gitweb (in gitweb/INSTALL). You can specify the following configuration variables when building GIT: * GIT_BINDIR - Points out where to find git executable. You should set up it to - the place where git binary was installed (usually /usr/bin) if you + Points where to find the git executable. You should set it up to + the place where the git binary was installed (usually /usr/bin) if you don't install git from sources together with gitweb. [Default: $(bindir)] * GITWEB_SITENAME Shown in the title of all generated pages, defaults to the server name @@ -24,13 +24,13 @@ You can specify the following configuration variables when building GIT: * GITWEB_PROJECTROOT The root directory for all projects shown by gitweb. Must be set correctly for gitweb to find repositories to display. See also - "Gitweb repositories" in INSTALL file for gitweb. [Default: /pub/git] + "Gitweb repositories" in the INSTALL file for gitweb. [Default: /pub/git] * GITWEB_PROJECT_MAXDEPTH - The filesystem traversing limit for getting projects list; the number + The filesystem traversing limit for getting the project list; the number is taken as depth relative to the projectroot. It is used when GITWEB_LIST is a directory (or is not set; then project root is used). Is is meant to speed up project listing on large work trees by limiting - find depth. [Default: 2007] + search depth. [Default: 2007] * GITWEB_LIST Points to a directory to scan for projects (defaults to project root if not set / if empty) or to a file with explicit listing of projects @@ -72,15 +72,15 @@ You can specify the following configuration variables when building GIT: Git base URLs used for URL to where fetch project from, i.e. full URL is "$git_base_url/$project". Shown on projects summary page. Repository URL for project can be also configured per repository; this - takes precendence over URL composed from base URL and project name. + takes precedence over URLs composed from base URL and a project name. Note that you can setup multiple base URLs (for example one for - git:// protocol access, one for http:// access) from gitweb config - file. [No default] + git:// protocol access, another for http:// access) from the gitweb + config file. [No default] * GITWEB_CSS Points to the location where you put gitweb.css on your web server - (or to be more generic URI of gitweb stylesheet). Relative to base - URI of gitweb. Note that you can setup multiple stylesheets from - gitweb config file. [Default: gitweb.css] + (or to be more generic, the URI of gitweb stylesheet). Relative to the + base URI of gitweb. Note that you can setup multiple stylesheets from + the gitweb config file. [Default: gitweb.css] * GITWEB_LOGO Points to the location where you put git-logo.png on your web server (or to be more generic URI of logo, 72x27 size, displayed in top right @@ -92,6 +92,11 @@ You can specify the following configuration variables when building GIT: 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 @@ -100,12 +105,19 @@ You can specify the following configuration variables when building GIT: is set when gitweb.cgi is executed, then the file specified in the environment variable will be loaded instead of the file specified when gitweb.cgi was created. [Default: gitweb_config.perl] + * GITWEB_CONFIG_SYSTEM + This Perl file will be loaded using 'do' as a fallback if GITWEB_CONFIG + does not exist. If the environment variable GITWEB_CONFIG_SYSTEM is set + when gitweb.cgi is executed, then the file specified in the environment + variable will be loaded instead of the file specified when gitweb.cgi was + created. [Default: /etc/gitweb.conf] Runtime gitweb configuration ---------------------------- You can adjust gitweb behaviour using the file specified in `GITWEB_CONFIG` -(defaults to 'gitweb_config.perl' in the same directory as the CGI). +(defaults to 'gitweb_config.perl' in the same directory as the CGI), and +as a fallback `GITWEB_CONFIG_SYSTEM` (defaults to /etc/gitweb.conf). The most notable thing that is not configurable at compile time are the optional features, stored in the '%features' variable. @@ -113,41 +125,59 @@ Ultimate description on how to reconfigure the default features setting in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found as comments inside 'gitweb.cgi'. -See also "Gitweb config file" (with example of gitweb config file), and -"Gitweb repositories" sections in INSTALL file for gitweb. +See also the "Gitweb config file" (with an example of config file), and +the "Gitweb repositories" sections in INSTALL file for gitweb. -Gitweb config file is [fragment] of perl code. You can set variables +The gitweb config file is a fragment of perl code. You can set variables using "our $variable = value"; text from "#" character until the end of a line is ignored. See perlsyn(1) man page for details. -Below there is list of vaiables which you might want to set in gitweb config. +Below is the list of variables which you might want to set in gitweb config. See the top of 'gitweb.cgi' for the full list of variables and their descriptions. Gitweb config file variables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can set, among others, the following variables in gitweb config files: +You can set, among others, the following variables in gitweb config files +(with the exception of $projectroot and $projects_list this list does +not include variables usually directly set during build): * $GIT - Cure git executable to use. By default set to "$GIT_BINDIR/git", which + Core git executable to use. By default set to "$GIT_BINDIR/git", which in turn is by default set to "$(bindir)/git". If you use git from binary package, set this to "/usr/bin/git". This can just be "git" if your webserver has a sensible PATH. If you have multiple git versions - installed it is / can be used to choose which one to use. + installed it can be used to choose which one to use. * $version Gitweb version, set automatically when creating gitweb.cgi from gitweb.perl. You might want to modify it if you are running modified gitweb. + * $projectroot + Absolute filesystem path which will be prepended to project path; + the path to repository is $projectroot/$project. Set to + $GITWEB_PROJECTROOT during installation. This variable have to be + set correctly for gitweb to find repositories. + * $projects_list + Source of projects list, either directory to scan, or text file + with list of repositories (in the " SP + " line format; actually there can be + any sequence of whitespace in place of space (SP)). Set to + $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 + - path to repository GIT_DIR, relative to $projectroot + * - displayed as repository owner, preferably full name, + or email, or both + +You can additionally use $projects_list file to limit which repositories +are visible, and together with $strict_export to limit access to +repositories (see "Gitweb repositories" section in gitweb/INSTALL). + Per-repository gitweb configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -204,21 +272,28 @@ You can use the following files in repository: * README.html A .html file (HTML fragment) which is included on the gitweb project summary page inside
block element. You can use it for longer - description of a project, to provide links for example to projects - homepage, etc. + description of a project, to provide links (for example to project's + 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; HTML will be escaped. By default set to Unnamed repository; edit this file to name it for gitweb. - from the template during creating repository. You can use + from the template during repository creation. You can use the gitweb.description repo configuration variable, but the file takes - precendence. + precedence. * cloneurl (or multiple-valued gitweb.url) File with repository URL (used for clone and fetch), one per line. Displayed in the project summary page. You can use multiple-valued gitweb.url repository configuration variable for that, but the file - takes precendence. + takes precedence. + * gitweb.owner + You can use the gitweb.owner repository configuration variable to set + repository's owner. It is displayed in the project list and summary + page. If it's not set, filesystem directory's owner is used + (via GECOS field / real name field from getpwiud(3)). * various gitweb.* config variables (in config) Read description of %feature hash for detailed list, and some descriptions. @@ -230,12 +305,15 @@ Webserver configuration If you want to have one URL for both gitweb and your http:// repositories, you can configure apache like this: - - ServerName git.domain.org + + ServerName git.example.org DocumentRoot /pub/git - RewriteEngine on - RewriteRule ^/(.*\.git/(?!/?(info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] SetEnv GITWEB_CONFIG /etc/gitweb.conf + RewriteEngine on + # make the front page an internal rewrite to the gitweb script + RewriteRule ^/$ /cgi-bin/gitweb.cgi + # make access for "dumb clients" work + RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] The above configuration expects your public repositories to live under @@ -251,6 +329,97 @@ override the defaults given at the head of the gitweb.perl (or gitweb.cgi). Look at the comments in that file for information on which variables and what they mean. +If you use the rewrite rules from the example you'll likely also need +something like the following in your gitweb.conf (or gitweb_config.perl) file: + + @stylesheets = ("/some/absolute/path/gitweb.css"); + $my_uri = "/"; + $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): + + + ServerAlias git.example.com + + DocumentRoot /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] + + + +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: + + + ServerAlias git.example.com + + DocumentRoot /var/www/gitweb + + AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3 + + 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] + + + +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