Read Object Process
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The read-object process enables Git to read all missing blobs with a
single process invocation for the entire life of a single Git command.
This is achieved by using a packet format (pkt-line, see technical/
protocol-common.txt) based protocol over standard input and standard
output as follows. All packets, except for the "*CONTENT" packets and
the "0000" flush packet, are considered text and therefore are
terminated by a LF.

Git starts the process when it encounters the first missing object that
needs to be retrieved. After the process is started, Git sends a welcome
message ("git-read-object-client"), a list of supported protocol version
numbers, and a flush packet. Git expects to read a welcome response
message ("git-read-object-server"), exactly one protocol version number
from the previously sent list, and a flush packet. All further
communication will be based on the selected version.

The remaining protocol description below documents "version=1". Please
note that "version=42" in the example below does not exist and is only
there to illustrate how the protocol would look with more than one
version.

After the version negotiation Git sends a list of all capabilities that
it supports and a flush packet. Git expects to read a list of desired
capabilities, which must be a subset of the supported capabilities list,
and a flush packet as response:
------------------------
packet: git> git-read-object-client
packet: git> version=1
packet: git> version=42
packet: git> 0000
packet: git< git-read-object-server
packet: git< version=1
packet: git< 0000
packet: git> capability=get
packet: git> capability=have
packet: git> capability=put
packet: git> capability=not-yet-invented
packet: git> 0000
packet: git< capability=get
packet: git< 0000
------------------------
The only supported capability in version 1 is "get".

Afterwards Git sends a list of "key=value" pairs terminated with a flush
packet. The list will contain at least the command (based on the
supported capabilities) and the sha1 of the object to retrieve. Please
note, that the process must not send any response before it received the
final flush packet.

When the process receives the "get" command, it should make the requested
object available in the git object store and then return success. Git will
then check the object store again and this time find it and proceed.
------------------------
packet: git> command=get
packet: git> sha1=0a214a649e1b3d5011e14a3dc227753f2bd2be05
packet: git> 0000
------------------------

The process is expected to respond with a list of "key=value" pairs
terminated with a flush packet. If the process does not experience
problems then the list must contain a "success" status.
------------------------
packet: git< status=success
packet: git< 0000
------------------------

In case the process cannot or does not want to process the content, it
is expected to respond with an "error" status.
------------------------
packet: git< status=error
packet: git< 0000
------------------------

In case the process cannot or does not want to process the content as
well as any future content for the lifetime of the Git process, then it
is expected to respond with an "abort" status at any point in the
protocol.
------------------------
packet: git< status=abort
packet: git< 0000
------------------------

Git neither stops nor restarts the process in case the "error"/"abort"
status is set.

If the process dies during the communication or does not adhere to the
protocol then Git will stop the process and restart it with the next
object that needs to be processed.

After the read-object process has processed an object it is expected to
wait for the next "key=value" list containing a command. Git will close
the command pipe on exit. The process is expected to detect EOF and exit
gracefully on its own. Git will wait until the process has stopped.

A long running read-object process demo implementation can be found in
`contrib/long-running-read-object/example.pl` located in the Git core
repository. If you develop your own long running process then the
`GIT_TRACE_PACKET` environment variables can be very helpful for
debugging (see linkgit:git[1]).
