{"thread":{"id":"23139","subject":"[PATCH v4] Improve remote-helpers documentation","startedAt":"2010-03-22T13:04:21Z","lastAt":"2010-03-22T16:57:06Z","messageCount":3,"participants":["Ramkumar Ramachandra","Daniel Barkalow"],"isPatch":true,"patchVersion":4,"patchTotal":null},"messages":[{"id":"137547","messageId":"f3271551003220604v4c9fbb5ep3b7c69300567a275@mail.gmail.com","threadId":"23139","inReplyTo":null,"subject":"[PATCH v4] Improve remote-helpers documentation","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-22T13:04:21Z","receivedAt":"2010-03-22T13:04:21Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n---\n Documentation/git-remote-helpers.txt |   40 +++++++++++++++++----------------\n 1 files changed, 21 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt\nb/Documentation/git-remote-helpers.txt\nindex 1b5f61a..2d5aa8c 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -3,7 +3,7 @@ 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 remote repositories\n\n SYNOPSIS\n --------\n@@ -13,10 +13,23 @@ 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 are spawned as binaries by\n+the main git programs and interact using text streams, without\n+linking.\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'. The curl helper essentially helps in transporting native\n+git objects.\n+\n+As opposed to native git objects, remote helpers can also provide a\n+fast-import stream through the 'import' capability. This makes them\n+especially useful when native interoperability with a foreign\n+versioning system is desired.\n\n COMMANDS\n --------\n@@ -118,17 +131,9 @@ capabilities reported by the helper.\n CAPABILITIES\n ------------\n\n-'fetch'::\n-\tThis helper supports the 'fetch' command.\n-\n-'option'::\n-\tThis helper supports the option command.\n-\n-'push'::\n-\tThis helper supports the 'push' command.\n-\n-'import'::\n-\tThis helper supports the 'import' command.\n+The following capabilities indicate that the remote helper supports\n+the corresponding command with the same name: 'fetch', 'option',\n+'push', 'connect', and 'import'.\n\n 'refspec' 'spec'::\n \tWhen using the import command, expect the source ref to have\n@@ -140,9 +145,6 @@ CAPABILITIES\n \tall, it must cover all refs reported by the list command; if\n \tit is not used, it is effectively \"*:*\"\n\n-'connect'::\n-\tThis helper supports the 'connect' command.\n-\n REF LIST ATTRIBUTES\n -------------------\n\n-- \n1.7.0.2\n"},{"id":"137562","messageId":"alpine.LNX.2.00.1003221143250.14365@iabervon.org","threadId":"23139","inReplyTo":"f3271551003220604v4c9fbb5ep3b7c69300567a275@mail.gmail.com","subject":"Re: [PATCH v4] Improve remote-helpers documentation","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2010-03-22T16:32:31Z","receivedAt":"2010-03-22T16:32:31Z","isPatch":true,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"Looks good, other than an optional suggestion below. Incidentally, it's \noften helpful to describe the differences between earlier versions and v4 \nof the patch between the \"---\" and the diffstat; that part of the email \ndoesn't go into the commit, but can be seen by reviewers.\n\nOn Mon, 22 Mar 2010, Ramkumar Ramachandra wrote:\n\n> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n> ---\n>  Documentation/git-remote-helpers.txt |   40 +++++++++++++++++----------------\n>  1 files changed, 21 insertions(+), 19 deletions(-)\n> \n> diff --git a/Documentation/git-remote-helpers.txt\n> b/Documentation/git-remote-helpers.txt\n> index 1b5f61a..2d5aa8c 100644\n> --- a/Documentation/git-remote-helpers.txt\n> +++ b/Documentation/git-remote-helpers.txt\n> @@ -3,7 +3,7 @@ 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 remote repositories\n> \n>  SYNOPSIS\n>  --------\n> @@ -13,10 +13,23 @@ 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 are spawned as binaries by\n> +the main git programs and interact using text streams, without\n> +linking.\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'. The curl helper essentially helps in transporting native\n> +git objects.\n> +\n> +As opposed to native git objects, remote helpers can also provide a\n> +fast-import stream through the 'import' capability. This makes them\n> +especially useful when native interoperability with a foreign\n> +versioning system is desired.\n> \n>  COMMANDS\n>  --------\n> @@ -118,17 +131,9 @@ capabilities reported by the helper.\n>  CAPABILITIES\n>  ------------\n> \n> -'fetch'::\n> -\tThis helper supports the 'fetch' command.\n> -\n> -'option'::\n> -\tThis helper supports the option command.\n> -\n> -'push'::\n> -\tThis helper supports the 'push' command.\n> -\n> -'import'::\n> -\tThis helper supports the 'import' command.\n> +The following capabilities indicate that the remote helper supports\n> +the corresponding command with the same name: 'fetch', 'option',\n> +'push', 'connect', and 'import'.\n\nThis is, indeed, what I was suggesting, although I think it might be more \nreadable like:\n\n'fetch'::\n'option'::\n'push'::\n'connect'::\n'import'::\n\tThis helper supports the corresponding command with the same name.\n\nBut I'm fine with whichever format is most helpful for someone trying to \nread the document (that is, to you).\n\n\t-Daniel\n*This .sig left intentionally blank*\n"},{"id":"137567","messageId":"f3271551003220957q5db34547t69b425f708628dff@mail.gmail.com","threadId":"23139","inReplyTo":"alpine.LNX.2.00.1003221143250.14365@iabervon.org","subject":"Re: [PATCH v4] Improve remote-helpers documentation","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-22T16:57:06Z","receivedAt":"2010-03-22T16:57:06Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"> But I'm fine with whichever format is most helpful for someone trying to\n> read the document (that is, to you).\n\nYour format is indeed more elegant- I've incorporated this change in v5. Thanks.\n\n-- Ram\n"}]}