Documentation/remote-helpers: explain capabilities first
The current remote helper documentation is from the perspective of git, so to speak: it presents a full menu of commands for a person invoking a remote helper to choose from. In practice, that's less useful than it could be, since the daunted novice remote-helper author probably just wanted a list of commands needs to implement to get started. So preface the command list with an overview of each capability, its purpose, and what commands it requires. As a side effect, this makes it a little clearer that git doesn't choose arbitrary commands to run, even if the remote helper advertises all capabilities --- instead, there are well defined command sequences for various tasks. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Nieder committed
Aug 29, 2011 at 22:56 UTC
b4fc8d6ac638723e4f4452752f8fb41efe1ec356
1 file changed
+129
-30
Documentation/git-remote-helpers.txt
+129
-30
@@ -24,22 +24,141 @@ output. Because a remote helper runs as an independent process from
24
git, there is no need to re-link git to add a new helper, nor any
25
need to link the helper with the implementation of git.
26
27
-Every helper must support the "capabilities" command, which git will
28
-use to determine what other commands the helper will accept. Other
29
-commands generally concern facilities like discovering and updating
30
-remote refs, transporting objects between the object database and
31
-the remote repository, and updating the local object store.
32
-
33
-Helpers supporting the 'fetch' capability can discover refs from the
34
-remote repository and transfer objects reachable from those refs to
35
-the local object store. Helpers supporting the 'push' capability can
36
-transfer local objects to the remote repository and update remote refs.
27
+Every helper must support the "capabilities" command, which git
28
+uses to determine what other commands the helper will accept. Those
29
+other commands can be used to discover and update remote refs,
30
+transport objects between the object database and the remote repository,
31
+and update the local object store.
32
33
Git comes with a "curl" family of remote helpers, that handle various
34
transport protocols, such as 'git-remote-http', 'git-remote-https',
35
'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities
36
'fetch', 'option', and 'push'.
37
38
+INPUT FORMAT
39
+------------
40
+
41
+Git sends the remote helper a list of commands on standard input, one
42
+per line. The first command is always the 'capabilities' command, in
43
+response to which the remote helper must print a list of the
44
+capabilities it supports (see below) followed by a blank line. The
45
+response to the capabilities command determines what commands Git uses
46
+in the remainder of the command stream.
47
+
48
+The command stream is terminated by a blank line. In some cases
49
+(indicated in the documentation of the relevant commands), this blank
50
+line is followed by a payload in some other protocol (e.g., the pack
51
+protocol), while in others it indicates the end of input.
52
+
53
+Capabilities
54
+~~~~~~~~~~~~
55
+
56
+Each remote helper is expected to support only a subset of commands.
57
+The operations a helper supports are declared to git in the response
58
+to the `capabilities` command (see COMMANDS, below).
59
+
60
+'option'::
61
+ For specifying settings like `verbosity` (how much output to
62
+ write to stderr) and `depth` (how much history is wanted in the
63
+ case of a shallow clone) that affect how other commands are
64
+ carried out.
65
+
66
+'connect'::
67
+ For fetching and pushing using git's native packfile protocol
68
+ that requires a bidirectional, full-duplex connection.
69
+
70
+'push'::
71
+ For listing remote refs and pushing specified objects from the
72
+ local object store to remote refs.
73
+
74
+'fetch'::
75
+ For listing remote refs and fetching the associated history to
76
+ the local object store.
77
+
78
+'import'::
79
+ For listing remote refs and fetching the associated history as
80
+ a fast-import stream.
81
+
82
+'refspec' <refspec>::
83
+ This modifies the 'import' capability, allowing the produced
84
+ fast-import stream to modify refs in a private namespace
85
+ instead of writing to refs/heads or refs/remotes directly.
86
+ It is recommended that all importers providing the 'import'
87
+ capability use this.
88
++
89
+A helper advertising the capability
90
+`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}`
91
+is saying that, when it is asked to `import refs/heads/topic`, the
92
+stream it outputs will update the `refs/svn/origin/branches/topic`
93
+ref.
94
++
95
+This capability can be advertised multiple times. The first
96
+applicable refspec takes precedence. The left-hand of refspecs
97
+advertised with this capability must cover all refs reported by
98
+the list command. If no 'refspec' capability is advertised,
99
+there is an implied `refspec {asterisk}:{asterisk}`.
100
+
101
+Capabilities for Pushing
102
+~~~~~~~~~~~~~~~~~~~~~~~~
103
+'connect'::
104
+ Can attempt to connect to 'git receive-pack' (for pushing),
105
+ 'git upload-pack', etc for communication using the
106
+ packfile protocol.
107
++
108
+Supported commands: 'connect'.
109
+
110
+'push'::
111
+ Can discover remote refs and push local commits and the
112
+ history leading up to them to new or existing remote refs.
113
++
114
+Supported commands: 'list for-push', 'push'.
115
+
116
+If a helper advertises both 'connect' and 'push', git will use
117
+'connect' if possible and fall back to 'push' if the helper requests
118
+so when connecting (see the 'connect' command under COMMANDS).
119
+
120
+Capabilities for Fetching
121
+~~~~~~~~~~~~~~~~~~~~~~~~~
122
+'connect'::
123
+ Can try to connect to 'git upload-pack' (for fetching),
124
+ 'git receive-pack', etc for communication using the
125
+ packfile protocol.
126
++
127
+Supported commands: 'connect'.
128
+
129
+'fetch'::
130
+ Can discover remote refs and transfer objects reachable from
131
+ them to the local object store.
132
++
133
+Supported commands: 'list', 'fetch'.
134
+
135
+'import'::
136
+ Can discover remote refs and output objects reachable from
137
+ them as a stream in fast-import format.
138
++
139
+Supported commands: 'list', 'import'.
140
+
141
+If a helper advertises 'connect', git will use it if possible and
142
+fall back to another capability if the helper requests so when
143
+connecting (see the 'connect' command under COMMANDS).
144
+When choosing between 'fetch' and 'import', git prefers 'fetch'.
145
+Other frontends may have some other order of preference.
146
+
147
+'refspec' <refspec>::
148
+ This modifies the 'import' capability.
149
++
150
+A helper advertising
151
+`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}`
152
+in its capabilities is saying that, when it handles
153
+`import refs/heads/topic`, the stream it outputs will update the
154
+`refs/svn/origin/branches/topic` ref.
155
++
156
+This capability can be advertised multiple times. The first
157
+applicable refspec takes precedence. The left-hand of refspecs
158
+advertised with this capability must cover all refs reported by
159
+the list command. If no 'refspec' capability is advertised,
160
+there is an implied `refspec {asterisk}:{asterisk}`.
161
+
162
INVOCATION
163
----------
164
@@ -171,26 +290,6 @@ completing a valid response for the current command.
290
Additional commands may be supported, as may be determined from
291
capabilities reported by the helper.
292
174
-CAPABILITIES
175
-------------
176
-
177
-'fetch'::
178
-'option'::
179
-'push'::
180
-'import'::
181
-'connect'::
182
- This helper supports the corresponding command with the same name.
183
-
184
-'refspec' 'spec'::
185
- When using the import command, expect the source ref to have
186
- been written to the destination ref. The earliest applicable
187
- refspec takes precedence. For example
188
- "refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}" means
189
- that, after an "import refs/heads/name", the script has written to
190
- refs/svn/origin/branches/name. If this capability is used at
191
- all, it must cover all refs reported by the list command; if
192
- it is not used, it is effectively "{asterisk}:{asterisk}"
193
-
293
REF LIST ATTRIBUTES
294
-------------------
295