mirror of
https://github.com/git/git.git
synced 2024-04-28 03:15:10 +02:00
Docs: split out long-running subprocess handshake
Separating out the implementation of the handshake when starting a
long-running subprocess (for example, as is done for a clean/smudge
filter) was done in commit fa64a2fdbe ("sub-process: refactor
handshake to common function", 2017-07-26), but its documentation still
resides in gitattributes. Split out the documentation as well.
Signed-off-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jonathan Tan
Junio C Hamano
parent
5be1f00a9a
commit
addad10594
|
|
@ -72,6 +72,7 @@ TECH_DOCS += SubmittingPatches
|
|||
TECH_DOCS += technical/hash-function-transition
|
||||
TECH_DOCS += technical/http-protocol
|
||||
TECH_DOCS += technical/index-format
|
||||
TECH_DOCS += technical/long-running-process-protocol
|
||||
TECH_DOCS += technical/pack-format
|
||||
TECH_DOCS += technical/pack-heuristics
|
||||
TECH_DOCS += technical/pack-protocol
|
||||
|
|
|
|||
|
|
@ -392,46 +392,14 @@ Long Running Filter Process
|
|||
If the filter command (a string value) is defined via
|
||||
`filter.<driver>.process` then Git can process all blobs with a
|
||||
single filter 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.
|
||||
command. This is achieved by using the long-running process protocol
|
||||
(described in technical/long-running-process-protocol.txt).
|
||||
|
||||
Git starts the filter when it encounters the first file
|
||||
that needs to be cleaned or smudged. After the filter started
|
||||
Git sends a welcome message ("git-filter-client"), a list of supported
|
||||
protocol version numbers, and a flush packet. Git expects to read a welcome
|
||||
response message ("git-filter-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=2". Please note that
|
||||
"version=42" in the example below does not exist and is only there
|
||||
to illustrate how the protocol would look like 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-filter-client
|
||||
packet: git> version=2
|
||||
packet: git> version=42
|
||||
packet: git> 0000
|
||||
packet: git< git-filter-server
|
||||
packet: git< version=2
|
||||
packet: git< 0000
|
||||
packet: git> capability=clean
|
||||
packet: git> capability=smudge
|
||||
packet: git> capability=not-yet-invented
|
||||
packet: git> 0000
|
||||
packet: git< capability=clean
|
||||
packet: git< capability=smudge
|
||||
packet: git< 0000
|
||||
------------------------
|
||||
Supported filter capabilities in version 2 are "clean", "smudge",
|
||||
and "delay".
|
||||
When Git encounters the first file that needs to be cleaned or smudged,
|
||||
it starts the filter and performs the handshake. In the handshake, the
|
||||
welcome message sent by Git is "git-filter-client", only version 2 is
|
||||
suppported, and the supported capabilities are "clean", "smudge", and
|
||||
"delay".
|
||||
|
||||
Afterwards Git sends a list of "key=value" pairs terminated with
|
||||
a flush packet. The list will contain at least the filter command
|
||||
|
|
@ -517,12 +485,6 @@ the protocol then Git will stop the filter process and restart it
|
|||
with the next file that needs to be processed. Depending on the
|
||||
`filter.<driver>.required` flag Git will interpret that as error.
|
||||
|
||||
After the filter has processed a command it is expected to wait for
|
||||
a "key=value" list containing the next command. Git will close
|
||||
the command pipe on exit. The filter is expected to detect EOF
|
||||
and exit gracefully on its own. Git will wait until the filter
|
||||
process has stopped.
|
||||
|
||||
Delay
|
||||
^^^^^
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,50 @@
|
|||
Long-running process protocol
|
||||
=============================
|
||||
|
||||
This protocol is used when Git needs to communicate with an external
|
||||
process throughout the entire life of a single Git command. All
|
||||
communication is in pkt-line format (see technical/protocol-common.txt)
|
||||
over standard input and standard output.
|
||||
|
||||
Handshake
|
||||
---------
|
||||
|
||||
Git starts by sending a welcome message (for example,
|
||||
"git-filter-client"), a list of supported protocol version numbers, and
|
||||
a flush packet. Git expects to read the welcome message with "server"
|
||||
instead of "client" (for example, "git-filter-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=2". Please
|
||||
note that "version=42" in the example below does not exist and is only
|
||||
there to illustrate how the protocol would look like 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-filter-client
|
||||
packet: git> version=2
|
||||
packet: git> version=42
|
||||
packet: git> 0000
|
||||
packet: git< git-filter-server
|
||||
packet: git< version=2
|
||||
packet: git< 0000
|
||||
packet: git> capability=clean
|
||||
packet: git> capability=smudge
|
||||
packet: git> capability=not-yet-invented
|
||||
packet: git> 0000
|
||||
packet: git< capability=clean
|
||||
packet: git< capability=smudge
|
||||
packet: git< 0000
|
||||
------------------------
|
||||
|
||||
Shutdown
|
||||
--------
|
||||
|
||||
Git will close
|
||||
the command pipe on exit. The filter is expected to detect EOF
|
||||
and exit gracefully on its own. Git will wait until the filter
|
||||
process has stopped.
|
||||
|
|
@ -73,8 +73,8 @@ static inline struct child_process *subprocess_get_child_process(
|
|||
}
|
||||
|
||||
/*
|
||||
* Perform the version and capability negotiation as described in the "Long
|
||||
* Running Filter Process" section of the gitattributes documentation using the
|
||||
* Perform the version and capability negotiation as described in the
|
||||
* "Handshake" section of long-running-process-protocol.txt using the
|
||||
* given requested versions and capabilities. The "versions" and "capabilities"
|
||||
* parameters are arrays terminated by a 0 or blank struct.
|
||||
*
|
||||
|
|
|
|||
Loading…
Reference in New Issue