Re: [PATCH] git-remote-helpers.txt: explain how import works with multiple refs

[Jonathan Nieder <jrnieder@gmail.com>]

Hi Matthieu,

Matthieu Moy wrote:

> --- a/Documentation/git-remote-helpers.txt
> +++ b/Documentation/git-remote-helpers.txt
> @@ -241,7 +241,22 @@ Supported if the helper has the "fetch" capability.
>  'push' +<src>:<dst>::
>  	Pushes the given local <src> commit or branch to the
>  	remote branch described by <dst>.  A batch sequence of
> -	one or more push commands is terminated with a blank line.
> +	one or more 'push' commands is terminated with a blank line
> +	(if there is only one reference to push, a single 'push' command
> +	is followed by a blank line). For example, the following would
> +	be two batches of 'push', the first asking the remote-helper
> +	to push the local ref 'master' to the remote ref 'master' and
> +	the local 'HEAD' to the remote 'branch', and the second
> +	asking to push ref 'foo' to ref 'bar' (forced update requested
> +	by the '+').
> ++
> +------------
> +push refs/heads/master:refs/heads/master
> +push HEAD:refs/heads/branch
> +\n
> +push +refs/heads/foo:refs/heads/bar
> +\n
> +------------

Probably examples like this could go in a later EXAMPLES section.

At first I was worried about this not actually working, thinking
"push" might have traditionally had the newline-ends-command-stream
semantics that "connect" has.  But the push codepath does not set the
no_disconnect_req flag, so I was worrying in vain. :)  The stream
passed to the helper ends with two newlines when git pushes.

>  +
>  Zero or more protocol options may be entered after the last 'push'
>  command, before the batch's terminating blank line.
> @@ -266,6 +281,11 @@ Supported if the helper has the "push" capability.
>  Especially useful for interoperability with a foreign versioning
>  system.
>  +
> +Just like 'push', a batch sequence of one or more 'import' is
> +terminated with a blank line. For each batch of 'import', the remote
> +helper should produce a fast-import stream terminated by a 'done'
> +command.
> ++
>  Supported if the helper has the "import" capability.

This documents v1.7.7-rc0~61^2~3 (transport-helper: change import
semantics, 2011-07-16).  Such a documentation fix was desperately
needed; thank you!

For what it's worth, with or without a change to prevent the example
from interrupting the flow of description,
Acked-by: Jonathan Nieder <jrnieder@gmail.com>