1GIT-HTTP-BACKEND(1)               Git Manual               GIT-HTTP-BACKEND(1)
2
3
4

NAME

6       git-http-backend - Server side implementation of Git over HTTP
7

SYNOPSIS

9       git http-backend
10

DESCRIPTION

12       A simple CGI program to serve the contents of a Git repository to Git
13       clients accessing the repository over http:// and https:// protocols.
14       The program supports clients fetching using both the smart HTTP
15       protocol and the backwards-compatible dumb HTTP protocol, as well as
16       clients pushing using the smart HTTP protocol. It also supports Git’s
17       more-efficient "v2" protocol if properly configured; see the discussion
18       of GIT_PROTOCOL in the ENVIRONMENT section below.
19
20       It verifies that the directory has the magic file
21       "git-daemon-export-ok", and it will refuse to export any Git directory
22       that hasn’t explicitly been marked for export this way (unless the
23       GIT_HTTP_EXPORT_ALL environment variable is set).
24
25       By default, only the upload-pack service is enabled, which serves git
26       fetch-pack and git ls-remote clients, which are invoked from git fetch,
27       git pull, and git clone. If the client is authenticated, the
28       receive-pack service is enabled, which serves git send-pack clients,
29       which is invoked from git push.
30

SERVICES

32       These services can be enabled/disabled using the per-repository
33       configuration file:
34
35       http.getanyfile
36           This serves Git clients older than version 1.6.6 that are unable to
37           use the upload pack service. When enabled, clients are able to read
38           any file within the repository, including objects that are no
39           longer reachable from a branch but are still present. It is enabled
40           by default, but a repository can disable it by setting this
41           configuration value to false.
42
43       http.uploadpack
44           This serves git fetch-pack and git ls-remote clients. It is enabled
45           by default, but a repository can disable it by setting this
46           configuration value to false.
47
48       http.receivepack
49           This serves git send-pack clients, allowing push. It is disabled by
50           default for anonymous users, and enabled by default for users
51           authenticated by the web server. It can be disabled by setting this
52           item to false, or enabled for all users, including anonymous users,
53           by setting it to true.
54

URL TRANSLATION

56       To determine the location of the repository on disk, git http-backend
57       concatenates the environment variables PATH_INFO, which is set
58       automatically by the web server, and GIT_PROJECT_ROOT, which must be
59       set manually in the web server configuration. If GIT_PROJECT_ROOT is
60       not set, git http-backend reads PATH_TRANSLATED, which is also set
61       automatically by the web server.
62

EXAMPLES

64       All of the following examples map http://$hostname/git/foo/bar.git to
65       /var/www/git/foo/bar.git.
66
67       Apache 2.x
68           Ensure mod_cgi, mod_alias, and mod_env are enabled, set
69           GIT_PROJECT_ROOT (or DocumentRoot) appropriately, and create a
70           ScriptAlias to the CGI:
71
72               SetEnv GIT_PROJECT_ROOT /var/www/git
73               SetEnv GIT_HTTP_EXPORT_ALL
74               ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/
75
76               # This is not strictly necessary using Apache and a modern version of
77               # git-http-backend, as the webserver will pass along the header in the
78               # environment as HTTP_GIT_PROTOCOL, and http-backend will copy that into
79               # GIT_PROTOCOL. But you may need this line (or something similar if you
80               # are using a different webserver), or if you want to support older Git
81               # versions that did not do that copying.
82               #
83               # Having the webserver set up GIT_PROTOCOL is perfectly fine even with
84               # modern versions (and will take precedence over HTTP_GIT_PROTOCOL,
85               # which means it can be used to override the client's request).
86               SetEnvIf Git-Protocol ".*" GIT_PROTOCOL=$0
87
88           To enable anonymous read access but authenticated write access,
89           require authorization for both the initial ref advertisement (which
90           we detect as a push via the service parameter in the query string),
91           and the receive-pack invocation itself:
92
93               RewriteCond %{QUERY_STRING} service=git-receive-pack [OR]
94               RewriteCond %{REQUEST_URI} /git-receive-pack$
95               RewriteRule ^/git/ - [E=AUTHREQUIRED:yes]
96
97               <LocationMatch "^/git/">
98                       Order Deny,Allow
99                       Deny from env=AUTHREQUIRED
100
101                       AuthType Basic
102                       AuthName "Git Access"
103                       Require group committers
104                       Satisfy Any
105                       ...
106               </LocationMatch>
107
108           If you do not have mod_rewrite available to match against the query
109           string, it is sufficient to just protect git-receive-pack itself,
110           like:
111
112               <LocationMatch "^/git/.*/git-receive-pack$">
113                       AuthType Basic
114                       AuthName "Git Access"
115                       Require group committers
116                       ...
117               </LocationMatch>
118
119           In this mode, the server will not request authentication until the
120           client actually starts the object negotiation phase of the push,
121           rather than during the initial contact. For this reason, you must
122           also enable the http.receivepack config option in any repositories
123           that should accept a push. The default behavior, if
124           http.receivepack is not set, is to reject any pushes by
125           unauthenticated users; the initial request will therefore report
126           403 Forbidden to the client, without even giving an opportunity for
127           authentication.
128
129           To require authentication for both reads and writes, use a Location
130           directive around the repository, or one of its parent directories:
131
132               <Location /git/private>
133                       AuthType Basic
134                       AuthName "Private Git Access"
135                       Require group committers
136                       ...
137               </Location>
138
139           To serve gitweb at the same url, use a ScriptAliasMatch to only
140           those URLs that git http-backend can handle, and forward the rest
141           to gitweb:
142
143               ScriptAliasMatch \
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
152               ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/
153
154           To serve multiple repositories from different gitnamespaces(7) in a
155           single repository:
156
157               SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1
158               ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1
159
160       Accelerated static Apache 2.x
161           Similar to the above, but Apache can be used to return static files
162           that are stored on disk. On many systems this may be more efficient
163           as Apache can ask the kernel to copy the file contents from the
164           file system directly to the network:
165
166               SetEnv GIT_PROJECT_ROOT /var/www/git
167
168               AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$          /var/www/git/$1
169               AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1
170               ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/
171
172           This can be combined with the gitweb configuration:
173
174               SetEnv GIT_PROJECT_ROOT /var/www/git
175
176               AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$          /var/www/git/$1
177               AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1
178               ScriptAliasMatch \
179                       "(?x)^/git/(.*/(HEAD | \
180                                       info/refs | \
181                                       objects/info/[^/]+ | \
182                                       git-(upload|receive)-pack))$" \
183                       /usr/libexec/git-core/git-http-backend/$1
184               ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/
185
186       Lighttpd
187           Ensure that mod_cgi, mod_alias, mod_auth, mod_setenv are loaded,
188           then set GIT_PROJECT_ROOT appropriately and redirect all requests
189           to the CGI:
190
191               alias.url += ( "/git" => "/usr/lib/git-core/git-http-backend" )
192               $HTTP["url"] =~ "^/git" {
193                       cgi.assign = ("" => "")
194                       setenv.add-environment = (
195                               "GIT_PROJECT_ROOT" => "/var/www/git",
196                               "GIT_HTTP_EXPORT_ALL" => ""
197                       )
198               }
199
200           To enable anonymous read access but authenticated write access:
201
202               $HTTP["querystring"] =~ "service=git-receive-pack" {
203                       include "git-auth.conf"
204               }
205               $HTTP["url"] =~ "^/git/.*/git-receive-pack$" {
206                       include "git-auth.conf"
207               }
208
209           where git-auth.conf looks something like:
210
211               auth.require = (
212                       "/" => (
213                               "method" => "basic",
214                               "realm" => "Git Access",
215                               "require" => "valid-user"
216                              )
217               )
218               # ...and set up auth.backend here
219
220           To require authentication for both reads and writes:
221
222               $HTTP["url"] =~ "^/git/private" {
223                       include "git-auth.conf"
224               }
225

ENVIRONMENT

227       git http-backend relies upon the CGI environment variables set by the
228       invoking web server, including:
229
230       •   PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED)
231
232       •   REMOTE_USER
233
234       •   REMOTE_ADDR
235
236       •   CONTENT_TYPE
237
238       •   QUERY_STRING
239
240       •   REQUEST_METHOD
241
242       The GIT_HTTP_EXPORT_ALL environment variable may be passed to
243       git-http-backend to bypass the check for the "git-daemon-export-ok"
244       file in each repository before allowing export of that repository.
245
246       The GIT_HTTP_MAX_REQUEST_BUFFER environment variable (or the
247       http.maxRequestBuffer config option) may be set to change the largest
248       ref negotiation request that git will handle during a fetch; any fetch
249       requiring a larger buffer will not succeed. This value should not
250       normally need to be changed, but may be helpful if you are fetching
251       from a repository with an extremely large number of refs. The value can
252       be specified with a unit (e.g., 100M for 100 megabytes). The default is
253       10 megabytes.
254
255       Clients may probe for optional protocol capabilities (like the v2
256       protocol) using the Git-Protocol HTTP header. In order to support
257       these, the contents of that header must appear in the GIT_PROTOCOL
258       environment variable. Most webservers will pass this header to the CGI
259       via the HTTP_GIT_PROTOCOL variable, and git-http-backend will
260       automatically copy that to GIT_PROTOCOL. However, some webservers may
261       be more selective about which headers they’ll pass, in which case they
262       need to be configured explicitly (see the mention of Git-Protocol in
263       the Apache config from the earlier EXAMPLES section).
264
265       The backend process sets GIT_COMMITTER_NAME to $REMOTE_USER and
266       GIT_COMMITTER_EMAIL to ${REMOTE_USER}@http.${REMOTE_ADDR}, ensuring
267       that any reflogs created by git-receive-pack contain some identifying
268       information of the remote user who performed the push.
269
270       All CGI environment variables are available to each of the hooks
271       invoked by the git-receive-pack.
272

GIT

274       Part of the git(1) suite
275
276
277
278Git 2.43.0                        11/20/2023               GIT-HTTP-BACKEND(1)
Impressum