1GITREMOTE-HELPERS(1) Git Manual GITREMOTE-HELPERS(1)
2
6 gitremote-helpers - Helper programs to interact with remote
7 repositories
8
10 git remote-<transport> <repository> [<URL>]
11
14 Remote helper programs are normally not used directly by end users, but
15 they are invoked by Git when it needs to interact with remote
16 repositories Git does not support natively. A given helper will
17 implement a subset of the capabilities documented here. When Git needs
18 to interact with a repository using a remote helper, it spawns the
19 helper as an independent process, sends commands to the helper’s
20 standard input, and expects results from the helper’s standard output.
21 Because a remote helper runs as an independent process from Git, there
22 is no need to re-link Git to add a new helper, nor any need to link the
23 helper with the implementation of Git.
24 Every helper must support the "capabilities" command, which Git uses to
26 determine what other commands the helper will accept. Those other
27 commands can be used to discover and update remote refs, transport
28 objects between the object database and the remote repository, and
29 update the local object store.
30 Git comes with a "curl" family of remote helpers, that handle various
32 transport protocols, such as git-remote-http, git-remote-https,
33 git-remote-ftp and git-remote-ftps. They implement the capabilities
34 fetch, option, and push.
35
37 Remote helper programs are invoked with one or (optionally) two
38 arguments. The first argument specifies a remote repository as in Git;
39 it is either the name of a configured remote or a URL. The second
40 argument specifies a URL; it is usually of the form
41 <transport>://<address>, but any arbitrary string is possible. The
42 GIT_DIR environment variable is set up for the remote helper and can be
43 used to determine where to store additional data or from which
44 directory to invoke auxiliary Git commands.
45 When Git encounters a URL of the form <transport>://<address>, where
47 <transport> is a protocol that it cannot handle natively, it
48 automatically invokes git remote-<transport> with the full URL as the
49 second argument. If such a URL is encountered directly on the command
50 line, the first argument is the same as the second, and if it is
51 encountered in a configured remote, the first argument is the name of
52 that remote.
53 A URL of the form <transport>::<address> explicitly instructs Git to
55 invoke git remote-<transport> with <address> as the second argument. If
56 such a URL is encountered directly on the command line, the first
57 argument is <address>, and if it is encountered in a configured remote,
58 the first argument is the name of that remote.
59 Additionally, when a configured remote has remote.<name>.vcs set to
61 <transport>, Git explicitly invokes git remote-<transport> with <name>
62 as the first argument. If set, the second argument is
63 remote.<name>.url; otherwise, the second argument is omitted.
64
66 Git sends the remote helper a list of commands on standard input, one
67 per line. The first command is always the capabilities command, in
68 response to which the remote helper must print a list of the
69 capabilities it supports (see below) followed by a blank line. The
70 response to the capabilities command determines what commands Git uses
71 in the remainder of the command stream.
72 The command stream is terminated by a blank line. In some cases
74 (indicated in the documentation of the relevant commands), this blank
75 line is followed by a payload in some other protocol (e.g., the pack
76 protocol), while in others it indicates the end of input.
77 Capabilities
79 Each remote helper is expected to support only a subset of commands.
80 The operations a helper supports are declared to Git in the response to
81 the capabilities command (see COMMANDS, below).
82 In the following, we list all defined capabilities and for each we list
84 which commands a helper with that capability must provide.
85 Capabilities for Pushing
87 connect
88 Can attempt to connect to git receive-pack (for pushing), git
89 upload-pack, etc for communication using git’s native packfile
90 protocol. This requires a bidirectional, full-duplex
91 connection.
92 Supported commands: connect.
94 stateless-connect
96 Experimental; for internal use only. Can attempt to connect to
97 a remote server for communication using git’s wire-protocol
98 version 2. See the documentation for the stateless-connect
99 command for more information.
100 Supported commands: stateless-connect.
102 push
104 Can discover remote refs and push local commits and the history
105 leading up to them to new or existing remote refs.
106 Supported commands: list for-push, push.
108 export
110 Can discover remote refs and push specified objects from a
111 fast-import stream to remote refs.
112 Supported commands: list for-push, export.
114 If a helper advertises connect, Git will use it if possible and
116 fall back to another capability if the helper requests so when
117 connecting (see the connect command under COMMANDS). When choosing
118 between push and export, Git prefers push. Other frontends may have
119 some other order of preference.
120 no-private-update
122 When using the refspec capability, git normally updates the
123 private ref on successful push. This update is disabled when
124 the remote-helper declares the capability no-private-update.
125 Capabilities for Fetching
127 connect
128 Can try to connect to git upload-pack (for fetching), git
129 receive-pack, etc for communication using the Git’s native
130 packfile protocol. This requires a bidirectional, full-duplex
131 connection.
132 Supported commands: connect.
134 stateless-connect
136 Experimental; for internal use only. Can attempt to connect to
137 a remote server for communication using git’s wire-protocol
138 version 2. See the documentation for the stateless-connect
139 command for more information.
140 Supported commands: stateless-connect.
142 fetch
144 Can discover remote refs and transfer objects reachable from
145 them to the local object store.
146 Supported commands: list, fetch.
148 import
150 Can discover remote refs and output objects reachable from them
151 as a stream in fast-import format.
152 Supported commands: list, import.
154 check-connectivity
156 Can guarantee that when a clone is requested, the received pack
157 is self contained and is connected.
158 If a helper advertises connect, Git will use it if possible and
160 fall back to another capability if the helper requests so when
161 connecting (see the connect command under COMMANDS). When choosing
162 between fetch and import, Git prefers fetch. Other frontends may
163 have some other order of preference.
164 Miscellaneous capabilities
166 option
167 For specifying settings like verbosity (how much output to
168 write to stderr) and depth (how much history is wanted in the
169 case of a shallow clone) that affect how other commands are
170 carried out.
171 refspec <refspec>
173 For remote helpers that implement import or export, this
174 capability allows the refs to be constrained to a private
175 namespace, instead of writing to refs/heads or refs/remotes
176 directly. It is recommended that all importers providing the
177 import capability use this. It’s mandatory for export.
178 A helper advertising the capability refspec
180 refs/heads/*:refs/svn/origin/branches/* is saying that, when it
181 is asked to import refs/heads/topic, the stream it outputs will
182 update the refs/svn/origin/branches/topic ref.
183 This capability can be advertised multiple times. The first
185 applicable refspec takes precedence. The left-hand of refspecs
186 advertised with this capability must cover all refs reported by
187 the list command. If no refspec capability is advertised, there
188 is an implied refspec *:*.
189 When writing remote-helpers for decentralized version control
191 systems, it is advised to keep a local copy of the repository
192 to interact with, and to let the private namespace refs point
193 to this local repository, while the refs/remotes namespace is
194 used to track the remote repository.
195 bidi-import
197 This modifies the import capability. The fast-import commands
198 cat-blob and ls can be used by remote-helpers to retrieve
199 information about blobs and trees that already exist in
200 fast-import’s memory. This requires a channel from fast-import
201 to the remote-helper. If it is advertised in addition to
202 "import", Git establishes a pipe from fast-import to the
203 remote-helper’s stdin. It follows that Git and fast-import are
204 both connected to the remote-helper’s stdin. Because Git can
205 send multiple commands to the remote-helper it is required that
206 helpers that use bidi-import buffer all import commands of a
207 batch before sending data to fast-import. This is to prevent
208 mixing commands and fast-import responses on the helper’s
209 stdin.
210 export-marks <file>
212 This modifies the export capability, instructing Git to dump
213 the internal marks table to <file> when complete. For details,
214 read up on --export-marks=<file> in git-fast-export(1).
215 import-marks <file>
217 This modifies the export capability, instructing Git to load
218 the marks specified in <file> before processing any input. For
219 details, read up on --import-marks=<file> in git-fast-
220 export(1).
221 signed-tags
223 This modifies the export capability, instructing Git to pass
224 --signed-tags=verbatim to git-fast-export(1). In the absence of
225 this capability, Git will use --signed-tags=warn-strip.
226
228 Commands are given by the caller on the helper’s standard input, one
229 per line.
230 capabilities
232 Lists the capabilities of the helper, one per line, ending with a
233 blank line. Each capability may be preceded with *, which marks
234 them mandatory for Git versions using the remote helper to
235 understand. Any unknown mandatory capability is a fatal error.
236 Support for this command is mandatory.
238 list
240 Lists the refs, one per line, in the format "<value> <name> [<attr>
241 ...]". The value may be a hex sha1 hash, "@<dest>" for a symref, or
242 "?" to indicate that the helper could not get the value of the ref.
243 A space-separated list of attributes follows the name; unrecognized
244 attributes are ignored. The list ends with a blank line.
245 See REF LIST ATTRIBUTES for a list of currently defined attributes.
247 Supported if the helper has the "fetch" or "import" capability.
249 list for-push
251 Similar to list, except that it is used if and only if the caller
252 wants to the resulting ref list to prepare push commands. A helper
253 supporting both push and fetch can use this to distinguish for
254 which operation the output of list is going to be used, possibly
255 reducing the amount of work that needs to be performed.
256 Supported if the helper has the "push" or "export" capability.
258 option <name> <value>
260 Sets the transport helper option <name> to <value>. Outputs a
261 single line containing one of ok (option successfully set),
262 unsupported (option not recognized) or error <msg> (option <name>
263 is supported but <value> is not valid for it). Options should be
264 set before other commands, and may influence the behavior of those
265 commands.
266 See OPTIONS for a list of currently defined options.
268 Supported if the helper has the "option" capability.
270 fetch <sha1> <name>
272 Fetches the given object, writing the necessary objects to the
273 database. Fetch commands are sent in a batch, one per line,
274 terminated with a blank line. Outputs a single blank line when all
275 fetch commands in the same batch are complete. Only objects which
276 were reported in the output of list with a sha1 may be fetched this
277 way.
278 Optionally may output a lock <file> line indicating a file under
280 GIT_DIR/objects/pack which is keeping a pack until refs can be
281 suitably updated.
282 If option check-connectivity is requested, the helper must output
284 connectivity-ok if the clone is self-contained and connected.
285 Supported if the helper has the "fetch" capability.
287 push +<src>:<dst>
289 Pushes the given local <src> commit or branch to the remote branch
290 described by <dst>. A batch sequence of one or more push commands
291 is terminated with a blank line (if there is only one reference to
292 push, a single push command is followed by a blank line). For
293 example, the following would be two batches of push, the first
294 asking the remote-helper to push the local ref master to the remote
295 ref master and the local HEAD to the remote branch, and the second
296 asking to push ref foo to ref bar (forced update requested by the
297 +).
298 push refs/heads/master:refs/heads/master
300 push HEAD:refs/heads/branch
301 \n
302 push +refs/heads/foo:refs/heads/bar
303 \n
304 Zero or more protocol options may be entered after the last push
306 command, before the batch’s terminating blank line.
307 When the push is complete, outputs one or more ok <dst> or error
309 <dst> <why>? lines to indicate success or failure of each pushed
310 ref. The status report output is terminated by a blank line. The
311 option field <why> may be quoted in a C style string if it contains
312 an LF.
313 Supported if the helper has the "push" capability.
315 import <name>
317 Produces a fast-import stream which imports the current value of
318 the named ref. It may additionally import other refs as needed to
319 construct the history efficiently. The script writes to a
320 helper-specific private namespace. The value of the named ref
321 should be written to a location in this namespace derived by
322 applying the refspecs from the "refspec" capability to the name of
323 the ref.
324 Especially useful for interoperability with a foreign versioning
326 system.
327 Just like push, a batch sequence of one or more import is
329 terminated with a blank line. For each batch of import, the remote
330 helper should produce a fast-import stream terminated by a done
331 command.
332 Note that if the bidi-import capability is used the complete batch
334 sequence has to be buffered before starting to send data to
335 fast-import to prevent mixing of commands and fast-import responses
336 on the helper’s stdin.
337 Supported if the helper has the "import" capability.
339 export
341 Instructs the remote helper that any subsequent input is part of a
342 fast-import stream (generated by git fast-export) containing
343 objects which should be pushed to the remote.
344 Especially useful for interoperability with a foreign versioning
346 system.
347 The export-marks and import-marks capabilities, if specified,
349 affect this command in so far as they are passed on to git
350 fast-export, which then will load/store a table of marks for local
351 objects. This can be used to implement for incremental operations.
352 Supported if the helper has the "export" capability.
354 connect <service>
356 Connects to given service. Standard input and standard output of
357 helper are connected to specified service (git prefix is included
358 in service name so e.g. fetching uses git-upload-pack as service)
359 on remote side. Valid replies to this command are empty line
360 (connection established), fallback (no smart transport support,
361 fall back to dumb transports) and just exiting with error message
362 printed (can’t connect, don’t bother trying to fall back). After
363 line feed terminating the positive (empty) response, the output of
364 service starts. After the connection ends, the remote helper exits.
365 Supported if the helper has the "connect" capability.
367 stateless-connect <service>
369 Experimental; for internal use only. Connects to the given remote
370 service for communication using git’s wire-protocol version 2.
371 Valid replies to this command are empty line (connection
372 established), fallback (no smart transport support, fall back to
373 dumb transports) and just exiting with error message printed (can’t
374 connect, don’t bother trying to fall back). After line feed
375 terminating the positive (empty) response, the output of the
376 service starts. Messages (both request and response) must consist
377 of zero or more PKT-LINEs, terminating in a flush packet. The
378 client must not expect the server to store any state in between
379 request-response pairs. After the connection ends, the remote
380 helper exits.
381 Supported if the helper has the "stateless-connect" capability.
383 If a fatal error occurs, the program writes the error message to stderr
385 and exits. The caller should expect that a suitable error message has
386 been printed if the child closes the connection without completing a
387 valid response for the current command.
388 Additional commands may be supported, as may be determined from
390 capabilities reported by the helper.
391
393 The list command produces a list of refs in which each ref may be
394 followed by a list of attributes. The following ref list attributes are
395 defined.
396 unchanged
398 This ref is unchanged since the last import or fetch, although the
399 helper cannot necessarily determine what value that produced.
400
402 The following options are defined and (under suitable circumstances)
403 set by Git if the remote helper has the option capability.
404 option verbosity <n>
406 Changes the verbosity of messages displayed by the helper. A value
407 of 0 for <n> means that processes operate quietly, and the helper
408 produces only error output. 1 is the default level of verbosity,
409 and higher values of <n> correspond to the number of -v flags
410 passed on the command line.
411 option progress {true|false}
413 Enables (or disables) progress messages displayed by the transport
414 helper during a command.
415 option depth <depth>
417 Deepens the history of a shallow repository.
418 'option deepen-since <timestamp>
420 Deepens the history of a shallow repository based on time.
421 'option deepen-not <ref>
423 Deepens the history of a shallow repository excluding ref. Multiple
424 options add up.
425 option deepen-relative {'true|false}
427 Deepens the history of a shallow repository relative to current
428 boundary. Only valid when used with "option depth".
429 option followtags {true|false}
431 If enabled the helper should automatically fetch annotated tag
432 objects if the object the tag points at was transferred during the
433 fetch command. If the tag is not fetched by the helper a second
434 fetch command will usually be sent to ask for the tag specifically.
435 Some helpers may be able to use this option to avoid a second
436 network connection.
437 option dry-run {true|false}: If true, pretend the operation completed
439 successfully, but don’t actually change any repository data. For most
440 helpers this only applies to the push, if supported.
441 option servpath <c-style-quoted-path>
443 Sets service path (--upload-pack, --receive-pack etc.) for next
444 connect. Remote helper may support this option, but must not rely
445 on this option being set before connect request occurs.
446 option check-connectivity {true|false}
448 Request the helper to check connectivity of a clone.
449 option force {true|false}
451 Request the helper to perform a force update. Defaults to false.
452 option cloning {true|false}
454 Notify the helper this is a clone request (i.e. the current
455 repository is guaranteed empty).
456 option update-shallow {true|false}
458 Allow to extend .git/shallow if the new refs require it.
459 option pushcert {true|false}
461 GPG sign pushes.
462 'option push-option <string>
464 Transmit <string> as a push option. As the push option must not
465 contain LF or NUL characters, the string is not encoded.
466 option from-promisor {true|false}
468 Indicate that these objects are being fetched from a promisor.
469 option no-dependents {true|false}
471 Indicate that only the objects wanted need to be fetched, not their
472 dependents.
473
475 git-remote(1)
476 git-remote-ext(1)
478 git-remote-fd(1)
480 git-remote-testgit(1)
482 git-fast-import(1)
484
486 Part of the git(1) suite
487Git 2.21.0 02/24/2019 GITREMOTE-HELPERS(1)