1GITREMOTE-HELPERS(7)              Git Manual              GITREMOTE-HELPERS(7)
2
3
4

NAME

6       gitremote-helpers - Helper programs to interact with remote
7       repositories
8

SYNOPSIS

10       git remote-<transport> <repository> [<URL>]
11

DESCRIPTION

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
24       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
30       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

INVOCATION

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
45       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
53       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
59       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

INPUT FORMAT

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
72       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
77   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
82       In the following, we list all defined capabilities and for each we list
83       which commands a helper with that capability must provide.
84
85       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
92               Supported commands: connect.
93
94           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
100               Supported commands: stateless-connect.
101
102           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
106               Supported commands: list for-push, push.
107
108           export
109               Can discover remote refs and push specified objects from a
110               fast-import stream to remote refs.
111
112               Supported commands: list for-push, export.
113
114           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
120           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
125       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
132               Supported commands: connect.
133
134           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
140               Supported commands: stateless-connect.
141
142           fetch
143               Can discover remote refs and transfer objects reachable from
144               them to the local object store.
145
146               Supported commands: list, fetch.
147
148           import
149               Can discover remote refs and output objects reachable from them
150               as a stream in fast-import format.
151
152               Supported commands: list, import.
153
154           check-connectivity
155               Can guarantee that when a clone is requested, the received pack
156               is self contained and is connected.
157
158           get
159               Can use the get command to download a file from a given URI.
160
161           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
167       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
174           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
181               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
186               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
192               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
198           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
213           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
218           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
224           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
229           object-format
230               This indicates that the helper is able to interact with the
231               remote side using an explicit hash algorithm extension.
232

COMMANDS

234       Commands are given by the caller on the helper’s standard input, one
235       per line.
236
237       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
243           Support for this command is mandatory.
244
245       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
253           See REF LIST ATTRIBUTES for a list of currently defined attributes.
254           See REF LIST KEYWORDS for a list of currently defined keywords.
255
256           Supported if the helper has the "fetch" or "import" capability.
257
258       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
265           Supported if the helper has the "push" or "export" capability.
266
267       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
275           See OPTIONS for a list of currently defined options.
276
277           Supported if the helper has the "option" capability.
278
279       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
287           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
296           If option check-connectivity is requested, the helper must output
297           connectivity-ok if the clone is self-contained and connected.
298
299           Supported if the helper has the "fetch" capability.
300
301       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
312               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
318           Zero or more protocol options may be entered after the last push
319           command, before the batch’s terminating blank line.
320
321           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
327           Supported if the helper has the "push" capability.
328
329       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
338           Especially useful for interoperability with a foreign versioning
339           system.
340
341           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
346           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
351           Supported if the helper has the "import" capability.
352
353       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
358           Especially useful for interoperability with a foreign versioning
359           system.
360
361           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
366           Supported if the helper has the "export" capability.
367
368       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
379           Supported if the helper has the "connect" capability.
380
381       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
396           Supported if the helper has the "stateless-connect" capability.
397
398       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
404       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
409       Additional commands may be supported, as may be determined from
410       capabilities reported by the helper.
411

REF LIST ATTRIBUTES

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
417       unchanged
418           This ref is unchanged since the last import or fetch, although the
419           helper cannot necessarily determine what value that produced.
420

REF LIST KEYWORDS

422       The list command may produce a list of key-value pairs. The following
423       keys are defined.
424
425       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

OPTIONS

431       The following options are defined and (under suitable circumstances)
432       set by Git if the remote helper has the option capability.
433
434       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
441       option progress {true|false}
442           Enables (or disables) progress messages displayed by the transport
443           helper during a command.
444
445       option depth <depth>
446           Deepens the history of a shallow repository.
447
448       'option deepen-since <timestamp>
449           Deepens the history of a shallow repository based on time.
450
451       'option deepen-not <ref>
452           Deepens the history of a shallow repository excluding ref. Multiple
453           options add up.
454
455       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
459       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
467       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
471       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
476       option check-connectivity {true|false}
477           Request the helper to check connectivity of a clone.
478
479       option force {true|false}
480           Request the helper to perform a force update. Defaults to false.
481
482       option cloning {true|false}
483           Notify the helper this is a clone request (i.e. the current
484           repository is guaranteed empty).
485
486       option update-shallow {true|false}
487           Allow to extend .git/shallow if the new refs require it.
488
489       option pushcert {true|false}
490           GPG sign pushes.
491
492       '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
496       option from-promisor {true|false}
497           Indicate that these objects are being fetched from a promisor.
498
499       option no-dependents {true|false}
500           Indicate that only the objects wanted need to be fetched, not their
501           dependents.
502
503       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
509       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
514           If set to an algorithm, indicate that the caller wants to interact
515           with the remote side using that algorithm.
516

SEE ALSO

518       git-remote(1)
519
520       git-remote-ext(1)
521
522       git-remote-fd(1)
523
524       git-fast-import(1)
525

GIT

527       Part of the git(1) suite
528
529
530
531Git 2.39.1                        2023-01-13              GITREMOTE-HELPERS(7)
Impressum