{"thread":{"id":"23132","subject":"[PATCH v3] Improve remote-helpers documentation","startedAt":"2010-03-22T03:37:05Z","lastAt":"2010-03-22T08:42:54Z","messageCount":2,"participants":["Ramkumar Ramachandra","Michael J Gruber"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"137508","messageId":"f3271551003212037u66e9680cm8677c80b25f4b3a6@mail.gmail.com","threadId":"23132","inReplyTo":null,"subject":"[PATCH v3] Improve remote-helpers documentation","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-22T03:37:05Z","receivedAt":"2010-03-22T03:37:05Z","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 |   39 +++++++++++++++++----------------\n 1 files changed, 20 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt\nb/Documentation/git-remote-helpers.txt\nindex 1b5f61a..b1f4e5d 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 main git\nwithout linking\n\n SYNOPSIS\n --------\n@@ -13,10 +13,22 @@ 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'. The curl helper essentially helps in moving around 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 it\n+especially useful when native interoperability with a foreign\n+versioning system is desired.\n\n COMMANDS\n --------\n@@ -118,17 +130,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 +144,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\n"},{"id":"137529","messageId":"4BA72D8E.5070508@drmicha.warpmail.net","threadId":"23132","inReplyTo":"f3271551003212037u66e9680cm8677c80b25f4b3a6@mail.gmail.com","subject":"Re: [PATCH v3] Improve remote-helpers documentation","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-03-22T08:42:54Z","receivedAt":"2010-03-22T08:42:54Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Ramkumar Ramachandra venit, vidit, dixit 22.03.2010 04:37:\n> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n> ---\n>  Documentation/git-remote-helpers.txt |   39 +++++++++++++++++----------------\n>  1 files changed, 20 insertions(+), 19 deletions(-)\n> \n> diff --git a/Documentation/git-remote-helpers.txt\n> b/Documentation/git-remote-helpers.txt\n> index 1b5f61a..b1f4e5d 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 main git\n> without linking\n\nBelow, you say that helpers help Git interact with remote repositories\n(which is correct). That should be matched by the short explanation\nabove. \"Without linking\" is a technical detail, so I suggest:\n\ngit-remote-helpers - Helper programs for interacting with remote\nrepositories\n\n> \n>  SYNOPSIS\n>  --------\n> @@ -13,10 +13,22 @@ 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\nIsn't it more the other way round? Git calls and interacts with the\nhelpers, and does not link in the helpers.\n\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 moving around 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 it\n> +especially useful when native interoperability with a foreign\n> +versioning system is desired.\n> \n>  COMMANDS\n>  --------\n> @@ -118,17 +130,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 +144,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\nRest looks fine.\n\nCheers,\nMichael\n"}]}