Skip to content

Commit 4be6af6

Browse files
gitstergitster
committed
Merge branch 'jk/pack-protocol-doc'
Streamline documentation of the pkt-line protocol. * jk/pack-protocol-doc: pack-protocol: clarify LF-handling in PKT-LINE()
2 parents 971f9ea + 1c9b659 commit 4be6af6

File tree

2 files changed

+30
-21
lines changed

2 files changed

+30
-21
lines changed

‎Documentation/technical/pack-protocol.txt‎

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,14 @@ data. The protocol functions to have a server tell a client what is
1414
currently on the server, then for the two to negotiate the smallest amount
1515
of data to send in order to fully update one or the other.
1616

17+
pkt-line Format
18+
---------------
19+
20+
The descriptions below build on the pkt-line format described in
21+
protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
22+
otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
23+
include a LF, but the receiver MUST NOT complain if it is not present.
24+
1725
Transports
1826
----------
1927
There are three transports over which the packfile protocol is
@@ -143,9 +151,6 @@ with the object name that each reference currently points to.
143151
003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{}
144152
0000
145153

146-
Server SHOULD terminate each non-flush line using LF ("\n") terminator;
147-
client MUST NOT complain if there is no terminator.
148-
149154
The returned response is a pkt-line stream describing each ref and
150155
its current value. The stream MUST be sorted by name according to
151156
the C locale ordering.
@@ -165,15 +170,15 @@ MUST peel the ref if it's an annotated tag.
165170
flush-pkt
166171

167172
no-refs = PKT-LINE(zero-id SP "capabilities^{}"
168-
NUL capability-list LF)
173+
NUL capability-list)
169174

170175
list-of-refs = first-ref *other-ref
171176
first-ref = PKT-LINE(obj-id SP refname
172-
NUL capability-list LF)
177+
NUL capability-list)
173178

174179
other-ref = PKT-LINE(other-tip / other-peeled)
175-
other-tip = obj-id SP refname LF
176-
other-peeled = obj-id SP refname "^{}" LF
180+
other-tip = obj-id SP refname
181+
other-peeled = obj-id SP refname "^{}"
177182

178183
shallow = PKT-LINE("shallow" SP obj-id)
179184

@@ -216,8 +221,8 @@ out of what the server said it could do with the first 'want' line.
216221

217222
depth-request = PKT-LINE("deepen" SP depth)
218223

219-
first-want = PKT-LINE("want" SP obj-id SP capability-list LF)
220-
additional-want = PKT-LINE("want" SP obj-id LF)
224+
first-want = PKT-LINE("want" SP obj-id SP capability-list)
225+
additional-want = PKT-LINE("want" SP obj-id)
221226

222227
depth = 1*DIGIT
223228
----
@@ -284,7 +289,7 @@ so that there is always a block of 32 "in-flight on the wire" at a time.
284289
compute-end
285290

286291
have-list = *have-line
287-
have-line = PKT-LINE("have" SP obj-id LF)
292+
have-line = PKT-LINE("have" SP obj-id)
288293
compute-end = flush-pkt / PKT-LINE("done")
289294
----
290295

@@ -348,10 +353,10 @@ Then the server will start sending its packfile data.
348353

349354
----
350355
server-response = *ack_multi ack / nak
351-
ack_multi = PKT-LINE("ACK" SP obj-id ack_status LF)
356+
ack_multi = PKT-LINE("ACK" SP obj-id ack_status)
352357
ack_status = "continue" / "common" / "ready"
353-
ack = PKT-LINE("ACK SP obj-id LF)
354-
nak = PKT-LINE("NAK" LF)
358+
ack = PKT-LINE("ACK" SP obj-id)
359+
nak = PKT-LINE("NAK")
355360
----
356361

357362
A simple clone may look like this (with no 'have' lines):
@@ -467,10 +472,10 @@ references.
467472
----
468473
update-request = *shallow ( command-list | push-cert ) [packfile]
469474

470-
shallow = PKT-LINE("shallow" SP obj-id LF)
475+
shallow = PKT-LINE("shallow" SP obj-id)
471476

472-
command-list = PKT-LINE(command NUL capability-list LF)
473-
*PKT-LINE(command LF)
477+
command-list = PKT-LINE(command NUL capability-list)
478+
*PKT-LINE(command)
474479
flush-pkt
475480

476481
command = create / delete / update
@@ -521,7 +526,8 @@ Push Certificate
521526

522527
A push certificate begins with a set of header lines. After the
523528
header and an empty line, the protocol commands follow, one per
524-
line.
529+
line. Note that the the trailing LF in push-cert PKT-LINEs is _not_
530+
optional; it must be present.
525531

526532
Currently, the following header fields are defined:
527533

@@ -560,12 +566,12 @@ update was successful, or 'ng [refname] [error]' if the update was not.
560566
1*(command-status)
561567
flush-pkt
562568

563-
unpack-status = PKT-LINE("unpack" SP unpack-result LF)
569+
unpack-status = PKT-LINE("unpack" SP unpack-result)
564570
unpack-result = "ok" / error-msg
565571

566572
command-status = command-ok / command-fail
567-
command-ok = PKT-LINE("ok" SP refname LF)
568-
command-fail = PKT-LINE("ng" SP refname SP error-msg LF)
573+
command-ok = PKT-LINE("ok" SP refname)
574+
command-fail = PKT-LINE("ng" SP refname SP error-msg)
569575

570576
error-msg = 1*(OCTECT) ; where not "ok"
571577
----

‎Documentation/technical/protocol-common.txt‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,10 @@ A pkt-line MAY contain binary data, so implementors MUST ensure
6262
pkt-line parsing/formatting routines are 8-bit clean.
6363

6464
A non-binary line SHOULD BE terminated by an LF, which if present
65-
MUST be included in the total length.
65+
MUST be included in the total length. Receivers MUST treat pkt-lines
66+
with non-binary data the same whether or not they contain the trailing
67+
LF (stripping the LF if present, and not complaining when it is
68+
missing).
6669

6770
The maximum length of a pkt-line's data component is 65520 bytes.
6871
Implementations MUST NOT send pkt-line whose length exceeds 65524

0 commit comments

Comments
 (0)