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

From: Ramkumar Ramachandra <artagnon@gmail.com>
Date: Mar 30, 2010, 19:17 UTC
Message-ID: <f3271551003301217h44c99d5bye4a614840661b05c@mail.gmail.com>
In-Reply-To: <20100330183748.GA10647@progeny.tock>

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