v2Documentation/remote-helpers: Add invocation section

Add an invocation section to specify what the command line arguments
mean. Also include a link to git-remote in the see also section.
---
 The first version contained too much information.
 Followed Daniel Barkalow's suggestion to strip it of caller information.

 Documentation/git-remote-helpers.txt |   16 ++++++++++++++++
 1 files changed, 16 insertions(+), 0 deletions(-)

Hi Ram,

Ramkumar Ramachandra wrote:

This last sentence (“ambiguities that may arise”) raises more questions than it answers in my opinion. Maybe it would make sense to say

 The first argument identifies a <repository> as it would be specified to
 git; typically, this is either a configured remote nickname or a URL.

 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.  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.

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

or something to that effect.

Jonathan

Hi Jonathan,

On Wed, Mar 31, 2010 at 12:07 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

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.

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

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.

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

Ramkumar Ramachandra wrote:

Not sure I understand. Are there restrictions on the content of remote->url[0]?

What I meant by "arbitrary string" is that it doesn’t have to have the form schema://path, it’s not restricted to a particular character set, it doesn’t have to avoid conflicting with meaningful URLs defined by other helpers, and so on. So it’s a resource locator but not very uniform.

This is probably not very relevant to the user, but it should be relevant to the remote helper writer, I think.

Jonathan

On Wed, Mar 31, 2010 at 12:47:09AM +0530, Ramkumar Ramachandra wrote:

Note that remote may have no URLs. Or the passed url may be like (pathological example):

'tls://srp-Ilari@[1067a6e3af81b5ea76d615280eee2bc3dd2e8079@tcp/ipv6~fe80::20e:a6ff:fe6f:2288%2]:7684/gitolite-admin'

Or it may be something even more exotic with absolutely no recognizable URL-like structure, say hypothetical git-remote-fd, which would have passed syntax like:

"3,4"

Which doesn't even resemble an URL.

-Ilari

Hi,

On Wed, Mar 31, 2010 at 1:20 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

Right. I'll try to reword this last part.

On Wed, Mar 31, 2010 at 1:40 AM, Ilari Liusvaara <ilari.liusvaara@elisanet.fi> wrote:

On Wed, Mar 31, 2010 at 1:29 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

Well, we're trying to document all these "urls" in urls.txt [1]. I should perhaps use the term "URL recognized by Git" and include a link to the urls page in the documentation?

[1] http://thread.gmane.org/gmane.comp.version-control.git/143499

Ramkumar Ramachandra wrote:

Hmm. urls.txt is not currently its own page; instead, it is included in git-clone(1) and so on. I hope to change that this weekend.

More to the point, wouldn’t "URL recognized by Git" mean a string like fd::3,4 rather than the 3,4 that is passed to ‘git remote-fd’?

Also worth keeping in mind: we want to support third-party helpers, too. So it is hard to have one centralized document that completely explains all possible URLs.

Jonathan

Hi,

On Wed, Mar 31, 2010 at 1:55 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

My thoughts exactly. The giturls(7) idea will have to be dropped. It looks like we have to post a patch for urls.txt to include some introductory text and turn it into giturls(1), a manpage in its own right. Then we have to remove references to urls.txt from all the documents and make them point to gituls(1). I suspect the whole thing will have to be done bit by bit, and go through several reviews. I can help out a bit, but I wait for you to write most of it first.

One very realistic problem: Ambiguity between general URLS, "URLS recognized by Git", and "arbitrary strings that perform the same function as URLS".

That falls under the <transport>::<address> category, but Ilari might very well come up with a totally new syntax for a remote helper he writes tomorrow.

Okay, I'll try to word it accordingly then. "URLS recognized by git, and arbitrary URL-like strings recognized by that specific remote helper program".

-- Ram