]> git.ipfire.org Git - thirdparty/git.git/blame - Documentation/git-http-backend.txt
Merge branch 'js/t3404-typofix' into maint
[thirdparty/git.git] / Documentation / git-http-backend.txt
CommitLineData
2f4038ab
SP
1git-http-backend(1)
2===================
3
4NAME
5----
6git-http-backend - Server side implementation of Git over HTTP
7
8SYNOPSIS
9--------
10[verse]
0b444cdb 11'git http-backend'
2f4038ab
SP
12
13DESCRIPTION
14-----------
15A simple CGI program to serve the contents of a Git repository to Git
16clients accessing the repository over http:// and https:// protocols.
6a5d0b0a 17The program supports clients fetching using both the smart HTTP protocol
b9af4ab3
ML
18and the backwards-compatible dumb HTTP protocol, as well as clients
19pushing using the smart HTTP protocol.
2f4038ab 20
8b2bd7cd 21It verifies that the directory has the magic file
2de9b711 22"git-daemon-export-ok", and it will refuse to export any Git directory
8b2bd7cd 23that hasn't explicitly been marked for export this way (unless the
47d81b5c 24`GIT_HTTP_EXPORT_ALL` environmental variable is set).
8b2bd7cd 25
2f4038ab 26By default, only the `upload-pack` service is enabled, which serves
0b444cdb
TR
27'git fetch-pack' and 'git ls-remote' clients, which are invoked from
28'git fetch', 'git pull', and 'git clone'. If the client is authenticated,
29the `receive-pack` service is enabled, which serves 'git send-pack'
30clients, which is invoked from 'git push'.
2f4038ab 31
556cfa3b
SP
32SERVICES
33--------
34These services can be enabled/disabled using the per-repository
35configuration file:
36
5abb013b 37http.getanyfile::
09f53b16 38 This serves Git clients older than version 1.6.6 that are unable to use the
5abb013b
SP
39 upload pack service. When enabled, clients are able to read
40 any file within the repository, including objects that are
41 no longer reachable from a branch but are still present.
42 It is enabled by default, but a repository can disable it
43 by setting this configuration item to `false`.
44
556cfa3b 45http.uploadpack::
0b444cdb 46 This serves 'git fetch-pack' and 'git ls-remote' clients.
556cfa3b
SP
47 It is enabled by default, but a repository can disable it
48 by setting this configuration item to `false`.
49
50http.receivepack::
0b444cdb 51 This serves 'git send-pack' clients, allowing push. It is
556cfa3b
SP
52 disabled by default for anonymous users, and enabled by
53 default for users authenticated by the web server. It can be
54 disabled by setting this item to `false`, or enabled for all
55 users, including anonymous users, by setting it to `true`.
56
2f4038ab
SP
57URL TRANSLATION
58---------------
0b444cdb 59To determine the location of the repository on disk, 'git http-backend'
917adc03
ML
60concatenates the environment variables PATH_INFO, which is set
61automatically by the web server, and GIT_PROJECT_ROOT, which must be set
62manually in the web server configuration. If GIT_PROJECT_ROOT is not
0b444cdb 63set, 'git http-backend' reads PATH_TRANSLATED, which is also set
917adc03 64automatically by the web server.
2f4038ab
SP
65
66EXAMPLES
67--------
d595bdc1
JK
68All of the following examples map `http://$hostname/git/foo/bar.git`
69to `/var/www/git/foo/bar.git`.
2f4038ab
SP
70
71Apache 2.x::
917adc03
ML
72 Ensure mod_cgi, mod_alias, and mod_env are enabled, set
73 GIT_PROJECT_ROOT (or DocumentRoot) appropriately, and
74 create a ScriptAlias to the CGI:
2f4038ab
SP
75+
76----------------------------------------------------------------
917adc03 77SetEnv GIT_PROJECT_ROOT /var/www/git
8b2bd7cd 78SetEnv GIT_HTTP_EXPORT_ALL
917adc03 79ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/
2f4038ab
SP
80----------------------------------------------------------------
81+
556cfa3b 82To enable anonymous read access but authenticated write access,
b0808819
JK
83require authorization for both the initial ref advertisement (which we
84detect as a push via the service parameter in the query string), and the
85receive-pack invocation itself:
86+
87----------------------------------------------------------------
88RewriteCond %{QUERY_STRING} service=git-receive-pack [OR]
89RewriteCond %{REQUEST_URI} /git-receive-pack$
90RewriteRule ^/git/ - [E=AUTHREQUIRED:yes]
91
92<LocationMatch "^/git/">
93 Order Deny,Allow
94 Deny from env=AUTHREQUIRED
95
96 AuthType Basic
97 AuthName "Git Access"
98 Require group committers
99 Satisfy Any
100 ...
101</LocationMatch>
102----------------------------------------------------------------
103+
104If you do not have `mod_rewrite` available to match against the query
105string, it is sufficient to just protect `git-receive-pack` itself,
106like:
556cfa3b
SP
107+
108----------------------------------------------------------------
f5ba2d18 109<LocationMatch "^/git/.*/git-receive-pack$">
556cfa3b
SP
110 AuthType Basic
111 AuthName "Git Access"
112 Require group committers
113 ...
114</LocationMatch>
115----------------------------------------------------------------
116+
fdae1910
JK
117In this mode, the server will not request authentication until the
118client actually starts the object negotiation phase of the push, rather
119than during the initial contact. For this reason, you must also enable
120the `http.receivepack` config option in any repositories that should
121accept a push. The default behavior, if `http.receivepack` is not set,
122is to reject any pushes by unauthenticated users; the initial request
123will therefore report `403 Forbidden` to the client, without even giving
124an opportunity for authentication.
125+
917adc03 126To require authentication for both reads and writes, use a Location
2f4038ab
SP
127directive around the repository, or one of its parent directories:
128+
129----------------------------------------------------------------
917adc03 130<Location /git/private>
2f4038ab
SP
131 AuthType Basic
132 AuthName "Private Git Access"
133 Require group committers
134 ...
917adc03 135</Location>
2f4038ab 136----------------------------------------------------------------
8127f778
ML
137+
138To serve gitweb at the same url, use a ScriptAliasMatch to only
0b444cdb 139those URLs that 'git http-backend' can handle, and forward the
8127f778
ML
140rest to gitweb:
141+
142----------------------------------------------------------------
143ScriptAliasMatch \
144 "(?x)^/git/(.*/(HEAD | \
145 info/refs | \
146 objects/(info/[^/]+ | \
147 [0-9a-f]{2}/[0-9a-f]{38} | \
148 pack/pack-[0-9a-f]{40}\.(pack|idx)) | \
149 git-(upload|receive)-pack))$" \
150 /usr/libexec/git-core/git-http-backend/$1
151
152ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/
153----------------------------------------------------------------
d49483f0
JT
154+
155To serve multiple repositories from different linkgit:gitnamespaces[7] in a
156single repository:
157+
158----------------------------------------------------------------
159SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1
160ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1
161----------------------------------------------------------------
2f4038ab
SP
162
163Accelerated static Apache 2.x::
164 Similar to the above, but Apache can be used to return static
8d75a1d1 165 files that are stored on disk. On many systems this may
2f4038ab
SP
166 be more efficient as Apache can ask the kernel to copy the
167 file contents from the file system directly to the network:
168+
169----------------------------------------------------------------
917adc03 170SetEnv GIT_PROJECT_ROOT /var/www/git
2f4038ab 171
0ebb1fa7
ML
172AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /var/www/git/$1
173AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1
174ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/
2f4038ab 175----------------------------------------------------------------
8127f778
ML
176+
177This can be combined with the gitweb configuration:
178+
179----------------------------------------------------------------
180SetEnv GIT_PROJECT_ROOT /var/www/git
181
182AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$ /var/www/git/$1
183AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1
184ScriptAliasMatch \
185 "(?x)^/git/(.*/(HEAD | \
186 info/refs | \
187 objects/info/[^/]+ | \
188 git-(upload|receive)-pack))$" \
189 /usr/libexec/git-core/git-http-backend/$1
190ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/
191----------------------------------------------------------------
2f4038ab 192
3813a33d 193Lighttpd::
5df05146 194 Ensure that `mod_cgi`, `mod_alias`, `mod_auth`, `mod_setenv` are
3813a33d
JK
195 loaded, then set `GIT_PROJECT_ROOT` appropriately and redirect
196 all requests to the CGI:
197+
198----------------------------------------------------------------
199alias.url += ( "/git" => "/usr/lib/git-core/git-http-backend" )
200$HTTP["url"] =~ "^/git" {
201 cgi.assign = ("" => "")
202 setenv.add-environment = (
203 "GIT_PROJECT_ROOT" => "/var/www/git",
204 "GIT_HTTP_EXPORT_ALL" => ""
205 )
206}
207----------------------------------------------------------------
208+
209To enable anonymous read access but authenticated write access:
210+
211----------------------------------------------------------------
212$HTTP["querystring"] =~ "service=git-receive-pack" {
213 include "git-auth.conf"
214}
215$HTTP["url"] =~ "^/git/.*/git-receive-pack$" {
216 include "git-auth.conf"
217}
218----------------------------------------------------------------
219+
220where `git-auth.conf` looks something like:
221+
222----------------------------------------------------------------
223auth.require = (
224 "/" => (
225 "method" => "basic",
226 "realm" => "Git Access",
227 "require" => "valid-user"
228 )
229)
230# ...and set up auth.backend here
231----------------------------------------------------------------
232+
3813a33d
JK
233To require authentication for both reads and writes:
234+
235----------------------------------------------------------------
236$HTTP["url"] =~ "^/git/private" {
237 include "git-auth.conf"
238}
239----------------------------------------------------------------
240
2f4038ab
SP
241
242ENVIRONMENT
243-----------
47d81b5c 244'git http-backend' relies upon the `CGI` environment variables set
2f4038ab
SP
245by the invoking web server, including:
246
917adc03 247* PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED)
2f4038ab
SP
248* REMOTE_USER
249* REMOTE_ADDR
250* CONTENT_TYPE
251* QUERY_STRING
252* REQUEST_METHOD
253
47d81b5c 254The `GIT_HTTP_EXPORT_ALL` environmental variable may be passed to
8b2bd7cd
TC
255'git-http-backend' to bypass the check for the "git-daemon-export-ok"
256file in each repository before allowing export of that repository.
257
6bc0cb51
JK
258The `GIT_HTTP_MAX_REQUEST_BUFFER` environment variable (or the
259`http.maxRequestBuffer` config variable) may be set to change the
260largest ref negotiation request that git will handle during a fetch; any
261fetch requiring a larger buffer will not succeed. This value should not
262normally need to be changed, but may be helpful if you are fetching from
263a repository with an extremely large number of refs. The value can be
264specified with a unit (e.g., `100M` for 100 megabytes). The default is
26510 megabytes.
266
556cfa3b
SP
267The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and
268GIT_COMMITTER_EMAIL to '$\{REMOTE_USER}@http.$\{REMOTE_ADDR\}',
269ensuring that any reflogs created by 'git-receive-pack' contain some
270identifying information of the remote user who performed the push.
271
47d81b5c 272All `CGI` environment variables are available to each of the hooks
556cfa3b
SP
273invoked by the 'git-receive-pack'.
274
2f4038ab
SP
275GIT
276---
277Part of the linkgit:git[1] suite