git-http-backend.1 (13382B)
- '\" t
- .\" Title: git-http-backend
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GIT\-HTTP\-BACKEND" "1" "2025-03-14" "Git 2\&.49\&.0" "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
- .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\&. It also supports Git\(cqs more\-efficient "v2" protocol if properly configured; see the discussion of \fBGIT_PROTOCOL\fR in the ENVIRONMENT section below\&.
- .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 environment 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 value 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 value 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
- .PP
- http\&.uploadarchive
- .RS 4
- This serves
- \fIgit archive\fR
- clients for remote archive over HTTP/HTTPS protocols\&. It is disabled by default\&. It only works in protocol v2\&.
- .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/
- # This is not strictly necessary using Apache and a modern version of
- # git\-http\-backend, as the webserver will pass along the header in the
- # environment as HTTP_GIT_PROTOCOL, and http\-backend will copy that into
- # GIT_PROTOCOL\&. But you may need this line (or something similar if you
- # are using a different webserver), or if you want to support older Git
- # versions that did not do that copying\&.
- #
- # Having the webserver set up GIT_PROTOCOL is perfectly fine even with
- # modern versions (and will take precedence over HTTP_GIT_PROTOCOL,
- # which means it can be used to override the client\*(Aqs request)\&.
- SetEnvIf Git\-Protocol "\&.*" GIT_PROTOCOL=$0
- .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\fR
- \fBForbidden\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
- .\}
- .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
- .\}
- .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
- .\}
- .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 environment 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 option) 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
- Clients may probe for optional protocol capabilities (like the v2 protocol) using the \fBGit\-Protocol\fR HTTP header\&. In order to support these, the contents of that header must appear in the \fBGIT_PROTOCOL\fR environment variable\&. Most webservers will pass this header to the CGI via the \fBHTTP_GIT_PROTOCOL\fR variable, and \fBgit\-http\-backend\fR will automatically copy that to \fBGIT_PROTOCOL\fR\&. However, some webservers may be more selective about which headers they\(cqll pass, in which case they need to be configured explicitly (see the mention of \fBGit\-Protocol\fR in the Apache config from the earlier EXAMPLES section)\&.
- .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