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
13 Remote helper programs are normally not used directly by end users, but
14 they are invoked by Git when it needs to interact with remote
15 repositories Git does not support natively. A given helper will
16 implement a subset of the capabilities documented here. When Git needs
17 to interact with a repository using a remote helper, it spawns the
18 helper as an independent process, sends commands to the helper’s
19 standard input, and expects results from the helper’s standard output.
20 Because a remote helper runs as an independent process from Git, there
21 is no need to re-link Git to add a new helper, nor any need to link the
22 helper with the implementation of Git.
23 Every helper must support the "capabilities" command, which Git uses to
25 determine what other commands the helper will accept. Those other
26 commands can be used to discover and update remote refs, transport
27 objects between the object database and the remote repository, and
28 update the local object store.
29 Git comes with a "curl" family of remote helpers, that handle various
31 transport protocols, such as git-remote-http, git-remote-https,
32 git-remote-ftp and git-remote-ftps. They implement the capabilities
33 fetch, option, and push.
34
36 Remote helper programs are invoked with one or (optionally) two
37 arguments. The first argument specifies a remote repository as in Git;
38 it is either the name of a configured remote or a URL. The second
39 argument specifies a URL; it is usually of the form
40 <transport>://<address>, but any arbitrary string is possible. The
41 GIT_DIR environment variable is set up for the remote helper and can be
42 used to determine where to store additional data or from which
43 directory to invoke auxiliary Git commands.
44 When Git encounters a URL of the form <transport>://<address>, where
46 <transport> is a protocol that it cannot handle natively, it
47 automatically invokes git remote-<transport> with the full URL as the
48 second argument. If such a URL is encountered directly on the command
49 line, the first argument is the same as the second, and if it is
50 encountered in a configured remote, the first argument is the name of
51 that remote.
52 A URL of the form <transport>::<address> explicitly instructs Git to
54 invoke git remote-<transport> with <address> as the second argument. If
55 such a URL is encountered directly on the command line, the first
56 argument is <address>, and if it is encountered in a configured remote,
57 the first argument is the name of that remote.
58 Additionally, when a configured remote has remote.<name>.vcs set to
60 <transport>, Git explicitly invokes git remote-<transport> with <name>
61 as the first argument. If set, the second argument is
62 remote.<name>.url; otherwise, the second argument is omitted.
63
65 Git sends the remote helper a list of commands on standard input, one
66 per line. The first command is always the capabilities command, in
67 response to which the remote helper must print a list of the
68 capabilities it supports (see below) followed by a blank line. The
69 response to the capabilities command determines what commands Git uses
70 in the remainder of the command stream.
71 The command stream is terminated by a blank line. In some cases
73 (indicated in the documentation of the relevant commands), this blank
74 line is followed by a payload in some other protocol (e.g., the pack
75 protocol), while in others it indicates the end of input.
76 Capabilities
78 Each remote helper is expected to support only a subset of commands.
79 The operations a helper supports are declared to Git in the response to
80 the capabilities command (see COMMANDS, below).
81 In the following, we list all defined capabilities and for each we list
83 which commands a helper with that capability must provide.
84 Capabilities for Pushing
86 connect
87 Can attempt to connect to git receive-pack (for pushing), git
88 upload-pack, etc for communication using git’s native packfile
89 protocol. This requires a bidirectional, full-duplex
90 connection.
91 Supported commands: connect.
93 stateless-connect
95 Experimental; for internal use only. Can attempt to connect to
96 a remote server for communication using git’s wire-protocol
97 version 2. See the documentation for the stateless-connect
98 command for more information.
99 Supported commands: stateless-connect.
101 push
103 Can discover remote refs and push local commits and the history
104 leading up to them to new or existing remote refs.
105 Supported commands: list for-push, push.
107 export
109 Can discover remote refs and push specified objects from a
110 fast-import stream to remote refs.
111 Supported commands: list for-push, export.
113 If a helper advertises connect, Git will use it if possible and
115 fall back to another capability if the helper requests so when
116 connecting (see the connect command under COMMANDS). When choosing
117 between push and export, Git prefers push. Other frontends may have
118 some other order of preference.
119 no-private-update
121 When using the refspec capability, git normally updates the
122 private ref on successful push. This update is disabled when
123 the remote-helper declares the capability no-private-update.
124 Capabilities for Fetching
126 connect
127 Can try to connect to git upload-pack (for fetching), git
128 receive-pack, etc for communication using the Git’s native
129 packfile protocol. This requires a bidirectional, full-duplex
130 connection.
131 Supported commands: connect.
133 stateless-connect
135 Experimental; for internal use only. Can attempt to connect to
136 a remote server for communication using git’s wire-protocol
137 version 2. See the documentation for the stateless-connect
138 command for more information.
139 Supported commands: stateless-connect.
141 fetch
143 Can discover remote refs and transfer objects reachable from
144 them to the local object store.
145 Supported commands: list, fetch.
147 import
149 Can discover remote refs and output objects reachable from them
150 as a stream in fast-import format.
151 Supported commands: list, import.
153 check-connectivity
155 Can guarantee that when a clone is requested, the received pack
156 is self contained and is connected.
157 get
159 Can use the get command to download a file from a given URI.
160 If a helper advertises connect, Git will use it if possible and
162 fall back to another capability if the helper requests so when
163 connecting (see the connect command under COMMANDS). When choosing
164 between fetch and import, Git prefers fetch. Other frontends may
165 have some other order of preference.
166 Miscellaneous capabilities
168 option
169 For specifying settings like verbosity (how much output to
170 write to stderr) and depth (how much history is wanted in the
171 case of a shallow clone) that affect how other commands are
172 carried out.
173 refspec <refspec>
175 For remote helpers that implement import or export, this
176 capability allows the refs to be constrained to a private
177 namespace, instead of writing to refs/heads or refs/remotes
178 directly. It is recommended that all importers providing the
179 import capability use this. It’s mandatory for export.
180 A helper advertising the capability refspec
182 refs/heads/*:refs/svn/origin/branches/* is saying that, when it
183 is asked to import refs/heads/topic, the stream it outputs will
184 update the refs/svn/origin/branches/topic ref.
185 This capability can be advertised multiple times. The first
187 applicable refspec takes precedence. The left-hand of refspecs
188 advertised with this capability must cover all refs reported by
189 the list command. If no refspec capability is advertised, there
190 is an implied refspec *:*.
191 When writing remote-helpers for decentralized version control
193 systems, it is advised to keep a local copy of the repository
194 to interact with, and to let the private namespace refs point
195 to this local repository, while the refs/remotes namespace is
196 used to track the remote repository.
197 bidi-import
199 This modifies the import capability. The fast-import commands
200 cat-blob and ls can be used by remote-helpers to retrieve
201 information about blobs and trees that already exist in
202 fast-import’s memory. This requires a channel from fast-import
203 to the remote-helper. If it is advertised in addition to
204 "import", Git establishes a pipe from fast-import to the
205 remote-helper’s stdin. It follows that Git and fast-import are
206 both connected to the remote-helper’s stdin. Because Git can
207 send multiple commands to the remote-helper it is required that
208 helpers that use bidi-import buffer all import commands of a
209 batch before sending data to fast-import. This is to prevent
210 mixing commands and fast-import responses on the helper’s
211 stdin.
212 export-marks <file>
214 This modifies the export capability, instructing Git to dump
215 the internal marks table to <file> when complete. For details,
216 read up on --export-marks=<file> in git-fast-export(1).
217 import-marks <file>
219 This modifies the export capability, instructing Git to load
220 the marks specified in <file> before processing any input. For
221 details, read up on --import-marks=<file> in git-fast-
222 export(1).
223 signed-tags
225 This modifies the export capability, instructing Git to pass
226 --signed-tags=verbatim to git-fast-export(1). In the absence of
227 this capability, Git will use --signed-tags=warn-strip.
228 object-format
230 This indicates that the helper is able to interact with the
231 remote side using an explicit hash algorithm extension.
232
234 Commands are given by the caller on the helper’s standard input, one
235 per line.
236 capabilities
238 Lists the capabilities of the helper, one per line, ending with a
239 blank line. Each capability may be preceded with *, which marks
240 them mandatory for Git versions using the remote helper to
241 understand. Any unknown mandatory capability is a fatal error.
242 Support for this command is mandatory.
244 list
246 Lists the refs, one per line, in the format "<value> <name> [<attr>
247 ...]". The value may be a hex sha1 hash, "@<dest>" for a symref,
248 ":<keyword> <value>" for a key-value pair, or "?" to indicate that
249 the helper could not get the value of the ref. A space-separated
250 list of attributes follows the name; unrecognized attributes are
251 ignored. The list ends with a blank line.
252 See REF LIST ATTRIBUTES for a list of currently defined attributes.
254 See REF LIST KEYWORDS for a list of currently defined keywords.
255 Supported if the helper has the "fetch" or "import" capability.
257 list for-push
259 Similar to list, except that it is used if and only if the caller
260 wants to the resulting ref list to prepare push commands. A helper
261 supporting both push and fetch can use this to distinguish for
262 which operation the output of list is going to be used, possibly
263 reducing the amount of work that needs to be performed.
264 Supported if the helper has the "push" or "export" capability.
266 option <name> <value>
268 Sets the transport helper option <name> to <value>. Outputs a
269 single line containing one of ok (option successfully set),
270 unsupported (option not recognized) or error <msg> (option <name>
271 is supported but <value> is not valid for it). Options should be
272 set before other commands, and may influence the behavior of those
273 commands.
274 See OPTIONS for a list of currently defined options.
276 Supported if the helper has the "option" capability.
278 fetch <sha1> <name>
280 Fetches the given object, writing the necessary objects to the
281 database. Fetch commands are sent in a batch, one per line,
282 terminated with a blank line. Outputs a single blank line when all
283 fetch commands in the same batch are complete. Only objects which
284 were reported in the output of list with a sha1 may be fetched this
285 way.
286 Optionally may output a lock <file> line indicating the full path
288 of a file under $GIT_DIR/objects/pack which is keeping a pack until
289 refs can be suitably updated. The path must end with .keep. This is
290 a mechanism to name a <pack,idx,keep> tuple by giving only the keep
291 component. The kept pack will not be deleted by a concurrent
292 repack, even though its objects may not be referenced until the
293 fetch completes. The .keep file will be deleted at the conclusion
294 of the fetch.
295 If option check-connectivity is requested, the helper must output
297 connectivity-ok if the clone is self-contained and connected.
298 Supported if the helper has the "fetch" capability.
300 push +<src>:<dst>
302 Pushes the given local <src> commit or branch to the remote branch
303 described by <dst>. A batch sequence of one or more push commands
304 is terminated with a blank line (if there is only one reference to
305 push, a single push command is followed by a blank line). For
306 example, the following would be two batches of push, the first
307 asking the remote-helper to push the local ref master to the remote
308 ref master and the local HEAD to the remote branch, and the second
309 asking to push ref foo to ref bar (forced update requested by the
310 +).
311 push refs/heads/master:refs/heads/master
313 push HEAD:refs/heads/branch
314 \n
315 push +refs/heads/foo:refs/heads/bar
316 \n
317 Zero or more protocol options may be entered after the last push
319 command, before the batch’s terminating blank line.
320 When the push is complete, outputs one or more ok <dst> or error
322 <dst> <why>? lines to indicate success or failure of each pushed
323 ref. The status report output is terminated by a blank line. The
324 option field <why> may be quoted in a C style string if it contains
325 an LF.
326 Supported if the helper has the "push" capability.
328 import <name>
330 Produces a fast-import stream which imports the current value of
331 the named ref. It may additionally import other refs as needed to
332 construct the history efficiently. The script writes to a
333 helper-specific private namespace. The value of the named ref
334 should be written to a location in this namespace derived by
335 applying the refspecs from the "refspec" capability to the name of
336 the ref.
337 Especially useful for interoperability with a foreign versioning
339 system.
340 Just like push, a batch sequence of one or more import is
342 terminated with a blank line. For each batch of import, the remote
343 helper should produce a fast-import stream terminated by a done
344 command.
345 Note that if the bidi-import capability is used the complete batch
347 sequence has to be buffered before starting to send data to
348 fast-import to prevent mixing of commands and fast-import responses
349 on the helper’s stdin.
350 Supported if the helper has the "import" capability.
352 export
354 Instructs the remote helper that any subsequent input is part of a
355 fast-import stream (generated by git fast-export) containing
356 objects which should be pushed to the remote.
357 Especially useful for interoperability with a foreign versioning
359 system.
360 The export-marks and import-marks capabilities, if specified,
362 affect this command in so far as they are passed on to git
363 fast-export, which then will load/store a table of marks for local
364 objects. This can be used to implement for incremental operations.
365 Supported if the helper has the "export" capability.
367 connect <service>
369 Connects to given service. Standard input and standard output of
370 helper are connected to specified service (git prefix is included
371 in service name so e.g. fetching uses git-upload-pack as service)
372 on remote side. Valid replies to this command are empty line
373 (connection established), fallback (no smart transport support,
374 fall back to dumb transports) and just exiting with error message
375 printed (can’t connect, don’t bother trying to fall back). After
376 line feed terminating the positive (empty) response, the output of
377 service starts. After the connection ends, the remote helper exits.
378 Supported if the helper has the "connect" capability.
380 stateless-connect <service>
382 Experimental; for internal use only. Connects to the given remote
383 service for communication using git’s wire-protocol version 2.
384 Valid replies to this command are empty line (connection
385 established), fallback (no smart transport support, fall back to
386 dumb transports) and just exiting with error message printed (can’t
387 connect, don’t bother trying to fall back). After line feed
388 terminating the positive (empty) response, the output of the
389 service starts. Messages (both request and response) must consist
390 of zero or more PKT-LINEs, terminating in a flush packet. Response
391 messages will then have a response end packet after the flush
392 packet to indicate the end of a response. The client must not
393 expect the server to store any state in between request-response
394 pairs. After the connection ends, the remote helper exits.
395 Supported if the helper has the "stateless-connect" capability.
397 get <uri> <path>
399 Downloads the file from the given <uri> to the given <path>. If
400 <path>.temp exists, then Git assumes that the .temp file is a
401 partial download from a previous attempt and will resume the
402 download from that position.
403 If a fatal error occurs, the program writes the error message to stderr
405 and exits. The caller should expect that a suitable error message has
406 been printed if the child closes the connection without completing a
407 valid response for the current command.
408 Additional commands may be supported, as may be determined from
410 capabilities reported by the helper.
411
413 The list command produces a list of refs in which each ref may be
414 followed by a list of attributes. The following ref list attributes are
415 defined.
416 unchanged
418 This ref is unchanged since the last import or fetch, although the
419 helper cannot necessarily determine what value that produced.
420
422 The list command may produce a list of key-value pairs. The following
423 keys are defined.
424 object-format
426 The refs are using the given hash algorithm. This keyword is only
427 used if the server and client both support the object-format
428 extension.
429
431 The following options are defined and (under suitable circumstances)
432 set by Git if the remote helper has the option capability.
433 option verbosity <n>
435 Changes the verbosity of messages displayed by the helper. A value
436 of 0 for <n> means that processes operate quietly, and the helper
437 produces only error output. 1 is the default level of verbosity,
438 and higher values of <n> correspond to the number of -v flags
439 passed on the command line.
440 option progress {true|false}
442 Enables (or disables) progress messages displayed by the transport
443 helper during a command.
444 option depth <depth>
446 Deepens the history of a shallow repository.
447 'option deepen-since <timestamp>
449 Deepens the history of a shallow repository based on time.
450 'option deepen-not <ref>
452 Deepens the history of a shallow repository excluding ref. Multiple
453 options add up.
454 option deepen-relative {'true|false}
456 Deepens the history of a shallow repository relative to current
457 boundary. Only valid when used with "option depth".
458 option followtags {true|false}
460 If enabled the helper should automatically fetch annotated tag
461 objects if the object the tag points at was transferred during the
462 fetch command. If the tag is not fetched by the helper a second
463 fetch command will usually be sent to ask for the tag specifically.
464 Some helpers may be able to use this option to avoid a second
465 network connection.
466 option dry-run {true|false}: If true, pretend the operation completed
468 successfully, but don’t actually change any repository data. For most
469 helpers this only applies to the push, if supported.
470 option servpath <c-style-quoted-path>
472 Sets service path (--upload-pack, --receive-pack etc.) for next
473 connect. Remote helper may support this option, but must not rely
474 on this option being set before connect request occurs.
475 option check-connectivity {true|false}
477 Request the helper to check connectivity of a clone.
478 option force {true|false}
480 Request the helper to perform a force update. Defaults to false.
481 option cloning {true|false}
483 Notify the helper this is a clone request (i.e. the current
484 repository is guaranteed empty).
485 option update-shallow {true|false}
487 Allow to extend .git/shallow if the new refs require it.
488 option pushcert {true|false}
490 GPG sign pushes.
491 'option push-option <string>
493 Transmit <string> as a push option. As the push option must not
494 contain LF or NUL characters, the string is not encoded.
495 option from-promisor {true|false}
497 Indicate that these objects are being fetched from a promisor.
498 option no-dependents {true|false}
500 Indicate that only the objects wanted need to be fetched, not their
501 dependents.
502 option atomic {true|false}
504 When pushing, request the remote server to update refs in a single
505 atomic transaction. If successful, all refs will be updated, or
506 none will. If the remote side does not support this capability, the
507 push will fail.
508 option object-format {true|algorithm}
510 If true, indicate that the caller wants hash algorithm information
511 to be passed back from the remote. This mode is used when fetching
512 refs.
513 If set to an algorithm, indicate that the caller wants to interact
515 with the remote side using that algorithm.
516
518 git-remote(1)
519 git-remote-ext(1)
521 git-remote-fd(1)
523 git-fast-import(1)
525
527 Part of the git(1) suite
528Git 2.43.0 11/20/2023 GITREMOTE-HELPERS(7)