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
Junio C Hamano
parent
8cbace93d2
commit
5db921054e
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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].
|
||||
|
||||
--
|
||||
|
||||
@ -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>::
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
|
||||
@ -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]
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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);
|
||||
|
||||
@ -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
|
||||
'
|
||||
|
||||
Loading…
Reference in New Issue
Block a user