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

[Ramkumar Ramachandra <artagnon@gmail.com>]

Hi Jonathan,

On Wed, Mar 31, 2010 at 12:07 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:
>  The first argument identifies a <repository> as it would be specified to
>  git; typically, this is either a configured remote nickname or a URL.

First, "identifies a <repository> as it would be specified to git"
doesn't emphasize on the fact that the repository is remote- it
emphasizes on repository, which isn't the desired result. Secondly,
why use the term "remote nickname"? `git remote add` adds a "remote",
not a "remote nickname" and similarly.

>  The second argument, if present, is a URL for the remote repository.
>  without such an argument, invocations for remotes with multiple
>  URLs set would be ambiguous.

Okay. I've explained what the ambiguity means in v3 of the patch. Thanks :)

>  If the second argument is missing,
>  this remote nickname does not have a URL set and should probably have
>  some transport-specific configuration set up separately.

I guess this didn't come out right. I'm dropping this line because I
don't think it's necessary. Including this line would mean that we'd
also need to explain other exceptional cases, like when the first
argument is not really a configured remote etc.

>  The URL in the second argument can be an arbitrary string.  It is up
>  to the remote helper to assign meaning to it.

I'm not sure this is correct. Here's an excerpt from remote.c
	if (argc > 2) {
		url = argv[2];
	} else {
		url = remote->url[0];
	}
Notice how url is set to remote->url[0], in the `else` branch, where
the remote is an "ordinary remote" built by remote_get(). Even though
url may be any arbitrary string in the `if` branch, there'll be
problems when the program gets into the `else` branch transparently.

-- Ram