{"thread":{"id":"23254","subject":"[PATCH v2] Documentation/remote-helpers: Add invocation section","startedAt":"2010-03-30T16:47:10Z","lastAt":"2010-03-30T20:42:44Z","messageCount":8,"participants":["Ramkumar Ramachandra","Jonathan Nieder","Ilari Liusvaara"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"138191","messageId":"f3271551003300947u4c7c2a83q13aaf786140bfa37@mail.gmail.com","threadId":"23254","inReplyTo":null,"subject":"[PATCH v2] Documentation/remote-helpers: Add invocation section","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-30T16:47:10Z","receivedAt":"2010-03-30T16:47:10Z","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 The first version contained too much information.\n Followed Daniel Barkalow's suggestion to strip it of caller information.\n\n Documentation/git-remote-helpers.txt | 16 ++++++++++++++++\n 1 files changed, 16 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt\nb/Documentation/git-remote-helpers.txt\nindex 2382fb4..e9c9d77 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -38,6 +38,16 @@ 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+arguments on the command line. The first argument specifies a remote\n+to use; typically, it is either the name of a remote in the\n+configuration or just a URL. The second argument is a URL, and serves\n+to resolve ambiguities that may arise when only the first argument is\n+specified.\n+\n COMMANDS\n --------\n\n@@ -206,6 +216,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":"138202","messageId":"20100330183748.GA10647@progeny.tock","threadId":"23254","inReplyTo":"f3271551003300947u4c7c2a83q13aaf786140bfa37@mail.gmail.com","subject":"Re: [PATCH v2] Documentation/remote-helpers: Add invocation section","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-03-30T18:37:48Z","receivedAt":"2010-03-30T18:37:48Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi Ram,\n\nRamkumar Ramachandra wrote:\n\n> +INVOCATION\n> +----------\n> +\n> +Remote helper programs are invoked with one or optionally two\n> +arguments on the command line. The first argument specifies a remote\n> +to use; typically, it is either the name of a remote in the\n> +configuration or just a URL. The second argument is a URL, and serves\n> +to resolve ambiguities that may arise when only the first argument is\n> +specified.\n\nThis last sentence (“ambiguities that may arise”) raises more questions\nthan it answers in my opinion. Maybe it would make sense to say\n\n The first argument identifies a as it would be specified to\n git; typically, this is either a configured remote nickname or a URL.\n\n The second argument, if present, is a URL for the remote repository.\n without such an argument, invocations for remotes with multiple\n URLs set would be ambiguous. If the second argument is missing,\n this remote nickname does not have a URL set and should probably have\n some transport-specific configuration set up separately.\n\n The URL in the second argument can be an arbitrary string. It is up\n to the remote helper to assign meaning to it.\n\nor something to that effect.\n\nJonathan\n"},{"id":"138203","messageId":"f3271551003301217h44c99d5bye4a614840661b05c@mail.gmail.com","threadId":"23254","inReplyTo":"20100330183748.GA10647@progeny.tock","subject":"Re: [PATCH v2] Documentation/remote-helpers: Add invocation section","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-30T19:17:09Z","receivedAt":"2010-03-30T19:17:09Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi Jonathan,\n\nOn Wed, Mar 31, 2010 at 12:07 AM, Jonathan Nieder wrote:\n>  The first argument identifies a as it would be specified to\n>  git; typically, this is either a configured remote nickname or a URL.\n\nFirst, \"identifies a as it would be specified to git\"\ndoesn't emphasize on the fact that the repository is remote- it\nemphasizes on repository, which isn't the desired result. Secondly,\nwhy use the term \"remote nickname\"? `git remote add` adds a \"remote\",\nnot a \"remote nickname\" and similarly.\n\n>  The second argument, if present, is a URL for the remote repository.\n>  without such an argument, invocations for remotes with multiple\n>  URLs set would be ambiguous.\n\nOkay. I've explained what the ambiguity means in v3 of the patch. Thanks :)\n\n> If the second argument is missing,\n>  this remote nickname does not have a URL set and should probably have\n>  some transport-specific configuration set up separately.\n\nI guess this didn't come out right. I'm dropping this line because I\ndon't think it's necessary. Including this line would mean that we'd\nalso need to explain other exceptional cases, like when the first\nargument is not really a configured remote etc.\n\n>  The URL in the second argument can be an arbitrary string.  It is up\n>  to the remote helper to assign meaning to it.\n\nI'm not sure this is correct. Here's an excerpt from remote.c\n\tif (argc > 2) {\n\t\turl = argv[2];\n\t} else {\n\t\turl = remote->url[0];\n\t}\nNotice how url is set to remote->url[0], in the `else` branch, where\nthe remote is an \"ordinary remote\" built by remote_get(). Even though\nurl may be any arbitrary string in the `if` branch, there'll be\nproblems when the program gets into the `else` branch transparently.\n\n-- Ram\n"},{"id":"138208","messageId":"20100330195910.GB10977@progeny.tock","threadId":"23254","inReplyTo":"f3271551003301217h44c99d5bye4a614840661b05c@mail.gmail.com","subject":"Re: [PATCH v2] Documentation/remote-helpers: Add invocation section","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-03-30T19:59:10Z","receivedAt":"2010-03-30T19:59:10Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n> On Wed, Mar 31, 2010 at 12:07 AM, Jonathan Nieder wrote:\n\n>>  The URL in the second argument can be an arbitrary string.  It is up\n>>  to the remote helper to assign meaning to it.\n>\n> I'm not sure this is correct. Here's an excerpt from remote.c\n> \tif (argc > 2) {\n> \t\turl = argv[2];\n> \t} else {\n> \t\turl = remote->url[0];\n> \t}\n> Notice how url is set to remote->url[0], in the `else` branch, where\n> the remote is an \"ordinary remote\" built by remote_get(). Even though\n> url may be any arbitrary string in the `if` branch, there'll be\n> problems when the program gets into the `else` branch transparently.\n\nNot sure I understand. Are there restrictions on the content of\nremote->url[0]?\n\nWhat I meant by \"arbitrary string\" is that it doesn’t have to have the\nform schema://path, it’s not restricted to a particular character set,\nit doesn’t have to avoid conflicting with meaningful URLs defined by\nother helpers, and so on. So it’s a resource locator but not very\nuniform.\n\nThis is probably not very relevant to the user, but it should be relevant\nto the remote helper writer, I think.\n\nJonathan\n"},{"id":"138211","messageId":"20100330201007.GA26121@LK-Perkele-V2.elisa-laajakaista.fi","threadId":"23254","inReplyTo":"f3271551003301217h44c99d5bye4a614840661b05c@mail.gmail.com","subject":"Re: [PATCH v2] Documentation/remote-helpers: Add invocation section","fromName":"Ilari Liusvaara","fromEmail":"ilari.liusvaara@elisanet.fi","sentAt":"2010-03-30T20:10:07Z","receivedAt":"2010-03-30T20:10:07Z","isPatch":true,"sender":{"key":"ilari.liusvaara@elisanet.fi","avatar":null},"body":"On Wed, Mar 31, 2010 at 12:47:09AM +0530, Ramkumar Ramachandra wrote:\n> \n> >  The URL in the second argument can be an arbitrary string.  It is up\n> >  to the remote helper to assign meaning to it.\n> \n> I'm not sure this is correct. Here's an excerpt from remote.c\n> \tif (argc > 2) {\n> \t\turl = argv[2];\n> \t} else {\n> \t\turl = remote->url[0];\n> \t}\n> Notice how url is set to remote->url[0], in the `else` branch, where\n> the remote is an \"ordinary remote\" built by remote_get(). Even though\n> url may be any arbitrary string in the `if` branch, there'll be\n> problems when the program gets into the `else` branch transparently.\n\nNote that remote may have no URLs. Or the passed url may be like \n(pathological example):\n\n'tls://srp-Ilari@[1067a6e3af81b5ea76d615280eee2bc3dd2e8079@tcp/ipv6~fe80::20e:a6ff:fe6f:2288%2]:7684/gitolite-admin'\n\nOr it may be something even more exotic with absolutely no recognizable\nURL-like structure, say hypothetical git-remote-fd, which would have\npassed syntax like:\n\n\"3,4\"\n\nWhich doesn't even resemble an URL.\n\n-Ilari\n"},{"id":"138212","messageId":"f3271551003301315i4bee002dm572e179819dbb1cd@mail.gmail.com","threadId":"23254","inReplyTo":"20100330201007.GA26121@LK-Perkele-V2.elisa-laajakaista.fi","subject":"Re: [PATCH v2] Documentation/remote-helpers: Add invocation section","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-30T20:15:30Z","receivedAt":"2010-03-30T20:15:30Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi,\n\nOn Wed, Mar 31, 2010 at 1:20 AM, Jonathan Nieder wrote:\n> A hypothetical ‘git remote-svn’ would not need to examine its first\n> argument at all, unless it wants to use it to name a store of additional\n> per-remote data.  From its perspective, the second argument is not to\n> disambiguate.  Instead, the second argument is all that matters.\n\nRight. I'll try to reword this last part.\n\nOn Wed, Mar 31, 2010 at 1:40 AM, Ilari Liusvaara\n wrote:\n> 'tls://srp-Ilari@[1067a6e3af81b5ea76d615280eee2bc3dd2e8079@tcp/ipv6~fe80::20e:a6ff:fe6f:2288%2]:7684/gitolite-admin'\n\nOn Wed, Mar 31, 2010 at 1:29 AM, Jonathan Nieder wrote:\n> What I meant by \"arbitrary string\" is that it doesn’t have to have the\n> form schema://path, it’s not restricted to a particular character set,\n> it doesn’t have to avoid conflicting with meaningful URLs defined by\n> other helpers, and so on.  So it’s a resource locator but not very\n> uniform.\n\nWell, we're trying to document all these \"urls\" in urls.txt [1]. I\nshould perhaps use the term \"URL recognized by Git\" and include a link\nto the urls page in the documentation?\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/143499\n"},{"id":"138213","messageId":"20100330202511.GC10977@progeny.tock","threadId":"23254","inReplyTo":"f3271551003301315i4bee002dm572e179819dbb1cd@mail.gmail.com","subject":"Re: [PATCH v2] Documentation/remote-helpers: Add invocation section","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-03-30T20:25:12Z","receivedAt":"2010-03-30T20:25:12Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n> On Wed, Mar 31, 2010 at 1:40 AM, Ilari Liusvaara wrote:\n>> 'tls://srp-Ilari@[1067a6e3af81b5ea76d615280eee2bc3dd2e8079@tcp/ipv6~fe80::20e:a6ff:fe6f:2288%2]:7684/gitolite-admin'\n> \n> On Wed, Mar 31, 2010 at 1:29 AM, Jonathan Nieder wrote:\n>> What I meant by \"arbitrary string\" is that it doesn’t have to have the\n>> form schema://path, it’s not restricted to a particular character set,\n>> it doesn’t have to avoid conflicting with meaningful URLs defined by\n>> other helpers, and so on.  So it’s a resource locator but not very\n>> uniform.\n>\n> Well, we're trying to document all these \"urls\" in urls.txt [1]. I\n> should perhaps use the term \"URL recognized by Git\" and include a link\n> to the urls page in the documentation?\n\nHmm. urls.txt is not currently its own page; instead, it is included\nin git-clone(1) and so on. I hope to change that this weekend.\n\nMore to the point, wouldn’t \"URL recognized by Git\" mean a string\nlike fd::3,4 rather than the 3,4 that is passed to ‘git remote-fd’?\n\nAlso worth keeping in mind: we want to support third-party helpers, too.\nSo it is hard to have one centralized document that completely explains\nall possible URLs.\n\nJonathan\n"},{"id":"138214","messageId":"f3271551003301342j2fcefee6l1e9c9fa2d012bc11@mail.gmail.com","threadId":"23254","inReplyTo":"20100330202511.GC10977@progeny.tock","subject":"Re: [PATCH v2] Documentation/remote-helpers: Add invocation section","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-30T20:42:44Z","receivedAt":"2010-03-30T20:42:44Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi,\n\nOn Wed, Mar 31, 2010 at 1:55 AM, Jonathan Nieder wrote:\n> Hmm.  urls.txt is not currently its own page; instead, it is included\n> in git-clone(1) and so on.  I hope to change that this weekend.\n\nMy thoughts exactly. The giturls(7) idea will have to be dropped. It\nlooks like we have to post a patch for urls.txt to include some\nintroductory text and turn it into giturls(1), a manpage in its own\nright. Then we have to remove references to urls.txt from all the\ndocuments and make them point to gituls(1). I suspect the whole thing\nwill have to be done bit by bit, and go through several reviews. I can\nhelp out a bit, but I wait for you to write most of it first.\n\nOne very realistic problem: Ambiguity between general URLS, \"URLS\nrecognized by Git\", and \"arbitrary strings that perform the same\nfunction as URLS\".\n\n> More to the point, wouldn’t \"URL recognized by Git\" mean a string\n> like fd::3,4 rather than the 3,4 that is passed to ‘git remote-fd’?\n\nThat falls under the ::
category, but Ilari might\nvery well come up with a totally new syntax for a remote helper he\nwrites tomorrow.\n\n> Also worth keeping in mind: we want to support third-party helpers, too.\n> So it is hard to have one centralized document that completely explains\n> all possible URLs.\n\nOkay, I'll try to word it accordingly then. \"URLS recognized by git,\nand arbitrary URL-like strings recognized by that specific remote\nhelper program\".\n\n-- Ram\n"}]}