Re: [PATCH v2 1/6] git-remote-helpers.txt: document invocation before input format

On 12.12.2012, at 23:14, Felipe Contreras wrote:

On Tue, Nov 27, 2012 at 5:03 PM, Max Horn [off-list ref] wrote:

quoted

index 5ce4cda..9a7e583 100644

--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/git-remote-helpers.txt

@@ -35,6 +35,37 @@ transport protocols, such as 'git-remote-http', 'git-remote-https',

'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities
'fetch', 'option', and 'push'.

+INVOCATION
+----------
+
+Remote helper programs are invoked with one or (optionally) two
+arguments. The first argument specifies a remote repository as in git;
+it is either the name of a configured remote or a URL. The second
+argument specifies a URL; it is usually of the form
+'<transport>://<address>', but any arbitrary string is possible.
+The 'GIT_DIR' environment variable is set up for the remote helper
+and can be used to determine where to store additional data or from
+which directory to invoke auxiliary git commands.
+
+When git encounters a URL of the form '<transport>://<address>', where
+'<transport>' is a protocol that it cannot handle natively, it
+automatically invokes 'git remote-<transport>' with the full URL as
+the second argument. If such a URL is encountered directly on the
+command line, the first argument is the same as the second, and if it
+is encountered in a configured remote, the first argument is the name
+of that remote.

Maybe it's worth mentioning that if the alias of the remote is not
specified, the URL is used instead.

Worth a thought yeah -- but beyond the scope of this patch: I merely moved this text around, but did not touch it otherwise.

quoted

+A URL of the form '<transport>::<address>' explicitly instructs git to
+invoke 'git remote-<transport>' with '<address>' as the second
+argument. If such a URL is encountered directly on the command line,
+the first argument is '<address>', and if it is encountered in a
+configured remote, the first argument is the name of that remote.
+
+Additionally, when a configured remote has 'remote.<name>.vcs' set to
+'<transport>', git explicitly invokes 'git remote-<transport>' with
+'<name>' as the first argument. If set, the second argument is
+'remote.<name>.url'; otherwise, the second argument is omitted.

I find all this text a bit confusing. First argument, second argument,
etc. Personally, I would describe everything in the terms of alias
(1st arg), and URL (2nd arg).

Yeah, I also thought about that, but as above, deliberately did not touch it here, but only moved it around. I'll be happy to revisit this on a future date, though.


Thanks for the feedback,
Max