logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-http-backend.1 (13382B)


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