Commit addad105 authored by Jonathan Tan's avatar Jonathan Tan Committed by Junio C Hamano

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 fa64a2fd ("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: default avatarJonathan Tan <jonathantanmy@google.com>
Signed-off-by: default avatarJunio C Hamano <gitster@pobox.com>
parent 5be1f00a
......@@ -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.
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".
command. This is achieved by using the long-running process protocol
(described in technical/long-running-process-protocol.txt).
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
^^^^^
......
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.
*
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment