diff options
Diffstat (limited to 'Documentation/git-http-backend.txt')
| -rw-r--r-- | Documentation/git-http-backend.txt | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt new file mode 100644 index 0000000000..5238820657 --- /dev/null +++ b/Documentation/git-http-backend.txt @@ -0,0 +1,188 @@ +git-http-backend(1) +=================== + +NAME +---- +git-http-backend - Server side implementation of Git over HTTP + +SYNOPSIS +-------- +[verse] +'git http-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't 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 +'git fetch-pack' and 'git ls-remote' clients, which are invoked from +'git fetch', 'git pull', and 'git clone'. If the client is authenticated, +the `receive-pack` service is enabled, which serves 'git send-pack' +clients, which is invoked from 'git push'. + +SERVICES +-------- +These services can be enabled/disabled using the per-repository +configuration file: + +http.getanyfile:: + This serves older Git clients which 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 'git fetch-pack' and 'git ls-remote' clients. + It is enabled by default, but a repository can disable it + by setting this configuration item to `false`. + +http.receivepack:: + This serves 'git send-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, 'git http-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, 'git http-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: ++ +---------------------------------------------------------------- +SetEnv GIT_PROJECT_ROOT /var/www/git +SetEnv GIT_HTTP_EXPORT_ALL +ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/ +---------------------------------------------------------------- ++ +To enable anonymous read access but authenticated write access, +require authorization with a LocationMatch directive: ++ +---------------------------------------------------------------- +<LocationMatch "^/git/.*/git-receive-pack$"> + AuthType Basic + AuthName "Git Access" + Require group committers + ... +</LocationMatch> +---------------------------------------------------------------- ++ +To require authentication for both reads and writes, use a Location +directive 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 only +those URLs that 'git http-backend' can handle, and forward the +rest 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/$1 + +ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/ +---------------------------------------------------------------- + +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: ++ +---------------------------------------------------------------- +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/ +---------------------------------------------------------------- ++ +This can be combined with the gitweb configuration: ++ +---------------------------------------------------------------- +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/ +---------------------------------------------------------------- + + +ENVIRONMENT +----------- +'git http-backend' relies upon the CGI environment variables set +by 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 + +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 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'. + +Author +------ +Written by Shawn O. Pearce <spearce@spearce.org>. + +Documentation +-------------- +Documentation by Shawn O. Pearce <spearce@spearce.org>. + +GIT +--- +Part of the linkgit:git[1] suite |