# [PATCH v4] Improve remote-helpers documentation 3 messages from 2010-03-22 to 2010-03-22. Participants: Ramkumar Ramachandra, Daniel Barkalow. Thread: https://gitlist.dev/t/23139 ## Ramkumar Ramachandra, 2010-03-22 13:04 Subject: [PATCH v4] Improve remote-helpers documentation Message-ID: URL: https://gitlist.dev/e/f3271551003220604v4c9fbb5ep3b7c69300567a275%40mail.gmail.com ``` Signed-off-by: Ramkumar Ramachandra --- Documentation/git-remote-helpers.txt | 40 +++++++++++++++++---------------- 1 files changed, 21 insertions(+), 19 deletions(-) diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 1b5f61a..2d5aa8c 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -3,7 +3,7 @@ git-remote-helpers(1) NAME ---- -git-remote-helpers - Helper programs for interoperation with remote git +git-remote-helpers - Helper programs for interacting with remote repositories SYNOPSIS -------- @@ -13,10 +13,23 @@ 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 are spawned as binaries by +the main git programs and interact using text streams, without +linking. + +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'. The curl helper essentially helps in transporting native +git objects. + +As opposed to native git objects, remote helpers can also provide a +fast-import stream through the 'import' capability. This makes them +especially useful when native interoperability with a foreign +versioning system is desired. COMMANDS -------- @@ -118,17 +131,9 @@ capabilities reported by the helper. CAPABILITIES ------------ -'fetch':: - This helper supports the 'fetch' command. - -'option':: - This helper supports the option command. - -'push':: - This helper supports the 'push' command. - -'import':: - This helper supports the 'import' command. +The following capabilities indicate that the remote helper supports +the corresponding command with the same name: 'fetch', 'option', +'push', 'connect', and 'import'. 'refspec' 'spec':: When using the import command, expect the source ref to have @@ -140,9 +145,6 @@ CAPABILITIES all, it must cover all refs reported by the list command; if it is not used, it is effectively "*:*" -'connect':: - This helper supports the 'connect' command. - REF LIST ATTRIBUTES ------------------- -- 1.7.0.2 ``` ## Daniel Barkalow, 2010-03-22 16:32 Subject: Re: [PATCH v4] Improve remote-helpers documentation Message-ID: URL: https://gitlist.dev/e/alpine.LNX.2.00.1003221143250.14365%40iabervon.org In-Reply-To: ``` Looks good, other than an optional suggestion below. Incidentally, it's often helpful to describe the differences between earlier versions and v4 of the patch between the "---" and the diffstat; that part of the email doesn't go into the commit, but can be seen by reviewers. On Mon, 22 Mar 2010, Ramkumar Ramachandra wrote: > Signed-off-by: Ramkumar Ramachandra > --- > Documentation/git-remote-helpers.txt | 40 +++++++++++++++++---------------- > 1 files changed, 21 insertions(+), 19 deletions(-) > > diff --git a/Documentation/git-remote-helpers.txt > b/Documentation/git-remote-helpers.txt > index 1b5f61a..2d5aa8c 100644 > --- a/Documentation/git-remote-helpers.txt > +++ b/Documentation/git-remote-helpers.txt > @@ -3,7 +3,7 @@ git-remote-helpers(1) > > NAME > ---- > -git-remote-helpers - Helper programs for interoperation with remote git > +git-remote-helpers - Helper programs for interacting with remote repositories > > SYNOPSIS > -------- > @@ -13,10 +13,23 @@ 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 are spawned as binaries by > +the main git programs and interact using text streams, without > +linking. > + > +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'. The curl helper essentially helps in transporting native > +git objects. > + > +As opposed to native git objects, remote helpers can also provide a > +fast-import stream through the 'import' capability. This makes them > +especially useful when native interoperability with a foreign > +versioning system is desired. > > COMMANDS > -------- > @@ -118,17 +131,9 @@ capabilities reported by the helper. > CAPABILITIES > ------------ > > -'fetch':: > - This helper supports the 'fetch' command. > - > -'option':: > - This helper supports the option command. > - > -'push':: > - This helper supports the 'push' command. > - > -'import':: > - This helper supports the 'import' command. > +The following capabilities indicate that the remote helper supports > +the corresponding command with the same name: 'fetch', 'option', > +'push', 'connect', and 'import'. This is, indeed, what I was suggesting, although I think it might be more readable like: 'fetch':: 'option':: 'push':: 'connect':: 'import':: This helper supports the corresponding command with the same name. But I'm fine with whichever format is most helpful for someone trying to read the document (that is, to you). -Daniel *This .sig left intentionally blank* ``` ## Ramkumar Ramachandra, 2010-03-22 16:57 Subject: Re: [PATCH v4] Improve remote-helpers documentation Message-ID: URL: https://gitlist.dev/e/f3271551003220957q5db34547t69b425f708628dff%40mail.gmail.com In-Reply-To: ``` > But I'm fine with whichever format is most helpful for someone trying to > read the document (that is, to you). Your format is indeed more elegant- I've incorporated this change in v5. Thanks. -- Ram ```