git-remote-helpers.txt: clarify command <-> capability correspondences
In particular, document 'list for-push' separately from 'list', as the former needs only be supported for the push/export capabilities, and the latter only for fetch/import. Indeed, a hypothetically 'push-only' helper would only need to support the former, not the latter. Signed-off-by: Max Horn <max@quendi.de> Acked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Max Horn committed
Nov 28, 2012 at 00:03 UTC
754cb1aeba75008730d223d856a28986c3c12726
1 file changed
+16
-5
Documentation/git-remote-helpers.txt
+16
-5
@@ -216,6 +216,8 @@ Commands are given by the caller on the helper's standard input, one per line.
216
which marks them mandatory for git versions using the remote
217
helper to understand. Any unknown mandatory capability is a
218
fatal error.
219
++
220
+Support for this command is mandatory.
221
222
'list'::
223
Lists the refs, one per line, in the format "<value> <name>
@@ -225,9 +227,18 @@ Commands are given by the caller on the helper's standard input, one per line.
227
the name; unrecognized attributes are ignored. The list ends
228
with a blank line.
229
+
228
-If 'push' is supported this may be called as 'list for-push'
229
-to obtain the current refs prior to sending one or more 'push'
230
-commands to the helper.
230
+Supported if the helper has the "fetch" or "import" capability.
231
+
232
+'list for-push'::
233
+ Similar to 'list', except that it is used if and only if
234
+ the caller wants to the resulting ref list to prepare
235
+ push commands.
236
+ A helper supporting both push and fetch can use this
237
+ to distinguish for which operation the output of 'list'
238
+ is going to be used, possibly reducing the amount
239
+ of work that needs to be performed.
240
++
241
+Supported if the helper has the "push" or "export" capability.
242
243
'option' <name> <value>::
244
Sets the transport helper option <name> to <value>. Outputs a
@@ -306,7 +317,7 @@ sequence has to be buffered before starting to send data to fast-import
317
to prevent mixing of commands and fast-import responses on the helper's
318
stdin.
319
+
309
-Supported if the helper has the 'import' capability.
320
+Supported if the helper has the "import" capability.
321
322
'export'::
323
Instructs the remote helper that any subsequent input is
@@ -322,7 +333,7 @@ fast-export', which then will load/store a table of marks for
333
local objects. This can be used to implement for incremental
334
operations.
335
+
325
-Supported if the helper has the 'export' capability.
336
+Supported if the helper has the "export" capability.
337
338
'connect' <service>::
339
Connects to given service. Standard input and standard output