git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
5f4d0e7195fc88dfee0454aae5a6b3f8f93bec43 blob 4335 bytes (raw)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
 Git Wire Protocol, Version 2
==============================

This document presents a specification for a version 2 of Git's wire
protocol.  Protocol v2 will improve upon v1 in the following ways:

  * Instead of multiple service names, multiple commands will be
    supported by a single service.
  * Easily extendable as capabilities are moved into their own section
    of the protocol, no longer being hidden behind a NUL byte and
    limited by the size of a pkt-line (as there will be a single
    capability per pkt-line).
  * Separate out other information hidden behind NUL bytes (e.g. agent
    string as a capability and symrefs can be requested using 'ls-refs')
  * Reference advertisement will be omitted unless explicitly requested
  * ls-refs command to explicitly request some refs

 Detailed Design
=================

A client can request to speak protocol v2 by sending `version=2` in the
side-channel `GIT_PROTOCOL` in the initial request to the server.

In protocol v2 communication is command oriented.  When first contacting a
server a list of capabilities will advertised.  Some of these capabilities
will be commands which a client can request be executed.  Once a command
has completed, a client can reuse the connection and request that other
commands be executed.

 Special Packets
-----------------

In protocol v2 these special packets will have the following semantics:

  * '0000' Flush Packet (flush-pkt) - indicates the end of a message
  * '0001' Delimiter Packet (delim-pkt) - separates sections of a message

 Capability Advertisement
--------------------------

A server which decides to communicate (based on a request from a client)
using protocol version 2, notifies the client by sending a version string
in its initial response followed by an advertisement of its capabilities.
Each capability is a key with an optional value.  Clients must ignore all
unknown keys.  Semantics of unknown values are left to the definition of
each key.  Some capabilities will describe commands which can be requested
to be executed by the client.

    capability-advertisement = protocol-version
			       capability-list
			       flush-pkt

    protocol-version = PKT-LINE("version 2" LF)
    capability-list = *capability
    capability = PKT-LINE(key[=value] LF)

    key = 1*CHAR
    value = 1*CHAR
    CHAR = 1*(ALPHA / DIGIT / "-" / "_")

A client then responds to select the command it wants with any particular
capabilities or arguments.  There is then an optional section where the
client can provide any command specific parameters or queries.

    command-request = command
		      capability-list
		      (command-args)
		      flush-pkt
    command = PKT-LINE("command=" key LF)
    command-args = delim-pkt
		   *arg
    arg = 1*CHAR

The server will then check to ensure that the client's request is
comprised of a valid command as well as valid capabilities which were
advertised.  If the request is valid the server will then execute the
command.

A particular command can last for as many rounds as are required to
complete the service (multiple for negotiation during fetch or no
additional trips in the case of ls-refs).

When finished a client should send an empty request of just a flush-pkt to
terminate the connection.

 Commands in v2
~~~~~~~~~~~~~~~~

Commands are the core actions that a client wants to perform (fetch, push,
etc).  Each command will be provided with a list capabilities and
arguments as requested by a client.

 Ls-refs
---------

Ls-refs is the command used to request a reference advertisement in v2.
Unlike the current reference advertisement, ls-refs takes in parameters
which can be used to limit the refs sent from the server.

Ls-ref takes in the following parameters wraped in packet-lines:

  symrefs: In addition to the object pointed by it, show the underlying
	   ref pointed by it when showing a symbolic ref.
  peel: Show peeled tags.
  ref-pattern <pattern>: When specified, only references matching the
			 given patterns are displayed.

The output of ls-refs is as follows:

    output = *ref
	     flush-pkt
    ref = PKT-LINE((tip | peeled) LF)
    tip = obj-id SP refname (SP symref-target)
    peeled = obj-id SP refname "^{}"

    symref = PKT-LINE("symref" SP symbolic-ref SP resolved-ref LF)
    shallow = PKT-LINE("shallow" SP obj-id LF)
debug log:

solving 5f4d0e719 ...
found 5f4d0e719 in https://public-inbox.org/git/20180103001828.205012-13-bmwill@google.com/
found b87ba3816 in https://public-inbox.org/git/20180103001828.205012-12-bmwill@google.com/

applying [1/2] https://public-inbox.org/git/20180103001828.205012-12-bmwill@google.com/
diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt
new file mode 100644
index 000000000..b87ba3816


applying [2/2] https://public-inbox.org/git/20180103001828.205012-13-bmwill@google.com/
diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt
index b87ba3816..5f4d0e719 100644

Checking patch Documentation/technical/protocol-v2.txt...
Applied patch Documentation/technical/protocol-v2.txt cleanly.
Checking patch Documentation/technical/protocol-v2.txt...
Applied patch Documentation/technical/protocol-v2.txt cleanly.

index at:
100644 5f4d0e7195fc88dfee0454aae5a6b3f8f93bec43	Documentation/technical/protocol-v2.txt

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).