git-http-backend
Server side implementation of Git over HTTP
SYNOPSIS
githttp -backend
DESCRIPTION
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 verifies that the directory has the magic file "git -daemon -export -ok", and it will refuse to export any Git directory that hasn explicitly been marked for export this way (unless the GIT_HTTP_EXPORT_ALL environmental variable is set) . By default, only the upload-pack service is enabled, which serves gitfetch -pack and gitls -remote clients, which are invoked from gitfetch , gitpull ,and gitclone . If the client is authenticated, the receive-pack service is enabled, which serves gitsend -pack clients, which is invoked from gitpush .
SERVICES
These services can be enabled/disabled using the per -repository configuration file:
http .getanyfile 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 false .
http .uploadpack This serves gitfetch -pack and gitls -remote clients . It is enabled by default, but a repository can disable it by setting this configuration item to false .
http .receivepack This serves gitsend -pack 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 false ,or enabled for all users, including anonymous users, by setting it to true .
http .getanyfile 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 false .
http .uploadpack This serves gitfetch -pack and gitls -remote clients . It is enabled by default, but a repository can disable it by setting this configuration item to false .
http .receivepack This serves gitsend -pack 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 false ,or enabled for all users, including anonymous users, by setting it to true .
URL TRANSLATION
To determine the location of the repository on disk, githttp -backend 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, githttp -backend reads PATH_TRANSLATED, which is also set automatically by the web server .
EXAMPLES
All of the following examples map http://$hostname/git/foo/bar.git to /var/www/git/foo/bar.git .
Apache 2 .x Ensure mod_cgi, mod_alias, and mod_env are enabled, set GIT_PROJECT_ROOT (or DocumentRoot) appropriately, and create a ScriptAlias to the CGI: .RS 4
SetEnv GIT_PROJECT_ROOT /var/www/git SetEnv GIT_HTTP_EXPORT_ALL ScriptAlias /git/ /usr/libexec/git -core/git -http -backend/ .RE 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: .RS 4
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> .RE If you do not have mod_rewrite available to match against the query string, it is sufficient to just protect git-receive -pack itself, like: .RS 4
<LocationMatch "^/git/ .*/git -receive -pack$"> AuthType Basic AuthName "Git Access" Require group committers . . . </LocationMatch> .RE 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 http.receivepack config option in any repositories that should accept a push . The default behavior, if http.receivepack is not set, is to reject any pushes by unauthenticated users; the initial request will therefore report 403Forbidden to the client, without even giving an opportunity for authentication . To require authentication for both reads and writes, use a Location directive around the repository, or one of its parent directories: .RS 4
<Location /git/private> AuthType Basic AuthName "Private Git Access" Require group committers . . . </Location> .RE To serve gitweb at the same url, use a ScriptAliasMatch to only those URLs that githttp -backend can handle, and forward the rest to gitweb: .RS 4
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/$1
ScriptAlias /git/ /var/www/cgi -bin/gitweb .cgi/ .RE To serve multiple repositories from different gitnamespaces (7) in a single repository: .RS 4
SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1 ScriptAliasMatch ^/git/[^/]*( .*) /usr/libexec/git -core/git -http -backend/storage .git$1 .RE
Accelerated static Apache 2 .x 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: .RS 4
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/ .RE This can be combined with the gitweb configuration: .RS 4
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 \ "(?x)^/git/( .*/(HEAD | \ info/refs | \ objects/info/[^/]+ | \ git -(upload|receive) -pack))$" \ /usr/libexec/git -core/git -http -backend/$1 ScriptAlias /git/ /var/www/cgi -bin/gitweb .cgi/ .RE
Lighttpd Ensure that mod_cgi , mod_alias , mod_auth , mod_setenv are loaded, then set GIT_PROJECT_ROOT appropriately and redirect all requests to the CGI: .RS 4
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" => "" ) } .RE To enable anonymous read access but authenticated write access: .RS 4
$HTTP["querystring"] =~ "service=git -receive -pack" { include "git -auth .conf" } $HTTP["url"] =~ "^/git/ .*/git -receive -pack$" { include "git -auth .conf" } .RE where git-auth .conf looks something like: .RS 4
auth .require = ( "/" => ( "method" => "basic", "realm" => "Git Access", "require" => "valid -user" ) ) # . . .and set up auth .backend here .RE To require authentication for both reads and writes: .RS 4
$HTTP["url"] =~ "^/git/private" { include "git -auth .conf" } .RE
Apache 2 .x Ensure mod_cgi, mod_alias, and mod_env are enabled, set GIT_PROJECT_ROOT (or DocumentRoot) appropriately, and create a ScriptAlias to the CGI: .RS 4
SetEnv GIT_PROJECT_ROOT /var/www/git SetEnv GIT_HTTP_EXPORT_ALL ScriptAlias /git/ /usr/libexec/git -core/git -http -backend/ .RE 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: .RS 4
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> .RE If you do not have mod_rewrite available to match against the query string, it is sufficient to just protect git-receive -pack itself, like: .RS 4
<LocationMatch "^/git/ .*/git -receive -pack$"> AuthType Basic AuthName "Git Access" Require group committers . . . </LocationMatch> .RE 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 http.receivepack config option in any repositories that should accept a push . The default behavior, if http.receivepack is not set, is to reject any pushes by unauthenticated users; the initial request will therefore report 403Forbidden to the client, without even giving an opportunity for authentication . To require authentication for both reads and writes, use a Location directive around the repository, or one of its parent directories: .RS 4
<Location /git/private> AuthType Basic AuthName "Private Git Access" Require group committers . . . </Location> .RE To serve gitweb at the same url, use a ScriptAliasMatch to only those URLs that githttp -backend can handle, and forward the rest to gitweb: .RS 4
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/$1
ScriptAlias /git/ /var/www/cgi -bin/gitweb .cgi/ .RE To serve multiple repositories from different gitnamespaces (7) in a single repository: .RS 4
SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1 ScriptAliasMatch ^/git/[^/]*( .*) /usr/libexec/git -core/git -http -backend/storage .git$1 .RE
Accelerated static Apache 2 .x 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: .RS 4
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/ .RE This can be combined with the gitweb configuration: .RS 4
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 \ "(?x)^/git/( .*/(HEAD | \ info/refs | \ objects/info/[^/]+ | \ git -(upload|receive) -pack))$" \ /usr/libexec/git -core/git -http -backend/$1 ScriptAlias /git/ /var/www/cgi -bin/gitweb .cgi/ .RE
Lighttpd Ensure that mod_cgi , mod_alias , mod_auth , mod_setenv are loaded, then set GIT_PROJECT_ROOT appropriately and redirect all requests to the CGI: .RS 4
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" => "" ) } .RE To enable anonymous read access but authenticated write access: .RS 4
$HTTP["querystring"] =~ "service=git -receive -pack" { include "git -auth .conf" } $HTTP["url"] =~ "^/git/ .*/git -receive -pack$" { include "git -auth .conf" } .RE where git-auth .conf looks something like: .RS 4
auth .require = ( "/" => ( "method" => "basic", "realm" => "Git Access", "require" => "valid -user" ) ) # . . .and set up auth .backend here .RE To require authentication for both reads and writes: .RS 4
$HTTP["url"] =~ "^/git/private" { include "git -auth .conf" } .RE
ENVIRONMENT
githttp -backend relies upon the CGI environment variables set by the invoking web server, including: '-04' '+03' .sp -1
2.3 PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED) '-04' '+03' .sp -1
2.3 REMOTE_USER '-04' '+03' .sp -1
2.3 REMOTE_ADDR '-04' '+03' .sp -1
2.3 CONTENT_TYPE '-04' '+03' .sp -1
2.3 QUERY_STRING '-04' '+03' .sp -1
2.3 REQUEST_METHOD The GIT_HTTP_EXPORT_ALL environmental variable may be passed to git-http -backend to bypass the check for the "git -daemon -export -ok" file in each repository before allowing export of that repository . The GIT_HTTP_MAX_REQUEST_BUFFER environment variable (or the http.maxRequestBuffer 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 ., 100M for 100 megabytes) . The default is 10 megabytes . The backend process sets GIT_COMMITTER_NAME to $REMOTE_USER and GIT_COMMITTER_EMAIL to ${REMOTE_USER}@http.${REMOTE_ADDR} ,ensuring that any reflogs created by git-receive -pack contain some identifying information of the remote user who performed the push . All CGI environment variables are available to each of the hooks invoked by the git-receive -pack .
2.3 PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED) '-04' '+03' .sp -1
2.3 REMOTE_USER '-04' '+03' .sp -1
2.3 REMOTE_ADDR '-04' '+03' .sp -1
2.3 CONTENT_TYPE '-04' '+03' .sp -1
2.3 QUERY_STRING '-04' '+03' .sp -1
2.3 REQUEST_METHOD The GIT_HTTP_EXPORT_ALL environmental variable may be passed to git-http -backend to bypass the check for the "git -daemon -export -ok" file in each repository before allowing export of that repository . The GIT_HTTP_MAX_REQUEST_BUFFER environment variable (or the http.maxRequestBuffer 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 ., 100M for 100 megabytes) . The default is 10 megabytes . The backend process sets GIT_COMMITTER_NAME to $REMOTE_USER and GIT_COMMITTER_EMAIL to ${REMOTE_USER}@http.${REMOTE_ADDR} ,ensuring that any reflogs created by git-receive -pack contain some identifying information of the remote user who performed the push . All CGI environment variables are available to each of the hooks invoked by the git-receive -pack .
GIT
Part of the git (1)suite
