diff options
Diffstat (limited to 'third_party/git/gitweb/INSTALL')
| -rw-r--r-- | third_party/git/gitweb/INSTALL | 328 |
1 files changed, 0 insertions, 328 deletions
diff --git a/third_party/git/gitweb/INSTALL b/third_party/git/gitweb/INSTALL deleted file mode 100644 index a58e6b3c44b0..000000000000 --- a/third_party/git/gitweb/INSTALL +++ /dev/null @@ -1,328 +0,0 @@ -GIT web Interface (gitweb) Installation -======================================= - -First you have to generate gitweb.cgi from gitweb.perl using -"make gitweb", then "make install-gitweb" appropriate files -(gitweb.cgi, gitweb.js, gitweb.css, git-logo.png and git-favicon.png) -to their destination. For example if git was (or is) installed with -/usr prefix and gitwebdir is /var/www/cgi-bin, you can do - - $ make prefix=/usr gitweb ;# as yourself - # make gitwebdir=/var/www/cgi-bin install-gitweb ;# as root - -Alternatively you can use autoconf generated ./configure script to -set up path to git binaries (via config.mak.autogen), so you can write -instead - - $ make configure ;# as yourself - $ ./configure --prefix=/usr ;# as yourself - $ make gitweb ;# as yourself - # make gitwebdir=/var/www/cgi-bin \ - install-gitweb ;# as root - -The above example assumes that your web server is configured to run -[executable] files in /var/www/cgi-bin/ as server scripts (as CGI -scripts). - - -Requirements ------------- - - - Core git tools - - Perl 5.8 - - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename. - - web server - -The following optional Perl modules are required for extra features - - CGI::Fast and FCGI - for running gitweb as FastCGI script - - HTML::TagCloud - for fancy tag cloud in project list view - - HTTP::Date or Time::ParseDate - to support If-Modified-Since for feeds - - -Build time configuration ------------------------- - -See also "How to configure gitweb for your local system" section below. - -- There are many configuration variables which affect building of - gitweb.cgi; see "default configuration for gitweb" section in main - (top dir) Makefile, and instructions for building gitweb target. - - One of the most important is where to find the git wrapper binary. Gitweb - tries to find the git wrapper at $(bindir)/git, so you have to set $bindir - when building gitweb.cgi, or $prefix from which $bindir is derived. If - you build and install gitweb together with the rest of the git suite, - there should be no problems. Otherwise, if git was for example - installed from a binary package, you have to set $prefix (or $bindir) - accordingly. - -- Another important issue is where are git repositories you want to make - available to gitweb. By default gitweb searches for repositories under - /pub/git; if you want to have projects somewhere else, like /home/git, - use GITWEB_PROJECTROOT build configuration variable. - - 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. This can be - changed (configured) as described in "Gitweb repositories" section - below. - - Note that gitweb deals directly with the object database, and does not - need a working directory; the name of the project is the name of its - repository object database, usually projectname.git for bare - repositories. If you want to provide gitweb access to non-bare (live) - repositories, you can make projectname.git a symbolic link under - projectroot linking to projectname/.git (but it is just - a suggestion). - -- You can control where gitweb tries to find its main CSS style file, - its JavaScript file, its favicon and logo with the GITWEB_CSS, GITWEB_JS - GITWEB_FAVICON and GITWEB_LOGO build configuration variables. By default - gitweb tries to find them in the same directory as gitweb.cgi script. - -- You can optionally generate minified versions of gitweb.js and gitweb.css - by defining the JSMIN and CSSMIN build configuration variables. By default - the non-minified versions will be used. NOTE: if you enable this option, - substitute gitweb.min.js and gitweb.min.css for all uses of gitweb.js and - gitweb.css in the help files. - - -How to configure gitweb for your local system ---------------------------------------------- - -You can specify the following configuration variables when building GIT: - - * GIT_BINDIR - 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 - (SERVER_NAME CGI environment variable) if not set. [No default] - * 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 the INSTALL file for gitweb. [Default: /pub/git] - * GITWEB_PROJECT_MAXDEPTH - 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). - This is meant to speed up project listing on large work trees by limiting - 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 - (together with projects' ownership). See "Generating projects list - using gitweb" in INSTALL file for gitweb to find out how to generate - such file from scan of a directory. [No default, which means use root - directory for projects] - * GITWEB_EXPORT_OK - Show repository only if this file exists (in repository). Only - effective if this variable evaluates to true. [No default / Not set] - * GITWEB_STRICT_EXPORT - Only allow viewing of repositories also shown on the overview page. - This for example makes GITWEB_EXPORT_OK to decide if repository is - available and not only if it is shown. If GITWEB_LIST points to - file with list of project, only those repositories listed would be - available for gitweb. [No default] - * GITWEB_HOMETEXT - 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] - * GITWEB_SITE_FOOTER - Filename of html text to include at bottom of each page. Relative to - gitweb.cgi script. [No default] - * GITWEB_HOME_LINK_STR - String of the home link on top of all pages, leading to $home_link - (usually main gitweb page, which means projects list). Used as first - part of gitweb view "breadcrumb trail": <home> / <project> / <view>. - [Default: projects] - * GITWEB_SITENAME - Name of your site or organization to appear in page titles. Set it - to something descriptive for clearer bookmarks etc. If not set - (if empty) gitweb uses "$SERVER_NAME Git", or "Untitled Git" if - SERVER_NAME CGI environment variable is not set (e.g. if running - gitweb as standalone script). [No default] - * GITWEB_BASE_URL - 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 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, 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, 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: static/gitweb.css (or - static/gitweb.min.css if the CSSMIN variable is defined / CSS minifier - is used)] - * GITWEB_JS - Points to the location 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: static/gitweb.js (or - static/gitweb.min.js if JSMIN build variable is defined / JavaScript - minifier is used)] - * CSSMIN, JSMIN - Invocation of a CSS minifier or a JavaScript minifier, respectively, - working as a filter (source on standard input, minified result on - standard output). If set, it is used to generate a minified version of - 'static/gitweb.css' or 'static/gitweb.js', respectively. *Note* that - minified files would have *.min.css and *.min.js extension, which is - important if you also set GITWEB_CSS and/or GITWEB_JS. [No default] - * 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 - corner of each gitweb page, and used as logo for Atom feed). Relative - to base URI of gitweb. [Default: static/git-logo.png] - * GITWEB_FAVICON - Points to the location where you put git-favicon.png on your web server - (or to be more generic URI of favicon, assumed to be image/png type; - 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: static/git-favicon.png] - * 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 configuration" section below, and top of 'gitweb.cgi' for their - full list and description. If the environment variable GITWEB_CONFIG - 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] - * HIGHLIGHT_BIN - Path to the highlight executable to use (must be the one from - http://www.andre-simon.de due to assumptions about parameters and output). - Useful if highlight is not installed on your webserver's PATH. - [Default: highlight] - -Build example -~~~~~~~~~~~~~ - -- To install gitweb to /var/www/cgi-bin/gitweb/, when git wrapper - is installed at /usr/local/bin/git, the repositories (projects) - we want to display are under /home/local/scm, and you do not use - minifiers, you can do - - make GITWEB_PROJECTROOT="/home/local/scm" \ - GITWEB_JS="gitweb/static/gitweb.js" \ - GITWEB_CSS="gitweb/static/gitweb.css" \ - GITWEB_LOGO="gitweb/static/git-logo.png" \ - GITWEB_FAVICON="gitweb/static/git-favicon.png" \ - bindir=/usr/local/bin \ - gitweb - - make gitwebdir=/var/www/cgi-bin/gitweb install-gitweb - - -Gitweb config file ------------------- - -See also "Runtime gitweb configuration" section in README file -for gitweb (in gitweb/README), and gitweb.conf(5) manpage. - -- 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 - using the GITWEB_CONFIG environment variable. If this file does not - exist, gitweb looks for a system-wide configuration file, normally - /etc/gitweb.conf. You can change the default using the - GITWEB_CONFIG_SYSTEM build configuration variable, and override it - through the GITWEB_CONFIG_SYSTEM environment variable. - - Note that the GITWEB_CONFIG_SYSTEM system-wide configuration file is - only used for instances that lack per-instance configuration file. - You can use GITWEB_CONFIG_COMMON common system-wide configuration - file (normally /etc/gitweb-common.conf) to keep common default - settings that apply to all instances. 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. - - See the top of gitweb.perl file for examples of customizable options. - -Config file example -~~~~~~~~~~~~~~~~~~~ - -To enable blame, pickaxe search, and snapshot support, while allowing -individual projects to turn them off, put the following in your -GITWEB_CONFIG file: - - $feature{'blame'}{'default'} = [1]; - $feature{'blame'}{'override'} = 1; - - $feature{'pickaxe'}{'default'} = [1]; - $feature{'pickaxe'}{'override'} = 1; - - $feature{'snapshot'}{'default'} = ['zip', 'tgz']; - $feature{'snapshot'}{'override'} = 1; - -If you allow overriding for the snapshot feature, you can specify which -snapshot formats are globally disabled. You can also add any command line -options you want (such as setting the compression level). For instance, -you can disable Zip compressed snapshots and set GZip to run at level 6 by -adding the following lines to your $GITWEB_CONFIG: - - $known_snapshot_formats{'zip'}{'disabled'} = 1; - $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6']; - - -Gitweb repositories -------------------- - -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" and "Advanced web server setup" sections -in gitweb(1) manpage. - - -- Apache2, gitweb installed as CGI script, - under /var/www/cgi-bin/ - - ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" - - <Directory "/var/www/cgi-bin"> - Options Indexes FollowSymlinks ExecCGI - AllowOverride None - Order allow,deny - Allow from all - </Directory> - -- Apache2, gitweb installed as mod_perl legacy script, - under /var/www/perl/ - - Alias /perl "/var/www/perl" - - <Directory "/var/www/perl"> - SetHandler perl-script - PerlResponseHandler ModPerl::Registry - PerlOptions +ParseHeaders - Options Indexes FollowSymlinks +ExecCGI - AllowOverride None - Order allow,deny - Allow from all - </Directory> |