[PATCH v5] Documentation/remote-helpers: Add invocation section

[PATCH v5] Documentation/remote-helpers: Add invocation section

[Ramkumar Ramachandra]

Add an 'Invocation' section to specify what the command line arguments
mean. Also include a link to git-remote in the 'See Also' section.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 What changed: After Junio's review, invocation section is more detailed.

 Documentation/git-remote-helpers.txt |   48 +++++++++++++++++++++++++++++++++-
 1 files changed, 47 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-remote-helpers.txt
b/Documentation/git-remote-helpers.txt
index 2382fb4..b3b42ff 100644
--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/git-remote-helpers.txt
@@ -7,7 +7,7 @@ git-remote-helpers - Helper programs to interact with
remote repositories

 SYNOPSIS
 --------
-'git remote-<transport>' <remote>
+'git remote-<transport>' <repository> [<URL>]

 DESCRIPTION
 -----------
@@ -38,6 +38,48 @@ Git comes with a "curl" family of remote helpers,
specifically
 'git-remote-ftps'. They implement the capabilities 'fetch', 'option',
 and 'push'.

+INVOCATION
+----------
+
+Remote helper programs are invoked with one or (optionally) two
+command line arguments. The first argument specifies a remote
+repository as in git; typically, it is either the name of a configured
+remote or just a URL. The second argument specifies a URL; it may
+either be a URL recognized by git, or an arbitrary URL-like string
+recognized by the specific helper being invoked. When the remote
+specified in the first argument has more than one configured URL, it
+serves to resolve the ambiguity and pick one of the URLs. Depending on
+the helper, supplying the second argument can make the first argument
+redundant.
+
+When git encounters a URL of the form '<transport>://<address>', where
+<transport> is a protocol that it cannot handle natively, it
+implicitly invokes 'git remote-<transport>' with
+the full URL as the second argument. The first argument
+is either the same as the second, when called from directly from
+command line, or <name> corresponding to the configured remote's name.
+
+A URL of the form '<transport>::<address>' explicitly instructs git to
+invoke the corresponding helper with '<address>' as the second
+argument. '<transport>::<string>' is the first argument when the
+helper is invoked directly from the command line, or '<name>'
+corresponding to the configured remote's name.
+
+Another explicit invocation case arises when a configured remote
+includes the remote.<name>.vcs is set to <transport>, in which case
+the 'git remote-<transport>' is invoked with a single argument,
+<name>.
+
+
+<nickname> with vcs set
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A remote can be configured to use the
+'git remote-<transport>' helper by setting the vcs variable to
+<transport> in the [remote "<nickname>"] section of a configuration file.
+The url variable in such a section is optional and can be set to an
+arbitrary string <address>.
+
 COMMANDS
 --------

@@ -206,6 +248,10 @@ OPTIONS
 	must not rely on this option being set before
 	connect request occurs.

+SEE ALSO
+--------
+linkgit:git-remote[1]
+
 Documentation
 -------------
 Documentation by Daniel Barkalow and Ilari Liusvaara
-- 
1.7.0.3

Re: [PATCH v5] Documentation/remote-helpers: Add invocation section

[Ramkumar Ramachandra]

> +<nickname> with vcs set
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +A remote can be configured to use the
> +'git remote-<transport>' helper by setting the vcs variable to
> +<transport> in the [remote "<nickname>"] section of a configuration file.
> +The url variable in such a section is optional and can be set to an
> +arbitrary string <address>.

I'm sorry- this was sloppy. Plus, it doesn't apply to master or pu.
I'll send in another revision of the patch with this hunk removed
rebased on pu.

-- Ram