[PATCH 0/3] use constants for sideband communication channels

[iheffner@gmail.com]

In order to make more clear how the different channels in sidechannel.c
are to be used, I'm proposing some macros/constants which can be used in
place of the "magic numbers" that mean little or nothing to someone not
familiar with the protocol.

In working on a script to handle archiving from a bare repository a
project which contained submodules, I had a difficult time determining
how to talk between my git-upload-archive replacement and git-archive.
It did not occur to me to look at documentation for git-send-pack or
git-receive-pack when trying to understand the communication protocol.
But looking through the code and poking at an implementation, I finally
understood that I needed to send a channel identifier to say what type
of communication I was sending. I determined that there were three
possible channels. I could easily tell that channel three (3) was for
catastrophic errors on the server side.  But it was not clear what the
difference between channel 1 and channel 2 were.  Because channel 2 was
the one that appeared to be read and parsed in some manner, I assumed
that this was the "important" data channel and tried sending my data on
that channel.

I was confused and frustrated when it appeared that git-archive treated
data coming from my --exec'd git-upload-archive replacement differently
than it did when receiving data from the real git-upload-archive.
Eventually I figured out that channel 1 was for data, channel 2 was for
non-fatal messages, and channel 3 was for fatal error communications.
Having comments in sidechannel.h would have helped. But constants or
macros would have helped as well and makes the code that uses them more
clear.

Ivan


 [PATCH 1/3] add constants for sideband communication channels
 [PATCH 2/3] switch sideband communication to use constants
 [PATCH 3/3] use SIDEBAND_*_ERROR constants in pack protocol

 builtin/fetch-pack.c     |    2 +-
 builtin/receive-pack.c   |    6 +++---
 builtin/send-pack.c      |    4 ++--
 builtin/upload-archive.c |    6 +++---
 sideband.c               |    6 +++---
 sideband.h               |    6 +++++-
 upload-pack.c            |   22 +++++++++++-----------
 7 files changed, 28 insertions(+), 24 deletions(-)