1GITREMOTE-HELPERS(1) Git Manual GITREMOTE-HELPERS(1)
2
6 gitremote-helpers - Helper programs to interact with remote
7 repositories
8
10 git remote-<transport> <repository> [<URL>]
11
14 Remote helper programs are normally not used directly by end users, but
15 they are invoked by Git when it needs to interact with remote
16 repositories Git does not support natively. A given helper will
17 implement a subset of the capabilities documented here. When Git needs
18 to interact with a repository using a remote helper, it spawns the
19 helper as an independent process, sends commands to the helper’s
20 standard input, and expects results from the helper’s standard output.
21 Because a remote helper runs as an independent process from Git, there
22 is no need to re-link Git to add a new helper, nor any need to link the
23 helper with the implementation of Git.
24 Every helper must support the "capabilities" command, which Git uses to
26 determine what other commands the helper will accept. Those other
27 commands can be used to discover and update remote refs, transport
28 objects between the object database and the remote repository, and
29 update the local object store.
30 Git comes with a "curl" family of remote helpers, that handle various
32 transport protocols, such as git-remote-http, git-remote-https,
33 git-remote-ftp and git-remote-ftps. They implement the capabilities
34 fetch, option, and push.
35
37 Remote helper programs are invoked with one or (optionally) two
38 arguments. The first argument specifies a remote repository as in Git;
39 it is either the name of a configured remote or a URL. The second
40 argument specifies a URL; it is usually of the form
41 <transport>://<address>, but any arbitrary string is possible. The
42 GIT_DIR environment variable is set up for the remote helper and can be
43 used to determine where to store additional data or from which
44 directory to invoke auxiliary Git commands.
45 When Git encounters a URL of the form <transport>://<address>, where
47 <transport> is a protocol that it cannot handle natively, it
48 automatically invokes git remote-<transport> with the full URL as the
49 second argument. If such a URL is encountered directly on the command
50 line, the first argument is the same as the second, and if it is
51 encountered in a configured remote, the first argument is the name of
52 that remote.
53 A URL of the form <transport>::<address> explicitly instructs Git to
55 invoke git remote-<transport> with <address> as the second argument. If
56 such a URL is encountered directly on the command line, the first
57 argument is <address>, and if it is encountered in a configured remote,
58 the first argument is the name of that remote.
59 Additionally, when a configured remote has remote.<name>.vcs set to
61 <transport>, Git explicitly invokes git remote-<transport> with <name>
62 as the first argument. If set, the second argument is
63 remote.<name>.url; otherwise, the second argument is omitted.
64
66 Git sends the remote helper a list of commands on standard input, one
67 per line. The first command is always the capabilities command, in
68 response to which the remote helper must print a list of the
69 capabilities it supports (see below) followed by a blank line. The
70 response to the capabilities command determines what commands Git uses
71 in the remainder of the command stream.
72 The command stream is terminated by a blank line. In some cases
74 (indicated in the documentation of the relevant commands), this blank
75 line is followed by a payload in some other protocol (e.g., the pack
76 protocol), while in others it indicates the end of input.
77 Capabilities
79 Each remote helper is expected to support only a subset of commands.
80 The operations a helper supports are declared to Git in the response to
81 the capabilities command (see COMMANDS, below).
82 In the following, we list all defined capabilities and for each we list
84 which commands a helper with that capability must provide.
85 Capabilities for Pushing
87 connect
88 Can attempt to connect to git receive-pack (for pushing), git
89 upload-pack, etc for communication using git’s native packfile
90 protocol. This requires a bidirectional, full-duplex
91 connection.
92 Supported commands: connect.
94 push
96 Can discover remote refs and push local commits and the history
97 leading up to them to new or existing remote refs.
98 Supported commands: list for-push, push.
100 export
102 Can discover remote refs and push specified objects from a
103 fast-import stream to remote refs.
104 Supported commands: list for-push, export.
106 If a helper advertises connect, Git will use it if possible and
108 fall back to another capability if the helper requests so when
109 connecting (see the connect command under COMMANDS). When choosing
110 between push and export, Git prefers push. Other frontends may have
111 some other order of preference.
112 Capabilities for Fetching
114 connect
115 Can try to connect to git upload-pack (for fetching), git
116 receive-pack, etc for communication using the Git’s native
117 packfile protocol. This requires a bidirectional, full-duplex
118 connection.
119 Supported commands: connect.
121 fetch
123 Can discover remote refs and transfer objects reachable from
124 them to the local object store.
125 Supported commands: list, fetch.
127 import
129 Can discover remote refs and output objects reachable from them
130 as a stream in fast-import format.
131 Supported commands: list, import.
133 If a helper advertises connect, Git will use it if possible and
135 fall back to another capability if the helper requests so when
136 connecting (see the connect command under COMMANDS). When choosing
137 between fetch and import, Git prefers fetch. Other frontends may
138 have some other order of preference.
139 Miscellaneous capabilities
141 option
142 For specifying settings like verbosity (how much output to
143 write to stderr) and depth (how much history is wanted in the
144 case of a shallow clone) that affect how other commands are
145 carried out.
146 refspec <refspec>
148 This modifies the import capability, allowing the produced
149 fast-import stream to modify refs in a private namespace
150 instead of writing to refs/heads or refs/remotes directly. It
151 is recommended that all importers providing the import
152 capability use this.
153 A helper advertising the capability refspec
155 refs/heads/*:refs/svn/origin/branches/* is saying that, when it
156 is asked to import refs/heads/topic, the stream it outputs will
157 update the refs/svn/origin/branches/topic ref.
158 This capability can be advertised multiple times. The first
160 applicable refspec takes precedence. The left-hand of refspecs
161 advertised with this capability must cover all refs reported by
162 the list command. If a helper does not need a specific refspec
163 capability then it should advertise refspec *:*.
164 bidi-import
166 This modifies the import capability. The fast-import commands
167 cat-blob and ls can be used by remote-helpers to retrieve
168 information about blobs and trees that already exist in
169 fast-import’s memory. This requires a channel from fast-import
170 to the remote-helper. If it is advertised in addition to
171 "import", Git establishes a pipe from fast-import to the
172 remote-helper’s stdin. It follows that Git and fast-import are
173 both connected to the remote-helper’s stdin. Because Git can
174 send multiple commands to the remote-helper it is required that
175 helpers that use bidi-import buffer all import commands of a
176 batch before sending data to fast-import. This is to prevent
177 mixing commands and fast-import responses on the helper’s
178 stdin.
179 export-marks <file>
181 This modifies the export capability, instructing Git to dump
182 the internal marks table to <file> when complete. For details,
183 read up on --export-marks=<file> in git-fast-export(1).
184 import-marks <file>
186 This modifies the export capability, instructing Git to load
187 the marks specified in <file> before processing any input. For
188 details, read up on --import-marks=<file> in git-fast-
189 export(1).
190 signed-tags
192 This modifies the export capability, instructing Git to pass
193 --signed-tags=verbatim to git-fast-export(1). In the absence of
194 this capability, Git will use --signed-tags=warn-strip.
195
197 Commands are given by the caller on the helper’s standard input, one
198 per line.
199 capabilities
201 Lists the capabilities of the helper, one per line, ending with a
202 blank line. Each capability may be preceded with *, which marks
203 them mandatory for Git versions using the remote helper to
204 understand. Any unknown mandatory capability is a fatal error.
205 Support for this command is mandatory.
207 list
209 Lists the refs, one per line, in the format "<value> <name> [<attr>
210 ...]". The value may be a hex sha1 hash, "@<dest>" for a symref, or
211 "?" to indicate that the helper could not get the value of the ref.
212 A space-separated list of attributes follows the name; unrecognized
213 attributes are ignored. The list ends with a blank line.
214 See REF LIST ATTRIBUTES for a list of currently defined attributes.
216 Supported if the helper has the "fetch" or "import" capability.
218 list for-push
220 Similar to list, except that it is used if and only if the caller
221 wants to the resulting ref list to prepare push commands. A helper
222 supporting both push and fetch can use this to distinguish for
223 which operation the output of list is going to be used, possibly
224 reducing the amount of work that needs to be performed.
225 Supported if the helper has the "push" or "export" capability.
227 option <name> <value>
229 Sets the transport helper option <name> to <value>. Outputs a
230 single line containing one of ok (option successfully set),
231 unsupported (option not recognized) or error <msg> (option <name>
232 is supported but <value> is not valid for it). Options should be
233 set before other commands, and may influence the behavior of those
234 commands.
235 See OPTIONS for a list of currently defined options.
237 Supported if the helper has the "option" capability.
239 fetch <sha1> <name>
241 Fetches the given object, writing the necessary objects to the
242 database. Fetch commands are sent in a batch, one per line,
243 terminated with a blank line. Outputs a single blank line when all
244 fetch commands in the same batch are complete. Only objects which
245 were reported in the output of list with a sha1 may be fetched this
246 way.
247 Optionally may output a lock <file> line indicating a file under
249 GIT_DIR/objects/pack which is keeping a pack until refs can be
250 suitably updated.
251 Supported if the helper has the "fetch" capability.
253 push +<src>:<dst>
255 Pushes the given local <src> commit or branch to the remote branch
256 described by <dst>. A batch sequence of one or more push commands
257 is terminated with a blank line (if there is only one reference to
258 push, a single push command is followed by a blank line). For
259 example, the following would be two batches of push, the first
260 asking the remote-helper to push the local ref master to the remote
261 ref master and the local HEAD to the remote branch, and the second
262 asking to push ref foo to ref bar (forced update requested by the
263 +).
264 push refs/heads/master:refs/heads/master
266 push HEAD:refs/heads/branch
267 \n
268 push +refs/heads/foo:refs/heads/bar
269 \n
270 Zero or more protocol options may be entered after the last push
272 command, before the batch’s terminating blank line.
273 When the push is complete, outputs one or more ok <dst> or error
275 <dst> <why>? lines to indicate success or failure of each pushed
276 ref. The status report output is terminated by a blank line. The
277 option field <why> may be quoted in a C style string if it contains
278 an LF.
279 Supported if the helper has the "push" capability.
281 import <name>
283 Produces a fast-import stream which imports the current value of
284 the named ref. It may additionally import other refs as needed to
285 construct the history efficiently. The script writes to a
286 helper-specific private namespace. The value of the named ref
287 should be written to a location in this namespace derived by
288 applying the refspecs from the "refspec" capability to the name of
289 the ref.
290 Especially useful for interoperability with a foreign versioning
292 system.
293 Just like push, a batch sequence of one or more import is
295 terminated with a blank line. For each batch of import, the remote
296 helper should produce a fast-import stream terminated by a done
297 command.
298 Note that if the bidi-import capability is used the complete batch
300 sequence has to be buffered before starting to send data to
301 fast-import to prevent mixing of commands and fast-import responses
302 on the helper’s stdin.
303 Supported if the helper has the "import" capability.
305 export
307 Instructs the remote helper that any subsequent input is part of a
308 fast-import stream (generated by git fast-export) containing
309 objects which should be pushed to the remote.
310 Especially useful for interoperability with a foreign versioning
312 system.
313 The export-marks and import-marks capabilities, if specified,
315 affect this command in so far as they are passed on to git
316 fast-export, which then will load/store a table of marks for local
317 objects. This can be used to implement for incremental operations.
318 Supported if the helper has the "export" capability.
320 connect <service>
322 Connects to given service. Standard input and standard output of
323 helper are connected to specified service (git prefix is included
324 in service name so e.g. fetching uses git-upload-pack as service)
325 on remote side. Valid replies to this command are empty line
326 (connection established), fallback (no smart transport support,
327 fall back to dumb transports) and just exiting with error message
328 printed (can’t connect, don’t bother trying to fall back). After
329 line feed terminating the positive (empty) response, the output of
330 service starts. After the connection ends, the remote helper exits.
331 Supported if the helper has the "connect" capability.
333 If a fatal error occurs, the program writes the error message to stderr
335 and exits. The caller should expect that a suitable error message has
336 been printed if the child closes the connection without completing a
337 valid response for the current command.
338 Additional commands may be supported, as may be determined from
340 capabilities reported by the helper.
341
343 The list command produces a list of refs in which each ref may be
344 followed by a list of attributes. The following ref list attributes are
345 defined.
346 unchanged
348 This ref is unchanged since the last import or fetch, although the
349 helper cannot necessarily determine what value that produced.
350
352 The following options are defined and (under suitable circumstances)
353 set by Git if the remote helper has the option capability.
354 option verbosity <n>
356 Changes the verbosity of messages displayed by the helper. A value
357 of 0 for <n> means that processes operate quietly, and the helper
358 produces only error output. 1 is the default level of verbosity,
359 and higher values of <n> correspond to the number of -v flags
360 passed on the command line.
361 option progress {true|false}
363 Enables (or disables) progress messages displayed by the transport
364 helper during a command.
365 option depth <depth>
367 Deepens the history of a shallow repository.
368 option followtags {true|false}
370 If enabled the helper should automatically fetch annotated tag
371 objects if the object the tag points at was transferred during the
372 fetch command. If the tag is not fetched by the helper a second
373 fetch command will usually be sent to ask for the tag specifically.
374 Some helpers may be able to use this option to avoid a second
375 network connection.
376 option dry-run {true|false}: If true, pretend the operation completed
378 successfully, but don’t actually change any repository data. For most
379 helpers this only applies to the push, if supported.
380 option servpath <c-style-quoted-path>
382 Sets service path (--upload-pack, --receive-pack etc.) for next
383 connect. Remote helper may support this option, but must not rely
384 on this option being set before connect request occurs.
385
387 git-remote(1)
388 git-remote-testgit(1)
390
392 Part of the git(1) suite
393Git 1.8.3.1 11/19/2018 GITREMOTE-HELPERS(1)