| '\" t |
| .\" Title: git-http-backend |
| .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> |
| .\" Date: 12/01/2018 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.20.0.rc2 |
| .\" Language: English |
| .\" |
| .TH "GIT\-HTTP\-BACKEND" "1" "12/01/2018" "Git 2\&.20\&.0\&.rc2" "Git Manual" |
| .\" ----------------------------------------------------------------- |
| .\" * Define some portability stuff |
| .\" ----------------------------------------------------------------- |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .\" http://bugs.debian.org/507673 |
| .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" ----------------------------------------------------------------- |
| .\" * set default formatting |
| .\" ----------------------------------------------------------------- |
| .\" disable hyphenation |
| .nh |
| .\" disable justification (adjust text to left margin only) |
| .ad l |
| .\" ----------------------------------------------------------------- |
| .\" * MAIN CONTENT STARTS HERE * |
| .\" ----------------------------------------------------------------- |
| .SH "NAME" |
| git-http-backend \- Server side implementation of Git over HTTP |
| .SH "SYNOPSIS" |
| .sp |
| .nf |
| \fIgit http\-backend\fR |
| .fi |
| .sp |
| .SH "DESCRIPTION" |
| .sp |
| A simple CGI program to serve the contents of a Git repository to Git clients accessing the repository over http:// and https:// protocols\&. The program supports clients fetching using both the smart HTTP protocol and the backwards\-compatible dumb HTTP protocol, as well as clients pushing using the smart HTTP protocol\&. |
| .sp |
| It verifies that the directory has the magic file "git\-daemon\-export\-ok", and it will refuse to export any Git directory that hasn\(cqt explicitly been marked for export this way (unless the \fBGIT_HTTP_EXPORT_ALL\fR environmental variable is set)\&. |
| .sp |
| By default, only the \fBupload\-pack\fR service is enabled, which serves \fIgit fetch\-pack\fR and \fIgit ls\-remote\fR clients, which are invoked from \fIgit fetch\fR, \fIgit pull\fR, and \fIgit clone\fR\&. If the client is authenticated, the \fBreceive\-pack\fR service is enabled, which serves \fIgit send\-pack\fR clients, which is invoked from \fIgit push\fR\&. |
| .SH "SERVICES" |
| .sp |
| These services can be enabled/disabled using the per\-repository configuration file: |
| .PP |
| http\&.getanyfile |
| .RS 4 |
| This serves Git clients older than version 1\&.6\&.6 that are unable to use the upload pack service\&. When enabled, clients are able to read any file within the repository, including objects that are no longer reachable from a branch but are still present\&. It is enabled by default, but a repository can disable it by setting this configuration item to |
| \fBfalse\fR\&. |
| .RE |
| .PP |
| http\&.uploadpack |
| .RS 4 |
| This serves |
| \fIgit fetch\-pack\fR |
| and |
| \fIgit ls\-remote\fR |
| clients\&. It is enabled by default, but a repository can disable it by setting this configuration item to |
| \fBfalse\fR\&. |
| .RE |
| .PP |
| http\&.receivepack |
| .RS 4 |
| This serves |
| \fIgit send\-pack\fR |
| clients, allowing push\&. It is disabled by default for anonymous users, and enabled by default for users authenticated by the web server\&. It can be disabled by setting this item to |
| \fBfalse\fR, or enabled for all users, including anonymous users, by setting it to |
| \fBtrue\fR\&. |
| .RE |
| .SH "URL TRANSLATION" |
| .sp |
| To determine the location of the repository on disk, \fIgit http\-backend\fR concatenates the environment variables PATH_INFO, which is set automatically by the web server, and GIT_PROJECT_ROOT, which must be set manually in the web server configuration\&. If GIT_PROJECT_ROOT is not set, \fIgit http\-backend\fR reads PATH_TRANSLATED, which is also set automatically by the web server\&. |
| .SH "EXAMPLES" |
| .sp |
| All of the following examples map \fBhttp://$hostname/git/foo/bar\&.git\fR to \fB/var/www/git/foo/bar\&.git\fR\&. |
| .PP |
| Apache 2\&.x |
| .RS 4 |
| Ensure mod_cgi, mod_alias, and mod_env are enabled, set GIT_PROJECT_ROOT (or DocumentRoot) appropriately, and create a ScriptAlias to the CGI: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| SetEnv GIT_PROJECT_ROOT /var/www/git |
| SetEnv GIT_HTTP_EXPORT_ALL |
| ScriptAlias /git/ /usr/libexec/git\-core/git\-http\-backend/ |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| To enable anonymous read access but authenticated write access, require authorization for both the initial ref advertisement (which we detect as a push via the service parameter in the query string), and the receive\-pack invocation itself: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| RewriteCond %{QUERY_STRING} service=git\-receive\-pack [OR] |
| RewriteCond %{REQUEST_URI} /git\-receive\-pack$ |
| RewriteRule ^/git/ \- [E=AUTHREQUIRED:yes] |
| |
| <LocationMatch "^/git/"> |
| Order Deny,Allow |
| Deny from env=AUTHREQUIRED |
| |
| AuthType Basic |
| AuthName "Git Access" |
| Require group committers |
| Satisfy Any |
| \&.\&.\&. |
| </LocationMatch> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| If you do not have |
| \fBmod_rewrite\fR |
| available to match against the query string, it is sufficient to just protect |
| \fBgit\-receive\-pack\fR |
| itself, like: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| <LocationMatch "^/git/\&.*/git\-receive\-pack$"> |
| AuthType Basic |
| AuthName "Git Access" |
| Require group committers |
| \&.\&.\&. |
| </LocationMatch> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| In this mode, the server will not request authentication until the client actually starts the object negotiation phase of the push, rather than during the initial contact\&. For this reason, you must also enable the |
| \fBhttp\&.receivepack\fR |
| config option in any repositories that should accept a push\&. The default behavior, if |
| \fBhttp\&.receivepack\fR |
| is not set, is to reject any pushes by unauthenticated users; the initial request will therefore report |
| \fB403 Forbidden\fR |
| to the client, without even giving an opportunity for authentication\&. |
| .sp |
| To require authentication for both reads and writes, use a Location directive around the repository, or one of its parent directories: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| <Location /git/private> |
| AuthType Basic |
| AuthName "Private Git Access" |
| Require group committers |
| \&.\&.\&. |
| </Location> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| To serve gitweb at the same url, use a ScriptAliasMatch to only those URLs that |
| \fIgit http\-backend\fR |
| can handle, and forward the rest to gitweb: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| ScriptAliasMatch \e |
| "(?x)^/git/(\&.*/(HEAD | \e |
| info/refs | \e |
| objects/(info/[^/]+ | \e |
| [0\-9a\-f]{2}/[0\-9a\-f]{38} | \e |
| pack/pack\-[0\-9a\-f]{40}\e\&.(pack|idx)) | \e |
| git\-(upload|receive)\-pack))$" \e |
| /usr/libexec/git\-core/git\-http\-backend/$1 |
| |
| ScriptAlias /git/ /var/www/cgi\-bin/gitweb\&.cgi/ |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| To serve multiple repositories from different |
| \fBgitnamespaces\fR(7) |
| in a single repository: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1 |
| ScriptAliasMatch ^/git/[^/]*(\&.*) /usr/libexec/git\-core/git\-http\-backend/storage\&.git$1 |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .PP |
| Accelerated static Apache 2\&.x |
| .RS 4 |
| Similar to the above, but Apache can be used to return static files that are stored on disk\&. On many systems this may be more efficient as Apache can ask the kernel to copy the file contents from the file system directly to the network: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| SetEnv GIT_PROJECT_ROOT /var/www/git |
| |
| AliasMatch ^/git/(\&.*/objects/[0\-9a\-f]{2}/[0\-9a\-f]{38})$ /var/www/git/$1 |
| AliasMatch ^/git/(\&.*/objects/pack/pack\-[0\-9a\-f]{40}\&.(pack|idx))$ /var/www/git/$1 |
| ScriptAlias /git/ /usr/libexec/git\-core/git\-http\-backend/ |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| This can be combined with the gitweb configuration: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| SetEnv GIT_PROJECT_ROOT /var/www/git |
| |
| AliasMatch ^/git/(\&.*/objects/[0\-9a\-f]{2}/[0\-9a\-f]{38})$ /var/www/git/$1 |
| AliasMatch ^/git/(\&.*/objects/pack/pack\-[0\-9a\-f]{40}\&.(pack|idx))$ /var/www/git/$1 |
| ScriptAliasMatch \e |
| "(?x)^/git/(\&.*/(HEAD | \e |
| info/refs | \e |
| objects/info/[^/]+ | \e |
| git\-(upload|receive)\-pack))$" \e |
| /usr/libexec/git\-core/git\-http\-backend/$1 |
| ScriptAlias /git/ /var/www/cgi\-bin/gitweb\&.cgi/ |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .PP |
| Lighttpd |
| .RS 4 |
| Ensure that |
| \fBmod_cgi\fR, |
| \fBmod_alias\fR, |
| \fBmod_auth\fR, |
| \fBmod_setenv\fR |
| are loaded, then set |
| \fBGIT_PROJECT_ROOT\fR |
| appropriately and redirect all requests to the CGI: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| alias\&.url += ( "/git" => "/usr/lib/git\-core/git\-http\-backend" ) |
| $HTTP["url"] =~ "^/git" { |
| cgi\&.assign = ("" => "") |
| setenv\&.add\-environment = ( |
| "GIT_PROJECT_ROOT" => "/var/www/git", |
| "GIT_HTTP_EXPORT_ALL" => "" |
| ) |
| } |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| To enable anonymous read access but authenticated write access: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $HTTP["querystring"] =~ "service=git\-receive\-pack" { |
| include "git\-auth\&.conf" |
| } |
| $HTTP["url"] =~ "^/git/\&.*/git\-receive\-pack$" { |
| include "git\-auth\&.conf" |
| } |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| where |
| \fBgit\-auth\&.conf\fR |
| looks something like: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| auth\&.require = ( |
| "/" => ( |
| "method" => "basic", |
| "realm" => "Git Access", |
| "require" => "valid\-user" |
| ) |
| ) |
| # \&.\&.\&.and set up auth\&.backend here |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| To require authentication for both reads and writes: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $HTTP["url"] =~ "^/git/private" { |
| include "git\-auth\&.conf" |
| } |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .SH "ENVIRONMENT" |
| .sp |
| \fIgit http\-backend\fR relies upon the \fBCGI\fR environment variables set by the invoking web server, including: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED) |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| REMOTE_USER |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| REMOTE_ADDR |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| CONTENT_TYPE |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| QUERY_STRING |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| REQUEST_METHOD |
| .RE |
| .sp |
| The \fBGIT_HTTP_EXPORT_ALL\fR environmental variable may be passed to \fIgit\-http\-backend\fR to bypass the check for the "git\-daemon\-export\-ok" file in each repository before allowing export of that repository\&. |
| .sp |
| The \fBGIT_HTTP_MAX_REQUEST_BUFFER\fR environment variable (or the \fBhttp\&.maxRequestBuffer\fR config variable) may be set to change the largest ref negotiation request that git will handle during a fetch; any fetch requiring a larger buffer will not succeed\&. This value should not normally need to be changed, but may be helpful if you are fetching from a repository with an extremely large number of refs\&. The value can be specified with a unit (e\&.g\&., \fB100M\fR for 100 megabytes)\&. The default is 10 megabytes\&. |
| .sp |
| The backend process sets GIT_COMMITTER_NAME to \fI$REMOTE_USER\fR and GIT_COMMITTER_EMAIL to \fI${REMOTE_USER}@http\&.${REMOTE_ADDR}\fR, ensuring that any reflogs created by \fIgit\-receive\-pack\fR contain some identifying information of the remote user who performed the push\&. |
| .sp |
| All \fBCGI\fR environment variables are available to each of the hooks invoked by the \fIgit\-receive\-pack\fR\&. |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |