Re: [PATCH] Improve documentation for git-remote-helpers

From: Daniel Barkalow <barkalow@iabervon.org>
Date: Mar 21, 2010, 23:29 UTC
Message-ID: <alpine.LNX.2.00.1003211907390.14365@iabervon.org>
In-Reply-To: <f3271551003211121o48f502fp954b649ff4ca8f8b@mail.gmail.com>

I'd like to start by saying that it's good to see patches early, and also that I think the best documentation comes from people who are new to something going back and forth with people who know it too well to know what needs to be said about it.

On Sun, 21 Mar 2010, Ramkumar Ramachandra wrote:

Show 17 quoted lines

> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Documentation/git-remote-helpers.txt |   22 ++++++++++++++++------
>  1 files changed, 16 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/git-remote-helpers.txt
> b/Documentation/git-remote-helpers.txt
> index 1b5f61a..54b36c8 100644
> --- a/Documentation/git-remote-helpers.txt
> +++ b/Documentation/git-remote-helpers.txt
> @@ -3,7 +3,8 @@ git-remote-helpers(1)
> 
>  NAME
>  ----
> -git-remote-helpers - Helper programs for interoperation with remote git
> +git-remote-helpers - Helper programs for interacting with main git
> +programs without linking to them

I think the name is supposed to fit on a single line. Adding more explanation is good, but probably more appropriate below.

Show 23 quoted lines

>  SYNOPSIS
>  --------
> @@ -13,10 +14,19 @@ DESCRIPTION
>  -----------
> 
>  These programs are normally not used directly by end users, but are
> -invoked by various git programs that interact with remote repositories
> -when the repository they would operate on will be accessed using
> -transport code not linked into the main git binary. Various particular
> -helper programs will behave as documented here.
> +invoked by various git programs that interact with remote
> +repositories.  For a program to qualify as a remote helper, it must
> +implement a subset of the capabilities documented here, and conform to
> +the remote helper protocol. Remote helpers interact with the main git
> +programs via text streams, and do not link to them.
> +
> +The curl helper is one such program. It is invoked via
> +'git-remote-http', 'git-remote-https', 'git-remote-ftp', or
> +'git-remote-ftps', and implments the capabilities 'fetch', 'option',
> +and 'push'.
> +
> +Remote helpers are often useful when native interoperability with a
> +foreign versioning system is desired.

You should probably make clear that a helper can provide a fast-import stream (a format which has been adopted by other version control systems) instead of native git objects, if the helper is not exchanging git objects from the remote repository and trying to preserve their identities. The curl helper is unusual in that it just moves git pbjects from place to place. (That is, the curl helper uses 'fetch' and 'push', but other helpers will mostly use 'import' and 'export'; the curl helper does need the ability to use the git object database, but other helpers mostly won't.)

Show 8 quoted lines

>  COMMANDS
>  --------
> @@ -122,7 +132,7 @@ CAPABILITIES
>        This helper supports the 'fetch' command.
> 
>  'option'::
> -       This helper supports the option command.
> +       This helper supports the 'option' command.

Yup. Or maybe these should be documented as a list of capabilities which mean that the helper supports the command with the same name, since that's a common pattern, and documenting it as a pattern makes it obvious that, if we have a new 'export' command, and it needs a capability, it'll fit the pattern.

Show 5 quoted lines

>  'push'::
>        This helper supports the 'push' command.
> --
> 1.7.0
>

	-Daniel
*This .sig left intentionally blank*