[PATCH v3] Improve remote-helpers documentation

[PATCH v3] Improve remote-helpers documentation

[Ramkumar Ramachandra]

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/git-remote-helpers.txt |   39 +++++++++++++++++----------------
 1 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/Documentation/git-remote-helpers.txt
b/Documentation/git-remote-helpers.txt
index 1b5f61a..b1f4e5d 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 main git
without linking

 SYNOPSIS
 --------
@@ -13,10 +13,22 @@ 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'. The curl helper essentially helps in moving around native
+git objects.
+
+As opposed to native git objects, remote helpers can also provide a
+fast-import stream through the 'import' capability. This makes it
+especially useful when native interoperability with a foreign
+versioning system is desired.

 COMMANDS
 --------
@@ -118,17 +130,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 +144,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

Re: [PATCH v3] Improve remote-helpers documentation

[Michael J Gruber]

Ramkumar Ramachandra venit, vidit, dixit 22.03.2010 04:37:
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Documentation/git-remote-helpers.txt |   39 +++++++++++++++++----------------
>  1 files changed, 20 insertions(+), 19 deletions(-)
> 
> diff --git a/Documentation/git-remote-helpers.txt
> b/Documentation/git-remote-helpers.txt
> index 1b5f61a..b1f4e5d 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 main git
> without linking

Below, you say that helpers help Git interact with remote repositories
(which is correct). That should be matched by the short explanation
above. "Without linking" is a technical detail, so I suggest:

git-remote-helpers - Helper programs for interacting with remote
repositories

> 
>  SYNOPSIS
>  --------
> @@ -13,10 +13,22 @@ 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.

Isn't it more the other way round? Git calls and interacts with the
helpers, and does not link in the helpers.

> +
> +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 moving around native
> +git objects.
> +
> +As opposed to native git objects, remote helpers can also provide a
> +fast-import stream through the 'import' capability. This makes it
> +especially useful when native interoperability with a foreign
> +versioning system is desired.
> 
>  COMMANDS
>  --------
> @@ -118,17 +130,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 +144,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
>  -------------------
> 

Rest looks fine.

Cheers,
Michael