On 10/28, Philip Oakley wrote:
> From: "Brandon Williams" <bmwill@xxxxxxxxxx>
> 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.
I'll work to make the language a little clearer.
>
> > 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.
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).
>
> >
> >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
