4c6fffe2ae · matheusbsbs/matheus-bagliano

@@ -0,0 +1,503 @@

1 +HTTP transfer protocols

2 +=======================

3 +

4 +Git supports two HTTP based transfer protocols. A "dumb" protocol

5 +which requires only a standard HTTP server on the server end of the

6 +connection, and a "smart" protocol which requires a Git aware CGI

7 +(or server module). This document describes both protocols.

8 +

9 +As a design feature smart clients can automatically upgrade "dumb"

10 +protocol URLs to smart URLs. This permits all users to have the

11 +same published URL, and the peers automatically select the most

12 +efficient transport available to them.

13 +

14 +

15 +URL Format

16 +----------

17 +

18 +URLs for Git repositories accessed by HTTP use the standard HTTP

19 +URL syntax documented by RFC 1738, so they are of the form:

20 +

21 + http://<host>:<port>/<path>?<searchpart>

22 +

23 +Within this documentation the placeholder $GIT_URL will stand for

24 +the http:// repository URL entered by the end-user.

25 +

26 +Servers SHOULD handle all requests to locations matching $GIT_URL, as

27 +both the "smart" and "dumb" HTTP protocols used by Git operate

28 +by appending additional path components onto the end of the user

29 +supplied $GIT_URL string.

30 +

31 +An example of a dumb client requesting for a loose object:

32 +

33 + $GIT_URL: http://example.com:8080/git/repo.git

34 + URL request: http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355

35 +

36 +An example of a smart request to a catch-all gateway:

37 +

38 + $GIT_URL: http://example.com/daemon.cgi?svc=git&q=

39 + URL request: http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack

40 +

41 +An example of a request to a submodule:

42 +

43 + $GIT_URL: http://example.com/git/repo.git/path/submodule.git

44 + URL request: http://example.com/git/repo.git/path/submodule.git/info/refs

45 +

46 +Clients MUST strip a trailing '/', if present, from the user supplied

47 +$GIT_URL string to prevent empty path tokens ('//') from appearing

48 +in any URL sent to a server. Compatible clients MUST expand

49 +'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.

50 +

51 +

52 +Authentication

53 +--------------

54 +

55 +Standard HTTP authentication is used if authentication is required

56 +to access a repository, and MAY be configured and enforced by the

57 +HTTP server software.

58 +

59 +Because Git repositories are accessed by standard path components

60 +server administrators MAY use directory based permissions within

61 +their HTTP server to control repository access.

62 +

63 +Clients SHOULD support Basic authentication as described by RFC 2616.

64 +Servers SHOULD support Basic authentication by relying upon the

65 +HTTP server placed in front of the Git server software.

66 +

67 +Servers SHOULD NOT require HTTP cookies for the purposes of

68 +authentication or access control.

69 +

70 +Clients and servers MAY support other common forms of HTTP based

71 +authentication, such as Digest authentication.

72 +

73 +

74 +SSL

75 +---

76 +

77 +Clients and servers SHOULD support SSL, particularly to protect

78 +passwords when relying on Basic HTTP authentication.

79 +

80 +

81 +Session State

82 +-------------

83 +

84 +The Git over HTTP protocol (much like HTTP itself) is stateless

85 +from the perspective of the HTTP server side. All state MUST be

86 +retained and managed by the client process. This permits simple

87 +round-robin load-balancing on the server side, without needing to

88 +worry about state management.

89 +

90 +Clients MUST NOT require state management on the server side in

91 +order to function correctly.

92 +

93 +Servers MUST NOT require HTTP cookies in order to function correctly.

94 +Clients MAY store and forward HTTP cookies during request processing

95 +as described by RFC 2616 (HTTP/1.1). Servers SHOULD ignore any

96 +cookies sent by a client.

97 +

98 +

99 +General Request Processing

100 +--------------------------

101 +

102 +Except where noted, all standard HTTP behavior SHOULD be assumed

103 +by both client and server. This includes (but is not necessarily

104 +limited to):

105 +

106 +If there is no repository at $GIT_URL, or the resource pointed to by a

107 +location matching $GIT_URL does not exist, the server MUST NOT respond

108 +with '200 OK' response. A server SHOULD respond with

109 +'404 Not Found', '410 Gone', or any other suitable HTTP status code

110 +which does not imply the resource exists as requested.

111 +

112 +If there is a repository at $GIT_URL, but access is not currently

113 +permitted, the server MUST respond with the '403 Forbidden' HTTP

114 +status code.

115 +

116 +Servers SHOULD support both HTTP 1.0 and HTTP 1.1.

117 +Servers SHOULD support chunked encoding for both request and response

118 +bodies.

119 +

120 +Clients SHOULD support both HTTP 1.0 and HTTP 1.1.

121 +Clients SHOULD support chunked encoding for both request and response

122 +bodies.

123 +

124 +Servers MAY return ETag and/or Last-Modified headers.

125 +

126 +Clients MAY revalidate cached entities by including If-Modified-Since

127 +and/or If-None-Match request headers.

128 +

129 +Servers MAY return '304 Not Modified' if the relevant headers appear

130 +in the request and the entity has not changed. Clients MUST treat

131 +'304 Not Modified' identical to '200 OK' by reusing the cached entity.

132 +

133 +Clients MAY reuse a cached entity without revalidation if the

134 +Cache-Control and/or Expires header permits caching. Clients and

135 +servers MUST follow RFC 2616 for cache controls.

136 +

137 +

138 +Discovering References

139 +----------------------

140 +

141 +All HTTP clients MUST begin either a fetch or a push exchange by

142 +discovering the references available on the remote repository.

143 +

144 +Dumb Clients

145 +~~~~~~~~~~~~

146 +

147 +HTTP clients that only support the "dumb" protocol MUST discover

148 +references by making a request for the special info/refs file of

149 +the repository.

150 +

151 +Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,

152 +without any search/query parameters.

153 +

154 + C: GET $GIT_URL/info/refs HTTP/1.0

155 +

156 + S: 200 OK

157 + S:

158 + S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint

159 + S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master

160 + S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0

161 + S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}

162 +

163 +The Content-Type of the returned info/refs entity SHOULD be

164 +"text/plain; charset=utf-8", but MAY be any content type.

165 +Clients MUST NOT attempt to validate the returned Content-Type.

166 +Dumb servers MUST NOT return a return type starting with

167 +"application/x-git-".

168 +

169 +Cache-Control headers MAY be returned to disable caching of the

170 +returned entity.

171 +

172 +When examining the response clients SHOULD only examine the HTTP

173 +status code. Valid responses are '200 OK', or '304 Not Modified'.

174 +

175 +The returned content is a UNIX formatted text file describing

176 +each ref and its known value. The file SHOULD be sorted by name

177 +according to the C locale ordering. The file SHOULD NOT include

178 +the default ref named 'HEAD'.

179 +

180 + info_refs = *( ref_record )

181 + ref_record = any_ref / peeled_ref

182 +

183 + any_ref = obj-id HTAB refname LF

184 + peeled_ref = obj-id HTAB refname LF

185 + obj-id HTAB refname "^{}" LF

186 +

187 +Smart Clients

188 +~~~~~~~~~~~~~

189 +

190 +HTTP clients that support the "smart" protocol (or both the

191 +"smart" and "dumb" protocols) MUST discover references by making

192 +a parameterized request for the info/refs file of the repository.

193 +

194 +The request MUST contain exactly one query parameter,

195 +'service=$servicename', where $servicename MUST be the service

196 +name the client wishes to contact to complete the operation.

197 +The request MUST NOT contain additional query parameters.

198 +

199 + C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0

200 +

201 + dumb server reply:

202 + S: 200 OK

203 + S:

204 + S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint

205 + S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master

206 + S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0

207 + S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}

208 +

209 + smart server reply:

210 + S: 200 OK

211 + S: Content-Type: application/x-git-upload-pack-advertisement

212 + S: Cache-Control: no-cache

213 + S:

214 + S: 001e# service=git-upload-pack\n

215 + S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n

216 + S: 0042d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n

217 + S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n

218 + S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n

219 +

220 +Dumb Server Response

221 +^^^^^^^^^^^^^^^^^^^^

222 +Dumb servers MUST respond with the dumb server reply format.

223 +

224 +See the prior section under dumb clients for a more detailed

225 +description of the dumb server response.

226 +

227 +Smart Server Response

228 +^^^^^^^^^^^^^^^^^^^^^

229 +If the server does not recognize the requested service name, or the

230 +requested service name has been disabled by the server administrator,

231 +the server MUST respond with the '403 Forbidden' HTTP status code.

232 +

233 +Otherwise, smart servers MUST respond with the smart server reply

234 +format for the requested service name.

235 +

236 +Cache-Control headers SHOULD be used to disable caching of the

237 +returned entity.

238 +

239 +The Content-Type MUST be 'application/x-$servicename-advertisement'.

240 +Clients SHOULD fall back to the dumb protocol if another content

241 +type is returned. When falling back to the dumb protocol clients

242 +SHOULD NOT make an additional request to $GIT_URL/info/refs, but

243 +instead SHOULD use the response already in hand. Clients MUST NOT

244 +continue if they do not support the dumb protocol.

245 +

246 +Clients MUST validate the status code is either '200 OK' or

247 +'304 Not Modified'.

248 +

249 +Clients MUST validate the first five bytes of the response entity

250 +matches the regex "^[0-9a-f]{4}#". If this test fails, clients

251 +MUST NOT continue.

252 +

253 +Clients MUST parse the entire response as a sequence of pkt-line

254 +records.

255 +

256 +Clients MUST verify the first pkt-line is "# service=$servicename".

257 +Servers MUST set $servicename to be the request parameter value.

258 +Servers SHOULD include an LF at the end of this line.

259 +Clients MUST ignore an LF at the end of the line.

260 +

261 +Servers MUST terminate the response with the magic "0000" end

262 +pkt-line marker.

263 +

264 +The returned response is a pkt-line stream describing each ref and

265 +its known value. The stream SHOULD be sorted by name according to

266 +the C locale ordering. The stream SHOULD include the default ref

267 +named 'HEAD' as the first ref. The stream MUST include capability

268 +declarations behind a NUL on the first ref.

269 +

270 + smart_reply = PKT-LINE("# service=$servicename" LF)

271 + ref_list

272 + "0000"

273 + ref_list = empty_list / non_empty_list

274 +

275 + empty_list = PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)

276 +

277 + non_empty_list = PKT-LINE(obj-id SP name NUL cap_list LF)

278 + *ref_record

279 +

280 + cap-list = capability *(SP capability)

281 + capability = 1*(LC_ALPHA / DIGIT / "-" / "_")

282 + LC_ALPHA = %x61-7A

283 +

284 + ref_record = any_ref / peeled_ref

285 + any_ref = PKT-LINE(obj-id SP name LF)

286 + peeled_ref = PKT-LINE(obj-id SP name LF)

287 + PKT-LINE(obj-id SP name "^{}" LF

288 +

289 +Smart Service git-upload-pack

290 +------------------------------

291 +This service reads from the repository pointed to by $GIT_URL.

292 +

293 +Clients MUST first perform ref discovery with

294 +'$GIT_URL/info/refs?service=git-upload-pack'.

295 +

296 + C: POST $GIT_URL/git-upload-pack HTTP/1.0

297 + C: Content-Type: application/x-git-upload-pack-request

298 + C:

299 + C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n

300 + C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n

301 + C: 0000

302 +

303 + S: 200 OK

304 + S: Content-Type: application/x-git-upload-pack-result

305 + S: Cache-Control: no-cache

306 + S:

307 + S: ....ACK %s, continue

308 + S: ....NAK

309 +

310 +Clients MUST NOT reuse or revalidate a cached reponse.

311 +Servers MUST include sufficient Cache-Control headers

312 +to prevent caching of the response.

313 +

314 +Servers SHOULD support all capabilities defined here.

315 +

316 +Clients MUST send at least one 'want' command in the request body.

317 +Clients MUST NOT reference an id in a 'want' command which did not

318 +appear in the response obtained through ref discovery unless the

319 +server advertises capability "allow-tip-sha1-in-want".

320 +

321 + compute_request = want_list

322 + have_list

323 + request_end

324 + request_end = "0000" / "done"

325 +

326 + want_list = PKT-LINE(want NUL cap_list LF)

327 + *(want_pkt)

328 + want_pkt = PKT-LINE(want LF)

329 + want = "want" SP id

330 + cap_list = *(SP capability) SP

331 +

332 + have_list = *PKT-LINE("have" SP id LF)

333 +

334 +TODO: Document this further.

335 +TODO: Don't use uppercase for variable names below.

336 +

337 +The Negotiation Algorithm

338 +~~~~~~~~~~~~~~~~~~~~~~~~~

339 +The computation to select the minimal pack proceeds as follows

340 +(c = client, s = server):

341 +

342 + init step:

343 + (c) Use ref discovery to obtain the advertised refs.

344 + (c) Place any object seen into set ADVERTISED.

345 +

346 + (c) Build an empty set, COMMON, to hold the objects that are later

347 + determined to be on both ends.

348 + (c) Build a set, WANT, of the objects from ADVERTISED the client

349 + wants to fetch, based on what it saw during ref discovery.

350 +

351 + (c) Start a queue, C_PENDING, ordered by commit time (popping newest

352 + first). Add all client refs. When a commit is popped from

353 + the queue its parents SHOULD be automatically inserted back.

354 + Commits MUST only enter the queue once.

355 +

356 + one compute step:

357 + (c) Send one $GIT_URL/git-upload-pack request:

358 +

359 + C: 0032want <WANT #1>...............................

360 + C: 0032want <WANT #2>...............................

361 + ....

362 + C: 0032have <COMMON #1>.............................

363 + C: 0032have <COMMON #2>.............................

364 + ....

365 + C: 0032have <HAVE #1>...............................

366 + C: 0032have <HAVE #2>...............................

367 + ....

368 + C: 0000

369 +

370 + The stream is organized into "commands", with each command

371 + appearing by itself in a pkt-line. Within a command line

372 + the text leading up to the first space is the command name,

373 + and the remainder of the line to the first LF is the value.

374 + Command lines are terminated with an LF as the last byte of

375 + the pkt-line value.

376 +

377 + Commands MUST appear in the following order, if they appear

378 + at all in the request stream:

379 +

380 + * want

381 + * have

382 +

383 + The stream is terminated by a pkt-line flush ("0000").

384 +

385 + A single "want" or "have" command MUST have one hex formatted

386 + SHA-1 as its value. Multiple SHA-1s MUST be sent by sending

387 + multiple commands.

388 +

389 + The HAVE list is created by popping the first 32 commits

390 + from C_PENDING. Less can be supplied if C_PENDING empties.

391 +

392 + If the client has sent 256 HAVE commits and has not yet

393 + received one of those back from S_COMMON, or the client has

394 + emptied C_PENDING it SHOULD include a "done" command to let

395 + the server know it won't proceed:

396 +

397 + C: 0009done

398 +

399 + (s) Parse the git-upload-pack request:

400 +

401 + Verify all objects in WANT are directly reachable from refs.

402 +

403 + The server MAY walk backwards through history or through

404 + the reflog to permit slightly stale requests.

405 +

406 + If no WANT objects are received, send an error:

407 +

408 +TODO: Define error if no want lines are requested.

409 +

410 + If any WANT object is not reachable, send an error:

411 +

412 +TODO: Define error if an invalid want is requested.

413 +

414 + Create an empty list, S_COMMON.

415 +

416 + If 'have' was sent:

417 +

418 + Loop through the objects in the order supplied by the client.

419 + For each object, if the server has the object reachable from

420 + a ref, add it to S_COMMON. If a commit is added to S_COMMON,

421 + do not add any ancestors, even if they also appear in HAVE.

422 +

423 + (s) Send the git-upload-pack response:

424 +

425 + If the server has found a closed set of objects to pack or the

426 + request ends with "done", it replies with the pack.

427 +

428 +TODO: Document the pack based response

429 + S: PACK...

430 +

431 + The returned stream is the side-band-64k protocol supported

432 + by the git-upload-pack service, and the pack is embedded into

433 + stream 1. Progress messages from the server side MAY appear

434 + in stream 2.

435 +

436 + Here a "closed set of objects" is defined to have at least

437 + one path from every WANT to at least one COMMON object.

438 +

439 + If the server needs more information, it replies with a

440 + status continue response:

441 +

442 +TODO: Document the non-pack response

443 +

444 + (c) Parse the upload-pack response:

445 +

446 +TODO: Document parsing response

447 +

448 + Do another compute step.

449 +

450 +

451 +Smart Service git-receive-pack

452 +------------------------------

453 +This service reads from the repository pointed to by $GIT_URL.

454 +

455 +Clients MUST first perform ref discovery with

456 +'$GIT_URL/info/refs?service=git-receive-pack'.

457 +

458 + C: POST $GIT_URL/git-receive-pack HTTP/1.0

459 + C: Content-Type: application/x-git-receive-pack-request

460 + C:

461 + C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status

462 + C: 0000

463 + C: PACK....

464 +

465 + S: 200 OK

466 + S: Content-Type: application/x-git-receive-pack-result

467 + S: Cache-Control: no-cache

468 + S:

469 + S: ....

470 +

471 +Clients MUST NOT reuse or revalidate a cached reponse.

472 +Servers MUST include sufficient Cache-Control headers

473 +to prevent caching of the response.

474 +

475 +Servers SHOULD support all capabilities defined here.

476 +

477 +Clients MUST send at least one command in the request body.

478 +Within the command portion of the request body clients SHOULD send

479 +the id obtained through ref discovery as old_id.

480 +

481 + update_request = command_list

482 + "PACK" <binary data>

483 +

484 + command_list = PKT-LINE(command NUL cap_list LF)

485 + *(command_pkt)

486 + command_pkt = PKT-LINE(command LF)

487 + cap_list = *(SP capability) SP

488 +

489 + command = create / delete / update

490 + create = zero-id SP new_id SP name

491 + delete = old_id SP zero-id SP name

492 + update = old_id SP new_id SP name

493 +

494 +TODO: Document this further.

495 +

496 +

497 +References

498 +----------

499 +

500 +link:http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]

501 +link:http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]

502 +link:technical/pack-protocol.txt

503 +link:technical/protocol-capabilities.txt

Document the HTTP transport protocols