diff options
Diffstat (limited to 'gitweb/INSTALL')
| -rw-r--r-- | gitweb/INSTALL | 111 |
1 files changed, 23 insertions, 88 deletions
diff --git a/gitweb/INSTALL b/gitweb/INSTALL index c5236fee9d..6d45406797 100644 --- a/gitweb/INSTALL +++ b/gitweb/INSTALL @@ -130,6 +130,8 @@ You can specify the following configuration variables when building GIT: Points to an .html file which is included on the gitweb project overview page ('projects_list' view), if it exists. Relative to gitweb.cgi script. [Default: indextext.html] + * GITWEB_SITE_HTML_HEAD_STRING + html snippet to include in the <head> section of each page. [No default] * GITWEB_SITE_HEADER Filename of html text to include at top of each page. Relative to gitweb.cgi script. [No default] @@ -229,9 +231,9 @@ Gitweb config file ------------------ See also "Runtime gitweb configuration" section in README file -for gitweb (in gitweb/README). +for gitweb (in gitweb/README), and gitweb.conf(5) manpage. -- You can configure gitweb further using the gitweb configuration file; +- You can configure gitweb further using the per-instance gitweb configuration file; by default this is a file named gitweb_config.perl in the same place as gitweb.cgi script. You can control the default place for the config file using the GITWEB_CONFIG build configuration variable, and you can set it @@ -241,6 +243,17 @@ for gitweb (in gitweb/README). GITWEB_CONFIG_SYSTEM build configuration variable, and override it through the GITWEB_CONFIG_SYSTEM environment variable. + Note that if per-instance configuration file exists, then system-wide + configuration is _not used at all_. This is quite untypical and suprising + behavior. On the other hand changing current behavior would break backwards + compatibility and can lead to unexpected changes in gitweb behavior. + Therefore gitweb also looks for common system-wide configuration file, + normally /etc/gitweb-common.conf (set during build time using build time + configuration variable GITWEB_CONFIG_COMMON, set it at runtime using + environment variable with the same name). Settings from per-instance or + system-wide configuration file override those from common system-wide + configuration file. + - 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) for details. @@ -276,97 +289,19 @@ adding the following lines to your $GITWEB_CONFIG: Gitweb repositories ------------------- -- By default all git repositories under projectroot are visible and - available to gitweb. The list of projects is generated by default by - scanning the projectroot directory for git repositories (for object - databases to be more exact). - - You can provide a pre-generated list of [visible] repositories, - together with information about their owners (the project ownership - defaults to the owner of the repository directory otherwise), by setting - the GITWEB_LIST build configuration variable (or the $projects_list - variable in the gitweb config file) to point to a plain file. - - Each line of the projects list file should consist of the url-encoded path - to the project repository database (relative to projectroot), followed - by the url-encoded project owner on the same line (separated by a space). - Spaces in both project path and project owner have to be encoded as either - '%20' or '+'. - - Other characters that have to be url-encoded, i.e. replaced by '%' - followed by two-digit character number in octal, are: other whitespace - characters (because they are field separator in a record), plus sign '+' - (because it can be used as replacement for spaces), and percent sign '%' - (which is used for encoding / escaping). - - You can generate the projects list index file using the project_index - action (the 'TXT' link on projects list page) directly from gitweb. - -- By default, even if a project is not visible on projects list page, you - can view it nevertheless by hand-crafting a gitweb URL. You can set the - GITWEB_STRICT_EXPORT build configuration variable (or the $strict_export - variable in the gitweb config file) to only allow viewing of - repositories also shown on the overview page. - -- Alternatively, you can configure gitweb to only list and allow - viewing of the explicitly exported repositories, via the - GITWEB_EXPORT_OK build configuration variable (or the $export_ok - variable in gitweb config file). If it evaluates to true, gitweb - shows repositories only if this file exists in its object database - (if directory has the magic file named $export_ok). - -- Finally, it is possible to specify an arbitrary perl subroutine that - will be called for each project to determine if it can be exported. - The subroutine receives an absolute path to the project as its only - parameter. - - For example, if you use mod_perl to run the script, and have dumb - http protocol authentication configured for your repositories, you - can use the following hook to allow access only if the user is - authorized to read the files: - - $export_auth_hook = sub { - use Apache2::SubRequest (); - use Apache2::Const -compile => qw(HTTP_OK); - my $path = "$_[0]/HEAD"; - my $r = Apache2::RequestUtil->request; - my $sub = $r->lookup_file($path); - return $sub->filename eq $path - && $sub->status == Apache2::Const::HTTP_OK; - }; - - -Generating projects list using gitweb -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We assume that GITWEB_CONFIG has its default Makefile value, namely -gitweb_config.perl. Put the following in gitweb_make_index.perl file: - - $GITWEB_CONFIG = "gitweb_config.perl"; - do $GITWEB_CONFIG if -e $GITWEB_CONFIG; - - $projects_list = $projectroot; - -Then create the following script to get list of project in the format -suitable for GITWEB_LIST build configuration variable (or -$projects_list variable in gitweb config): - - #!/bin/sh - - export GITWEB_CONFIG="gitweb_make_index.perl" - export GATEWAY_INTERFACE="CGI/1.1" - export HTTP_ACCEPT="*/*" - export REQUEST_METHOD="GET" - export QUERY_STRING="a=project_index" - - perl -- /var/www/cgi-bin/gitweb.cgi +By default gitweb shows all git repositories under single common repository +root on a local filesystem; see description of GITWEB_PROJECTROOT build-time +configuration variable above (and also of GITWEB_LIST). + +More advanced usage, like limiting access or visibility of repositories and +managing multiple roots are described on gitweb manpage. Example web server configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See also "Webserver configuration" section in README file for gitweb -(in gitweb/README). +See also "Webserver configuration" and "Advanced web server setup" sections +in gitweb(1) manpage. - Apache2, gitweb installed as CGI script, |