{"thread":{"id":"23123","subject":"[PATCH] Improve documentation for git-remote-helpers","startedAt":"2010-03-21T17:26:33Z","lastAt":"2010-03-22T15:40:04Z","messageCount":9,"participants":["Ramkumar Ramachandra","Daniel Barkalow","Sverre Rabbelier"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"137457","messageId":"f3271551003211026m376b86d6ga915f85a623eddfd@mail.gmail.com","threadId":"23123","inReplyTo":null,"subject":"[PATCH] Improve documentation for git-remote-helpers","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-21T17:26:33Z","receivedAt":"2010-03-21T17:26:33Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Signed-off-by: Ramkumar Ramachandra \n---\n Documentation/git-remote-helpers.txt | 22 ++++++++++++++++------\n 1 files changed, 16 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt\nb/Documentation/git-remote-helpers.txt\nindex 1b5f61a..54b36c8 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -3,7 +3,8 @@ git-remote-helpers(1)\n\n NAME\n ----\n-git-remote-helpers - Helper programs for interoperation with remote git\n+git-remote-helpers - Helper programs for interacting with main git\n+programs without linking to them\n\n SYNOPSIS\n --------\n@@ -13,10 +14,19 @@ DESCRIPTION\n -----------\n\n These programs are normally not used directly by end users, but are\n-invoked by various git programs that interact with remote repositories\n-when the repository they would operate on will be accessed using\n-transport code not linked into the main git binary. Various particular\n-helper programs will behave as documented here.\n+invoked by various git programs that interact with remote\n+repositories. For a program to qualify as a remote helper, it must\n+implement a subset of the capabilities documented here, and conform to\n+the remote helper protocol. Remote helpers interact with the main git\n+programs via text streams, and do not link to them.\n+\n+The curl helper is one such program. It is invoked via\n+'git-remote-http', 'git-remote-https', 'git-remote-ftp', or\n+'git-remote-ftps', and implments the capabilities 'fetch', 'option',\n+and 'push'.\n+\n+Remote helpers are often useful when native interoperability with a\n+foreign versioning system is desired.\n\n COMMANDS\n --------\n@@ -122,7 +132,7 @@ CAPABILITIES\n \tThis helper supports the 'fetch' command.\n\n 'option'::\n-\tThis helper supports the option command.\n+\tThis helper supports the 'option' command.\n\n 'push'::\n \tThis helper supports the 'push' command.\n-- \n1.7.0\n"},{"id":"137467","messageId":"f3271551003211121o48f502fp954b649ff4ca8f8b@mail.gmail.com","threadId":"23123","inReplyTo":"f3271551003211026m376b86d6ga915f85a623eddfd@mail.gmail.com","subject":"[PATCH] Improve documentation for git-remote-helpers","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-21T18:21:13Z","receivedAt":"2010-03-21T18:21:13Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Signed-off-by: Ramkumar Ramachandra \n---\n Documentation/git-remote-helpers.txt |   22 ++++++++++++++++------\n 1 files changed, 16 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt\nb/Documentation/git-remote-helpers.txt\nindex 1b5f61a..54b36c8 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -3,7 +3,8 @@ git-remote-helpers(1)\n\n NAME\n ----\n-git-remote-helpers - Helper programs for interoperation with remote git\n+git-remote-helpers - Helper programs for interacting with main git\n+programs without linking to them\n\n SYNOPSIS\n --------\n@@ -13,10 +14,19 @@ DESCRIPTION\n -----------\n\n These programs are normally not used directly by end users, but are\n-invoked by various git programs that interact with remote repositories\n-when the repository they would operate on will be accessed using\n-transport code not linked into the main git binary. Various particular\n-helper programs will behave as documented here.\n+invoked by various git programs that interact with remote\n+repositories.  For a program to qualify as a remote helper, it must\n+implement a subset of the capabilities documented here, and conform to\n+the remote helper protocol. Remote helpers interact with the main git\n+programs via text streams, and do not link to them.\n+\n+The curl helper is one such program. It is invoked via\n+'git-remote-http', 'git-remote-https', 'git-remote-ftp', or\n+'git-remote-ftps', and implments the capabilities 'fetch', 'option',\n+and 'push'.\n+\n+Remote helpers are often useful when native interoperability with a\n+foreign versioning system is desired.\n\n COMMANDS\n --------\n@@ -122,7 +132,7 @@ CAPABILITIES\n       This helper supports the 'fetch' command.\n\n 'option'::\n-       This helper supports the option command.\n+       This helper supports the 'option' command.\n\n 'push'::\n       This helper supports the 'push' command.\n--\n1.7.0\n"},{"id":"137492","messageId":"alpine.LNX.2.00.1003211907390.14365@iabervon.org","threadId":"23123","inReplyTo":"f3271551003211121o48f502fp954b649ff4ca8f8b@mail.gmail.com","subject":"Re: [PATCH] Improve documentation for git-remote-helpers","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2010-03-21T23:29:50Z","receivedAt":"2010-03-21T23:29:50Z","isPatch":true,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"I'd like to start by saying that it's good to see patches early, and also \nthat I think the best documentation comes from people who are new to \nsomething going back and forth with people who know it too well to know \nwhat needs to be said about it.\n\nOn Sun, 21 Mar 2010, Ramkumar Ramachandra wrote:\n\n> Signed-off-by: Ramkumar Ramachandra \n> ---\n>  Documentation/git-remote-helpers.txt |   22 ++++++++++++++++------\n>  1 files changed, 16 insertions(+), 6 deletions(-)\n> \n> diff --git a/Documentation/git-remote-helpers.txt\n> b/Documentation/git-remote-helpers.txt\n> index 1b5f61a..54b36c8 100644\n> --- a/Documentation/git-remote-helpers.txt\n> +++ b/Documentation/git-remote-helpers.txt\n> @@ -3,7 +3,8 @@ git-remote-helpers(1)\n> \n>  NAME\n>  ----\n> -git-remote-helpers - Helper programs for interoperation with remote git\n> +git-remote-helpers - Helper programs for interacting with main git\n> +programs without linking to them\n\nI think the name is supposed to fit on a single line. Adding more \nexplanation is good, but probably more appropriate below.\n\n>  SYNOPSIS\n>  --------\n> @@ -13,10 +14,19 @@ DESCRIPTION\n>  -----------\n> \n>  These programs are normally not used directly by end users, but are\n> -invoked by various git programs that interact with remote repositories\n> -when the repository they would operate on will be accessed using\n> -transport code not linked into the main git binary. Various particular\n> -helper programs will behave as documented here.\n> +invoked by various git programs that interact with remote\n> +repositories.  For a program to qualify as a remote helper, it must\n> +implement a subset of the capabilities documented here, and conform to\n> +the remote helper protocol. Remote helpers interact with the main git\n> +programs via text streams, and do not link to them.\n> +\n> +The curl helper is one such program. It is invoked via\n> +'git-remote-http', 'git-remote-https', 'git-remote-ftp', or\n> +'git-remote-ftps', and implments the capabilities 'fetch', 'option',\n> +and 'push'.\n> +\n> +Remote helpers are often useful when native interoperability with a\n> +foreign versioning system is desired.\n\nYou should probably make clear that a helper can provide a fast-import \nstream (a format which has been adopted by other version control systems) \ninstead of native git objects, if the helper is not exchanging git objects \nfrom the remote repository and trying to preserve their identities. The \ncurl helper is unusual in that it just moves git pbjects from place to \nplace. (That is, the curl helper uses 'fetch' and 'push', but other \nhelpers will mostly use 'import' and 'export'; the curl helper does need \nthe ability to use the git object database, but other helpers mostly \nwon't.)\n\n>  COMMANDS\n>  --------\n> @@ -122,7 +132,7 @@ CAPABILITIES\n>        This helper supports the 'fetch' command.\n> \n>  'option'::\n> -       This helper supports the option command.\n> +       This helper supports the 'option' command.\n\nYup. Or maybe these should be documented as a list of capabilities which \nmean that the helper supports the command with the same name, since that's \na common pattern, and documenting it as a pattern makes it obvious that, \nif we have a new 'export' command, and it needs a capability, it'll fit \nthe pattern.\n\n>  'push'::\n>        This helper supports the 'push' command.\n> --\n> 1.7.0\n> \n\n\t-Daniel\n*This .sig left intentionally blank*"},{"id":"137493","messageId":"fabb9a1e1003211635w27f0b22em73c7c6431c3998af@mail.gmail.com","threadId":"23123","inReplyTo":"alpine.LNX.2.00.1003211907390.14365@iabervon.org","subject":"Re: [PATCH] Improve documentation for git-remote-helpers","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-03-21T23:35:38Z","receivedAt":"2010-03-21T23:35:38Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\nOn Mon, Mar 22, 2010 at 00:29, Daniel Barkalow wrote:\n> Yup. Or maybe these should be documented as a list of capabilities which\n> mean that the helper supports the command with the same name, since that's\n> a common pattern, and documenting it as a pattern makes it obvious that,\n> if we have a new 'export' command, and it needs a capability, it'll fit\n> the pattern.\n\nSpeaking of which, I have uploaded a preliminary version of the export\ncapability to my github repository [0] since Ramkumar wanted to have a\nlook at it. Sadly I have not been able to test it yet, I wanted to\nwork on that today but instead spent hours on getting the first\nargument to the helper to be 'origin' (or whatever the user sets it to\nwith the --origin option), something that's been bothering me forever.\nNo documentation yet though, working on that ;).\n\n[0] http://github.com/SRabbelier/git\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"137495","messageId":"alpine.LNX.2.00.1003211951360.14365@iabervon.org","threadId":"23123","inReplyTo":"fabb9a1e1003211635w27f0b22em73c7c6431c3998af@mail.gmail.com","subject":"Re: [PATCH] Improve documentation for git-remote-helpers","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2010-03-22T00:06:36Z","receivedAt":"2010-03-22T00:06:36Z","isPatch":true,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"On Mon, 22 Mar 2010, Sverre Rabbelier wrote:\n\n> Heya,\n> \n> On Mon, Mar 22, 2010 at 00:29, Daniel Barkalow wrote:\n> > Yup. Or maybe these should be documented as a list of capabilities which\n> > mean that the helper supports the command with the same name, since that's\n> > a common pattern, and documenting it as a pattern makes it obvious that,\n> > if we have a new 'export' command, and it needs a capability, it'll fit\n> > the pattern.\n> \n> Speaking of which, I have uploaded a preliminary version of the export\n> capability to my github repository [0] since Ramkumar wanted to have a\n> look at it. Sadly I have not been able to test it yet, I wanted to\n> work on that today but instead spent hours on getting the first\n> argument to the helper to be 'origin' (or whatever the user sets it to\n> with the --origin option), something that's been bothering me forever.\n> No documentation yet though, working on that ;).\n> \n> [0] http://github.com/SRabbelier/git\n\nLooks generally right, but I think you need to do \n\"finish_command(&exporter);\" first, and actually get some feedback from \nthe helper. I think the right thing is actually to put the output of the \nhelper into fast-import again, and have that give one of three \nconclusions:\n\n - We tried to send sha1 A to the foreign system, and it rejected us \n entirely.\n - We tried to send sha1 A to the foreign system, and reimporting what it \n put in for us actually gives us sha1 A, so the transformation is \n lossless.\n - We tried to send sha1 A to the foreign system, but reimporting what it\n put in for us gives us sha1 B instead. This means B is as close to a \n replacement for A as we can get in this case, and the git core should \n know about the situation (although, for now, it doesn't have anything \n to do about it).\n\nAt the least, in the third case, we should update any tracking branches to \nmatch what the foreign system now contains, not to match what we tried to \nput there.\n\nBut even without considering the third case (IIRC, hg and git can \ninteroperate losslessly), you need to get feedback in some way if the \nremote entirely rejected us.\n\n\t-Daniel\n*This .sig left intentionally blank*\n"},{"id":"137507","messageId":"f3271551003212004r4ac7db34vad5b23f5d930476d@mail.gmail.com","threadId":"23123","inReplyTo":"alpine.LNX.2.00.1003211907390.14365@iabervon.org","subject":"Re: [PATCH] Improve documentation for git-remote-helpers","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-22T03:04:07Z","receivedAt":"2010-03-22T03:04:07Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"> I'd like to start by saying that it's good to see patches early, and also\n> that I think the best documentation comes from people who are new to\n> something going back and forth with people who know it too well to know\n> what needs to be said about it.\n\nThanks :) I just posted a second revision of the patch incorporating\nyour suggestions.\n\n> Yup. Or maybe these should be documented as a list of capabilities which\n> mean that the helper supports the command with the same name, since that's\n> a common pattern, and documenting it as a pattern makes it obvious that,\n> if we have a new 'export' command, and it needs a capability, it'll fit\n> the pattern.\n\nEvery capability doesn't necessarily have a corresponding command with\nthe same name, and vice-versa (see refspec spec?). Besides, I think\nit's necessary for the manpage to have a list of capabilities listed\nin one place. I'll think about a better format when we get more\ncapabilities/ commands.\n\n-- Ram\n"},{"id":"137509","messageId":"f3271551003212038i4239a852g9f9350cb1c93f8db@mail.gmail.com","threadId":"23123","inReplyTo":"f3271551003212004r4ac7db34vad5b23f5d930476d@mail.gmail.com","subject":"Re: [PATCH] Improve documentation for git-remote-helpers","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-22T03:38:31Z","receivedAt":"2010-03-22T03:38:31Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"> Every capability doesn't necessarily have a corresponding command with\n> the same name, and vice-versa (see refspec spec?). Besides, I think\n> it's necessary for the manpage to have a list of capabilities listed\n> in one place. I'll think about a better format when we get more\n> capabilities/ commands.\n\nI think I might have misunderstood what you said. So, I've posted a\nthird revision of the patch- is it the desired result?\n\n-- Ram\n"},{"id":"137523","messageId":"f3271551003220028w79d2f1b4q5a47ca8d21515288@mail.gmail.com","threadId":"23123","inReplyTo":"fabb9a1e1003211635w27f0b22em73c7c6431c3998af@mail.gmail.com","subject":"Re: [PATCH] Improve documentation for git-remote-helpers","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-22T07:28:05Z","receivedAt":"2010-03-22T07:28:05Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"> Speaking of which, I have uploaded a preliminary version of the export\n> capability to my github repository [0] since Ramkumar wanted to have a\n> look at it. Sadly I have not been able to test it yet, I wanted to\n> work on that today but instead spent hours on getting the first\n> argument to the helper to be 'origin' (or whatever the user sets it to\n> with the --origin option), something that's been bothering me forever.\n> No documentation yet though, working on that ;).\n\nThanks! I'll look at it in the evening.\n\n-- Ram\n"},{"id":"137558","messageId":"fabb9a1e1003220840q5b9b791ft83c8fd4793b83be2@mail.gmail.com","threadId":"23123","inReplyTo":"alpine.LNX.2.00.1003211951360.14365@iabervon.org","subject":"Re: [PATCH] Improve documentation for git-remote-helpers","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-03-22T15:40:04Z","receivedAt":"2010-03-22T15:40:04Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\nOn Mon, Mar 22, 2010 at 01:06, Daniel Barkalow wrote:\n> Looks generally right, but I think you need to do\n> \"finish_command(&exporter);\" first, and actually get some feedback from\n> the helper. I think the right thing is actually to put the output of the\n> helper into fast-import again, and have that give one of three\n> conclusions:\n\nI'm not sure that makes sense (at least to me). I think you are right\nin that we need to collect output from the helper, but I don't see any\nadded value in feeding that into fast-import. I think we should rather\nread from the helper after we finish exporting to figure out what\nhappened. The different cases you described are I think indeed what we\nshould look for.\n\n-- \nCheers,\n\nSverre Rabbelier\n"}]}