git-http-backend.1 [plain text]
'\" t
.\" Title: git-http-backend
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 06/01/2011
.\" Manual: Git Manual
.\" Source: Git 1.7.5.4
.\" Language: English
.\"
.TH "GIT\-HTTP\-BACKEND" "1" "06/01/2011" "Git 1\&.7\&.5\&.4" "Git Manual"
.\" -----------------------------------------------------------------
.\" * 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 GIT_HTTP_EXPORT_ALL environmental variable is set)\&.
.sp
By default, only the upload\-pack 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 receive\-pack 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
false\&.
.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
false\&.
.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
false, or enabled for all users, including anonymous users, by setting it to
true\&.
.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 \fIhttp://$hostname/git/foo/bar\&.git\fR to \fI/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 with a LocationMatch directive:
.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
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
.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
.SH "ENVIRONMENT"
.sp
\fIgit http\-backend\fR relies upon the CGI 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 GIT_HTTP_EXPORT_ALL 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 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 CGI environment variables are available to each of the hooks invoked by the \fIgit\-receive\-pack\fR\&.
.SH "AUTHOR"
.sp
Written by Shawn O\&. Pearce <\m[blue]\fBspearce@spearce\&.org\fR\m[]\&\s-2\u[1]\d\s+2>\&.
.SH "DOCUMENTATION"
.sp
Documentation by Shawn O\&. Pearce <\m[blue]\fBspearce@spearce\&.org\fR\m[]\&\s-2\u[1]\d\s+2>\&.
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite
.SH "NOTES"
.IP " 1." 4
spearce@spearce.org
.RS 4
\%mailto:spearce@spearce.org
.RE