[PATCH] pack-protocol: document newline behavior in push commands

Our pack-protocol spec indicates that a pushing client should send ref update commands like:

  $old_sha1 $new_sha1 $ref\n

with each ref update in its own pktline, with a trailing newline. However, git itself does not follow this behavior; it omits the trailing newline.

For the most part the distinction is harmless. The `receive-pack` on the other end will call `packet_read_line`, which strips off the newline if it is there, and we are fine either way.

Things are more complicated for the initial ref, which also has capabilities. The spec says to send:

  $old_sha1 $new_sha1 $ref\0 $caps\n

which is also OK by the current `receive-pack code (the newline is at the end of the packet, so we still strip it).

As an aside, it would _not_ be OK to send:

  $old_sha1 $new_sha1 $ref\n\0 $caps\n

The spec does not allow that and receive-pack would reject it, but it is perhaps a mistake that a naive client implementation might make.

So what is in the current spec is quite reasonable, and simply follows the normal rules for pkt-line framing (we say LF, but it really is optional). But it does not document how git actually behaves.

Signed-off-by: Jeff King <peff@peff.net>
---
+cc Junio, Dave, and Shawn, as this is somewhat related to the
discussion in
http://thread.gmane.org/gmane.comp.version-control.git/273175/focus=273444

I happened to be looking into some protocol stuff recently and noticed that we do not follow the spec here (but interestingly, libgit2 does!).

Frankly, this feels a bit like a step backwards to me. I am tempted to suggest instead that git start sending the newlines, but I'm not sure it's worth any potential fallout.

I'm also tempted to scrap this and say it just falls under the rule that every PKT-LINE is "sender SHOULD include LF" and "receiver MUST NOT complain about missing LF" (which does appear earlier in the document, though in a different context). Or maybe we should write out that rule explicitly and drop the "LF" from all parts of the grammar (which is what the thread above advocates).

 Documentation/technical/pack-protocol.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)