{"thread":{"id":"32212","subject":"[PATCH 2/6] Document missing remote helper capabilities","startedAt":"2012-11-27T17:44:33Z","lastAt":"2012-12-12T22:22:41Z","messageCount":16,"participants":["Max Horn","Junio C Hamano","Sverre Rabbelier","Felipe Contreras"],"isPatch":true,"patchVersion":1,"patchTotal":6},"messages":[{"id":"204007","messageId":"1354038279-76475-1-git-send-email-max@quendi.de","threadId":"32212","inReplyTo":null,"subject":"[PATCH 0/6] Improve remote helper documentation","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T17:44:33Z","receivedAt":"2012-11-27T17:44:33Z","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 Document invocation first, then input format\n Document missing remote helper capabilities\n Fix grammar\n Rearrange the description of remote helper capabilities\n Make clearer which commands must be supported for which capabilities\n Remove 'for-push' from ref list attributes list, link to subsections\n\n Documentation/git-remote-helpers.txt | 241 ++++++++++++++++++++---------------\n 1 file changed, 136 insertions(+), 105 deletions(-)\n\n-- \n1.8.0.393.gcc9701d\n"},{"id":"204006","messageId":"1354038279-76475-2-git-send-email-max@quendi.de","threadId":"32212","inReplyTo":"1354038279-76475-1-git-send-email-max@quendi.de","subject":"[PATCH 1/6] Document invocation first, then input format","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T17:44:34Z","receivedAt":"2012-11-27T17:44:34Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"In the distant past, the order was 'Invocation', 'Commands',\n'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":"204001","messageId":"1354038279-76475-3-git-send-email-max@quendi.de","threadId":"32212","inReplyTo":"1354038279-76475-1-git-send-email-max@quendi.de","subject":"[PATCH 2/6] Document missing remote helper capabilities","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T17:44:35Z","receivedAt":"2012-11-27T17:44:35Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"The 'export' and '(im|ex)port-marks' capabilities were not\ndocumented at all\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":"204005","messageId":"1354038279-76475-4-git-send-email-max@quendi.de","threadId":"32212","inReplyTo":"1354038279-76475-1-git-send-email-max@quendi.de","subject":"[PATCH 3/6] Fix grammar","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T17:44:36Z","receivedAt":"2012-11-27T17:44:36Z","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":"204002","messageId":"1354038279-76475-5-git-send-email-max@quendi.de","threadId":"32212","inReplyTo":"1354038279-76475-1-git-send-email-max@quendi.de","subject":"[PATCH 4/6] Rearrange the description of remote helper capabilities","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T17:44:37Z","receivedAt":"2012-11-27T17:44:37Z","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":"204003","messageId":"1354038279-76475-6-git-send-email-max@quendi.de","threadId":"32212","inReplyTo":"1354038279-76475-1-git-send-email-max@quendi.de","subject":"[PATCH 5/6] Make clearer which commands must be supported for which capabilities","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T17:44:38Z","receivedAt":"2012-11-27T17:44:38Z","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',\nas the former needs only be supported for the 'push' capability,\nand the latter only for fetch/import/export. In particular,\na hypothetically 'push-only' helper only needs 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":"204004","messageId":"1354038279-76475-7-git-send-email-max@quendi.de","threadId":"32212","inReplyTo":"1354038279-76475-1-git-send-email-max@quendi.de","subject":"[PATCH 6/6] Remove 'for-push' from ref list attributes list, link to subsections","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T17:44:39Z","receivedAt":"2012-11-27T17:44:39Z","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\nSigned-off-by: Max Horn \n---\n Documentation/git-remote-helpers.txt | 13 ++++++++-----\n 1 file changed, 8 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\nindex 023dcca..081cb06 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-- \n1.8.0.393.gcc9701d\n"},{"id":"204024","messageId":"7v8v9mn5k6.fsf@alter.siamese.dyndns.org","threadId":"32212","inReplyTo":"1354038279-76475-4-git-send-email-max@quendi.de","subject":"Re: [PATCH 3/6] Fix grammar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-11-27T20:39:53Z","receivedAt":"2012-11-27T20:39:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n> Subject: Re: [PATCH 3/6] Fix grammar\n\nPlease run \"git shortlog -200 --no-merges\" from the tip of your\ntopic branch before sending a series out, and see if you can\nimmediately identify what area each of your patches affects.\n\n> Signed-off-by: Max Horn \n> ---\n> Documentation/git-remote-helpers.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\n> index 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"},{"id":"204035","messageId":"5F2BC41E-6F77-44B8-B05E-8FB07E82EFA3@quendi.de","threadId":"32212","inReplyTo":"7v8v9mn5k6.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 3/6] Fix grammar","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-11-27T21:23:33Z","receivedAt":"2012-11-27T21:23:33Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"\nOn 27.11.2012, at 21:39, Junio C Hamano wrote:\n\n> Max Horn writes:\n> \n>> Subject: Re: [PATCH 3/6] Fix grammar\n> \n> Please run \"git shortlog -200 --no-merges\" from the tip of your\n> topic branch before sending a series out, and see if you can\n> immediately identify what area each of your patches affects.\n\nFirst off: I apologize for the inconvenience my stumbling causes :-(, and I'll try to learn and do better next time I send this or another series.\n\nIn this particular case, I am not 100% sure if I understood you correctly, i.e. what exactly you are trying to tell me. Is it (in a nutshell) that the subject lines of my commits suck, as they don't identify which area of code they touch? At least that's the thing I notice when looking at that shortlog... Bad, of course...\n\nIf this is indeed it, would a commit message like\n\n git-remote-helper.txt: minor grammar fix\n\nbe OK? If this is indeed it, I'll be happy to reroll and resubmit the series accordingly. If I am mistaken and something else / more is wrong, please be so kind and let me know, too.\n\n\nSorry once more and thank you very much for your feedback,\nMax\n\n> \n>> Signed-off-by: Max Horn \n>> ---\n>> Documentation/git-remote-helpers.txt | 6 +++---\n>> 1 file changed, 3 insertions(+), 3 deletions(-)\n>> \n>> diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt\n>> index 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> --\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":"204039","messageId":"7v4nkan1pv.fsf@alter.siamese.dyndns.org","threadId":"32212","inReplyTo":"5F2BC41E-6F77-44B8-B05E-8FB07E82EFA3@quendi.de","subject":"Re: [PATCH 3/6] Fix grammar","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-11-27T22:02:52Z","receivedAt":"2012-11-27T22:02:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n> If this is indeed it, would a commit message like\n>\n> git-remote-helper.txt: minor grammar fix\n\nPerfect. Thanks.\n"},{"id":"204581","messageId":"7v1uf1he6m.fsf@alter.siamese.dyndns.org","threadId":"32212","inReplyTo":"1354038279-76475-1-git-send-email-max@quendi.de","subject":"Re: [PATCH 0/6] Improve remote helper documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-07T19:09:37Z","receivedAt":"2012-12-07T19:09:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n> Various remote helper capabilities and commands were not\n> documented, in particular 'export', or documented in a misleading\n> way (e.g. 'for-push' was listed as a ref attribute understood by\n> git, which is not the case). This patch series changes that, and\n> also address some other things in the remote helper documentation\n> that I found jarring when reading through it.\n>\n> Note that the description of export and (im|ex)port-marks probably can be\n> improved, and I hope that somebody who knows more about them\n> than me and/or is better at writing documentation will do just that.\n> But I felt it was better to provide something than to do nothing\n> and only complain, as I did previously on this subject ;-).\n\nA second ping to people who have touched transport-helper.c,\nremote-testsvn.c, git-remote-testgit, and contrib/remote-helpers/ in\nthe past 18 months for comments. I've re-read the documentation\nupdates myself and didn't find anything majorly objectionable.\n\nExcept for a minor nit in 6/6; I think \"defined options\" should be\n\"defined attributes\".\n\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 the name; unrecognized attributes are ignored. The list ends\n with a blank line.\n +\n +See REF LIST ATTRIBUTES for a list of currently defined options.\n ++\n"},{"id":"204585","messageId":"CAGdFq_j-zXfCAWpwzxOYdzYgHovfqBj1xHJTy07y-bCvr-aqMQ@mail.gmail.com","threadId":"32212","inReplyTo":"7v1uf1he6m.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 0/6] Improve remote helper documentation","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2012-12-07T20:26:44Z","receivedAt":"2012-12-07T20:26:44Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"On Fri, Dec 7, 2012 at 11:09 AM, Junio C Hamano wrote:\n> A second ping to people who have touched transport-helper.c,\n> remote-testsvn.c, git-remote-testgit, and contrib/remote-helpers/ in\n> the past 18 months for comments. I've re-read the documentation\n> updates myself and didn't find anything majorly objectionable.\n\nFWIW:\n\nAcked-by: Sverre Rabbelier \n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"204590","messageId":"A6FF9929-74F8-4F2F-BA0B-1B1086D4E7F5@quendi.de","threadId":"32212","inReplyTo":"7v1uf1he6m.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 0/6] Improve remote helper documentation","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-12-07T21:41:00Z","receivedAt":"2012-12-07T21:41:00Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"\nOn 07.12.2012, at 20:09, Junio C Hamano wrote:\n\n> Max Horn writes:\n> \n>> Various remote helper capabilities and commands were not\n>> documented, in particular 'export', or documented in a misleading\n>> way (e.g. 'for-push' was listed as a ref attribute understood by\n>> git, which is not the case). This patch series changes that, and\n>> also address some other things in the remote helper documentation\n>> that I found jarring when reading through it.\n>> \n>> Note that the description of export and (im|ex)port-marks probably can be\n>> improved, and I hope that somebody who knows more about them\n>> than me and/or is better at writing documentation will do just that.\n>> But I felt it was better to provide something than to do nothing\n>> and only complain, as I did previously on this subject ;-).\n> \n> A second ping to people who have touched transport-helper.c,\n> remote-testsvn.c, git-remote-testgit, and contrib/remote-helpers/ in\n> the past 18 months for comments. I've re-read the documentation\n> updates myself and didn't find anything majorly objectionable.\n> \n> Except for a minor nit in 6/6; I think \"defined options\" should be\n> \"defined attributes\".\n> \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> the name; unrecognized attributes are ignored. The list ends\n> with a blank line.\n> +\n> +See REF LIST ATTRIBUTES for a list of currently defined options.\n> ++\n\nIndeed, my mistake. Dumb question since I am still not completely familiar with the procedures here: Would you just fix this yourself as you apply this, or is it better (or even required) that I reroll for this? (Of course if I ned to re-roll for other reasons, I'd fix this one as well).\n\n\nThanks,\nMax"},{"id":"204591","messageId":"7vehj1fs3c.fsf@alter.siamese.dyndns.org","threadId":"32212","inReplyTo":"A6FF9929-74F8-4F2F-BA0B-1B1086D4E7F5@quendi.de","subject":"Re: [PATCH 0/6] Improve remote helper documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-07T21:52:07Z","receivedAt":"2012-12-07T21:52:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n> On 07.12.2012, at 20:09, Junio C Hamano wrote:\n>\n>> Except for a minor nit in 6/6; I think \"defined options\" should be\n>> \"defined attributes\".\n>> \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>> the name; unrecognized attributes are ignored. The list ends\n>> with a blank line.\n>> +\n>> +See REF LIST ATTRIBUTES for a list of currently defined options.\n>> ++\n>\n> Indeed, my mistake. Dumb question since I am still not completely\n> familiar with the procedures here: Would you just fix this\n> yourself as you apply this, or is it better (or even required)\n> that I reroll for this? (Of course if I ned to re-roll for other\n> reasons, I'd fix this one as well).\n\nI didn't see any other issues myself, and I didn't see anybody\nraising issues on the series, either, so I could fix it up by\namending what is already queued, as long as you are OK with it.\n\nThanks.\n"},{"id":"204595","messageId":"A82E2605-13FC-4B9A-B9F4-7D416054588D@quendi.de","threadId":"32212","inReplyTo":"7vehj1fs3c.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 0/6] Improve remote helper documentation","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-12-07T22:38:45Z","receivedAt":"2012-12-07T22:38:45Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"\nOn 07.12.2012, at 22:52, Junio C Hamano wrote:\n\n> Max Horn writes:\n> \n>> On 07.12.2012, at 20:09, Junio C Hamano wrote:\n>> \n>>> Except for a minor nit in 6/6; I think \"defined options\" should be\n>>> \"defined attributes\".\n>>> \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>>> the name; unrecognized attributes are ignored. The list ends\n>>> with a blank line.\n>>> +\n>>> +See REF LIST ATTRIBUTES for a list of currently defined options.\n>>> ++\n>> \n>> Indeed, my mistake. Dumb question since I am still not completely\n>> familiar with the procedures here: Would you just fix this\n>> yourself as you apply this, or is it better (or even required)\n>> that I reroll for this? (Of course if I ned to re-roll for other\n>> reasons, I'd fix this one as well).\n> \n> I didn't see any other issues myself, and I didn't see anybody\n> raising issues on the series, either, so I could fix it up by\n> amending what is already queued, as long as you are OK with it.\n\nSure, I'd appreciate if you could make that fix.\n\nThanks,\nMax\n"},{"id":"204787","messageId":"CAMP44s3CgLip2fBi=k6iAdv+zXVFuf6fonxcyiYzMB4NMHf_gw@mail.gmail.com","threadId":"32212","inReplyTo":"7v1uf1he6m.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 0/6] Improve remote helper documentation","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2012-12-12T22:22:41Z","receivedAt":"2012-12-12T22:22:41Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Fri, Dec 7, 2012 at 1:09 PM, Junio C Hamano wrote:\n> Max Horn writes:\n>\n>> Various remote helper capabilities and commands were not\n>> documented, in particular 'export', or documented in a misleading\n>> way (e.g. 'for-push' was listed as a ref attribute understood by\n>> git, which is not the case). This patch series changes that, and\n>> also address some other things in the remote helper documentation\n>> that I found jarring when reading through it.\n>>\n>> Note that the description of export and (im|ex)port-marks probably can be\n>> improved, and I hope that somebody who knows more about them\n>> than me and/or is better at writing documentation will do just that.\n>> But I felt it was better to provide something than to do nothing\n>> and only complain, as I did previously on this subject ;-).\n>\n> A second ping to people who have touched transport-helper.c,\n> remote-testsvn.c, git-remote-testgit, and contrib/remote-helpers/ in\n> the past 18 months for comments. I've re-read the documentation\n> updates myself and didn't find anything majorly objectionable.\n>\n> Except for a minor nit in 6/6; I think \"defined options\" should be\n> \"defined attributes\".\n\nI think the wording in 1/6 can be improved. Other than that I don't\nhave any comments, what I'm familiar with looks good to me.\n\n-- \nFelipe Contreras\n"}]}