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

NAME

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

SYNOPSIS

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

DESCRIPTION

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
25       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
31       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

INVOCATION

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
46       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
54       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
60       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

INPUT FORMAT

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
73       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
78   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
83       In the following, we list all defined capabilities and for each we list
84       which commands a helper with that capability must provide.
85
86       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
93               Supported commands: connect.
94
95           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
101               Supported commands: stateless-connect.
102
103           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
107               Supported commands: list for-push, push.
108
109           export
110               Can discover remote refs and push specified objects from a
111               fast-import stream to remote refs.
112
113               Supported commands: list for-push, export.
114
115           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
121           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
126       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
133               Supported commands: connect.
134
135           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
141               Supported commands: stateless-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 them
151               as a stream in fast-import format.
152
153               Supported commands: list, import.
154
155           check-connectivity
156               Can guarantee that when a clone is requested, the received pack
157               is self contained and is connected.
158
159           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
165       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
172           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
179               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
184               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
190               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
196           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
211           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
216           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
222           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

COMMANDS

228       Commands are given by the caller on the helper’s standard input, one
229       per line.
230
231       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
237           Support for this command is mandatory.
238
239       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
246           See REF LIST ATTRIBUTES for a list of currently defined attributes.
247
248           Supported if the helper has the "fetch" or "import" capability.
249
250       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
257           Supported if the helper has the "push" or "export" capability.
258
259       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
267           See OPTIONS for a list of currently defined options.
268
269           Supported if the helper has the "option" capability.
270
271       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
279           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
283           If option check-connectivity is requested, the helper must output
284           connectivity-ok if the clone is self-contained and connected.
285
286           Supported if the helper has the "fetch" capability.
287
288       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
299               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
305           Zero or more protocol options may be entered after the last push
306           command, before the batch’s terminating blank line.
307
308           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
314           Supported if the helper has the "push" capability.
315
316       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
325           Especially useful for interoperability with a foreign versioning
326           system.
327
328           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
333           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
338           Supported if the helper has the "import" capability.
339
340       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
345           Especially useful for interoperability with a foreign versioning
346           system.
347
348           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
353           Supported if the helper has the "export" capability.
354
355       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
366           Supported if the helper has the "connect" capability.
367
368       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
382           Supported if the helper has the "stateless-connect" capability.
383
384       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
389       Additional commands may be supported, as may be determined from
390       capabilities reported by the helper.
391

REF LIST ATTRIBUTES

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
397       unchanged
398           This ref is unchanged since the last import or fetch, although the
399           helper cannot necessarily determine what value that produced.
400

OPTIONS

402       The following options are defined and (under suitable circumstances)
403       set by Git if the remote helper has the option capability.
404
405       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
412       option progress {true|false}
413           Enables (or disables) progress messages displayed by the transport
414           helper during a command.
415
416       option depth <depth>
417           Deepens the history of a shallow repository.
418
419       'option deepen-since <timestamp>
420           Deepens the history of a shallow repository based on time.
421
422       'option deepen-not <ref>
423           Deepens the history of a shallow repository excluding ref. Multiple
424           options add up.
425
426       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
430       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
438       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
442       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
447       option check-connectivity {true|false}
448           Request the helper to check connectivity of a clone.
449
450       option force {true|false}
451           Request the helper to perform a force update. Defaults to false.
452
453       option cloning {true|false}
454           Notify the helper this is a clone request (i.e. the current
455           repository is guaranteed empty).
456
457       option update-shallow {true|false}
458           Allow to extend .git/shallow if the new refs require it.
459
460       option pushcert {true|false}
461           GPG sign pushes.
462
463       '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
467       option from-promisor {true|false}
468           Indicate that these objects are being fetched from a promisor.
469
470       option no-dependents {true|false}
471           Indicate that only the objects wanted need to be fetched, not their
472           dependents.
473

SEE ALSO

475       git-remote(1)
476
477       git-remote-ext(1)
478
479       git-remote-fd(1)
480
481       git-remote-testgit(1)
482
483       git-fast-import(1)
484

GIT

486       Part of the git(1) suite
487
488
489
490Git 2.20.1                        12/15/2018              GITREMOTE-HELPERS(1)
Impressum