git http-backend

A simple CGI program to serve the contents of a Git repository to Gitclients accessing the repository over http:// and https:// protocols.The program supports clients fetching using both the smart HTTP protocoland the backwards-compatible dumb HTTP protocol, as well as clientspushing using the smart HTTP protocol. It also supports Git’smore-efficient "v2" protocol if properly configured; see thediscussion ofGIT_PROTOCOL in the ENVIRONMENT section below.

It verifies that the directory has the magic file"git-daemon-export-ok", and it will refuse to export any Git directorythat hasn’t explicitly been marked for export this way (unless theGIT_HTTP_EXPORT_ALL environment variable is set).

By default, only theupload-pack service is enabled, which servesgit fetch-pack andgit ls-remote clients, which are invoked fromgit fetch,git pull, andgit clone. If the client is authenticated,thereceive-pack service is enabled, which servesgit send-packclients, which is invoked fromgit push.

These services can be enabled/disabled using the per-repositoryconfiguration file:

http.getanyfile

This serves Git clients older than version 1.6.6 that are unable to use theupload pack service. When enabled, clients are able to readany file within the repository, including objects that areno longer reachable from a branch but are still present.It is enabled by default, but a repository can disable itby setting this configuration value tofalse.

http.uploadpack

This servesgit fetch-pack andgit ls-remote clients.It is enabled by default, but a repository can disable itby setting this configuration value tofalse.

http.receivepack

This servesgit send-pack clients, allowing push. It isdisabled by default for anonymous users, and enabled bydefault for users authenticated by the web server. It can bedisabled by setting this item tofalse, or enabled for allusers, including anonymous users, by setting it totrue.

http.uploadarchive

This servesgit archive clients for remote archive over HTTP/HTTPSprotocols. It is disabled by default. It only works in protocol v2.

To determine the location of the repository on disk,git http-backendconcatenates the environment variables PATH_INFO, which is setautomatically by the web server, and GIT_PROJECT_ROOT, which must be setmanually in the web server configuration. If GIT_PROJECT_ROOT is notset,git http-backend reads PATH_TRANSLATED, which is also setautomatically by the web server.

All of the following examples maphttp://$hostname/git/foo/bar.gitto/var/www/git/foo/bar.git.

Apache 2.x

Ensure mod_cgi, mod_alias, and mod_env are enabled, setGIT_PROJECT_ROOT (or DocumentRoot) appropriately, andcreate a ScriptAlias to the CGI:

SetEnv GIT_PROJECT_ROOT /var/www/gitSetEnv GIT_HTTP_EXPORT_ALLScriptAlias /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's request).SetEnvIf Git-Protocol ".*" GIT_PROTOCOL=$0

To enable anonymous read access but authenticated write access,require authorization for both the initial ref advertisement (which wedetect as a push via the service parameter in the query string), and thereceive-pack invocation itself:

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>

If you do not havemod_rewrite available to match against the querystring, it is sufficient to just protectgit-receive-pack itself,like:

<LocationMatch "^/git/.*/git-receive-pack$">        AuthType Basic        AuthName "Git Access"        Require group committers        ...</LocationMatch>

In this mode, the server will not request authentication until theclient actually starts the object negotiation phase of the push, ratherthan during the initial contact. For this reason, you must also enablethehttp.receivepack config option in any repositories that shouldaccept a push. The default behavior, ifhttp.receivepack is not set,is to reject any pushes by unauthenticated users; the initial requestwill therefore report403Forbidden to the client, without even givingan opportunity for authentication.

To require authentication for both reads and writes, use a Locationdirective around the repository, or one of its parent directories:

<Location /git/private>        AuthType Basic        AuthName "Private Git Access"        Require group committers        ...</Location>

To serve gitweb at the same url, use a ScriptAliasMatch to onlythose URLs thatgit http-backend can handle, and forward therest to gitweb:

ScriptAliasMatch \        "(?x)^/git/(.*/(HEAD | \                        info/refs | \                        objects/(info/[^/]+ | \                                 [0-9a-f]{2}/[0-9a-f]{38} | \                                 pack/pack-[0-9a-f]{40}\.(pack|idx)) | \                        git-(upload|receive)-pack))$" \        /usr/libexec/git-core/git-http-backend/$1ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/

To serve multiple repositories from differentgitnamespaces(7) in asingle repository:

SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1

Accelerated static Apache 2.x

Similar to the above, but Apache can be used to return staticfiles that are stored on disk. On many systems this maybe more efficient as Apache can ask the kernel to copy thefile contents from the file system directly to the network:

SetEnv GIT_PROJECT_ROOT /var/www/gitAliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$          /var/www/git/$1AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/

This can be combined with the gitweb configuration:

SetEnv GIT_PROJECT_ROOT /var/www/gitAliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$          /var/www/git/$1AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1ScriptAliasMatch \        "(?x)^/git/(.*/(HEAD | \                        info/refs | \                        objects/info/[^/]+ | \                        git-(upload|receive)-pack))$" \        /usr/libexec/git-core/git-http-backend/$1ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/

Lighttpd

Ensure thatmod_cgi,mod_alias,mod_auth,mod_setenv areloaded, then setGIT_PROJECT_ROOT appropriately and redirectall requests to the CGI:

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" => ""        )}

To enable anonymous read access but authenticated write access:

$HTTP["querystring"] =~ "service=git-receive-pack" {        include "git-auth.conf"}$HTTP["url"] =~ "^/git/.*/git-receive-pack$" {        include "git-auth.conf"}

wheregit-auth.conf looks something like:

auth.require = (        "/" => (                "method" => "basic",                "realm" => "Git Access",                "require" => "valid-user"               ))# ...and set up auth.backend here

To require authentication for both reads and writes:

$HTTP["url"] =~ "^/git/private" {        include "git-auth.conf"}

git http-backend relies upon theCGI environment variables setby the invoking web server, including:

• PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED)

• REMOTE_USER

• REMOTE_ADDR

• CONTENT_TYPE

• QUERY_STRING

• REQUEST_METHOD

TheGIT_HTTP_EXPORT_ALL environment variable may be passed togit-http-backend to bypass the check for the "git-daemon-export-ok"file in each repository before allowing export of that repository.

TheGIT_HTTP_MAX_REQUEST_BUFFER environment variable (or thehttp.maxRequestBuffer config option) may be set to change thelargest ref negotiation request that git will handle during a fetch; anyfetch requiring a larger buffer will not succeed. This value should notnormally need to be changed, but may be helpful if you are fetching froma repository with an extremely large number of refs. The value can bespecified with a unit (e.g.,100M for 100 megabytes). The default is10 megabytes.

Clients may probe for optional protocol capabilities (like the v2protocol) using theGit-Protocol HTTP header. In order to supportthese, the contents of that header must appear in theGIT_PROTOCOLenvironment variable. Most webservers will pass this header to the CGIvia theHTTP_GIT_PROTOCOL variable, andgit-http-backend willautomatically copy that toGIT_PROTOCOL. However, some webservers maybe more selective about which headers they’ll pass, in which case theyneed to be configured explicitly (see the mention ofGit-Protocol inthe Apache config from the earlier EXAMPLES section).

The backend process sets GIT_COMMITTER_NAME to$REMOTE_USER andGIT_COMMITTER_EMAIL to${REMOTE_USER}@http.${REMOTE_ADDR},ensuring that any reflogs created bygit-receive-pack contain someidentifying information of the remote user who performed the push.

AllCGI environment variables are available to each of the hooksinvoked by thegit-receive-pack.

Part of thegit(1) suite