{"thread":{"id":"23257","subject":"[PATCH v3] Documentation/remote-helpers: Add invocation section","startedAt":"2010-03-30T19:18:44Z","lastAt":"2010-03-30T19:50:55Z","messageCount":3,"participants":["Ramkumar Ramachandra","Jonathan Nieder"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"138205","messageId":"f3271551003301218k4828c44id700b4865001baf9@mail.gmail.com","threadId":"23257","inReplyTo":null,"subject":"[PATCH v3] Documentation/remote-helpers: Add invocation section","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-30T19:18:44Z","receivedAt":"2010-03-30T19:18:44Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Add an invocation section to specify what the command line arguments\nmean. Also include a link to git-remote in the see also section.\n---\n What changed since v2: Explained the meaning of ambiguity, and\n improved overall clarity.\n\n Documentation/git-remote-helpers.txt |   17 +++++++++++++++++\n 1 files changed, 17 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt\nb/Documentation/git-remote-helpers.txt\nindex 2382fb4..4375678 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -38,6 +38,17 @@ Git comes with a \"curl\" family of remote helpers,\nspecifically\n 'git-remote-ftps'. They implement the capabilities 'fetch', 'option',\n and 'push'.\n\n+INVOCATION\n+----------\n+\n+Remote helper programs are invoked with one or (optionally) two\n+command line arguments. The first argument specifies a remote\n+repository as it would be in git; typically, it is either the name of\n+a configured remote or just a URL. The second argument, if present, is\n+a URL, and serves to resolve ambiguities that may arise when only the\n+first argument is specified (i.e. when a remote has more than one\n+configured URL).\n+\n COMMANDS\n --------\n\n@@ -206,6 +217,12 @@ OPTIONS\n \tmust not rely on this option being set before\n \tconnect request occurs.\n\n+\n+SEE ALSO\n+--------\n+linkgit:git-remote[1]\n+\n+\n Documentation\n -------------\n Documentation by Daniel Barkalow and Ilari Liusvaara\n-- \n1.7.0.3\n"},{"id":"138206","messageId":"f3271551003301228i241f681mfa55f4ef871010fb@mail.gmail.com","threadId":"23257","inReplyTo":"f3271551003301218k4828c44id700b4865001baf9@mail.gmail.com","subject":"Re: [PATCH v3] Documentation/remote-helpers: Add invocation section","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-30T19:28:22Z","receivedAt":"2010-03-30T19:28:22Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi,\n\nOops, I just noticed that I've been forgetting to sign off on the last\nfew patches.\n\nSigned-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n\n-- Ram\n"},{"id":"138207","messageId":"20100330195055.GA10977@progeny.tock","threadId":"23257","inReplyTo":"f3271551003301218k4828c44id700b4865001baf9@mail.gmail.com","subject":"Re: [PATCH v3] Documentation/remote-helpers: Add invocation section","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-03-30T19:50:55Z","receivedAt":"2010-03-30T19:50:55Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n\n> +INVOCATION\n> +----------\n> +\n> +Remote helper programs are invoked with one or (optionally) two\n> +command line arguments. The first argument specifies a remote\n> +repository as it would be in git; typically, it is either the name of\n> +a configured remote or just a URL.\n\nYes, better.\n\n> The second argument, if present, is\n> +a URL, and serves to resolve ambiguities that may arise when only the\n> +first argument is specified (i.e. when a remote has more than one\n> +configured URL).\n\nThis seems to suggest that the remote helper should pay attention\nprimarily to the first argument and then use the second argument to\nfigure out some detail.  But AFAICT that is not true.\n\nAs I understand it, there are two cases.  I will call them the\n“Subversion-like” (URL-based) and the “Perforce-like” (no URL) cases.\nSee [1] for an example of where I am getting this from, or see [2] for\nmore explanation of what I mean.\n\nA hypothetical ‘git remote-svn’ would not need to examine its first\nargument at all, unless it wants to use it to name a store of additional\nper-remote data.  From its perspective, the second argument is not to\ndisambiguate.  Instead, the second argument is all that matters.\n\nA hypothetical ‘git remote-p4’ might not understand URLs at all.\nIf so, it should error out if the first argument does not correspond to\na [remote \"foo\"] stanza or a second argument is supplied.\n\nRegards,\nJonathan\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/125374/focus=125410\n[2] Examples:\n\nIn the Subversion-like case, the remote vcs uses a URL to identify the\nrepository.  So the configuration might look like\n\n\t[remote \"upstream\"]\n\tvcs = svn\n\turl = http://svn.example.com/some/project\n\tsvn-fetch = branches/*:refs/remotes/upstream/*:\n\tsvn-fetch = trunk:refs/remotes/upstream/trunk\n\tsvn-fetch = tags/*:refs/tags/*\n\nor\n\n\t[remote \"upstream\"]\n\turl = svn://svn.example.com/some/project\n\tsvn-fetch = trunk:refs/remotes/upstream/master\n\nThere may be some cases in which this supposed URL should not actually be\na URL, as in:\n\n\t[remote \"upstream\"]\n\tvcs = svn\n\turl = /path/to/local/repo\n\tsvn-fetch = :refs/remotes/upstream/master\n\nand for this reason, the rule is that the URL can be an arbitrary string.\n\nIn the Perforce-like case, there is additional configuration required to\ndescribe a repository _anyway_, so there is no need for a URL.  The\nconfiguration looks like this:\n\n\t[remote \"upstream\"]\n\t\tvcs = p4\n\t[p4 \"origin\"]\n\t\tfind-server-command = ssh bunch of complicated options\n\t\trandom-p4-option = ...\n\t\trandom-other-p4-option = ...\n\n(or so I hear).  This case is quite weird in my opinion, but anyway,\nthere is no URL.\n"}]}