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 fa64a2fdbeed ("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>
Jonathan Tan committed
Jan 25, 2018 at 10:53 UTC
addad10594583092ad92a4b82c40040b913bb8ee
4 files changed
+61
-48
Documentation/Makefile
+1
@@ -72,6 +72,7 @@ TECH_DOCS += SubmittingPatches
72
TECH_DOCS += technical/hash-function-transition
73
TECH_DOCS += technical/http-protocol
74
TECH_DOCS += technical/index-format
75
+TECH_DOCS += technical/long-running-process-protocol
76
TECH_DOCS += technical/pack-format
77
TECH_DOCS += technical/pack-heuristics
78
TECH_DOCS += technical/pack-protocol
Documentation/gitattributes.txt
+8
-46
@@ -392,46 +392,14 @@ Long Running Filter Process
392
If the filter command (a string value) is defined via
393
`filter.<driver>.process` then Git can process all blobs with a
394
single filter invocation for the entire life of a single Git
395
-command. This is achieved by using a packet format (pkt-line,
396
-see technical/protocol-common.txt) based protocol over standard
397
-input and standard output as follows. All packets, except for the
398
-"*CONTENT" packets and the "0000" flush packet, are considered
399
-text and therefore are terminated by a LF.
400
-
401
-Git starts the filter when it encounters the first file
402
-that needs to be cleaned or smudged. After the filter started
403
-Git sends a welcome message ("git-filter-client"), a list of supported
404
-protocol version numbers, and a flush packet. Git expects to read a welcome
405
-response message ("git-filter-server"), exactly one protocol version number
406
-from the previously sent list, and a flush packet. All further
407
-communication will be based on the selected version. The remaining
408
-protocol description below documents "version=2". Please note that
409
-"version=42" in the example below does not exist and is only there
410
-to illustrate how the protocol would look like with more than one
411
-version.
412
-
413
-After the version negotiation Git sends a list of all capabilities that
414
-it supports and a flush packet. Git expects to read a list of desired
415
-capabilities, which must be a subset of the supported capabilities list,
416
-and a flush packet as response:
417
-------------------------
418
-packet: git> git-filter-client
419
-packet: git> version=2
420
-packet: git> version=42
421
-packet: git> 0000
422
-packet: git< git-filter-server
423
-packet: git< version=2
424
-packet: git< 0000
425
-packet: git> capability=clean
426
-packet: git> capability=smudge
427
-packet: git> capability=not-yet-invented
428
-packet: git> 0000
429
-packet: git< capability=clean
430
-packet: git< capability=smudge
431
-packet: git< 0000
432
-------------------------
433
-Supported filter capabilities in version 2 are "clean", "smudge",
434
-and "delay".
395
+command. This is achieved by using the long-running process protocol
396
+(described in technical/long-running-process-protocol.txt).
397
+
398
+When Git encounters the first file that needs to be cleaned or smudged,
399
+it starts the filter and performs the handshake. In the handshake, the
400
+welcome message sent by Git is "git-filter-client", only version 2 is
401
+suppported, and the supported capabilities are "clean", "smudge", and
402
+"delay".
403
404
Afterwards Git sends a list of "key=value" pairs terminated with
405
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
485
with the next file that needs to be processed. Depending on the
486
`filter.<driver>.required` flag Git will interpret that as error.
487
520
-After the filter has processed a command it is expected to wait for
521
-a "key=value" list containing the next command. Git will close
522
-the command pipe on exit. The filter is expected to detect EOF
523
-and exit gracefully on its own. Git will wait until the filter
524
-process has stopped.
525
-
488
Delay
489
^^^^^
490
Documentation/technical/long-running-process-protocol.txt
new
+50
@@ -0,0 +1,50 @@
1
+Long-running process protocol
2
+=============================
3
+
4
+This protocol is used when Git needs to communicate with an external
5
+process throughout the entire life of a single Git command. All
6
+communication is in pkt-line format (see technical/protocol-common.txt)
7
+over standard input and standard output.
8
+
9
+Handshake
10
+---------
11
+
12
+Git starts by sending a welcome message (for example,
13
+"git-filter-client"), a list of supported protocol version numbers, and
14
+a flush packet. Git expects to read the welcome message with "server"
15
+instead of "client" (for example, "git-filter-server"), exactly one
16
+protocol version number from the previously sent list, and a flush
17
+packet. All further communication will be based on the selected version.
18
+The remaining protocol description below documents "version=2". Please
19
+note that "version=42" in the example below does not exist and is only
20
+there to illustrate how the protocol would look like with more than one
21
+version.
22
+
23
+After the version negotiation Git sends a list of all capabilities that
24
+it supports and a flush packet. Git expects to read a list of desired
25
+capabilities, which must be a subset of the supported capabilities list,
26
+and a flush packet as response:
27
+------------------------
28
+packet: git> git-filter-client
29
+packet: git> version=2
30
+packet: git> version=42
31
+packet: git> 0000
32
+packet: git< git-filter-server
33
+packet: git< version=2
34
+packet: git< 0000
35
+packet: git> capability=clean
36
+packet: git> capability=smudge
37
+packet: git> capability=not-yet-invented
38
+packet: git> 0000
39
+packet: git< capability=clean
40
+packet: git< capability=smudge
41
+packet: git< 0000
42
+------------------------
43
+
44
+Shutdown
45
+--------
46
+
47
+Git will close
48
+the command pipe on exit. The filter is expected to detect EOF
49
+and exit gracefully on its own. Git will wait until the filter
50
+process has stopped.
sub-process.h
+2
-2
@@ -73,8 +73,8 @@ static inline struct child_process *subprocess_get_child_process(
73
}
74
75
/*
76
- * Perform the version and capability negotiation as described in the "Long
77
- * Running Filter Process" section of the gitattributes documentation using the
76
+ * Perform the version and capability negotiation as described in the
77
+ * "Handshake" section of long-running-process-protocol.txt using the
78
* given requested versions and capabilities. The "versions" and "capabilities"
79
* parameters are arrays terminated by a 0 or blank struct.
80
*