# [PATCH] Improve documentation for git-remote-helpers 9 messages from 2010-03-21 to 2010-03-22. Participants: Ramkumar Ramachandra, Daniel Barkalow, Sverre Rabbelier. Thread: https://gitlist.dev/t/23123 ## Ramkumar Ramachandra, 2010-03-21 17:26 Subject: [PATCH] Improve documentation for git-remote-helpers Message-ID: URL: https://gitlist.dev/e/f3271551003211026m376b86d6ga915f85a623eddfd%40mail.gmail.com ``` Signed-off-by: Ramkumar Ramachandra --- 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 ``` ## Ramkumar Ramachandra, 2010-03-21 18:21 Subject: [PATCH] Improve documentation for git-remote-helpers Message-ID: URL: https://gitlist.dev/e/f3271551003211121o48f502fp954b649ff4ca8f8b%40mail.gmail.com In-Reply-To: ``` Signed-off-by: Ramkumar Ramachandra ---  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 ``` ## Daniel Barkalow, 2010-03-21 23:29 Subject: Re: [PATCH] Improve documentation for git-remote-helpers Message-ID: URL: https://gitlist.dev/e/alpine.LNX.2.00.1003211907390.14365%40iabervon.org In-Reply-To: ``` 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 > --- >  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* ``` ## Sverre Rabbelier, 2010-03-21 23:35 Subject: Re: [PATCH] Improve documentation for git-remote-helpers Message-ID: URL: https://gitlist.dev/e/fabb9a1e1003211635w27f0b22em73c7c6431c3998af%40mail.gmail.com In-Reply-To: ``` Heya, On Mon, Mar 22, 2010 at 00:29, Daniel Barkalow 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 ``` ## Daniel Barkalow, 2010-03-22 00:06 Subject: Re: [PATCH] Improve documentation for git-remote-helpers Message-ID: URL: https://gitlist.dev/e/alpine.LNX.2.00.1003211951360.14365%40iabervon.org In-Reply-To: ``` On Mon, 22 Mar 2010, Sverre Rabbelier wrote: > Heya, > > On Mon, Mar 22, 2010 at 00:29, Daniel Barkalow 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* ``` ## Ramkumar Ramachandra, 2010-03-22 03:04 Subject: Re: [PATCH] Improve documentation for git-remote-helpers Message-ID: URL: https://gitlist.dev/e/f3271551003212004r4ac7db34vad5b23f5d930476d%40mail.gmail.com In-Reply-To: ``` > 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 ``` ## Ramkumar Ramachandra, 2010-03-22 03:38 Subject: Re: [PATCH] Improve documentation for git-remote-helpers Message-ID: URL: https://gitlist.dev/e/f3271551003212038i4239a852g9f9350cb1c93f8db%40mail.gmail.com In-Reply-To: ``` > 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 ``` ## Ramkumar Ramachandra, 2010-03-22 07:28 Subject: Re: [PATCH] Improve documentation for git-remote-helpers Message-ID: URL: https://gitlist.dev/e/f3271551003220028w79d2f1b4q5a47ca8d21515288%40mail.gmail.com In-Reply-To: ``` > 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 ``` ## Sverre Rabbelier, 2010-03-22 15:40 Subject: Re: [PATCH] Improve documentation for git-remote-helpers Message-ID: URL: https://gitlist.dev/e/fabb9a1e1003220840q5b9b791ft83c8fd4793b83be2%40mail.gmail.com In-Reply-To: ``` Heya, On Mon, Mar 22, 2010 at 01:06, Daniel Barkalow 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 ```