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@xxxxxxxxx> --- 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html