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

[PATCH v3] 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.
---
 What changed since v2: Explained the meaning of ambiguity, and
 improved overall clarity.

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

diff --git a/Documentation/git-remote-helpers.txt
b/Documentation/git-remote-helpers.txt
index 2382fb4..4375678 100644
--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/git-remote-helpers.txt
@@ -38,6 +38,17 @@ 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
+command line arguments. The first argument specifies a remote
+repository as it would be in git; typically, it is either the name of
+a configured remote or just a URL. The second argument, if present, is
+a URL, and serves to resolve ambiguities that may arise when only the
+first argument is specified (i.e. when a remote has more than one
+configured URL).
+
 COMMANDS
 --------

@@ -206,6 +217,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 v3] Documentation/remote-helpers: Add invocation section

[Ramkumar Ramachandra]

Hi,

Oops, I just noticed that I've been forgetting to sign off on the last
few patches.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>

-- Ram

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

[Jonathan Nieder]

Ramkumar Ramachandra wrote:

> +INVOCATION
> +----------
> +
> +Remote helper programs are invoked with one or (optionally) two
> +command line arguments. The first argument specifies a remote
> +repository as it would be in git; typically, it is either the name of
> +a configured remote or just a URL.

Yes, better.

> The second argument, if present, is
> +a URL, and serves to resolve ambiguities that may arise when only the
> +first argument is specified (i.e. when a remote has more than one
> +configured URL).

This seems to suggest that the remote helper should pay attention
primarily to the first argument and then use the second argument to
figure out some detail.  But AFAICT that is not true.

As I understand it, there are two cases.  I will call them the
“Subversion-like” (URL-based) and the “Perforce-like” (no URL) cases.
See [1] for an example of where I am getting this from, or see [2] for
more explanation of what I mean.

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.

A hypothetical ‘git remote-p4’ might not understand URLs at all.
If so, it should error out if the first argument does not correspond to
a [remote "foo"] stanza or a second argument is supplied.

Regards,
Jonathan

[1] http://thread.gmane.org/gmane.comp.version-control.git/125374/focus=125410
[2] Examples:

In the Subversion-like case, the remote vcs uses a URL to identify the
repository.  So the configuration might look like

	[remote "upstream"]
	vcs = svn
	url = http://svn.example.com/some/project
	svn-fetch = branches/*:refs/remotes/upstream/*:
	svn-fetch = trunk:refs/remotes/upstream/trunk
	svn-fetch = tags/*:refs/tags/*

or

	[remote "upstream"]
	url = svn://svn.example.com/some/project
	svn-fetch = trunk:refs/remotes/upstream/master

There may be some cases in which this supposed URL should not actually be
a URL, as in:

	[remote "upstream"]
	vcs = svn
	url = /path/to/local/repo
	svn-fetch = :refs/remotes/upstream/master

and for this reason, the rule is that the URL can be an arbitrary string.

In the Perforce-like case, there is additional configuration required to
describe a repository _anyway_, so there is no need for a URL.  The
configuration looks like this:

	[remote "upstream"]
		vcs = p4
	[p4 "origin"]
		find-server-command = ssh bunch of complicated options
		random-p4-option = ...
		random-other-p4-option = ...

(or so I hear).  This case is quite weird in my opinion, but anyway,
there is no URL.