]>
Commit | Line | Data |
---|---|---|
1 | git-remote-helpers(1) | |
2 | ===================== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-remote-helpers - Helper programs to interact with remote repositories | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | 'git remote-<transport>' <repository> [<URL>] | |
12 | ||
13 | DESCRIPTION | |
14 | ----------- | |
15 | ||
16 | Remote helper programs are normally not used directly by end users, | |
17 | but they are invoked by git when it needs to interact with remote | |
18 | repositories git does not support natively. A given helper will | |
19 | implement a subset of the capabilities documented here. When git | |
20 | needs to interact with a repository using a remote helper, it spawns | |
21 | the helper as an independent process, sends commands to the helper's | |
22 | standard input, and expects results from the helper's standard | |
23 | 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 | |
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/*:refs/svn/origin/branches/*` | |
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 *:*`. | |
100 | ||
101 | 'bidi-import':: | |
102 | The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers | |
103 | to retrieve information about blobs and trees that already exist in | |
104 | fast-import's memory. This requires a channel from fast-import to the | |
105 | remote-helper. | |
106 | If it is advertised in addition to "import", git establishes a pipe from | |
107 | fast-import to the remote-helper's stdin. | |
108 | It follows that git and fast-import are both connected to the | |
109 | remote-helper's stdin. Because git can send multiple commands to | |
110 | the remote-helper it is required that helpers that use 'bidi-import' | |
111 | buffer all 'import' commands of a batch before sending data to fast-import. | |
112 | This is to prevent mixing commands and fast-import responses on the | |
113 | helper's stdin. | |
114 | ||
115 | Capabilities for Pushing | |
116 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
117 | 'connect':: | |
118 | Can attempt to connect to 'git receive-pack' (for pushing), | |
119 | 'git upload-pack', etc for communication using the | |
120 | packfile protocol. | |
121 | + | |
122 | Supported commands: 'connect'. | |
123 | ||
124 | 'push':: | |
125 | Can discover remote refs and push local commits and the | |
126 | history leading up to them to new or existing remote refs. | |
127 | + | |
128 | Supported commands: 'list for-push', 'push'. | |
129 | ||
130 | If a helper advertises both 'connect' and 'push', git will use | |
131 | 'connect' if possible and fall back to 'push' if the helper requests | |
132 | so when connecting (see the 'connect' command under COMMANDS). | |
133 | ||
134 | Capabilities for Fetching | |
135 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
136 | 'connect':: | |
137 | Can try to connect to 'git upload-pack' (for fetching), | |
138 | 'git receive-pack', etc for communication using the | |
139 | packfile protocol. | |
140 | + | |
141 | Supported commands: 'connect'. | |
142 | ||
143 | 'fetch':: | |
144 | Can discover remote refs and transfer objects reachable from | |
145 | them to the local object store. | |
146 | + | |
147 | Supported commands: 'list', 'fetch'. | |
148 | ||
149 | 'import':: | |
150 | Can discover remote refs and output objects reachable from | |
151 | them as a stream in fast-import format. | |
152 | + | |
153 | Supported commands: 'list', 'import'. | |
154 | ||
155 | If a helper advertises 'connect', git will use it if possible and | |
156 | fall back to another capability if the helper requests so when | |
157 | connecting (see the 'connect' command under COMMANDS). | |
158 | When choosing between 'fetch' and 'import', git prefers 'fetch'. | |
159 | Other frontends may have some other order of preference. | |
160 | ||
161 | 'refspec' <refspec>:: | |
162 | This modifies the 'import' capability. | |
163 | + | |
164 | A helper advertising | |
165 | `refspec refs/heads/*:refs/svn/origin/branches/*` | |
166 | in its capabilities is saying that, when it handles | |
167 | `import refs/heads/topic`, the stream it outputs will update the | |
168 | `refs/svn/origin/branches/topic` ref. | |
169 | + | |
170 | This capability can be advertised multiple times. The first | |
171 | applicable refspec takes precedence. The left-hand of refspecs | |
172 | advertised with this capability must cover all refs reported by | |
173 | the list command. If no 'refspec' capability is advertised, | |
174 | there is an implied `refspec *:*`. | |
175 | ||
176 | INVOCATION | |
177 | ---------- | |
178 | ||
179 | Remote helper programs are invoked with one or (optionally) two | |
180 | arguments. The first argument specifies a remote repository as in git; | |
181 | it is either the name of a configured remote or a URL. The second | |
182 | argument specifies a URL; it is usually of the form | |
183 | '<transport>://<address>', but any arbitrary string is possible. | |
184 | The 'GIT_DIR' environment variable is set up for the remote helper | |
185 | and can be used to determine where to store additional data or from | |
186 | which directory to invoke auxiliary git commands. | |
187 | ||
188 | When git encounters a URL of the form '<transport>://<address>', where | |
189 | '<transport>' is a protocol that it cannot handle natively, it | |
190 | automatically invokes 'git remote-<transport>' with the full URL as | |
191 | the second argument. If such a URL is encountered directly on the | |
192 | command line, the first argument is the same as the second, and if it | |
193 | is encountered in a configured remote, the first argument is the name | |
194 | of that remote. | |
195 | ||
196 | A URL of the form '<transport>::<address>' explicitly instructs git to | |
197 | invoke 'git remote-<transport>' with '<address>' as the second | |
198 | argument. If such a URL is encountered directly on the command line, | |
199 | the first argument is '<address>', and if it is encountered in a | |
200 | configured remote, the first argument is the name of that remote. | |
201 | ||
202 | Additionally, when a configured remote has 'remote.<name>.vcs' set to | |
203 | '<transport>', git explicitly invokes 'git remote-<transport>' with | |
204 | '<name>' as the first argument. If set, the second argument is | |
205 | 'remote.<name>.url'; otherwise, the second argument is omitted. | |
206 | ||
207 | COMMANDS | |
208 | -------- | |
209 | ||
210 | Commands are given by the caller on the helper's standard input, one per line. | |
211 | ||
212 | 'capabilities':: | |
213 | Lists the capabilities of the helper, one per line, ending | |
214 | with a blank line. Each capability may be preceded with '*', | |
215 | which marks them mandatory for git version using the remote | |
216 | helper to understand (unknown mandatory capability is fatal | |
217 | error). | |
218 | ||
219 | 'list':: | |
220 | Lists the refs, one per line, in the format "<value> <name> | |
221 | [<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for | |
222 | a symref, or "?" to indicate that the helper could not get the | |
223 | value of the ref. A space-separated list of attributes follows | |
224 | the name; unrecognized attributes are ignored. The list ends | |
225 | with a blank line. | |
226 | + | |
227 | If 'push' is supported this may be called as 'list for-push' | |
228 | to obtain the current refs prior to sending one or more 'push' | |
229 | commands to the helper. | |
230 | ||
231 | 'option' <name> <value>:: | |
232 | Sets the transport helper option <name> to <value>. Outputs a | |
233 | single line containing one of 'ok' (option successfully set), | |
234 | 'unsupported' (option not recognized) or 'error <msg>' | |
235 | (option <name> is supported but <value> is not valid | |
236 | for it). Options should be set before other commands, | |
237 | and may influence the behavior of those commands. | |
238 | + | |
239 | Supported if the helper has the "option" capability. | |
240 | ||
241 | 'fetch' <sha1> <name>:: | |
242 | Fetches the given object, writing the necessary objects | |
243 | to the database. Fetch commands are sent in a batch, one | |
244 | per line, terminated with a blank line. | |
245 | Outputs a single blank line when all fetch commands in the | |
246 | same batch are complete. Only objects which were reported | |
247 | in the ref list with a sha1 may be fetched this way. | |
248 | + | |
249 | Optionally may output a 'lock <file>' line indicating a file under | |
250 | GIT_DIR/objects/pack which is keeping a pack until refs can be | |
251 | suitably updated. | |
252 | + | |
253 | Supported if the helper has the "fetch" capability. | |
254 | ||
255 | 'push' +<src>:<dst>:: | |
256 | Pushes the given local <src> commit or branch to the | |
257 | remote branch described by <dst>. A batch sequence of | |
258 | one or more 'push' commands is terminated with a blank line | |
259 | (if there is only one reference to push, a single 'push' command | |
260 | is followed by a blank line). For example, the following would | |
261 | be two batches of 'push', the first asking the remote-helper | |
262 | to push the local ref 'master' to the remote ref 'master' and | |
263 | the local 'HEAD' to the remote 'branch', and the second | |
264 | asking to push ref 'foo' to ref 'bar' (forced update requested | |
265 | by the '+'). | |
266 | + | |
267 | ------------ | |
268 | push refs/heads/master:refs/heads/master | |
269 | push HEAD:refs/heads/branch | |
270 | \n | |
271 | push +refs/heads/foo:refs/heads/bar | |
272 | \n | |
273 | ------------ | |
274 | + | |
275 | Zero or more protocol options may be entered after the last 'push' | |
276 | command, before the batch's terminating blank line. | |
277 | + | |
278 | When the push is complete, outputs one or more 'ok <dst>' or | |
279 | 'error <dst> <why>?' lines to indicate success or failure of | |
280 | each pushed ref. The status report output is terminated by | |
281 | a blank line. The option field <why> may be quoted in a C | |
282 | style string if it contains an LF. | |
283 | + | |
284 | Supported if the helper has the "push" capability. | |
285 | ||
286 | 'import' <name>:: | |
287 | Produces a fast-import stream which imports the current value | |
288 | of the named ref. It may additionally import other refs as | |
289 | needed to construct the history efficiently. The script writes | |
290 | to a helper-specific private namespace. The value of the named | |
291 | ref should be written to a location in this namespace derived | |
292 | by applying the refspecs from the "refspec" capability to the | |
293 | name of the ref. | |
294 | + | |
295 | Especially useful for interoperability with a foreign versioning | |
296 | system. | |
297 | + | |
298 | Just like 'push', a batch sequence of one or more 'import' is | |
299 | terminated with a blank line. For each batch of 'import', the remote | |
300 | helper should produce a fast-import stream terminated by a 'done' | |
301 | command. | |
302 | + | |
303 | Note that if the 'bidi-import' capability is used the complete batch | |
304 | sequence has to be buffered before starting to send data to fast-import | |
305 | to prevent mixing of commands and fast-import responses on the helper's | |
306 | stdin. | |
307 | + | |
308 | Supported if the helper has the 'import' capability. | |
309 | ||
310 | 'connect' <service>:: | |
311 | Connects to given service. Standard input and standard output | |
312 | of helper are connected to specified service (git prefix is | |
313 | included in service name so e.g. fetching uses 'git-upload-pack' | |
314 | as service) on remote side. Valid replies to this command are | |
315 | empty line (connection established), 'fallback' (no smart | |
316 | transport support, fall back to dumb transports) and just | |
317 | exiting with error message printed (can't connect, don't | |
318 | bother trying to fall back). After line feed terminating the | |
319 | positive (empty) response, the output of service starts. After | |
320 | the connection ends, the remote helper exits. | |
321 | + | |
322 | Supported if the helper has the "connect" capability. | |
323 | ||
324 | If a fatal error occurs, the program writes the error message to | |
325 | stderr and exits. The caller should expect that a suitable error | |
326 | message has been printed if the child closes the connection without | |
327 | completing a valid response for the current command. | |
328 | ||
329 | Additional commands may be supported, as may be determined from | |
330 | capabilities reported by the helper. | |
331 | ||
332 | REF LIST ATTRIBUTES | |
333 | ------------------- | |
334 | ||
335 | 'for-push':: | |
336 | The caller wants to use the ref list to prepare push | |
337 | commands. A helper might chose to acquire the ref list by | |
338 | opening a different type of connection to the destination. | |
339 | ||
340 | 'unchanged':: | |
341 | This ref is unchanged since the last import or fetch, although | |
342 | the helper cannot necessarily determine what value that produced. | |
343 | ||
344 | OPTIONS | |
345 | ------- | |
346 | 'option verbosity' <n>:: | |
347 | Changes the verbosity of messages displayed by the helper. | |
348 | A value of 0 for <n> means that processes operate | |
349 | quietly, and the helper produces only error output. | |
350 | 1 is the default level of verbosity, and higher values | |
351 | of <n> correspond to the number of -v flags passed on the | |
352 | command line. | |
353 | ||
354 | 'option progress' \{'true'|'false'\}:: | |
355 | Enables (or disables) progress messages displayed by the | |
356 | transport helper during a command. | |
357 | ||
358 | 'option depth' <depth>:: | |
359 | Deepens the history of a shallow repository. | |
360 | ||
361 | 'option followtags' \{'true'|'false'\}:: | |
362 | If enabled the helper should automatically fetch annotated | |
363 | tag objects if the object the tag points at was transferred | |
364 | during the fetch command. If the tag is not fetched by | |
365 | the helper a second fetch command will usually be sent to | |
366 | ask for the tag specifically. Some helpers may be able to | |
367 | use this option to avoid a second network connection. | |
368 | ||
369 | 'option dry-run' \{'true'|'false'\}: | |
370 | If true, pretend the operation completed successfully, | |
371 | but don't actually change any repository data. For most | |
372 | helpers this only applies to the 'push', if supported. | |
373 | ||
374 | 'option servpath <c-style-quoted-path>':: | |
375 | Sets service path (--upload-pack, --receive-pack etc.) for | |
376 | next connect. Remote helper may support this option, but | |
377 | must not rely on this option being set before | |
378 | connect request occurs. | |
379 | ||
380 | SEE ALSO | |
381 | -------- | |
382 | linkgit:git-remote[1] | |
383 | ||
384 | linkgit:git-remote-testgit[1] | |
385 | ||
386 | GIT | |
387 | --- | |
388 | Part of the linkgit:git[1] suite |