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>
This commit is contained in:
Ævar Arnfjörð Bjarmason 2022-08-04 18:28:36 +02:00 committed by Junio C Hamano
parent 8cbace93d2
commit 5db921054e
17 changed files with 106 additions and 37 deletions

View File

@ -30,6 +30,10 @@ MAN5_TXT += githooks.txt
MAN5_TXT += gitignore.txt
MAN5_TXT += gitmailmap.txt
MAN5_TXT += gitmodules.txt
MAN5_TXT += gitprotocol-capabilities.txt
MAN5_TXT += gitprotocol-common.txt
MAN5_TXT += gitprotocol-pack.txt
MAN5_TXT += gitprotocol-v2.txt
MAN5_TXT += gitrepository-layout.txt
MAN5_TXT += gitweb.conf.txt
@ -105,12 +109,8 @@ TECH_DOCS += technical/long-running-process-protocol
TECH_DOCS += technical/multi-pack-index
TECH_DOCS += technical/pack-format
TECH_DOCS += technical/pack-heuristics
TECH_DOCS += technical/pack-protocol
TECH_DOCS += technical/parallel-checkout
TECH_DOCS += technical/partial-clone
TECH_DOCS += technical/protocol-capabilities
TECH_DOCS += technical/protocol-common
TECH_DOCS += technical/protocol-v2
TECH_DOCS += technical/racy-git
TECH_DOCS += technical/reftable
TECH_DOCS += technical/send-pack-pipeline

View File

@ -1,7 +1,7 @@
lsrefs.unborn::
May be "advertise" (the default), "allow", or "ignore". If "advertise",
the server will respond to the client sending "unborn" (as described in
protocol-v2.txt) and will advertise support for this feature during the
linkgit:gitprotocol-v2[5]) and will advertise support for this feature during the
protocol v2 capability advertisement. "allow" is the same as
"advertise" except that the server will not advertise support for this
feature; this is useful for load-balanced servers that cannot be

View File

@ -58,6 +58,6 @@ protocol.version::
* `1` - the original wire protocol with the addition of a version string
in the initial response from the server.
* `2` - link:technical/protocol-v2.html[wire protocol version 2].
* `2` - Wire protocol version 2, see linkgit:gitprotocol-v2[5].
--

View File

@ -40,9 +40,8 @@ OPTIONS
Used by linkgit:git-http-backend[1] to serve up
`$GIT_URL/info/refs?service=git-upload-pack` requests. See
"Smart Clients" in link:technical/http-protocol.html[the HTTP
transfer protocols] documentation and "HTTP Transport" in
link:technical/protocol-v2.html[the Git Wire Protocol, Version
2] documentation. Also understood by
transfer protocols] documentation and "HTTP Transport" in the
linkgit:gitprotocol-v2[5] documentation. Also understood by
linkgit:git-receive-pack[1].
<directory>::

View File

@ -27,7 +27,7 @@ FORMAT
------
We will use ABNF notation to define the Git bundle format. See
link:technical/protocol-common.html for the details.
linkgit:gitprotocol-common[5] for the details.
A v2 bundle looks like this:

View File

@ -1,8 +1,20 @@
Git Protocol Capabilities
=========================
gitprotocol-capabilities(5)
===========================
NAME
----
gitprotocol-capabilities - Protocol v0 and v1 capabilities
SYNOPSIS
--------
[verse]
<over-the-wire-protocol>
DESCRIPTION
-----------
NOTE: this document describes capabilities for versions 0 and 1 of the pack
protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]
doc.
Servers SHOULD support all capabilities defined in this document.
@ -77,7 +89,7 @@ interleaved with S-R-Q.
multi_ack_detailed
------------------
This is an extension of multi_ack that permits client to better
understand the server's in-memory state. See pack-protocol.txt,
understand the server's in-memory state. See linkgit:gitprotocol-pack[5],
section "Packfile Negotiation" for more information.
no-done
@ -281,7 +293,7 @@ a packfile upload and reference update. If the pushing client requests
this capability, after unpacking and updating references the server
will respond with whether the packfile unpacked successfully and if
each reference was updated successfully. If any of those were not
successful, it will send back an error message. See pack-protocol.txt
successful, it will send back an error message. See linkgit:gitprotocol-pack[5]
for example messages.
report-status-v2
@ -292,7 +304,7 @@ adding new "option" directives in order to support reference rewritten by
the "proc-receive" hook. The "proc-receive" hook may handle a command
for a pseudo-reference which may create or update a reference with
different name, new-oid, and old-oid. While the capability
'report-status' cannot report for such case. See pack-protocol.txt
'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5]
for details.
delete-refs
@ -378,3 +390,7 @@ packet-line, and must not contain non-printable or whitespace characters. The
current implementation uses trace2 session IDs (see
link:api-trace2.html[api-trace2] for details), but this may change and users of
the session ID should not rely on this fact.
GIT
---
Part of the linkgit:git[1] suite

View File

@ -1,5 +1,20 @@
Documentation Common to Pack and Http Protocols
===============================================
gitprotocol-common(5)
=====================
NAME
----
gitprotocol-common - Things common to various protocols
SYNOPSIS
--------
[verse]
<over-the-wire-protocol>
DESCRIPTION
-----------
This document sets defines things common to various over-the-wire
protocols and file formats used in Git.
ABNF Notation
-------------
@ -97,3 +112,7 @@ Examples (as C-style strings):
"000bfoobar\n" "foobar\n"
"0004" ""
----
GIT
---
Part of the linkgit:git[1] suite

View File

@ -1,5 +1,17 @@
Packfile transfer protocols
===========================
gitprotocol-pack(5)
===================
NAME
----
gitprotocol-pack - How packs are transferred over-the-wire
SYNOPSIS
--------
[verse]
<over-the-wire-protocol>
DESCRIPTION
-----------
Git supports transferring data in packfiles over the ssh://, git://, http:// and
file:// transports. There exist two sets of protocols, one for pushing
@ -18,7 +30,7 @@ pkt-line Format
---------------
The descriptions below build on the pkt-line format described in
protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
linkgit:gitprotocol-common[5]. When the grammar indicate `PKT-LINE(...)`, unless
otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
include a LF, but the receiver MUST NOT complain if it is not present.
@ -60,7 +72,7 @@ Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
Servers that receive any such Extra Parameters MUST ignore all
unrecognized keys. Currently, the only Extra Parameter recognized is
"version" with a value of '1' or '2'. See protocol-v2.txt for more
"version" with a value of '1' or '2'. See linkgit:gitprotocol-v2[5] for more
information on protocol version 2.
Git Transport
@ -707,3 +719,7 @@ An example client/server communication might look like this:
S: 0018ok refs/heads/debug\n
S: 002ang refs/heads/master non-fast-forward\n
----
GIT
---
Part of the linkgit:git[1] suite

View File

@ -1,5 +1,17 @@
Git Wire Protocol, Version 2
============================
gitprotocol-v2(5)
=================
NAME
----
gitprotocol-v2 - Git Wire Protocol, Version 2
SYNOPSIS
--------
[verse]
<over-the-wire-protocol>
DESCRIPTION
-----------
This document presents a specification for a version 2 of Git's wire
protocol. Protocol v2 will improve upon v1 in the following ways:
@ -26,8 +38,7 @@ Packet-Line Framing
-------------------
All communication is done using packet-line framing, just as in v1. See
`Documentation/technical/pack-protocol.txt` and
`Documentation/technical/protocol-common.txt` for more information.
linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-common[5] for more information.
In protocol v2 these special packets will have the following semantics:
@ -42,7 +53,7 @@ Initial Client Request
In general a client can request to speak protocol v2 by sending
`version=2` through the respective side-channel for the transport being
used which inevitably sets `GIT_PROTOCOL`. More information can be
found in `pack-protocol.txt` and `http-protocol.txt`, as well as the
found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the
`GIT_PROTOCOL` definition in `git.txt`. In all cases the
response from the server is the capability advertisement.
@ -566,3 +577,7 @@ and associated requested information, each separated by a single space.
attr = "size"
obj-info = obj-id SP obj-size
GIT
---
Part of the linkgit:git[1] suite

View File

@ -78,7 +78,7 @@ client and an optional response message from the server. Both the
client and server messages are unlimited in length and are terminated
with a flush packet.
The pkt-line routines (Documentation/technical/protocol-common.txt)
The pkt-line routines (linkgit:gitprotocol-common[5])
are used to simplify buffer management during message generation,
transmission, and reception. A flush packet is used to mark the end
of the message. This allows the sender to incrementally generate and

View File

@ -222,7 +222,7 @@ smart server reply:
S: 0000
The client may send Extra Parameters (see
Documentation/technical/pack-protocol.txt) as a colon-separated string
linkgit:gitprotocol-pack[5]) as a colon-separated string
in the Git-Protocol HTTP header.
Uses the `--http-backend-info-refs` option to
@ -518,5 +518,5 @@ References
http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
link:technical/pack-protocol.html
link:technical/protocol-capabilities.html
linkgit:gitprotocol-pack[5]
linkgit:gitprotocol-capabilities[5]

View File

@ -3,7 +3,7 @@ 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)
communication is in pkt-line format (see linkgit:gitprotocol-common[5])
over standard input and standard output.
Handshake

View File

@ -18,7 +18,7 @@ a `packfile-uris` argument, the server MAY send a `packfile-uris` section
directly before the `packfile` section (right after `wanted-refs` if it is
sent) containing URIs of any of the given protocols. The URIs point to
packfiles that use only features that the client has declared that it supports
(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of
(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of
this section.
Clients should then download and index all the given URIs (in addition to

View File

@ -79,7 +79,7 @@ Design Details
upload-pack negotiation.
+
This uses the existing capability discovery mechanism.
See "filter" in Documentation/technical/pack-protocol.txt.
See "filter" in linkgit:gitprotocol-pack[5].
- Clients pass a "filter-spec" to clone and fetch which is passed to the
server to request filtering during packfile construction.

View File

@ -218,6 +218,10 @@ gitk mainporcelain
gitmailmap userinterfaces
gitmodules userinterfaces
gitnamespaces guide
gitprotocol-capabilities developerinterfaces
gitprotocol-common developerinterfaces
gitprotocol-pack developerinterfaces
gitprotocol-v2 developerinterfaces
gitremote-helpers guide
gitrepository-layout userinterfaces
gitrevisions userinterfaces

View File

@ -69,7 +69,7 @@ int valid_remote_name(const char *name);
struct strvec;
/*
* Determine what <prefix> values to pass to the peer in ref-prefix lines
* (see Documentation/technical/protocol-v2.txt).
* (see linkgit:gitprotocol-v2[5]).
*/
void refspec_ref_prefixes(const struct refspec *rs,
struct strvec *ref_prefixes);

View File

@ -181,8 +181,8 @@ test_expect_success 'no-op half-auth fetch does not require a password' '
# This is not possible with protocol v2, since both objects and refs
# are obtained from the "git-upload-pack" path. A solution to this is
# to teach the server and client to be able to inline ls-refs requests
# as an Extra Parameter (see pack-protocol.txt), so that "info/refs"
# can serve refs, just like it does in protocol v0.
# as an Extra Parameter (see "git help gitformat-pack-protocol"), so that
# "info/refs" can serve refs, just like it does in protocol v0.
GIT_TEST_PROTOCOL_VERSION=0 git --git-dir=half-auth fetch &&
expect_askpass none
'