[PATCH v5] Improve remote-helpers documentation
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
Cosmetic change since v4: The capabilities fetch, option, push,
connect, and import are presented in a more elegant manner.
Documentation/git-remote-helpers.txt | 35 +++++++++++++++++++--------------
1 files changed, 20 insertions(+), 15 deletions(-)
diff --git a/Documentation/git-remote-helpers.txt
b/Documentation/git-remote-helpers.txt
index 1b5f61a..990d302 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
--------
@@ -119,16 +132,11 @@ CAPABILITIES
------------
'fetch'::
- This helper supports the 'fetch' command.
-
'option'::
- This helper supports the option command.
-
'push'::
- This helper supports the 'push' command.
-
+'connect'::
'import'::
- This helper supports the 'import' command.
+ This helper supports the corresponding command with the same name.
'refspec' 'spec'::
When using the import command, expect the source ref to have
@@ -140,9 +148,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
Ramkumar Ramachandra <artagnon@gmail.com>