1GITREMOTE-HELPERS(7) Git Manual GITREMOTE-HELPERS(7)
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 the full path
280 of a file under $GIT_DIR/objects/pack which is keeping a pack until
281 refs can be suitably updated. The path must end with .keep. This is
282 a mechanism to name a <pack,idx,keep> tuple by giving only the keep
283 component. The kept pack will not be deleted by a concurrent
284 repack, even though its objects may not be referenced until the
285 fetch completes. The .keep file will be deleted at the conclusion
286 of the fetch.
287 If option check-connectivity is requested, the helper must output
289 connectivity-ok if the clone is self-contained and connected.
290 Supported if the helper has the "fetch" capability.
292 push +<src>:<dst>
294 Pushes the given local <src> commit or branch to the remote branch
295 described by <dst>. A batch sequence of one or more push commands
296 is terminated with a blank line (if there is only one reference to
297 push, a single push command is followed by a blank line). For
298 example, the following would be two batches of push, the first
299 asking the remote-helper to push the local ref master to the remote
300 ref master and the local HEAD to the remote branch, and the second
301 asking to push ref foo to ref bar (forced update requested by the
302 +).
303 push refs/heads/master:refs/heads/master
305 push HEAD:refs/heads/branch
306 \n
307 push +refs/heads/foo:refs/heads/bar
308 \n
309 Zero or more protocol options may be entered after the last push
311 command, before the batch’s terminating blank line.
312 When the push is complete, outputs one or more ok <dst> or error
314 <dst> <why>? lines to indicate success or failure of each pushed
315 ref. The status report output is terminated by a blank line. The
316 option field <why> may be quoted in a C style string if it contains
317 an LF.
318 Supported if the helper has the "push" capability.
320 import <name>
322 Produces a fast-import stream which imports the current value of
323 the named ref. It may additionally import other refs as needed to
324 construct the history efficiently. The script writes to a
325 helper-specific private namespace. The value of the named ref
326 should be written to a location in this namespace derived by
327 applying the refspecs from the "refspec" capability to the name of
328 the ref.
329 Especially useful for interoperability with a foreign versioning
331 system.
332 Just like push, a batch sequence of one or more import is
334 terminated with a blank line. For each batch of import, the remote
335 helper should produce a fast-import stream terminated by a done
336 command.
337 Note that if the bidi-import capability is used the complete batch
339 sequence has to be buffered before starting to send data to
340 fast-import to prevent mixing of commands and fast-import responses
341 on the helper’s stdin.
342 Supported if the helper has the "import" capability.
344 export
346 Instructs the remote helper that any subsequent input is part of a
347 fast-import stream (generated by git fast-export) containing
348 objects which should be pushed to the remote.
349 Especially useful for interoperability with a foreign versioning
351 system.
352 The export-marks and import-marks capabilities, if specified,
354 affect this command in so far as they are passed on to git
355 fast-export, which then will load/store a table of marks for local
356 objects. This can be used to implement for incremental operations.
357 Supported if the helper has the "export" capability.
359 connect <service>
361 Connects to given service. Standard input and standard output of
362 helper are connected to specified service (git prefix is included
363 in service name so e.g. fetching uses git-upload-pack as service)
364 on remote side. Valid replies to this command are empty line
365 (connection established), fallback (no smart transport support,
366 fall back to dumb transports) and just exiting with error message
367 printed (can’t connect, don’t bother trying to fall back). After
368 line feed terminating the positive (empty) response, the output of
369 service starts. After the connection ends, the remote helper exits.
370 Supported if the helper has the "connect" capability.
372 stateless-connect <service>
374 Experimental; for internal use only. Connects to the given remote
375 service for communication using git’s wire-protocol version 2.
376 Valid replies to this command are empty line (connection
377 established), fallback (no smart transport support, fall back to
378 dumb transports) and just exiting with error message printed (can’t
379 connect, don’t bother trying to fall back). After line feed
380 terminating the positive (empty) response, the output of the
381 service starts. Messages (both request and response) must consist
382 of zero or more PKT-LINEs, terminating in a flush packet. The
383 client must not expect the server to store any state in between
384 request-response pairs. After the connection ends, the remote
385 helper exits.
386 Supported if the helper has the "stateless-connect" capability.
388 If a fatal error occurs, the program writes the error message to stderr
390 and exits. The caller should expect that a suitable error message has
391 been printed if the child closes the connection without completing a
392 valid response for the current command.
393 Additional commands may be supported, as may be determined from
395 capabilities reported by the helper.
396
398 The list command produces a list of refs in which each ref may be
399 followed by a list of attributes. The following ref list attributes are
400 defined.
401 unchanged
403 This ref is unchanged since the last import or fetch, although the
404 helper cannot necessarily determine what value that produced.
405
407 The following options are defined and (under suitable circumstances)
408 set by Git if the remote helper has the option capability.
409 option verbosity <n>
411 Changes the verbosity of messages displayed by the helper. A value
412 of 0 for <n> means that processes operate quietly, and the helper
413 produces only error output. 1 is the default level of verbosity,
414 and higher values of <n> correspond to the number of -v flags
415 passed on the command line.
416 option progress {true|false}
418 Enables (or disables) progress messages displayed by the transport
419 helper during a command.
420 option depth <depth>
422 Deepens the history of a shallow repository.
423 'option deepen-since <timestamp>
425 Deepens the history of a shallow repository based on time.
426 'option deepen-not <ref>
428 Deepens the history of a shallow repository excluding ref. Multiple
429 options add up.
430 option deepen-relative {'true|false}
432 Deepens the history of a shallow repository relative to current
433 boundary. Only valid when used with "option depth".
434 option followtags {true|false}
436 If enabled the helper should automatically fetch annotated tag
437 objects if the object the tag points at was transferred during the
438 fetch command. If the tag is not fetched by the helper a second
439 fetch command will usually be sent to ask for the tag specifically.
440 Some helpers may be able to use this option to avoid a second
441 network connection.
442 option dry-run {true|false}: If true, pretend the operation completed
444 successfully, but don’t actually change any repository data. For most
445 helpers this only applies to the push, if supported.
446 option servpath <c-style-quoted-path>
448 Sets service path (--upload-pack, --receive-pack etc.) for next
449 connect. Remote helper may support this option, but must not rely
450 on this option being set before connect request occurs.
451 option check-connectivity {true|false}
453 Request the helper to check connectivity of a clone.
454 option force {true|false}
456 Request the helper to perform a force update. Defaults to false.
457 option cloning {true|false}
459 Notify the helper this is a clone request (i.e. the current
460 repository is guaranteed empty).
461 option update-shallow {true|false}
463 Allow to extend .git/shallow if the new refs require it.
464 option pushcert {true|false}
466 GPG sign pushes.
467 'option push-option <string>
469 Transmit <string> as a push option. As the push option must not
470 contain LF or NUL characters, the string is not encoded.
471 option from-promisor {true|false}
473 Indicate that these objects are being fetched from a promisor.
474 option no-dependents {true|false}
476 Indicate that only the objects wanted need to be fetched, not their
477 dependents.
478 option atomic {true|false}
480 When pushing, request the remote server to update refs in a single
481 atomic transaction. If successful, all refs will be updated, or
482 none will. If the remote side does not support this capability, the
483 push will fail.
484
486 git-remote(1)
487 git-remote-ext(1)
489 git-remote-fd(1)
491 git-fast-import(1)
493
495 Part of the git(1) suite
496Git 2.24.1 12/10/2019 GITREMOTE-HELPERS(7)