[PATCH] Improve documentation for git-remote-helpers

[PATCH] Improve documentation for git-remote-helpers

[Ramkumar Ramachandra]

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

 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.

 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.

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

[PATCH] Improve documentation for git-remote-helpers

[Ramkumar Ramachandra]

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

 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.

 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.

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

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

[Daniel Barkalow]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 3408 bytes --]

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:

> 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.

>  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.)

>  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.

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

	-Daniel
*This .sig left intentionally blank*

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

[Sverre Rabbelier]

Heya,

On Mon, Mar 22, 2010 at 00:29, Daniel Barkalow <barkalow@iabervon.org> wrote:
> 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.

Speaking of which, I have uploaded a preliminary version of the export
capability to my github repository [0] since Ramkumar wanted to have a
look at it. Sadly I have not been able to test it yet, I wanted to
work on that today but instead spent hours on getting the first
argument to the helper to be 'origin' (or whatever the user sets it to
with the --origin option), something that's been bothering me forever.
No documentation yet though, working on that ;).

[0] http://github.com/SRabbelier/git

-- 
Cheers,

Sverre Rabbelier

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

[Daniel Barkalow]

On Mon, 22 Mar 2010, Sverre Rabbelier wrote:

> Heya,
> 
> On Mon, Mar 22, 2010 at 00:29, Daniel Barkalow <barkalow@iabervon.org> wrote:
> > 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.
> 
> Speaking of which, I have uploaded a preliminary version of the export
> capability to my github repository [0] since Ramkumar wanted to have a
> look at it. Sadly I have not been able to test it yet, I wanted to
> work on that today but instead spent hours on getting the first
> argument to the helper to be 'origin' (or whatever the user sets it to
> with the --origin option), something that's been bothering me forever.
> No documentation yet though, working on that ;).
> 
> [0] http://github.com/SRabbelier/git

Looks generally right, but I think you need to do 
"finish_command(&exporter);" first, and actually get some feedback from 
the helper. I think the right thing is actually to put the output of the 
helper into fast-import again, and have that give one of three 
conclusions:

 - We tried to send sha1 A to the foreign system, and it rejected us 
   entirely.
 - We tried to send sha1 A to the foreign system, and reimporting what it 
   put in for us actually gives us sha1 A, so the transformation is 
   lossless.
 - We tried to send sha1 A to the foreign system, but reimporting what it
   put in for us gives us sha1 B instead. This means B is as close to a 
   replacement for A as we can get in this case, and the git core should 
   know about the situation (although, for now, it doesn't have anything 
   to do about it).

At the least, in the third case, we should update any tracking branches to 
match what the foreign system now contains, not to match what we tried to 
put there.

But even without considering the third case (IIRC, hg and git can 
interoperate losslessly), you need to get feedback in some way if the 
remote entirely rejected us.

	-Daniel
*This .sig left intentionally blank*

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

[Sverre Rabbelier]

Heya,

On Mon, Mar 22, 2010 at 01:06, Daniel Barkalow <barkalow@iabervon.org> wrote:
> Looks generally right, but I think you need to do
> "finish_command(&exporter);" first, and actually get some feedback from
> the helper. I think the right thing is actually to put the output of the
> helper into fast-import again, and have that give one of three
> conclusions:

I'm not sure that makes sense (at least to me). I think you are right
in that we need to collect output from the helper, but I don't see any
added value in feeding that into fast-import. I think we should rather
read from the helper after we finish exporting to figure out what
happened. The different cases you described are I think indeed what we
should look for.

-- 
Cheers,

Sverre Rabbelier

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

[Ramkumar Ramachandra]

> Speaking of which, I have uploaded a preliminary version of the export
> capability to my github repository [0] since Ramkumar wanted to have a
> look at it. Sadly I have not been able to test it yet, I wanted to
> work on that today but instead spent hours on getting the first
> argument to the helper to be 'origin' (or whatever the user sets it to
> with the --origin option), something that's been bothering me forever.
> No documentation yet though, working on that ;).

Thanks! I'll look at it in the evening.

-- Ram

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

[Ramkumar Ramachandra]

> 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.

Thanks :) I just posted a second revision of the patch incorporating
your suggestions.

> 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.

Every capability doesn't necessarily have a corresponding command with
the same name, and vice-versa (see refspec spec?). Besides, I think
it's necessary for the manpage to have a list of capabilities listed
in one place. I'll think about a better format when we get more
capabilities/ commands.

-- Ram

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

[Ramkumar Ramachandra]

> Every capability doesn't necessarily have a corresponding command with
> the same name, and vice-versa (see refspec spec?). Besides, I think
> it's necessary for the manpage to have a list of capabilities listed
> in one place. I'll think about a better format when we get more
> capabilities/ commands.

I think I might have misunderstood what you said. So, I've posted a
third revision of the patch- is it the desired result?

-- Ram