Jonathan Nieder <jrnieder@xxxxxxxxx> writes:
> Here's an old attempt to make the documentation a little easier to read,
> and hopefully also to add to.
Thanks, that helps. I wish we had all this earlier ;-).
> +Git sends the remote helper a list of commands on standard input, one
> +per line. The first command is always the 'capabilities' command,
Do we want to set this in stone? Wouldn't a Git implementation calling
"option" before "capabilities" be correct?
> +Capabilities
> +~~~~~~~~~~~~
(perhaps name the section "Overview of Capabilities"?)
[...]
> +'refspec' <refspec>::
> + This modifies the 'import' capability, allowing the produced
> + fast-import stream to modify refs in a private namespace
> + instead of writing to refs/heads or refs/remotes directly.
> + It is recommended that all importers providing the 'import'
> + capability use this.
> ++
> +A helper advertising the capability
> +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}`
> +is saying that, when it is asked to `import refs/heads/topic`, the
> +stream it outputs will update the `refs/svn/origin/branches/topic`
> +ref.
> ++
> +This capability can be advertised multiple times. The first
> +applicable refspec takes precedence. The left-hand of refspecs
> +advertised with this capability must cover all refs reported by
> +the list command. If no 'refspec' capability is advertised,
> +there is an implied `refspec {asterisk}:{asterisk}`.
Since this "Capabilities" section is meant to be an overview, I'd
shorten this to
+'refspec' <refspec>::
+ This modifies the 'import' capability, allowing the produced
+ fast-import stream to modify refs in a private namespace
+ instead of writing to refs/heads or refs/remotes directly.
and drop the detailed explanation here.
> +Capabilities for Fetching
> +~~~~~~~~~~~~~~~~~~~~~~~~~
[...]
> +'refspec' <refspec>::
> + This modifies the 'import' capability.
Since this would be the "detailed explanation" part, this is the one
readers will read more carefully, so I'd put the recommandation right
here:
+ It is recommended that all importers providing the 'import'
+ capability use this.
and of course, keep this:
> ++
> +A helper advertising
> +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}`
> +in its capabilities is saying that, when it handles
> +`import refs/heads/topic`, the stream it outputs will update the
> +`refs/svn/origin/branches/topic` ref.
> ++
> +This capability can be advertised multiple times. The first
> +applicable refspec takes precedence. The left-hand of refspecs
> +advertised with this capability must cover all refs reported by
> +the list command. If no 'refspec' capability is advertised,
> +there is an implied `refspec {asterisk}:{asterisk}`.
> +
--
Matthieu Moy
http://www-verimag.imag.fr/~moy/
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html