docs: move protocol-related docs to man section 5
Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space. By moving the things that discuss the protocol we can properly link from e.g. lsrefs.unborn and protocol.version documentation to a manpage we build by default. So far we have been using the "gitformat-" prefix for the documentation we've been moving over from Documentation/technical/*, but for protocol documentation let's use "gitprotocol-*". Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Aug 4, 2022 at 18:28 UTC
5db921054e685a4dbaeb622acda53d6a154e947f
17 files changed
+106
-37
Documentation/Makefile
+4
-4
@@ -30,6 +30,10 @@ MAN5_TXT += githooks.txt
30
MAN5_TXT += gitignore.txt
31
MAN5_TXT += gitmailmap.txt
32
MAN5_TXT += gitmodules.txt
33
+MAN5_TXT += gitprotocol-capabilities.txt
34
+MAN5_TXT += gitprotocol-common.txt
35
+MAN5_TXT += gitprotocol-pack.txt
36
+MAN5_TXT += gitprotocol-v2.txt
37
MAN5_TXT += gitrepository-layout.txt
38
MAN5_TXT += gitweb.conf.txt
39
@@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol
109
TECH_DOCS += technical/multi-pack-index
110
TECH_DOCS += technical/pack-format
111
TECH_DOCS += technical/pack-heuristics
108
-TECH_DOCS += technical/pack-protocol
112
TECH_DOCS += technical/parallel-checkout
113
TECH_DOCS += technical/partial-clone
111
-TECH_DOCS += technical/protocol-capabilities
112
-TECH_DOCS += technical/protocol-common
113
-TECH_DOCS += technical/protocol-v2
114
TECH_DOCS += technical/racy-git
115
TECH_DOCS += technical/reftable
116
TECH_DOCS += technical/send-pack-pipeline
Documentation/config/lsrefs.txt
+1
-1
@@ -1,7 +1,7 @@
1
lsrefs.unborn::
2
May be "advertise" (the default), "allow", or "ignore". If "advertise",
3
the server will respond to the client sending "unborn" (as described in
4
- protocol-v2.txt) and will advertise support for this feature during the
4
+ linkgit:gitprotocol-v2[5]) and will advertise support for this feature during the
5
protocol v2 capability advertisement. "allow" is the same as
6
"advertise" except that the server will not advertise support for this
7
feature; this is useful for load-balanced servers that cannot be
Documentation/config/protocol.txt
+1
-1
@@ -58,6 +58,6 @@ protocol.version::
58
* `1` - the original wire protocol with the addition of a version string
59
in the initial response from the server.
60
61
-* `2` - link:technical/protocol-v2.html[wire protocol version 2].
61
+* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5].
62
63
--
Documentation/git-upload-pack.txt
+2
-3
@@ -40,9 +40,8 @@ OPTIONS
40
Used by linkgit:git-http-backend[1] to serve up
41
`$GIT_URL/info/refs?service=git-upload-pack` requests. See
42
"Smart Clients" in link:technical/http-protocol.html[the HTTP
43
- transfer protocols] documentation and "HTTP Transport" in
44
- link:technical/protocol-v2.html[the Git Wire Protocol, Version
45
- 2] documentation. Also understood by
43
+ transfer protocols] documentation and "HTTP Transport" in the
44
+ linkgit:gitprotocol-v2[5] documentation. Also understood by
45
linkgit:git-receive-pack[1].
46
47
<directory>::
Documentation/gitformat-bundle.txt
+1
-1
@@ -27,7 +27,7 @@ FORMAT
27
------
28
29
We will use ABNF notation to define the Git bundle format. See
30
-link:technical/protocol-common.html for the details.
30
+linkgit:gitprotocol-common[5] for the details.
31
32
A v2 bundle looks like this:
33
Documentation/gitprotocol-capabilities.txt
renamed
+22
-6
@@ -1,8 +1,20 @@
1
-Git Protocol Capabilities
2
-=========================
1
+gitprotocol-capabilities(5)
2
+===========================
3
+
4
+NAME
5
+----
6
+gitprotocol-capabilities - Protocol v0 and v1 capabilities
7
+
8
+SYNOPSIS
9
+--------
10
+[verse]
11
+<over-the-wire-protocol>
12
+
13
+DESCRIPTION
14
+-----------
15
16
NOTE: this document describes capabilities for versions 0 and 1 of the pack
5
-protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
17
+protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]
18
doc.
19
20
Servers SHOULD support all capabilities defined in this document.
@@ -77,7 +89,7 @@ interleaved with S-R-Q.
89
multi_ack_detailed
90
------------------
91
This is an extension of multi_ack that permits client to better
80
-understand the server's in-memory state. See pack-protocol.txt,
92
+understand the server's in-memory state. See linkgit:gitprotocol-pack[5],
93
section "Packfile Negotiation" for more information.
94
95
no-done
@@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests
293
this capability, after unpacking and updating references the server
294
will respond with whether the packfile unpacked successfully and if
295
each reference was updated successfully. If any of those were not
284
-successful, it will send back an error message. See pack-protocol.txt
296
+successful, it will send back an error message. See linkgit:gitprotocol-pack[5]
297
for example messages.
298
299
report-status-v2
@@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by
304
the "proc-receive" hook. The "proc-receive" hook may handle a command
305
for a pseudo-reference which may create or update a reference with
306
different name, new-oid, and old-oid. While the capability
295
-'report-status' cannot report for such case. See pack-protocol.txt
307
+'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5]
308
for details.
309
310
delete-refs
@@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The
390
current implementation uses trace2 session IDs (see
391
link:api-trace2.html[api-trace2] for details), but this may change and users of
392
the session ID should not rely on this fact.
393
+
394
+GIT
395
+---
396
+Part of the linkgit:git[1] suite
Documentation/gitprotocol-common.txt
renamed
+21
-2
@@ -1,5 +1,20 @@
1
-Documentation Common to Pack and Http Protocols
2
-===============================================
1
+gitprotocol-common(5)
2
+=====================
3
+
4
+NAME
5
+----
6
+gitprotocol-common - Things common to various protocols
7
+
8
+SYNOPSIS
9
+--------
10
+[verse]
11
+<over-the-wire-protocol>
12
+
13
+DESCRIPTION
14
+-----------
15
+
16
+This document sets defines things common to various over-the-wire
17
+protocols and file formats used in Git.
18
19
ABNF Notation
20
-------------
@@ -97,3 +112,7 @@ Examples (as C-style strings):
112
"000bfoobar\n" "foobar\n"
113
"0004" ""
114
----
115
+
116
+GIT
117
+---
118
+Part of the linkgit:git[1] suite
Documentation/gitprotocol-pack.txt
renamed
+20
-4
@@ -1,5 +1,17 @@
1
-Packfile transfer protocols
2
-===========================
1
+gitprotocol-pack(5)
2
+===================
3
+
4
+NAME
5
+----
6
+gitprotocol-pack - How packs are transferred over-the-wire
7
+
8
+SYNOPSIS
9
+--------
10
+[verse]
11
+<over-the-wire-protocol>
12
+
13
+DESCRIPTION
14
+-----------
15
16
Git supports transferring data in packfiles over the ssh://, git://, http:// and
17
file:// transports. There exist two sets of protocols, one for pushing
@@ -18,7 +30,7 @@ pkt-line Format
30
---------------
31
32
The descriptions below build on the pkt-line format described in
21
-protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
33
+linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless
34
otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
35
include a LF, but the receiver MUST NOT complain if it is not present.
36
@@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
72
73
Servers that receive any such Extra Parameters MUST ignore all
74
unrecognized keys. Currently, the only Extra Parameter recognized is
63
-"version" with a value of '1' or '2'. See protocol-v2.txt for more
75
+"version" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more
76
information on protocol version 2.
77
78
Git Transport
@@ -707,3 +719,7 @@ An example client/server communication might look like this:
719
S: 0018ok refs/heads/debug\n
720
S: 002ang refs/heads/master non-fast-forward\n
721
----
722
+
723
+GIT
724
+---
725
+Part of the linkgit:git[1] suite
Documentation/gitprotocol-v2.txt
renamed
+20
-5
@@ -1,5 +1,17 @@
1
-Git Wire Protocol, Version 2
2
-============================
1
+gitprotocol-v2(5)
2
+=================
3
+
4
+NAME
5
+----
6
+gitprotocol-v2 - Git Wire Protocol, Version 2
7
+
8
+SYNOPSIS
9
+--------
10
+[verse]
11
+<over-the-wire-protocol>
12
+
13
+DESCRIPTION
14
+-----------
15
16
This document presents a specification for a version 2 of Git's wire
17
protocol. Protocol v2 will improve upon v1 in the following ways:
@@ -26,8 +38,7 @@ Packet-Line Framing
38
-------------------
39
40
All communication is done using packet-line framing, just as in v1. See
29
-`Documentation/technical/pack-protocol.txt` and
30
-`Documentation/technical/protocol-common.txt` for more information.
41
+linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information.
42
43
In protocol v2 these special packets will have the following semantics:
44
@@ -42,7 +53,7 @@ Initial Client Request
53
In general a client can request to speak protocol v2 by sending
54
`version=2` through the respective side-channel for the transport being
55
used which inevitably sets `GIT_PROTOCOL`. More information can be
45
-found in `pack-protocol.txt` and `http-protocol.txt`, as well as the
56
+found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the
57
`GIT_PROTOCOL` definition in `git.txt`. In all cases the
58
response from the server is the capability advertisement.
59
@@ -566,3 +577,7 @@ and associated requested information, each separated by a single space.
577
attr = "size"
578
579
obj-info = obj-id SP obj-size
580
+
581
+GIT
582
+---
583
+Part of the linkgit:git[1] suite
Documentation/technical/api-simple-ipc.txt
+1
-1
@@ -78,7 +78,7 @@ client and an optional response message from the server. Both the
78
client and server messages are unlimited in length and are terminated
79
with a flush packet.
80
81
-The pkt-line routines (Documentation/technical/protocol-common.txt)
81
+The pkt-line routines (linkgit:gitprotocol-common[5])
82
are used to simplify buffer management during message generation,
83
transmission, and reception. A flush packet is used to mark the end
84
of the message. This allows the sender to incrementally generate and
Documentation/technical/http-protocol.txt
+3
-3
@@ -222,7 +222,7 @@ smart server reply:
222
S: 0000
223
224
The client may send Extra Parameters (see
225
-Documentation/technical/pack-protocol.txt) as a colon-separated string
225
+linkgit:gitprotocol-pack[5]) as a colon-separated string
226
in the Git-Protocol HTTP header.
227
228
Uses the `--http-backend-info-refs` option to
@@ -518,5 +518,5 @@ References
518
519
http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
520
http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
521
-link:technical/pack-protocol.html
522
-link:technical/protocol-capabilities.html
521
+linkgit:gitprotocol-pack[5]
522
+linkgit:gitprotocol-capabilities[5]
Documentation/technical/long-running-process-protocol.txt
+1
-1
@@ -3,7 +3,7 @@ Long-running process protocol
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)
6
+communication is in pkt-line format (see linkgit:gitprotocol-common[5])
7
over standard input and standard output.
8
9
Handshake
Documentation/technical/packfile-uri.txt
+1
-1
@@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section
18
directly before the `packfile` section (right after `wanted-refs` if it is
19
sent) containing URIs of any of the given protocols. The URIs point to
20
packfiles that use only features that the client has declared that it supports
21
-(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of
21
+(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of
22
this section.
23
24
Clients should then download and index all the given URIs (in addition to
Documentation/technical/partial-clone.txt
+1
-1
@@ -79,7 +79,7 @@ Design Details
79
upload-pack negotiation.
80
+
81
This uses the existing capability discovery mechanism.
82
-See "filter" in Documentation/technical/pack-protocol.txt.
82
+See "filter" in linkgit:gitprotocol-pack[5].
83
84
- Clients pass a "filter-spec" to clone and fetch which is passed to the
85
server to request filtering during packfile construction.
command-list.txt
+4
@@ -218,6 +218,10 @@ gitk mainporcelain
218
gitmailmap userinterfaces
219
gitmodules userinterfaces
220
gitnamespaces guide
221
+gitprotocol-capabilities developerinterfaces
222
+gitprotocol-common developerinterfaces
223
+gitprotocol-pack developerinterfaces
224
+gitprotocol-v2 developerinterfaces
225
gitremote-helpers guide
226
gitrepository-layout userinterfaces
227
gitrevisions userinterfaces
refspec.h
+1
-1
@@ -69,7 +69,7 @@ int valid_remote_name(const char *name);
69
struct strvec;
70
/*
71
* Determine what <prefix> values to pass to the peer in ref-prefix lines
72
- * (see Documentation/technical/protocol-v2.txt).
72
+ * (see linkgit:gitprotocol-v2[5]).
73
*/
74
void refspec_ref_prefixes(const struct refspec *rs,
75
struct strvec *ref_prefixes);
t/t5551-http-fetch-smart.sh
+2
-2
@@ -181,8 +181,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '
181
# This is not possible with protocol v2, since both objects and refs
182
# are obtained from the "git-upload-pack" path. A solution to this is
183
# to teach the server and client to be able to inline ls-refs requests
184
- # as an Extra Parameter (see pack-protocol.txt), so that "info/refs"
185
- # can serve refs, just like it does in protocol v0.
184
+ # as an Extra Parameter (see "git help gitformat-pack-protocol"), so that
185
+ # "info/refs" can serve refs, just like it does in protocol v0.
186
GIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&
187
expect_askpass none
188
'