git-remote-helpers.txt: rearrange description of capabilities
This also remove some duplication in the descriptions (e.g. refspec was explained twice with similar level of detail). 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
0673bb28d0b96393e526030c96e7dbfac2fc33a2
1 file changed
+56
-78
Documentation/git-remote-helpers.txt
+56
-78
@@ -88,81 +88,17 @@ Each remote helper is expected to support only a subset of commands.
88
The operations a helper supports are declared to git in the response
89
to the `capabilities` command (see COMMANDS, below).
90
91
-'option'::
92
- For specifying settings like `verbosity` (how much output to
93
- write to stderr) and `depth` (how much history is wanted in the
94
- case of a shallow clone) that affect how other commands are
95
- carried out.
96
-
97
-'connect'::
98
- For fetching and pushing using git's native packfile protocol
99
- that requires a bidirectional, full-duplex connection.
100
-
101
-'push'::
102
- For listing remote refs and pushing specified objects from the
103
- local object store to remote refs.
104
-
105
-'fetch'::
106
- For listing remote refs and fetching the associated history to
107
- the local object store.
108
-
109
-'export'::
110
- For listing remote refs and pushing specified objects from a
111
- fast-import stream to remote refs.
112
-
113
-'import'::
114
- For listing remote refs and fetching the associated history as
115
- a fast-import stream.
116
-
117
-'refspec' <refspec>::
118
- This modifies the 'import' capability, allowing the produced
119
- fast-import stream to modify refs in a private namespace
120
- instead of writing to refs/heads or refs/remotes directly.
121
- It is recommended that all importers providing the 'import'
122
- capability use this.
123
-+
124
-A helper advertising the capability
125
-`refspec refs/heads/*:refs/svn/origin/branches/*`
126
-is saying that, when it is asked to `import refs/heads/topic`, the
127
-stream it outputs will update the `refs/svn/origin/branches/topic`
128
-ref.
129
-+
130
-This capability can be advertised multiple times. The first
131
-applicable refspec takes precedence. The left-hand of refspecs
132
-advertised with this capability must cover all refs reported by
133
-the list command. If no 'refspec' capability is advertised,
134
-there is an implied `refspec *:*`.
135
-
136
-'bidi-import'::
137
- The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers
138
- to retrieve information about blobs and trees that already exist in
139
- fast-import's memory. This requires a channel from fast-import to the
140
- remote-helper.
141
- If it is advertised in addition to "import", git establishes a pipe from
142
- fast-import to the remote-helper's stdin.
143
- It follows that git and fast-import are both connected to the
144
- remote-helper's stdin. Because git can send multiple commands to
145
- the remote-helper it is required that helpers that use 'bidi-import'
146
- buffer all 'import' commands of a batch before sending data to fast-import.
147
- This is to prevent mixing commands and fast-import responses on the
148
- helper's stdin.
149
-
150
-'export-marks' <file>::
151
- This modifies the 'export' capability, instructing git to dump the
152
- internal marks table to <file> when complete. For details,
153
- read up on '--export-marks=<file>' in linkgit:git-fast-export[1].
154
-
155
-'import-marks' <file>::
156
- This modifies the 'export' capability, instructing git to load the
157
- marks specified in <file> before processing any input. For details,
158
- read up on '--import-marks=<file>' in linkgit:git-fast-export[1].
91
+In the following, we list all defined capabilities and for
92
+each we list which commands a helper with that capability
93
+must provide.
94
95
Capabilities for Pushing
161
-~~~~~~~~~~~~~~~~~~~~~~~~
96
+^^^^^^^^^^^^^^^^^^^^^^^^
97
'connect'::
98
Can attempt to connect to 'git receive-pack' (for pushing),
164
- 'git upload-pack', etc for communication using the
165
- packfile protocol.
99
+ 'git upload-pack', etc for communication using
100
+ git's native packfile protocol. This
101
+ requires a bidirectional, full-duplex connection.
102
+
103
Supported commands: 'connect'.
104
@@ -186,11 +122,12 @@ Other frontends may have some other order of preference.
122
123
124
Capabilities for Fetching
189
-~~~~~~~~~~~~~~~~~~~~~~~~~
125
+^^^^^^^^^^^^^^^^^^^^^^^^^
126
'connect'::
127
Can try to connect to 'git upload-pack' (for fetching),
128
'git receive-pack', etc for communication using the
193
- packfile protocol.
129
+ git's native packfile protocol. This
130
+ requires a bidirectional, full-duplex connection.
131
+
132
Supported commands: 'connect'.
133
@@ -212,14 +149,27 @@ connecting (see the 'connect' command under COMMANDS).
149
When choosing between 'fetch' and 'import', git prefers 'fetch'.
150
Other frontends may have some other order of preference.
151
152
+Miscellaneous capabilities
153
+^^^^^^^^^^^^^^^^^^^^^^^^^^
154
+
155
+'option'::
156
+ For specifying settings like `verbosity` (how much output to
157
+ write to stderr) and `depth` (how much history is wanted in the
158
+ case of a shallow clone) that affect how other commands are
159
+ carried out.
160
+
161
'refspec' <refspec>::
216
- This modifies the 'import' capability.
162
+ This modifies the 'import' capability, allowing the produced
163
+ fast-import stream to modify refs in a private namespace
164
+ instead of writing to refs/heads or refs/remotes directly.
165
+ It is recommended that all importers providing the 'import'
166
+ capability use this.
167
+
218
-A helper advertising
168
+A helper advertising the capability
169
`refspec refs/heads/*:refs/svn/origin/branches/*`
220
-in its capabilities is saying that, when it handles
221
-`import refs/heads/topic`, the stream it outputs will update the
222
-`refs/svn/origin/branches/topic` ref.
170
+is saying that, when it is asked to `import refs/heads/topic`, the
171
+stream it outputs will update the `refs/svn/origin/branches/topic`
172
+ref.
173
+
174
This capability can be advertised multiple times. The first
175
applicable refspec takes precedence. The left-hand of refspecs
@@ -227,6 +177,34 @@ advertised with this capability must cover all refs reported by
177
the list command. If no 'refspec' capability is advertised,
178
there is an implied `refspec *:*`.
179
180
+'bidi-import'::
181
+ This modifies the 'import' capability.
182
+ The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers
183
+ to retrieve information about blobs and trees that already exist in
184
+ fast-import's memory. This requires a channel from fast-import to the
185
+ remote-helper.
186
+ If it is advertised in addition to "import", git establishes a pipe from
187
+ fast-import to the remote-helper's stdin.
188
+ It follows that git and fast-import are both connected to the
189
+ remote-helper's stdin. Because git can send multiple commands to
190
+ the remote-helper it is required that helpers that use 'bidi-import'
191
+ buffer all 'import' commands of a batch before sending data to fast-import.
192
+ This is to prevent mixing commands and fast-import responses on the
193
+ helper's stdin.
194
+
195
+'export-marks' <file>::
196
+ This modifies the 'export' capability, instructing git to dump the
197
+ internal marks table to <file> when complete. For details,
198
+ read up on '--export-marks=<file>' in linkgit:git-fast-export[1].
199
+
200
+'import-marks' <file>::
201
+ This modifies the 'export' capability, instructing git to load the
202
+ marks specified in <file> before processing any input. For details,
203
+ read up on '--import-marks=<file>' in linkgit:git-fast-export[1].
204
+
205
+
206
+
207
+
208
COMMANDS
209
--------
210