Re: [RFC PATCH 2/3] Add specification of git-vcs helpers

[Junio C Hamano <gitster@pobox.com>]

Daniel Barkalow <barkalow@iabervon.org> writes:

> So far, I've actually used list and import; I've also implemented an 
> export, but haven't figured out exactly how the user should cause it to be 
> used.
> ...
> +'capabilities'::
> +	Prints the capabilities of the helper, one per line. These are:
> +	 - import: the basic import command
> +	 - marks: import should be done with a saved marks file
> +	 - find-new-branches: detect new branches
> +	 - export: the general export command
> +	 - fork: create a new branch and export to it
> +	 - anonymous-fork: make commits on a branch without an inherent name
> +	 - merge: merge branches (of whatever type the system supports)
> +
> +	If the helper doesn't support "merge", the default for pull is
> +	to rebase instead of merging.

Have you tried formatting this to both html and man?  I think you need to
dedent the second paragraph, and have '+' as the sole character on a line
immediately before, without any blank lines.  The formatted output of the
description of 'export' is probably more troublesome as it is much longer.

This list feels like overengineered yet without enough thinking behind it.

Your 'list' allows to list what can become branches on the git end, so as
long as you have tracking information on the git side, find-new-branches
seems unnecessary, for examle.  Worse, find-new-branches needs its own
tracking mechansim anyway, but that means how the namespace for remote
tracking branches is managed is left to the vcs backends, even though that
namespace is directly visiblt to git --- my gut feeling is that it would
probably better to arrange things similar to what git native transport
does already.  'list' would say "The remote has what can become refs on
the git end and calls them A, B, C", and the built-in code, using ref
mapping specification, maps them to refs/remotes/somename/{A,B,C}.  You do
it again and if you see the remote has D but does not have B anymore, you
know D is a new branch and B was deleted.

What does 'merge' mean?  It cannot mean to fetch their changes from
foreign vcs and create a merge locally (you only need import from the
backend, and merge will be a usual git merge).  Perhaps you meant if you
can export a merge back?  Some foreign systems may support importing
merges but not octopus, so it may not be just a black-or-white boolean.

Also "the default is to rebase instead of merge" is probably too weak.
You would want to error out if the user tried to merge, wouldn't you?

> +'list'::
> +	Takes the remote name, and outputs the names of refs. These
> +	may be followed, after a single space, by "changed" or
> +	"unchanged", indicating whether the foreign repository has
> +	changed from the state in the ref. If the helper doesn't know,
> +	it doesn't have to provide a value. (In particular, it
> +	shouldn't do expensive operations, such as importing the
> +	content, to see whether it matches.)

I am guessing by 'a value' you mean 'changed/unchanged', iow you are not
saying if the helper does not know it can omit such refs from the list,
but it is unclear.