Re: [PATCH 1/2] Documentation/remote-helpers: Add invocation and see also sections

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

I know almost nothing about the transport machinery, so please take
anything I say with a grain of salt.

Ramkumar Ramachandra wrote:

> --- a/Documentation/git-remote-helpers.txt
> +++ b/Documentation/git-remote-helpers.txt
> @@ -38,6 +38,54 @@ Git comes with a "curl" family of remote helpers, specifically
>  'git-remote-ftps'. They implement the capabilities 'fetch', 'option',
>  and 'push'.
> 
> +INVOCATION
> +----------
> +
> +These programs can always be invoked as 'git remote-<transport>' by
> +the end user. However, the following are five situations in which
> +these programs are automatically invoked by git in decreasing order of
> +priority.

It took a moment for me to figure out what “decreasing order of priority”
means here.  Maybe it would be clearer to make the cases mutually
exclusive so it is not needed.

That is:

 These programs can be used directly as ‘git remote-<transport>’ by
 users and third-party scripts.  However, in the more usual case,
 they will be used transparently by the transport machinery (i.e., by
 commands such as git ls-remote, git send-pack, and git archive --remote).

 The “remote name” and URL passed to the remote helper depend on how
 the repository is specified to git.

> +1. URL using <transport>::<string> syntax is used directly on command
> +   line.
> ++
> +The helper is invoked with <transport>::<string> as the first argument
> +and <string> as the second argument.

 <transport>::<address>
 ~~~~~~~~~~~~~~~~~~~~~~
 A URL of the form <transport>::<address> can be used to name a
 repository on the git command line, with <address> an arbitrary string.

 The 'git remote-<transport>' helper will be invoked with the full
 <transport>::<address> URL as the first argument and <address> as the
 second argument.
 
> ++
> +<name> can only contain alphanumeric characters 0-9, A-Z and a-z.
> +
> +2. remote.<name>.url is unset, but remote.<name>.vcs is set to
> +   <transport>.
> ++
> +The helper is invoked with a single argument, <name>.
> +

 <nickname> with vcs set
 ~~~~~~~~~~~~~~~~~~~~~~~
 A remote nickname (see git-remote(1)) 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>.

 If the url variable is set, the helper will be invoked with <nickname>
 as the first argument and <address> as the second argument.
 Otherwise, the helper will be invoked with a single argument, <nickname>.

> +4. remote.<name>.url is set to a value using the
> +   <transport>://<rest-of-URL> syntax.
> ++
> +The helper is invoked with <name> as the first argument and
> +<helper>://<rest-of-URL> as the second argument.
> ++
> +<transport> cannot be equal to any of builtin protocols 'rsync',
> +'file', 'git', 'ssh', 'git+ssh' and 'ssh+git'
> +

 <nickname> with vcs unset
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 If the [remote "<nickname>"] configuration does not include a vcs
 setting, a remote helper can be specified by a url setting with a
 value of the form "<transport>://<rest-of-URL>".

 The ‘git remote-<transport>’ helper will be invoked with
 the <nickname> as first argument and <transport>://<rest-of-URL>
 as the second argument.

 Exception: the built-in 'rsync', 'file', 'git', 'ssh', 'git+ssh',
 and 'ssh+git' transports are not handled using remote helpers.

> +5. URL using <transport>://<rest-of-URL> syntax is used directly on
> +   command line.
> ++
> +The helper is invoked with two arguments, both equal to
> +<transport>://<rest-of-URL>.
> ++
> +<transport> cannot be equal to any of builtin protocols 'rsync',
> +'file', 'git', 'ssh', 'git+ssh' and 'ssh+git'
> +

 <transport>://<rest-of-URL>
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A URL of the form <transport>://<rest-of-URL> can be used to name a
 repository on the git command line, with <rest-of-URL> an arbitrary
 string.

 If 'transport' is not one of the built-in protocols listed above,
 the 'git remote-<transport>' helper will be invoked with two
 arguments, both equal to the full <transport>://<rest-of-URL>
 URL.

>  COMMANDS
>  --------
> 
> @@ -206,6 +254,10 @@ OPTIONS
>  	must not rely on this option being set before
>  	connect request occurs.
> 
> +SEE ALSO
> +--------
> +linkgit:git-config[1]

linkgit:git-remote[1], too.

HTH,
Jonathan