From: "Brandon Williams" <bmw...@google.com>
Sent: Friday, October 20, 2017 6:18 PM
Objective
===========
Replace Git's current wire protocol with a simpler, less wasteful
protocol that can evolve over time.
<snip>
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.
This sounds odd. If the keys are known then their semantics are known. Or
the keys are unknown and they and their values are ignored.
Maybe: Capability keys shall define their response to unknown key values.
Some capabilities will describe commands
which can be requested to be executed by the client.
<snip>
Ls-refs
---------
Ls-refs can be looked at as the equivalent of the current ls-remote as
it is a way to query a remote for the references that it has. Unlike
the current ls-remote, the filtering of the output is done on the server
side by passing a number of parameters to the server-side command
instead of the filtering occurring on the client.
Ls-ref takes in the following parameters:
--head, --tags: Limit to only refs/heads or refs/tags
--refs: Do not show peeled tags or pseudorefs like HEAD
--symref: In addition to the object pointed by it, show the underlying
ref pointed by it when showing a symbolic ref
<refspec>: When specified, only references matching the given patterns
are displayed.
Does the --symref also the pseudorefs?
Isn't there a need somethimes to determine the ref that the remote's HEAD
points to. This is an issue with the current clone and bundle code when
there is a choice of refs/branches that could be the current HEAD ref and
the wrong one is chosen, though this V2 change doesn't affect bundles.
The output of ls-refs is as follows:
output = (no-refs / list-of-refs)
*symref
*shallow
flush-pkt
no-refs = PKT-LINE(zero-id SP no-refs LF)
list-of-refs = *ref
ref = PKT-LINE((tip / peeled) LF)
tip = obj-id SP refname
peeled = obj-id SP refname "^{}"
symref = PKT-LINE("symref" SP symbolic-ref SP resolved-ref LF)
shallow = PKT-LINE("shallow" SP obj-id LF)
Fetch
-------
Fetch will need to be a modified version of the v1 fetch protocol. Some
potential areas for improvement are: Ref-in-want, CDN offloading,
Fetch-options.
Since we'll have an 'ls-ref' service we can eliminate the need of fetch
to perform a ref-advertisement, instead a client can run the 'ls-refs'
service first, in order to find out what refs the server has, and then
request those refs directly using the fetch service.
//TODO Flush out the design
Fetch-object
--------------
This service could be used by partial clones in order to request missing
objects.
//TODO Flush out the design
Push
------
Push will need to be a modified version of the v1 push protocol. Some
potential areas for improvement are: Fix push-options, Negotiation for
force push.
One change that will need to happen is to improve how `push-options` are
sent to the server (so that they aren't sent twice!!). Also the
report-status needs to be better than it currently is in v1 so that
tools like gerrit can explain what it did with the ref-update the client
sent to it. Maybe have a push-rebase capability or command?
//TODO Flush out the design
Other Considerations
======================
* Move away from pkt-line framing?
* Have responses structured in well known formats (e.g. JSON)
* Eliminate initial round-trip using 'GIT_PROTOCOL' side-channel
* Additional commands in a partial clone world (e.g. log, grep)
--
Philip
