Please document Haskell team style Vcs-Git sytax

[Jonathan Nieder]

Hi,

Ian Jackson wrote:
> Russ Allbery writes:

>> So, maybe something like:
>>
>>     <url> -b <branch> [<path>; <key>=<value> ...]
>>
>> to build off of what we already have?  (With, obviously, a bunch of that
>> syntax marked as optional.)  If we ban "=" in <path>, we can allow for
>> <path> to be optional but some other key/value pair to be provided.
>
> SGTM.  We can specify that [ ] contains optional information.

Taking a step back, I'd like to understand the use case a little better.

In Subversion, it's standard to use paths to represent multiple projects
and even branches within a repository.  So in that setting, I completely
understand why <path> is part of the URL.

In Git, when you "git clone" a repository, that represents a single
codebase.  There is no parameter you can pass to "git clone" that
tells it to clone just a subdirectory.  So we aren't including the
<path> in Vcs-Git in order to determine what parameters to pass to
"git clone".

Given that, what *are* we including the <path> for?  And similarly,
what is the use case behind the other key/value pairs described here?

It's possible that it might make sense to use separate fields for this
information --- e.g. a

  Vcs-Git-Path: <path>

or something like that.  That way, you get extensibility for free.

Alternatively, maybe there is a lurking Git feature request here, for
example for an atomic view across multiple repositories, or for the
ability to clone just a subdirectory of a repository (with
https://crbug.com/git/2 you already almost have that, though it's
fussy to set up sparse checkout to do it and you still have to "cd"
into the subdirectory).

Curious,
Jonathan