{"thread":{"id":"32216","subject":"[PATCH v2 1/6] git-remote-helpers.txt: document invocation before input format","startedAt":"2012-11-27T23:03:20Z","lastAt":"2012-12-12T23:15:37Z","messageCount":16,"participants":["Max Horn","Felipe Contreras","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":6},"messages":[{"id":"204045","messageId":"1354057407-83151-1-git-send-email-max@quendi.de","threadId":"32216","inReplyTo":null,"subject":"[PATCH v2 0/6] Improve remote helper documentation","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T23:03:20Z","receivedAt":"2012-11-27T23:03:20Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"Various remote helper capabilities and commands were not\ndocumented, in particular 'export', or documented in a misleading\nway (e.g. 'for-push' was listed as a ref attribute understood by\ngit, which is not the case). This patch series changes that, and\nalso address some other things in the remote helper documentation\nthat I found jarring when reading through it.\n\nNote that the description of export and (im|ex)port-marks probably can be\nimproved, and I hope that somebody who knows more about them\nthan me and/or is better at writing documentation will do just that.\nBut I felt it was better to provide something than to do nothing\nand only complain, as I did previously on this subject ;-).\n\nMax Horn (6):\n git-remote-helpers.txt: document invocation before input format\n git-remote-helpers.txt: document missing capabilities\n git-remote-helpers.txt: minor grammar fix\n git-remote-helpers.txt: rearrange description of capabilities\n git-remote-helpers.txt: clarify command <-> capability correspondences\n git-remote-helpers.txt: clarify options & ref list attributes\n\n Documentation/git-remote-helpers.txt | 245 ++++++++++++++++++++---------------\n 1 file changed, 140 insertions(+), 105 deletions(-)\n\n-- \n1.8.0.393.gcc9701d\n"},{"id":"204042","messageId":"1354057407-83151-2-git-send-email-max@quendi.de","threadId":"32216","inReplyTo":"1354057407-83151-1-git-send-email-max@quendi.de","subject":"[PATCH v2 1/6] git-remote-helpers.txt: document invocation before input format","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T23:03:21Z","receivedAt":"2012-11-27T23:03:21Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"In the distant past, the order things were documented was\n'Invocation', 'Commands', 'Capabilities', ...\n\nThen it was decided that before giving a list of Commands, there\nshould be an overall description of the 'Input format', which was\na wise decision. However, this description was put as the very\nfirst thing, with the rationale that any implementor would want\nto know that first.\n\nHowever, it seems an implementor would actually first need to\nknow how the remote helper will be invoked, so moving\n'Invocation' to the front again seems logical. Moreover, we now\ndon't switch from discussing the input format to the invocation\nstyle and then back to input related stuff.\n\nSigned-off-by: Max Horn \n---\n Documentation/git-remote-helpers.txt | 62 ++++++++++++++++++------------------\n 1 file changed, 31 insertions(+), 31 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\nindex 5ce4cda..9a7e583 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -35,6 +35,37 @@ transport protocols, such as 'git-remote-http', 'git-remote-https',\n 'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities\n 'fetch', 'option', and 'push'.\n \n+INVOCATION\n+----------\n+\n+Remote helper programs are invoked with one or (optionally) two\n+arguments. The first argument specifies a remote repository as in git;\n+it is either the name of a configured remote or a URL. The second\n+argument specifies a URL; it is usually of the form\n+'://
', but any arbitrary string is possible.\n+The 'GIT_DIR' environment variable is set up for the remote helper\n+and can be used to determine where to store additional data or from\n+which directory to invoke auxiliary git commands.\n+\n+When git encounters a URL of the form '://
', where\n+'' is a protocol that it cannot handle natively, it\n+automatically invokes 'git remote-' with the full URL as\n+the second argument. If such a URL is encountered directly on the\n+command line, the first argument is the same as the second, and if it\n+is encountered in a configured remote, the first argument is the name\n+of that remote.\n+\n+A URL of the form '::
' explicitly instructs git to\n+invoke 'git remote-' with '
' as the second\n+argument. If such a URL is encountered directly on the command line,\n+the first argument is '
', and if it is encountered in a\n+configured remote, the first argument is the name of that remote.\n+\n+Additionally, when a configured remote has 'remote..vcs' set to\n+'', git explicitly invokes 'git remote-' with\n+'' as the first argument. If set, the second argument is\n+'remote..url'; otherwise, the second argument is omitted.\n+\n INPUT FORMAT\n ------------\n \n@@ -173,37 +204,6 @@ advertised with this capability must cover all refs reported by\n the list command. If no 'refspec' capability is advertised,\n there is an implied `refspec *:*`.\n \n-INVOCATION\n-----------\n-\n-Remote helper programs are invoked with one or (optionally) two\n-arguments. The first argument specifies a remote repository as in git;\n-it is either the name of a configured remote or a URL. The second\n-argument specifies a URL; it is usually of the form\n-'://
', but any arbitrary string is possible.\n-The 'GIT_DIR' environment variable is set up for the remote helper\n-and can be used to determine where to store additional data or from\n-which directory to invoke auxiliary git commands.\n-\n-When git encounters a URL of the form '://
', where\n-'' is a protocol that it cannot handle natively, it\n-automatically invokes 'git remote-' with the full URL as\n-the second argument. If such a URL is encountered directly on the\n-command line, the first argument is the same as the second, and if it\n-is encountered in a configured remote, the first argument is the name\n-of that remote.\n-\n-A URL of the form '::
' explicitly instructs git to\n-invoke 'git remote-' with '
' as the second\n-argument. If such a URL is encountered directly on the command line,\n-the first argument is '
', and if it is encountered in a\n-configured remote, the first argument is the name of that remote.\n-\n-Additionally, when a configured remote has 'remote..vcs' set to\n-'', git explicitly invokes 'git remote-' with\n-'' as the first argument. If set, the second argument is\n-'remote..url'; otherwise, the second argument is omitted.\n-\n COMMANDS\n --------\n \n-- \n1.8.0.393.gcc9701d\n"},{"id":"204043","messageId":"1354057407-83151-3-git-send-email-max@quendi.de","threadId":"32216","inReplyTo":"1354057407-83151-1-git-send-email-max@quendi.de","subject":"[PATCH v2 2/6] git-remote-helpers.txt: document missing capabilities","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T23:03:22Z","receivedAt":"2012-11-27T23:03:22Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"Specifically, document the 'export' and '(im|ex)port-marks'\ncapabilities as well as the export command, which were\nundocumented (but in active use).\n\nSigned-off-by: Max Horn \n---\n Documentation/git-remote-helpers.txt | 45 +++++++++++++++++++++++++++++++++---\n 1 file changed, 42 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\nindex 9a7e583..db63541 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -106,6 +106,10 @@ to the `capabilities` command (see COMMANDS, below).\n \tFor listing remote refs and fetching the associated history to\n \tthe local object store.\n \n+'export'::\n+\tFor listing remote refs and pushing specified objects from a\n+\tfast-import stream to remote refs.\n+\n 'import'::\n \tFor listing remote refs and fetching the associated history as\n \ta fast-import stream.\n@@ -143,6 +147,16 @@ there is an implied `refspec *:*`.\n \tThis is to prevent mixing commands and fast-import responses on the\n \thelper's stdin.\n \n+'export-marks' ::\n+\tThis modifies the 'export' capability, instructing git to dump the\n+\tinternal marks table to when complete. For details,\n+\tread up on '--export-marks=' in linkgit:git-fast-export[1].\n+\n+'import-marks' ::\n+\tThis modifies the 'export' capability, instructing git to load the\n+\tmarks specified in before processing any input. For details,\n+\tread up on '--import-marks=' in linkgit:git-fast-export[1].\n+\n Capabilities for Pushing\n ~~~~~~~~~~~~~~~~~~~~~~~~\n 'connect'::\n@@ -158,9 +172,18 @@ Supported commands: 'connect'.\n +\n Supported commands: 'list for-push', 'push'.\n \n-If a helper advertises both 'connect' and 'push', git will use\n-'connect' if possible and fall back to 'push' if the helper requests\n-so when connecting (see the 'connect' command under COMMANDS).\n+'export'::\n+\tCan discover remote refs and push specified objects from a\n+\tfast-import stream to remote refs.\n++\n+Supported commands: 'list for-push', 'export'.\n+\n+If a helper advertises 'connect', git will use it if possible and\n+fall back to another capability if the helper requests so when\n+connecting (see the 'connect' command under COMMANDS).\n+When choosing between 'push' and 'export', git prefers 'push'.\n+Other frontends may have some other order of preference.\n+\n \n Capabilities for Fetching\n ~~~~~~~~~~~~~~~~~~~~~~~~~\n@@ -307,6 +330,22 @@ stdin.\n +\n Supported if the helper has the 'import' capability.\n \n+'export'::\n+\tInstructs the remote helper that any subsequent input is\n+\tpart of a fast-import stream (generated by 'git fast-export')\n+\tcontaining objects which should be pushed to the remote.\n++\n+Especially useful for interoperability with a foreign versioning\n+system.\n++\n+The 'export-marks' and 'import-marks' capabilities, if specified,\n+affect this command in so far as they are passed on to 'git\n+fast-export', which then will load/store a table of marks for\n+local objects. This can be used to implement for incremental\n+operations.\n++\n+Supported if the helper has the 'export' capability.\n+\n 'connect' ::\n \tConnects to given service. Standard input and standard output\n \tof helper are connected to specified service (git prefix is\n-- \n1.8.0.393.gcc9701d\n"},{"id":"204048","messageId":"1354057407-83151-4-git-send-email-max@quendi.de","threadId":"32216","inReplyTo":"1354057407-83151-1-git-send-email-max@quendi.de","subject":"[PATCH v2 3/6] git-remote-helpers.txt: minor grammar fix","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T23:03:23Z","receivedAt":"2012-11-27T23:03:23Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"\nSigned-off-by: Max Horn \n---\n Documentation/git-remote-helpers.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\nindex db63541..7eb43d7 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -235,9 +235,9 @@ Commands are given by the caller on the helper's standard input, one per line.\n 'capabilities'::\n \tLists the capabilities of the helper, one per line, ending\n \twith a blank line. Each capability may be preceded with '*',\n-\twhich marks them mandatory for git version using the remote\n-\thelper to understand (unknown mandatory capability is fatal\n-\terror).\n+\twhich marks them mandatory for git versions using the remote\n+\thelper to understand. Any unknown mandatory capability is a\n+\tfatal error.\n \n 'list'::\n \tLists the refs, one per line, in the format \" \n-- \n1.8.0.393.gcc9701d\n"},{"id":"204047","messageId":"1354057407-83151-5-git-send-email-max@quendi.de","threadId":"32216","inReplyTo":"1354057407-83151-1-git-send-email-max@quendi.de","subject":"[PATCH v2 4/6] git-remote-helpers.txt: rearrange description of capabilities","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T23:03:24Z","receivedAt":"2012-11-27T23:03:24Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"This also remove some duplication in the descriptions\n(e.g. refspec was explained twice with similar level of detail).\n\nSigned-off-by: Max Horn \n---\n Documentation/git-remote-helpers.txt | 134 +++++++++++++++--------------------\n 1 file changed, 56 insertions(+), 78 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\nindex 7eb43d7..7ac1461 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -88,81 +88,17 @@ Each remote helper is expected to support only a subset of commands.\n The operations a helper supports are declared to git in the response\n to the `capabilities` command (see COMMANDS, below).\n \n-'option'::\n-\tFor specifying settings like `verbosity` (how much output to\n-\twrite to stderr) and `depth` (how much history is wanted in the\n-\tcase of a shallow clone) that affect how other commands are\n-\tcarried out.\n-\n-'connect'::\n-\tFor fetching and pushing using git's native packfile protocol\n-\tthat requires a bidirectional, full-duplex connection.\n-\n-'push'::\n-\tFor listing remote refs and pushing specified objects from the\n-\tlocal object store to remote refs.\n-\n-'fetch'::\n-\tFor listing remote refs and fetching the associated history to\n-\tthe local object store.\n-\n-'export'::\n-\tFor listing remote refs and pushing specified objects from a\n-\tfast-import stream to remote refs.\n-\n-'import'::\n-\tFor listing remote refs and fetching the associated history as\n-\ta fast-import stream.\n-\n-'refspec' ::\n-\tThis modifies the 'import' capability, allowing the produced\n-\tfast-import stream to modify refs in a private namespace\n-\tinstead of writing to refs/heads or refs/remotes directly.\n-\tIt is recommended that all importers providing the 'import'\n-\tcapability use this.\n-+\n-A helper advertising the capability\n-`refspec refs/heads/*:refs/svn/origin/branches/*`\n-is saying that, when it is asked to `import refs/heads/topic`, the\n-stream it outputs will update the `refs/svn/origin/branches/topic`\n-ref.\n-+\n-This capability can be advertised multiple times. The first\n-applicable refspec takes precedence. The left-hand of refspecs\n-advertised with this capability must cover all refs reported by\n-the list command. If no 'refspec' capability is advertised,\n-there is an implied `refspec *:*`.\n-\n-'bidi-import'::\n-\tThe fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers\n-\tto retrieve information about blobs and trees that already exist in\n-\tfast-import's memory. This requires a channel from fast-import to the\n-\tremote-helper.\n-\tIf it is advertised in addition to \"import\", git establishes a pipe from\n-\tfast-import to the remote-helper's stdin.\n-\tIt follows that git and fast-import are both connected to the\n-\tremote-helper's stdin. Because git can send multiple commands to\n-\tthe remote-helper it is required that helpers that use 'bidi-import'\n-\tbuffer all 'import' commands of a batch before sending data to fast-import.\n-\tThis is to prevent mixing commands and fast-import responses on the\n-\thelper's stdin.\n-\n-'export-marks' ::\n-\tThis modifies the 'export' capability, instructing git to dump the\n-\tinternal marks table to when complete. For details,\n-\tread up on '--export-marks=' in linkgit:git-fast-export[1].\n-\n-'import-marks' ::\n-\tThis modifies the 'export' capability, instructing git to load the\n-\tmarks specified in before processing any input. For details,\n-\tread up on '--import-marks=' in linkgit:git-fast-export[1].\n+In the following, we list all defined capabilities and for\n+each we list which commands a helper with that capability\n+must provide.\n \n Capabilities for Pushing\n-~~~~~~~~~~~~~~~~~~~~~~~~\n+^^^^^^^^^^^^^^^^^^^^^^^^\n 'connect'::\n \tCan attempt to connect to 'git receive-pack' (for pushing),\n-\t'git upload-pack', etc for communication using the\n-\tpackfile protocol.\n+\t'git upload-pack', etc for communication using\n+\tgit's native packfile protocol. This\n+\trequires a bidirectional, full-duplex connection.\n +\n Supported commands: 'connect'.\n \n@@ -186,11 +122,12 @@ Other frontends may have some other order of preference.\n \n \n Capabilities for Fetching\n-~~~~~~~~~~~~~~~~~~~~~~~~~\n+^^^^^^^^^^^^^^^^^^^^^^^^^\n 'connect'::\n \tCan try to connect to 'git upload-pack' (for fetching),\n \t'git receive-pack', etc for communication using the\n-\tpackfile protocol.\n+\tgit's native packfile protocol. This\n+\trequires a bidirectional, full-duplex connection.\n +\n Supported commands: 'connect'.\n \n@@ -212,14 +149,27 @@ connecting (see the 'connect' command under COMMANDS).\n When choosing between 'fetch' and 'import', git prefers 'fetch'.\n Other frontends may have some other order of preference.\n \n+Miscellaneous capabilities\n+^^^^^^^^^^^^^^^^^^^^^^^^^^\n+\n+'option'::\n+\tFor specifying settings like `verbosity` (how much output to\n+\twrite to stderr) and `depth` (how much history is wanted in the\n+\tcase of a shallow clone) that affect how other commands are\n+\tcarried out.\n+\n 'refspec' ::\n-\tThis modifies the 'import' capability.\n+\tThis modifies the 'import' capability, allowing the produced\n+\tfast-import stream to modify refs in a private namespace\n+\tinstead of writing to refs/heads or refs/remotes directly.\n+\tIt is recommended that all importers providing the 'import'\n+\tcapability use this.\n +\n-A helper advertising\n+A helper advertising the capability\n `refspec refs/heads/*:refs/svn/origin/branches/*`\n-in its capabilities is saying that, when it handles\n-`import refs/heads/topic`, the stream it outputs will update the\n-`refs/svn/origin/branches/topic` ref.\n+is saying that, when it is asked to `import refs/heads/topic`, the\n+stream it outputs will update the `refs/svn/origin/branches/topic`\n+ref.\n +\n This capability can be advertised multiple times. The first\n applicable refspec takes precedence. The left-hand of refspecs\n@@ -227,6 +177,34 @@ advertised with this capability must cover all refs reported by\n the list command. If no 'refspec' capability is advertised,\n there is an implied `refspec *:*`.\n \n+'bidi-import'::\n+\tThis modifies the 'import' capability.\n+\tThe fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers\n+\tto retrieve information about blobs and trees that already exist in\n+\tfast-import's memory. This requires a channel from fast-import to the\n+\tremote-helper.\n+\tIf it is advertised in addition to \"import\", git establishes a pipe from\n+\tfast-import to the remote-helper's stdin.\n+\tIt follows that git and fast-import are both connected to the\n+\tremote-helper's stdin. Because git can send multiple commands to\n+\tthe remote-helper it is required that helpers that use 'bidi-import'\n+\tbuffer all 'import' commands of a batch before sending data to fast-import.\n+\tThis is to prevent mixing commands and fast-import responses on the\n+\thelper's stdin.\n+\n+'export-marks' ::\n+\tThis modifies the 'export' capability, instructing git to dump the\n+\tinternal marks table to when complete. For details,\n+\tread up on '--export-marks=' in linkgit:git-fast-export[1].\n+\n+'import-marks' ::\n+\tThis modifies the 'export' capability, instructing git to load the\n+\tmarks specified in before processing any input. For details,\n+\tread up on '--import-marks=' in linkgit:git-fast-export[1].\n+\n+\n+\n+\n COMMANDS\n --------\n \n-- \n1.8.0.393.gcc9701d\n"},{"id":"204044","messageId":"1354057407-83151-6-git-send-email-max@quendi.de","threadId":"32216","inReplyTo":"1354057407-83151-1-git-send-email-max@quendi.de","subject":"[PATCH v2 5/6] git-remote-helpers.txt: clarify command <-> capability correspondences","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T23:03:25Z","receivedAt":"2012-11-27T23:03:25Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"In particular, document 'list for-push' separately from 'list', as\nthe former needs only be supported for the push/export\ncapabilities, and the latter only for fetch/import. Indeed, a\nhypothetically 'push-only' helper would only need to support the\nformer, not the latter.\n\nSigned-off-by: Max Horn \n---\n Documentation/git-remote-helpers.txt | 21 ++++++++++++++++-----\n 1 file changed, 16 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\nindex 7ac1461..023dcca 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -216,6 +216,8 @@ Commands are given by the caller on the helper's standard input, one per line.\n \twhich marks them mandatory for git versions using the remote\n \thelper to understand. Any unknown mandatory capability is a\n \tfatal error.\n++\n+Support for this command is mandatory.\n \n 'list'::\n \tLists the refs, one per line, in the format \" \n@@ -225,9 +227,18 @@ Commands are given by the caller on the helper's standard input, one per line.\n \tthe name; unrecognized attributes are ignored. The list ends\n \twith a blank line.\n +\n-If 'push' is supported this may be called as 'list for-push'\n-to obtain the current refs prior to sending one or more 'push'\n-commands to the helper.\n+Supported if the helper has the \"fetch\" or \"import\" capability.\n+\n+'list for-push'::\n+\tSimilar to 'list', except that it is used if and only if\n+\tthe caller wants to the resulting ref list to prepare\n+\tpush commands.\n+\tA helper supporting both push and fetch can use this\n+\tto distinguish for which operation the output of 'list'\n+\tis going to be used, possibly reducing the amount\n+\tof work that needs to be performed.\n++\n+Supported if the helper has the \"push\" or \"export\" capability.\n \n 'option' ::\n \tSets the transport helper option to . Outputs a\n@@ -306,7 +317,7 @@ sequence has to be buffered before starting to send data to fast-import\n to prevent mixing of commands and fast-import responses on the helper's\n stdin.\n +\n-Supported if the helper has the 'import' capability.\n+Supported if the helper has the \"import\" capability.\n \n 'export'::\n \tInstructs the remote helper that any subsequent input is\n@@ -322,7 +333,7 @@ fast-export', which then will load/store a table of marks for\n local objects. This can be used to implement for incremental\n operations.\n +\n-Supported if the helper has the 'export' capability.\n+Supported if the helper has the \"export\" capability.\n \n 'connect' ::\n \tConnects to given service. Standard input and standard output\n-- \n1.8.0.393.gcc9701d\n"},{"id":"204049","messageId":"1354057407-83151-7-git-send-email-max@quendi.de","threadId":"32216","inReplyTo":"1354057407-83151-1-git-send-email-max@quendi.de","subject":"[PATCH v2 6/6] git-remote-helpers.txt: clarify options & ref list attributes","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T23:03:26Z","receivedAt":"2012-11-27T23:03:26Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"The documentation was misleading in that it gave the impression that\n'for-push' could be used as a ref attribute in the output of the\n'list' command. That is wrong.\n\nAlso, explicitly point out the connection between the commands\n'list' and 'options' on the one hand, and the sections\n'REF LIST ATTRIBUTES' and 'OPTIONS' on the other hand.\n\nSigned-off-by: Max Horn \n---\n Documentation/git-remote-helpers.txt | 17 ++++++++++++-----\n 1 file changed, 12 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\nindex 023dcca..e1df01d 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -227,6 +227,8 @@ Support for this command is mandatory.\n \tthe name; unrecognized attributes are ignored. The list ends\n \twith a blank line.\n +\n+See REF LIST ATTRIBUTES for a list of currently defined options.\n++\n Supported if the helper has the \"fetch\" or \"import\" capability.\n \n 'list for-push'::\n@@ -248,6 +250,8 @@ Supported if the helper has the \"push\" or \"export\" capability.\n \tfor it). Options should be set before other commands,\n \tand may influence the behavior of those commands.\n +\n+See OPTIONS for a list of currently defined options.\n++\n Supported if the helper has the \"option\" capability.\n \n 'fetch' ::\n@@ -256,7 +260,7 @@ Supported if the helper has the \"option\" capability.\n \tper line, terminated with a blank line.\n \tOutputs a single blank line when all fetch commands in the\n \tsame batch are complete. Only objects which were reported\n-\tin the ref list with a sha1 may be fetched this way.\n+\tin the output of 'list' with a sha1 may be fetched this way.\n +\n Optionally may output a 'lock ' line indicating a file under\n GIT_DIR/objects/pack which is keeping a pack until refs can be\n@@ -360,10 +364,9 @@ capabilities reported by the helper.\n REF LIST ATTRIBUTES\n -------------------\n \n-'for-push'::\n-\tThe caller wants to use the ref list to prepare push\n-\tcommands. A helper might chose to acquire the ref list by\n-\topening a different type of connection to the destination.\n+The 'list' command produces a list of refs in which each ref\n+may be followed by a list of attributes. The following ref list\n+attributes are defined.\n \n 'unchanged'::\n \tThis ref is unchanged since the last import or fetch, although\n@@ -371,6 +374,10 @@ REF LIST ATTRIBUTES\n \n OPTIONS\n -------\n+\n+The following options are defined and (under suitable circumstances)\n+set by git if the remote helper has the 'option' capability.\n+\n 'option verbosity' ::\n \tChanges the verbosity of messages displayed by the helper.\n \tA value of 0 for means that processes operate\n-- \n1.8.0.393.gcc9701d\n"},{"id":"204046","messageId":"1354057407-83151-8-git-send-email-max@quendi.de","threadId":"32216","inReplyTo":"1354057407-83151-1-git-send-email-max@quendi.de","subject":"[PATCH 6/6] git-remote-helpers.txt: clarify ref list attributes, link to subsections","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T23:03:27Z","receivedAt":"2012-11-27T23:03:27Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"The documentation was misleading in that it gave the impression that\n'for-push' could be used as a ref attribute in the output of the\n'list' command. That is wrong.\n\nAlso, explicitly point out the connection between the commands\n'list' and 'options' on the one hand, and the sections\n'REF LIST ATTRIBUTES' and 'OPTIONS' on the other hand.\n\nSigned-off-by: Max Horn \n---\n Documentation/git-remote-helpers.txt | 17 ++++++++++++-----\n 1 file changed, 12 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\nindex 023dcca..e1df01d 100644\n--- a/Documentation/git-remote-helpers.txt\n+++ b/Documentation/git-remote-helpers.txt\n@@ -227,6 +227,8 @@ Support for this command is mandatory.\n \tthe name; unrecognized attributes are ignored. The list ends\n \twith a blank line.\n +\n+See REF LIST ATTRIBUTES for a list of currently defined options.\n++\n Supported if the helper has the \"fetch\" or \"import\" capability.\n \n 'list for-push'::\n@@ -248,6 +250,8 @@ Supported if the helper has the \"push\" or \"export\" capability.\n \tfor it). Options should be set before other commands,\n \tand may influence the behavior of those commands.\n +\n+See OPTIONS for a list of currently defined options.\n++\n Supported if the helper has the \"option\" capability.\n \n 'fetch' ::\n@@ -256,7 +260,7 @@ Supported if the helper has the \"option\" capability.\n \tper line, terminated with a blank line.\n \tOutputs a single blank line when all fetch commands in the\n \tsame batch are complete. Only objects which were reported\n-\tin the ref list with a sha1 may be fetched this way.\n+\tin the output of 'list' with a sha1 may be fetched this way.\n +\n Optionally may output a 'lock ' line indicating a file under\n GIT_DIR/objects/pack which is keeping a pack until refs can be\n@@ -360,10 +364,9 @@ capabilities reported by the helper.\n REF LIST ATTRIBUTES\n -------------------\n \n-'for-push'::\n-\tThe caller wants to use the ref list to prepare push\n-\tcommands. A helper might chose to acquire the ref list by\n-\topening a different type of connection to the destination.\n+The 'list' command produces a list of refs in which each ref\n+may be followed by a list of attributes. The following ref list\n+attributes are defined.\n \n 'unchanged'::\n \tThis ref is unchanged since the last import or fetch, although\n@@ -371,6 +374,10 @@ REF LIST ATTRIBUTES\n \n OPTIONS\n -------\n+\n+The following options are defined and (under suitable circumstances)\n+set by git if the remote helper has the 'option' capability.\n+\n 'option verbosity' ::\n \tChanges the verbosity of messages displayed by the helper.\n \tA value of 0 for means that processes operate\n-- \n1.8.0.393.gcc9701d\n"},{"id":"204051","messageId":"67C20CB2-BFCC-483A-A564-D9978C792CD6@quendi.de","threadId":"32216","inReplyTo":"1354057407-83151-8-git-send-email-max@quendi.de","subject":"Re: [PATCH 6/6] git-remote-helpers.txt: clarify ref list attributes, link to subsections","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T23:06:34Z","receivedAt":"2012-11-27T23:06:34Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"Ouch. This one should *not* have been sent (the \"[PATCH v2 6/6]\" one is the correct one). Very sorry :(. I'll triple check next time.\nMax\n\nOn 28.11.2012, at 00:03, Max Horn wrote:\n\n> The documentation was misleading in that it gave the impression that\n> 'for-push' could be used as a ref attribute in the output of the\n> 'list' command. That is wrong.\n> \n> Also, explicitly point out the connection between the commands\n> 'list' and 'options' on the one hand, and the sections\n> 'REF LIST ATTRIBUTES' and 'OPTIONS' on the other hand.\n> \n> Signed-off-by: Max Horn \n> ---\n> Documentation/git-remote-helpers.txt | 17 ++++++++++++-----\n> 1 file changed, 12 insertions(+), 5 deletions(-)\n> \n> diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\n> index 023dcca..e1df01d 100644\n> --- a/Documentation/git-remote-helpers.txt\n> +++ b/Documentation/git-remote-helpers.txt\n> @@ -227,6 +227,8 @@ Support for this command is mandatory.\n> \tthe name; unrecognized attributes are ignored. The list ends\n> \twith a blank line.\n> +\n> +See REF LIST ATTRIBUTES for a list of currently defined options.\n> ++\n> Supported if the helper has the \"fetch\" or \"import\" capability.\n> \n> 'list for-push'::\n> @@ -248,6 +250,8 @@ Supported if the helper has the \"push\" or \"export\" capability.\n> \tfor it). Options should be set before other commands,\n> \tand may influence the behavior of those commands.\n> +\n> +See OPTIONS for a list of currently defined options.\n> ++\n> Supported if the helper has the \"option\" capability.\n> \n> 'fetch' ::\n> @@ -256,7 +260,7 @@ Supported if the helper has the \"option\" capability.\n> \tper line, terminated with a blank line.\n> \tOutputs a single blank line when all fetch commands in the\n> \tsame batch are complete. Only objects which were reported\n> -\tin the ref list with a sha1 may be fetched this way.\n> +\tin the output of 'list' with a sha1 may be fetched this way.\n> +\n> Optionally may output a 'lock ' line indicating a file under\n> GIT_DIR/objects/pack which is keeping a pack until refs can be\n> @@ -360,10 +364,9 @@ capabilities reported by the helper.\n> REF LIST ATTRIBUTES\n> -------------------\n> \n> -'for-push'::\n> -\tThe caller wants to use the ref list to prepare push\n> -\tcommands. A helper might chose to acquire the ref list by\n> -\topening a different type of connection to the destination.\n> +The 'list' command produces a list of refs in which each ref\n> +may be followed by a list of attributes. The following ref list\n> +attributes are defined.\n> \n> 'unchanged'::\n> \tThis ref is unchanged since the last import or fetch, although\n> @@ -371,6 +374,10 @@ REF LIST ATTRIBUTES\n> \n> OPTIONS\n> -------\n> +\n> +The following options are defined and (under suitable circumstances)\n> +set by git if the remote helper has the 'option' capability.\n> +\n> 'option verbosity' ::\n> \tChanges the verbosity of messages displayed by the helper.\n> \tA value of 0 for means that processes operate\n> -- \n> 1.8.0.393.gcc9701d\n> \n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n> \n"},{"id":"204785","messageId":"CAMP44s3vO9b4-XxqatEc2w3KJLqLGgyjPuKpQkAXHQwTJJEQTg@mail.gmail.com","threadId":"32216","inReplyTo":"1354057407-83151-2-git-send-email-max@quendi.de","subject":"Re: [PATCH v2 1/6] git-remote-helpers.txt: document invocation before input format","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-12-12T22:14:26Z","receivedAt":"2012-12-12T22:14:26Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Tue, Nov 27, 2012 at 5:03 PM, Max Horn wrote:\n\n> index 5ce4cda..9a7e583 100644\n> --- a/Documentation/git-remote-helpers.txt\n> +++ b/Documentation/git-remote-helpers.txt\n> @@ -35,6 +35,37 @@ transport protocols, such as 'git-remote-http', 'git-remote-https',\n> 'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities\n> 'fetch', 'option', and 'push'.\n>\n> +INVOCATION\n> +----------\n> +\n> +Remote helper programs are invoked with one or (optionally) two\n> +arguments. The first argument specifies a remote repository as in git;\n> +it is either the name of a configured remote or a URL. The second\n> +argument specifies a URL; it is usually of the form\n> +'://
', but any arbitrary string is possible.\n> +The 'GIT_DIR' environment variable is set up for the remote helper\n> +and can be used to determine where to store additional data or from\n> +which directory to invoke auxiliary git commands.\n> +\n> +When git encounters a URL of the form '://
', where\n> +'' is a protocol that it cannot handle natively, it\n> +automatically invokes 'git remote-' with the full URL as\n> +the second argument. If such a URL is encountered directly on the\n> +command line, the first argument is the same as the second, and if it\n> +is encountered in a configured remote, the first argument is the name\n> +of that remote.\n\nMaybe it's worth mentioning that if the alias of the remote is not\nspecified, the URL is used instead.\n\n> +A URL of the form '::
' explicitly instructs git to\n> +invoke 'git remote-' with '
' as the second\n> +argument. If such a URL is encountered directly on the command line,\n> +the first argument is '
', and if it is encountered in a\n> +configured remote, the first argument is the name of that remote.\n> +\n> +Additionally, when a configured remote has 'remote..vcs' set to\n> +'', git explicitly invokes 'git remote-' with\n> +'' as the first argument. If set, the second argument is\n> +'remote..url'; otherwise, the second argument is omitted.\n\nI find all this text a bit confusing. First argument, second argument,\netc. Personally, I would describe everything in the terms of alias\n(1st arg), and URL (2nd arg).\n\n-- \nFelipe Contreras\n"},{"id":"204795","messageId":"839EECE2-4459-4358-B7E8-5D64374A0540@quendi.de","threadId":"32216","inReplyTo":"CAMP44s3vO9b4-XxqatEc2w3KJLqLGgyjPuKpQkAXHQwTJJEQTg@mail.gmail.com","subject":"Re: [PATCH v2 1/6] git-remote-helpers.txt: document invocation before input format","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-12-12T22:58:54Z","receivedAt":"2012-12-12T22:58:54Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"\nOn 12.12.2012, at 23:14, Felipe Contreras wrote:\n\n> On Tue, Nov 27, 2012 at 5:03 PM, Max Horn wrote:\n> \n>> index 5ce4cda..9a7e583 100644\n>> --- a/Documentation/git-remote-helpers.txt\n>> +++ b/Documentation/git-remote-helpers.txt\n>> @@ -35,6 +35,37 @@ transport protocols, such as 'git-remote-http', 'git-remote-https',\n>> 'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities\n>> 'fetch', 'option', and 'push'.\n>> \n>> +INVOCATION\n>> +----------\n>> +\n>> +Remote helper programs are invoked with one or (optionally) two\n>> +arguments. The first argument specifies a remote repository as in git;\n>> +it is either the name of a configured remote or a URL. The second\n>> +argument specifies a URL; it is usually of the form\n>> +'://
', but any arbitrary string is possible.\n>> +The 'GIT_DIR' environment variable is set up for the remote helper\n>> +and can be used to determine where to store additional data or from\n>> +which directory to invoke auxiliary git commands.\n>> +\n>> +When git encounters a URL of the form '://
', where\n>> +'' is a protocol that it cannot handle natively, it\n>> +automatically invokes 'git remote-' with the full URL as\n>> +the second argument. If such a URL is encountered directly on the\n>> +command line, the first argument is the same as the second, and if it\n>> +is encountered in a configured remote, the first argument is the name\n>> +of that remote.\n> \n> Maybe it's worth mentioning that if the alias of the remote is not\n> specified, the URL is used instead.\n\nWorth a thought yeah -- but beyond the scope of this patch: I merely moved this text around, but did not touch it otherwise.\n\n> \n>> +A URL of the form '::
' explicitly instructs git to\n>> +invoke 'git remote-' with '
' as the second\n>> +argument. If such a URL is encountered directly on the command line,\n>> +the first argument is '
', and if it is encountered in a\n>> +configured remote, the first argument is the name of that remote.\n>> +\n>> +Additionally, when a configured remote has 'remote..vcs' set to\n>> +'', git explicitly invokes 'git remote-' with\n>> +'' as the first argument. If set, the second argument is\n>> +'remote..url'; otherwise, the second argument is omitted.\n> \n> I find all this text a bit confusing. First argument, second argument,\n> etc. Personally, I would describe everything in the terms of alias\n> (1st arg), and URL (2nd arg).\n\nYeah, I also thought about that, but as above, deliberately did not touch it here, but only moved it around. I'll be happy to revisit this on a future date, though.\n\n\nThanks for the feedback,\nMax"},{"id":"204797","messageId":"CAMP44s1xetknwdOT5EseuASQE_2WFP1e1-Ao2RWYeya+EJ9SfQ@mail.gmail.com","threadId":"32216","inReplyTo":"839EECE2-4459-4358-B7E8-5D64374A0540@quendi.de","subject":"Re: [PATCH v2 1/6] git-remote-helpers.txt: document invocation before input format","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-12-12T23:00:52Z","receivedAt":"2012-12-12T23:00:52Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Wed, Dec 12, 2012 at 4:58 PM, Max Horn wrote:\n>\n> On 12.12.2012, at 23:14, Felipe Contreras wrote:\n>\n>> On Tue, Nov 27, 2012 at 5:03 PM, Max Horn wrote:\n>>\n>>> index 5ce4cda..9a7e583 100644\n>>> --- a/Documentation/git-remote-helpers.txt\n>>> +++ b/Documentation/git-remote-helpers.txt\n>>> @@ -35,6 +35,37 @@ transport protocols, such as 'git-remote-http', 'git-remote-https',\n>>> 'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities\n>>> 'fetch', 'option', and 'push'.\n>>>\n>>> +INVOCATION\n>>> +----------\n>>> +\n>>> +Remote helper programs are invoked with one or (optionally) two\n>>> +arguments. The first argument specifies a remote repository as in git;\n>>> +it is either the name of a configured remote or a URL. The second\n>>> +argument specifies a URL; it is usually of the form\n>>> +'://
', but any arbitrary string is possible.\n>>> +The 'GIT_DIR' environment variable is set up for the remote helper\n>>> +and can be used to determine where to store additional data or from\n>>> +which directory to invoke auxiliary git commands.\n>>> +\n>>> +When git encounters a URL of the form '://
', where\n>>> +'' is a protocol that it cannot handle natively, it\n>>> +automatically invokes 'git remote-' with the full URL as\n>>> +the second argument. If such a URL is encountered directly on the\n>>> +command line, the first argument is the same as the second, and if it\n>>> +is encountered in a configured remote, the first argument is the name\n>>> +of that remote.\n>>\n>> Maybe it's worth mentioning that if the alias of the remote is not\n>> specified, the URL is used instead.\n>\n> Worth a thought yeah -- but beyond the scope of this patch: I merely moved this text around, but did not touch it otherwise.\n>\n>>\n>>> +A URL of the form '::
' explicitly instructs git to\n>>> +invoke 'git remote-' with '
' as the second\n>>> +argument. If such a URL is encountered directly on the command line,\n>>> +the first argument is '
', and if it is encountered in a\n>>> +configured remote, the first argument is the name of that remote.\n>>> +\n>>> +Additionally, when a configured remote has 'remote..vcs' set to\n>>> +'', git explicitly invokes 'git remote-' with\n>>> +'' as the first argument. If set, the second argument is\n>>> +'remote..url'; otherwise, the second argument is omitted.\n>>\n>> I find all this text a bit confusing. First argument, second argument,\n>> etc. Personally, I would describe everything in the terms of alias\n>> (1st arg), and URL (2nd arg).\n>\n> Yeah, I also thought about that, but as above, deliberately did not touch it here, but only moved it around. I'll be happy to revisit this on a future date, though.\n\nOh, in that case it's fine, but I would have named it \"move invocation\nbefore input format\", or something that has *move*, or *shuffle*.\n\n-- \nFelipe Contreras\n"},{"id":"204799","messageId":"7v62463mbd.fsf@alter.siamese.dyndns.org","threadId":"32216","inReplyTo":"839EECE2-4459-4358-B7E8-5D64374A0540@quendi.de","subject":"Re: [PATCH v2 1/6] git-remote-helpers.txt: document invocation before input format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-12T23:03:34Z","receivedAt":"2012-12-12T23:03:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n> Worth a thought yeah -- but beyond the scope of this patch: I\n> merely moved this text around, but did not touch it otherwise.\n> ...\n> Yeah, I also thought about that, but as above, deliberately did\n> not touch it here, but only moved it around. I'll be happy to\n> revisit this on a future date, though.\n\nThat sounds like a sensible approach. So what's been cooking on\n'next' is OK, it seems.\n\nAs this is merely a doc update, I may be tempted to merge it down to\nthe 'master' branch before the next -rc.\n\nThanks.\n"},{"id":"204800","messageId":"A0E9390A-58CE-4E3E-A1A6-2D5CDB62FE06@quendi.de","threadId":"32216","inReplyTo":"CAMP44s1xetknwdOT5EseuASQE_2WFP1e1-Ao2RWYeya+EJ9SfQ@mail.gmail.com","subject":"Re: [PATCH v2 1/6] git-remote-helpers.txt: document invocation before input format","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-12-12T23:05:35Z","receivedAt":"2012-12-12T23:05:35Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"\nOn 13.12.2012, at 00:00, Felipe Contreras wrote:\n[...]\n\n>>> \n>>> I find all this text a bit confusing. First argument, second argument,\n>>> etc. Personally, I would describe everything in the terms of alias\n>>> (1st arg), and URL (2nd arg).\n>> \n>> Yeah, I also thought about that, but as above, deliberately did not touch it here, but only moved it around. I'll be happy to revisit this on a future date, though.\n> \n> Oh, in that case it's fine, but I would have named it \"move invocation\n> before input format\", or something that has *move*, or *shuffle*.\n\nAgreed. It explicit says move in the body of the commit message, but not in the summary line.. That would be an improvement, I gueess. Junio, if you want, feel free to reword the summary line of the patch accordingly, e.g. changing it from\n\n git-remote-helpers.txt: document invocation before input format\n\nto something like\n\n git-remote-helpers.txt: move 'invocation' section before 'input format'\n\nOf course I can also re-roll, if that is necessary/preferred.\n\n\nCheers,\nMax"},{"id":"204803","messageId":"7vwqwm27az.fsf@alter.siamese.dyndns.org","threadId":"32216","inReplyTo":"A0E9390A-58CE-4E3E-A1A6-2D5CDB62FE06@quendi.de","subject":"Re: [PATCH v2 1/6] git-remote-helpers.txt: document invocation before input format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-12T23:13:08Z","receivedAt":"2012-12-12T23:13:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n> Of course I can also re-roll, if that is necessary/preferred.\n\nNo, you can't. The topic has been cooking in 'next' for some days\nnow already.\n"},{"id":"204805","messageId":"D4E7946A-85B6-4044-AC38-9F7B77D0BA5F@quendi.de","threadId":"32216","inReplyTo":"7vwqwm27az.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH v2 1/6] git-remote-helpers.txt: document invocation before input format","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-12-12T23:15:37Z","receivedAt":"2012-12-12T23:15:37Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"\nOn 13.12.2012, at 00:13, Junio C Hamano wrote:\n\n> Max Horn writes:\n> \n>> Of course I can also re-roll, if that is necessary/preferred.\n> \n> No, you can't. The topic has been cooking in 'next' for some days\n> now already.\n\nAh, right, I somehow missed that :-/. Well, I guess it's at most a tiny minor cleanup anyway and thus not important :-).\n\n\nCheers,\nMax"}]}