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

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

[Ramkumar Ramachandra]

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(-)

diff --git a/Documentation/git-remote-helpers.txt
b/Documentation/git-remote-helpers.txt
index 2382fb4..e9c9d77 100644
--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/git-remote-helpers.txt
@@ -38,6 +38,16 @@ Git comes with a "curl" family of remote helpers,
specifically
 'git-remote-ftps'. They implement the capabilities 'fetch', 'option',
 and 'push'.

+INVOCATION
+----------
+
+Remote helper programs are invoked with one or optionally two
+arguments on the command line. The first argument specifies a remote
+to use; typically, it is either the name of a remote in the
+configuration or just a URL. The second argument is a URL, and serves
+to resolve ambiguities that may arise when only the first argument is
+specified.
+
 COMMANDS
 --------

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

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

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

[Jonathan Nieder]

Hi Ram,

Ramkumar Ramachandra wrote:

> +INVOCATION
> +----------
> +
> +Remote helper programs are invoked with one or optionally two
> +arguments on the command line. The first argument specifies a remote
> +to use; typically, it is either the name of a remote in the
> +configuration or just a URL. The second argument is a URL, and serves
> +to resolve ambiguities that may arise when only the first argument is
> +specified.

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

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

[Ramkumar Ramachandra]

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

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

[Jonathan Nieder]

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

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

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

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

[Ilari Liusvaara]

On Wed, Mar 31, 2010 at 12:47:09AM +0530, Ramkumar Ramachandra wrote:
> 
> >  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.

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

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

[Ramkumar Ramachandra]

Hi,

On Wed, Mar 31, 2010 at 1:20 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> A hypothetical ‘git remote-svn’ would not need to examine its first
> argument at all, unless it wants to use it to name a store of additional
> per-remote data.  From its perspective, the second argument is not to
> disambiguate.  Instead, the second argument is all that matters.

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:
> 'tls://srp-Ilari@[1067a6e3af81b5ea76d615280eee2bc3dd2e8079@tcp/ipv6~fe80::20e:a6ff:fe6f:2288%2]:7684/gitolite-admin'

On Wed, Mar 31, 2010 at 1:29 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> 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.

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

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

[Jonathan Nieder]

Ramkumar Ramachandra wrote:
> On Wed, Mar 31, 2010 at 1:40 AM, Ilari Liusvaara wrote:
>> 'tls://srp-Ilari@[1067a6e3af81b5ea76d615280eee2bc3dd2e8079@tcp/ipv6~fe80::20e:a6ff:fe6f:2288%2]:7684/gitolite-admin'
> 
> On Wed, Mar 31, 2010 at 1:29 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:
>> 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.
>
> 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?

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

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

[Ramkumar Ramachandra]

Hi,

On Wed, Mar 31, 2010 at 1:55 AM, Jonathan Nieder <jrnieder@gmail.com> 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.

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

> 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’?

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.

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

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