man1/git-http-backend.1

   1 '\" t
   2 .\"     Title: git-http-backend
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2023-08-14
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.42.0.rc1.11.gfc6bba66bc
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-HTTP\-BACKEND" "1" "2023\-08\-14" "Git 2\&.42\&.0\&.rc1\&.11\&.gf" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-http-backend \- Server side implementation of Git over HTTP
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit http\-backend\fR
  36 .fi
  37 .sp
  38 .SH "DESCRIPTION"
  39 .sp
  40 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 also supports Git\(cqs more\-efficient "v2" protocol if properly configured; see the discussion of \fBGIT_PROTOCOL\fR in the ENVIRONMENT section below\&.
  41 .sp
  42 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 \fBGIT_HTTP_EXPORT_ALL\fR environmental variable is set)\&.
  43 .sp
  44 By default, only the \fBupload\-pack\fR 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 \fBreceive\-pack\fR service is enabled, which serves \fIgit send\-pack\fR clients, which is invoked from \fIgit push\fR\&.
  45 .SH "SERVICES"
  46 .sp
  47 These services can be enabled/disabled using the per\-repository configuration file:
  48 .PP
  49 http\&.getanyfile
  50 .RS 4
  51 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
  52 \fBfalse\fR\&.
  53 .RE
  54 .PP
  55 http\&.uploadpack
  56 .RS 4
  57 This serves
  58 \fIgit fetch\-pack\fR
  59 and
  60 \fIgit ls\-remote\fR
  61 clients\&. It is enabled by default, but a repository can disable it by setting this configuration item to
  62 \fBfalse\fR\&.
  63 .RE
  64 .PP
  65 http\&.receivepack
  66 .RS 4
  67 This serves
  68 \fIgit send\-pack\fR
  69 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
  70 \fBfalse\fR, or enabled for all users, including anonymous users, by setting it to
  71 \fBtrue\fR\&.
  72 .RE
  73 .SH "URL TRANSLATION"
  74 .sp
  75 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\&.
  76 .SH "EXAMPLES"
  77 .sp
  78 All of the following examples map \fBhttp://$hostname/git/foo/bar\&.git\fR to \fB/var/www/git/foo/bar\&.git\fR\&.
  79 .PP
  80 Apache 2\&.x
  81 .RS 4
  82 Ensure mod_cgi, mod_alias, and mod_env are enabled, set GIT_PROJECT_ROOT (or DocumentRoot) appropriately, and create a ScriptAlias to the CGI:
  83 .sp
  84 .if n \{\
  85 .RS 4
  86 .\}
  87 .nf
  88 SetEnv GIT_PROJECT_ROOT /var/www/git
  89 SetEnv GIT_HTTP_EXPORT_ALL
  90 ScriptAlias /git/ /usr/libexec/git\-core/git\-http\-backend/
  91
  92 # This is not strictly necessary using Apache and a modern version of
  93 # git\-http\-backend, as the webserver will pass along the header in the
  94 # environment as HTTP_GIT_PROTOCOL, and http\-backend will copy that into
  95 # GIT_PROTOCOL\&. But you may need this line (or something similar if you
  96 # are using a different webserver), or if you want to support older Git
  97 # versions that did not do that copying\&.
  98 #
  99 # Having the webserver set up GIT_PROTOCOL is perfectly fine even with
 100 # modern versions (and will take precedence over HTTP_GIT_PROTOCOL,
 101 # which means it can be used to override the client\*(Aqs request)\&.
 102 SetEnvIf Git\-Protocol "\&.*" GIT_PROTOCOL=$0
 103 .fi
 104 .if n \{\
 105 .RE
 106 .\}
 107 .sp
 108 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:
 109 .sp
 110 .if n \{\
 111 .RS 4
 112 .\}
 113 .nf
 114 RewriteCond %{QUERY_STRING} service=git\-receive\-pack [OR]
 115 RewriteCond %{REQUEST_URI} /git\-receive\-pack$
 116 RewriteRule ^/git/ \- [E=AUTHREQUIRED:yes]
 117
 118 <LocationMatch "^/git/">
 119         Order Deny,Allow
 120         Deny from env=AUTHREQUIRED
 121
 122         AuthType Basic
 123         AuthName "Git Access"
 124         Require group committers
 125         Satisfy Any
 126         \&.\&.\&.
 127 </LocationMatch>
 128 .fi
 129 .if n \{\
 130 .RE
 131 .\}
 132 .sp
 133 If you do not have
 134 \fBmod_rewrite\fR
 135 available to match against the query string, it is sufficient to just protect
 136 \fBgit\-receive\-pack\fR
 137 itself, like:
 138 .sp
 139 .if n \{\
 140 .RS 4
 141 .\}
 142 .nf
 143 <LocationMatch "^/git/\&.*/git\-receive\-pack$">
 144         AuthType Basic
 145         AuthName "Git Access"
 146         Require group committers
 147         \&.\&.\&.
 148 </LocationMatch>
 149 .fi
 150 .if n \{\
 151 .RE
 152 .\}
 153 .sp
 154 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
 155 \fBhttp\&.receivepack\fR
 156 config option in any repositories that should accept a push\&. The default behavior, if
 157 \fBhttp\&.receivepack\fR
 158 is not set, is to reject any pushes by unauthenticated users; the initial request will therefore report
 159 \fB403 Forbidden\fR
 160 to the client, without even giving an opportunity for authentication\&.
 161 .sp
 162 To require authentication for both reads and writes, use a Location directive around the repository, or one of its parent directories:
 163 .sp
 164 .if n \{\
 165 .RS 4
 166 .\}
 167 .nf
 168 <Location /git/private>
 169         AuthType Basic
 170         AuthName "Private Git Access"
 171         Require group committers
 172         \&.\&.\&.
 173 </Location>
 174 .fi
 175 .if n \{\
 176 .RE
 177 .\}
 178 .sp
 179 To serve gitweb at the same url, use a ScriptAliasMatch to only those URLs that
 180 \fIgit http\-backend\fR
 181 can handle, and forward the rest to gitweb:
 182 .sp
 183 .if n \{\
 184 .RS 4
 185 .\}
 186 .nf
 187 ScriptAliasMatch \e
 188         "(?x)^/git/(\&.*/(HEAD | \e
 189                         info/refs | \e
 190                         objects/(info/[^/]+ | \e
 191                                  [0\-9a\-f]{2}/[0\-9a\-f]{38} | \e
 192                                  pack/pack\-[0\-9a\-f]{40}\e\&.(pack|idx)) | \e
 193                         git\-(upload|receive)\-pack))$" \e
 194         /usr/libexec/git\-core/git\-http\-backend/$1
 195
 196 ScriptAlias /git/ /var/www/cgi\-bin/gitweb\&.cgi/
 197 .fi
 198 .if n \{\
 199 .RE
 200 .\}
 201 .sp
 202 To serve multiple repositories from different
 203 \fBgitnamespaces\fR(7)
 204 in a single repository:
 205 .sp
 206 .if n \{\
 207 .RS 4
 208 .\}
 209 .nf
 210 SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1
 211 ScriptAliasMatch ^/git/[^/]*(\&.*) /usr/libexec/git\-core/git\-http\-backend/storage\&.git$1
 212 .fi
 213 .if n \{\
 214 .RE
 215 .\}
 216 .sp
 217 .RE
 218 .PP
 219 Accelerated static Apache 2\&.x
 220 .RS 4
 221 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:
 222 .sp
 223 .if n \{\
 224 .RS 4
 225 .\}
 226 .nf
 227 SetEnv GIT_PROJECT_ROOT /var/www/git
 228
 229 AliasMatch ^/git/(\&.*/objects/[0\-9a\-f]{2}/[0\-9a\-f]{38})$          /var/www/git/$1
 230 AliasMatch ^/git/(\&.*/objects/pack/pack\-[0\-9a\-f]{40}\&.(pack|idx))$ /var/www/git/$1
 231 ScriptAlias /git/ /usr/libexec/git\-core/git\-http\-backend/
 232 .fi
 233 .if n \{\
 234 .RE
 235 .\}
 236 .sp
 237 This can be combined with the gitweb configuration:
 238 .sp
 239 .if n \{\
 240 .RS 4
 241 .\}
 242 .nf
 243 SetEnv GIT_PROJECT_ROOT /var/www/git
 244
 245 AliasMatch ^/git/(\&.*/objects/[0\-9a\-f]{2}/[0\-9a\-f]{38})$          /var/www/git/$1
 246 AliasMatch ^/git/(\&.*/objects/pack/pack\-[0\-9a\-f]{40}\&.(pack|idx))$ /var/www/git/$1
 247 ScriptAliasMatch \e
 248         "(?x)^/git/(\&.*/(HEAD | \e
 249                         info/refs | \e
 250                         objects/info/[^/]+ | \e
 251                         git\-(upload|receive)\-pack))$" \e
 252         /usr/libexec/git\-core/git\-http\-backend/$1
 253 ScriptAlias /git/ /var/www/cgi\-bin/gitweb\&.cgi/
 254 .fi
 255 .if n \{\
 256 .RE
 257 .\}
 258 .sp
 259 .RE
 260 .PP
 261 Lighttpd
 262 .RS 4
 263 Ensure that
 264 \fBmod_cgi\fR,
 265 \fBmod_alias\fR,
 266 \fBmod_auth\fR,
 267 \fBmod_setenv\fR
 268 are loaded, then set
 269 \fBGIT_PROJECT_ROOT\fR
 270 appropriately and redirect all requests to the CGI:
 271 .sp
 272 .if n \{\
 273 .RS 4
 274 .\}
 275 .nf
 276 alias\&.url += ( "/git" => "/usr/lib/git\-core/git\-http\-backend" )
 277 $HTTP["url"] =~ "^/git" {
 278         cgi\&.assign = ("" => "")
 279         setenv\&.add\-environment = (
 280                 "GIT_PROJECT_ROOT" => "/var/www/git",
 281                 "GIT_HTTP_EXPORT_ALL" => ""
 282         )
 283 }
 284 .fi
 285 .if n \{\
 286 .RE
 287 .\}
 288 .sp
 289 To enable anonymous read access but authenticated write access:
 290 .sp
 291 .if n \{\
 292 .RS 4
 293 .\}
 294 .nf
 295 $HTTP["querystring"] =~ "service=git\-receive\-pack" {
 296         include "git\-auth\&.conf"
 297 }
 298 $HTTP["url"] =~ "^/git/\&.*/git\-receive\-pack$" {
 299         include "git\-auth\&.conf"
 300 }
 301 .fi
 302 .if n \{\
 303 .RE
 304 .\}
 305 .sp
 306 where
 307 \fBgit\-auth\&.conf\fR
 308 looks something like:
 309 .sp
 310 .if n \{\
 311 .RS 4
 312 .\}
 313 .nf
 314 auth\&.require = (
 315         "/" => (
 316                 "method" => "basic",
 317                 "realm" => "Git Access",
 318                 "require" => "valid\-user"
 319                )
 320 )
 321 # \&.\&.\&.and set up auth\&.backend here
 322 .fi
 323 .if n \{\
 324 .RE
 325 .\}
 326 .sp
 327 To require authentication for both reads and writes:
 328 .sp
 329 .if n \{\
 330 .RS 4
 331 .\}
 332 .nf
 333 $HTTP["url"] =~ "^/git/private" {
 334         include "git\-auth\&.conf"
 335 }
 336 .fi
 337 .if n \{\
 338 .RE
 339 .\}
 340 .sp
 341 .RE
 342 .SH "ENVIRONMENT"
 343 .sp
 344 \fIgit http\-backend\fR relies upon the \fBCGI\fR environment variables set by the invoking web server, including:
 345 .sp
 346 .RS 4
 347 .ie n \{\
 348 \h'-04'\(bu\h'+03'\c
 349 .\}
 350 .el \{\
 351 .sp -1
 352 .IP \(bu 2.3
 353 .\}
 354 PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED)
 355 .RE
 356 .sp
 357 .RS 4
 358 .ie n \{\
 359 \h'-04'\(bu\h'+03'\c
 360 .\}
 361 .el \{\
 362 .sp -1
 363 .IP \(bu 2.3
 364 .\}
 365 REMOTE_USER
 366 .RE
 367 .sp
 368 .RS 4
 369 .ie n \{\
 370 \h'-04'\(bu\h'+03'\c
 371 .\}
 372 .el \{\
 373 .sp -1
 374 .IP \(bu 2.3
 375 .\}
 376 REMOTE_ADDR
 377 .RE
 378 .sp
 379 .RS 4
 380 .ie n \{\
 381 \h'-04'\(bu\h'+03'\c
 382 .\}
 383 .el \{\
 384 .sp -1
 385 .IP \(bu 2.3
 386 .\}
 387 CONTENT_TYPE
 388 .RE
 389 .sp
 390 .RS 4
 391 .ie n \{\
 392 \h'-04'\(bu\h'+03'\c
 393 .\}
 394 .el \{\
 395 .sp -1
 396 .IP \(bu 2.3
 397 .\}
 398 QUERY_STRING
 399 .RE
 400 .sp
 401 .RS 4
 402 .ie n \{\
 403 \h'-04'\(bu\h'+03'\c
 404 .\}
 405 .el \{\
 406 .sp -1
 407 .IP \(bu 2.3
 408 .\}
 409 REQUEST_METHOD
 410 .RE
 411 .sp
 412 The \fBGIT_HTTP_EXPORT_ALL\fR 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\&.
 413 .sp
 414 The \fBGIT_HTTP_MAX_REQUEST_BUFFER\fR environment variable (or the \fBhttp\&.maxRequestBuffer\fR 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\&., \fB100M\fR for 100 megabytes)\&. The default is 10 megabytes\&.
 415 .sp
 416 Clients may probe for optional protocol capabilities (like the v2 protocol) using the \fBGit\-Protocol\fR HTTP header\&. In order to support these, the contents of that header must appear in the \fBGIT_PROTOCOL\fR environment variable\&. Most webservers will pass this header to the CGI via the \fBHTTP_GIT_PROTOCOL\fR variable, and \fBgit\-http\-backend\fR will automatically copy that to \fBGIT_PROTOCOL\fR\&. However, some webservers may be more selective about which headers they\(cqll pass, in which case they need to be configured explicitly (see the mention of \fBGit\-Protocol\fR in the Apache config from the earlier EXAMPLES section)\&.
 417 .sp
 418 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\&.
 419 .sp
 420 All \fBCGI\fR environment variables are available to each of the hooks invoked by the \fIgit\-receive\-pack\fR\&.
 421 .SH "GIT"
 422 .sp
 423 Part of the \fBgit\fR(1) suite