On 10/28, Philip Oakley wrote:

From: "Brandon Williams" <redacted>
Sent: Friday, October 20, 2017 6:18 PM

quoted

Objective
===========

Replace Git's current wire protocol with a simpler, less wasteful
protocol that can evolve over time.

<snip>

quoted

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.

quoted

  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.

I'll work to make the language a little clearer.

quoted

Some capabilities will describe commands
which can be requested to be executed by the client.

<snip>

quoted

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.

Yeah, currently the resolution of HEAD is stuffed into the
capability line in v1.  The intention of this would be to allow for the
resolution of all symrefs (including HEAD).

quoted

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

-- 
Brandon Williams