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

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

[Ramkumar Ramachandra]

Add Invocation section, and fill it with documentation by Ilari
Liusvaara. Add See Also section refering to the git-config page
because several configration options are referred to in the Invocation
section.
---
 Documentation/git-remote-helpers.txt |   51 +++++++++++++++++++++++++++++++++
 1 files changed, 51 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-remote-helpers.txt
b/Documentation/git-remote-helpers.txt
index 2382fb4..58533e5 100644
--- 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.
+
+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.
++
+<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>.
+
+3. remote.<name>.url is set to a value using the <transport>::<string>
+   syntax.
++
+The helper is invoked with <name> as the first argument and <string>
+as the second argument.
++
+<name> can only contain alphanumeric characters 0-9, A-Z and a-z.
+
+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'
+
+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'
+
 COMMANDS
 --------

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

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

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

[Jonathan Nieder]

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

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

[Ramkumar Ramachandra]

Hi,

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

Thanks for the fantastic corrections/ additions! I'll wait for Daniel
Barkalow's response to see whether or not to include this in the
manpage.

-- Ram

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

[Junio C Hamano]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> diff --git a/Documentation/git-remote-helpers.txt
> b/Documentation/git-remote-helpers.txt
> index 2382fb4..58533e5 100644
> --- 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.

That directly contradicts with what you wrote in the other [1/2] patch to
the same file, where you said "are normally not used directly by end
users".

Yes they _can_ be invoked, but unless you are in the business of debugging
them, you usually don't, so I don't see much point saying this.

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

>> +INVOCATION
>> +----------
>> +
>> +These programs can always be invoked as 'git remote-<transport>' by
>> +the end user.
>
> That directly contradicts with what you wrote in the other [1/2] patch to
> the same file, where you said "are normally not used directly by end
> users".

Scratch this comment; you are already up to v4.  Sorry.