]>
Commit | Line | Data |
---|---|---|
6eb996b5 DB |
1 | git-remote-helpers(1) |
2 | ===================== | |
3 | ||
4 | NAME | |
5 | ---- | |
00b84e9d | 6 | git-remote-helpers - Helper programs to interact with remote repositories |
6eb996b5 DB |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
b6c8d2d6 | 10 | 'git remote-<transport>' <repository> [<URL>] |
6eb996b5 DB |
11 | |
12 | DESCRIPTION | |
13 | ----------- | |
14 | ||
00b84e9d RR |
15 | Remote helper programs are normally not used directly by end users, |
16 | but they are invoked by git when it needs to interact with remote | |
17 | repositories git does not support natively. A given helper will | |
18 | implement a subset of the capabilities documented here. When git | |
19 | needs to interact with a repository using a remote helper, it spawns | |
20 | the helper as an independent process, sends commands to the helper's | |
21 | standard input, and expects results from the helper's standard | |
22 | output. Because a remote helper runs as an independent process from | |
23 | git, there is no need to re-link git to add a new helper, nor any | |
24 | need to link the helper with the implementation of git. | |
25 | ||
26 | Every helper must support the "capabilities" command, which git will | |
27 | use to determine what other commands the helper will accept. Other | |
28 | commands generally concern facilities like discovering and updating | |
29 | remote refs, transporting objects between the object database and | |
30 | the remote repository, and updating the local object store. | |
31 | ||
32 | Helpers supporting the 'fetch' capability can discover refs from the | |
33 | remote repository and transfer objects reachable from those refs to | |
34 | the local object store. Helpers supporting the 'push' capability can | |
35 | transfer local objects to the remote repository and update remote refs. | |
36 | ||
37 | Git comes with a "curl" family of remote helpers, that handle various | |
38 | transport protocols, such as 'git-remote-http', 'git-remote-https', | |
39 | 'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities | |
40 | 'fetch', 'option', and 'push'. | |
6eb996b5 | 41 | |
b6c8d2d6 RR |
42 | INVOCATION |
43 | ---------- | |
44 | ||
45 | Remote helper programs are invoked with one or (optionally) two | |
46 | arguments. The first argument specifies a remote repository as in git; | |
47 | it is either the name of a configured remote or a URL. The second | |
272a36b6 RR |
48 | argument specifies a URL; it is usually of the form |
49 | '<transport>://<address>', but any arbitrary string is possible. | |
b6c8d2d6 RR |
50 | |
51 | When git encounters a URL of the form '<transport>://<address>', where | |
52 | '<transport>' is a protocol that it cannot handle natively, it | |
53 | automatically invokes 'git remote-<transport>' with the full URL as | |
54 | the second argument. If such a URL is encountered directly on the | |
55 | command line, the first argument is the same as the second, and if it | |
56 | is encountered in a configured remote, the first argument is the name | |
57 | of that remote. | |
58 | ||
59 | A URL of the form '<transport>::<address>' explicitly instructs git to | |
60 | invoke 'git remote-<transport>' with '<address>' as the second | |
61 | argument. If such a URL is encountered directly on the command line, | |
62 | the first argument is '<address>', and if it is encountered in a | |
63 | configured remote, the first argument is the name of that remote. | |
64 | ||
65 | Additionally, when a configured remote has 'remote.<name>.vcs' set to | |
66 | '<transport>', git explicitly invokes 'git remote-<transport>' with | |
67 | '<name>' as the first argument. If set, the second argument is | |
68 | 'remote.<name>.url'; otherwise, the second argument is omitted. | |
69 | ||
6eb996b5 DB |
70 | COMMANDS |
71 | -------- | |
72 | ||
73 | Commands are given by the caller on the helper's standard input, one per line. | |
74 | ||
75 | 'capabilities':: | |
76 | Lists the capabilities of the helper, one per line, ending | |
d43427d3 RR |
77 | with a blank line. Each capability may be preceded with '*', |
78 | which marks them mandatory for git version using the remote | |
28ed5b35 IL |
79 | helper to understand (unknown mandatory capability is fatal |
80 | error). | |
6eb996b5 DB |
81 | |
82 | 'list':: | |
83 | Lists the refs, one per line, in the format "<value> <name> | |
84 | [<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for | |
85 | a symref, or "?" to indicate that the helper could not get the | |
86 | value of the ref. A space-separated list of attributes follows | |
d43427d3 RR |
87 | the name; unrecognized attributes are ignored. The list ends |
88 | with a blank line. | |
ae4efe19 SP |
89 | + |
90 | If 'push' is supported this may be called as 'list for-push' | |
91 | to obtain the current refs prior to sending one or more 'push' | |
92 | commands to the helper. | |
6eb996b5 | 93 | |
ef08ef9e | 94 | 'option' <name> <value>:: |
d43427d3 | 95 | Sets the transport helper option <name> to <value>. Outputs a |
ef08ef9e SP |
96 | single line containing one of 'ok' (option successfully set), |
97 | 'unsupported' (option not recognized) or 'error <msg>' | |
d43427d3 | 98 | (option <name> is supported but <value> is not valid |
ef08ef9e | 99 | for it). Options should be set before other commands, |
d43427d3 | 100 | and may influence the behavior of those commands. |
ef08ef9e SP |
101 | + |
102 | Supported if the helper has the "option" capability. | |
6eb996b5 DB |
103 | |
104 | 'fetch' <sha1> <name>:: | |
292ce46b SP |
105 | Fetches the given object, writing the necessary objects |
106 | to the database. Fetch commands are sent in a batch, one | |
d43427d3 | 107 | per line, terminated with a blank line. |
292ce46b SP |
108 | Outputs a single blank line when all fetch commands in the |
109 | same batch are complete. Only objects which were reported | |
110 | in the ref list with a sha1 may be fetched this way. | |
111 | + | |
112 | Optionally may output a 'lock <file>' line indicating a file under | |
113 | GIT_DIR/objects/pack which is keeping a pack until refs can be | |
114 | suitably updated. | |
6eb996b5 DB |
115 | + |
116 | Supported if the helper has the "fetch" capability. | |
117 | ||
ae4efe19 | 118 | 'push' +<src>:<dst>:: |
d43427d3 | 119 | Pushes the given local <src> commit or branch to the |
ae4efe19 SP |
120 | remote branch described by <dst>. A batch sequence of |
121 | one or more push commands is terminated with a blank line. | |
122 | + | |
123 | Zero or more protocol options may be entered after the last 'push' | |
124 | command, before the batch's terminating blank line. | |
125 | + | |
126 | When the push is complete, outputs one or more 'ok <dst>' or | |
127 | 'error <dst> <why>?' lines to indicate success or failure of | |
128 | each pushed ref. The status report output is terminated by | |
129 | a blank line. The option field <why> may be quoted in a C | |
130 | style string if it contains an LF. | |
131 | + | |
132 | Supported if the helper has the "push" capability. | |
133 | ||
e65e91ed DB |
134 | 'import' <name>:: |
135 | Produces a fast-import stream which imports the current value | |
136 | of the named ref. It may additionally import other refs as | |
72ff8943 DB |
137 | needed to construct the history efficiently. The script writes |
138 | to a helper-specific private namespace. The value of the named | |
139 | ref should be written to a location in this namespace derived | |
140 | by applying the refspecs from the "refspec" capability to the | |
141 | name of the ref. | |
e65e91ed | 142 | + |
d43427d3 RR |
143 | Especially useful for interoperability with a foreign versioning |
144 | system. | |
145 | + | |
e65e91ed DB |
146 | Supported if the helper has the "import" capability. |
147 | ||
fa8c097c IL |
148 | 'connect' <service>:: |
149 | Connects to given service. Standard input and standard output | |
150 | of helper are connected to specified service (git prefix is | |
151 | included in service name so e.g. fetching uses 'git-upload-pack' | |
152 | as service) on remote side. Valid replies to this command are | |
153 | empty line (connection established), 'fallback' (no smart | |
154 | transport support, fall back to dumb transports) and just | |
155 | exiting with error message printed (can't connect, don't | |
156 | bother trying to fall back). After line feed terminating the | |
157 | positive (empty) response, the output of service starts. After | |
158 | the connection ends, the remote helper exits. | |
159 | + | |
160 | Supported if the helper has the "connect" capability. | |
161 | ||
6eb996b5 DB |
162 | If a fatal error occurs, the program writes the error message to |
163 | stderr and exits. The caller should expect that a suitable error | |
164 | message has been printed if the child closes the connection without | |
165 | completing a valid response for the current command. | |
166 | ||
167 | Additional commands may be supported, as may be determined from | |
168 | capabilities reported by the helper. | |
169 | ||
170 | CAPABILITIES | |
171 | ------------ | |
172 | ||
173 | 'fetch':: | |
ef08ef9e | 174 | 'option':: |
ae4efe19 | 175 | 'push':: |
e65e91ed | 176 | 'import':: |
d43427d3 RR |
177 | 'connect':: |
178 | This helper supports the corresponding command with the same name. | |
e65e91ed | 179 | |
72ff8943 DB |
180 | 'refspec' 'spec':: |
181 | When using the import command, expect the source ref to have | |
182 | been written to the destination ref. The earliest applicable | |
183 | refspec takes precedence. For example | |
184 | "refs/heads/*:refs/svn/origin/branches/*" means that, after an | |
185 | "import refs/heads/name", the script has written to | |
186 | refs/svn/origin/branches/name. If this capability is used at | |
187 | all, it must cover all refs reported by the list command; if | |
188 | it is not used, it is effectively "*:*" | |
189 | ||
6eb996b5 DB |
190 | REF LIST ATTRIBUTES |
191 | ------------------- | |
192 | ||
ae4efe19 SP |
193 | 'for-push':: |
194 | The caller wants to use the ref list to prepare push | |
195 | commands. A helper might chose to acquire the ref list by | |
196 | opening a different type of connection to the destination. | |
6eb996b5 | 197 | |
f8ec9167 DB |
198 | 'unchanged':: |
199 | This ref is unchanged since the last import or fetch, although | |
200 | the helper cannot necessarily determine what value that produced. | |
6eb996b5 | 201 | |
ef08ef9e SP |
202 | OPTIONS |
203 | ------- | |
204 | 'option verbosity' <N>:: | |
d43427d3 RR |
205 | Changes the verbosity of messages displayed by the helper. |
206 | A value of 0 for N means that processes operate | |
207 | quietly, and the helper produces only error output. | |
208 | 1 is the default level of verbosity, and higher values | |
ef08ef9e SP |
209 | of N correspond to the number of -v flags passed on the |
210 | command line. | |
211 | ||
212 | 'option progress' \{'true'|'false'\}:: | |
d43427d3 | 213 | Enables (or disables) progress messages displayed by the |
ef08ef9e SP |
214 | transport helper during a command. |
215 | ||
216 | 'option depth' <depth>:: | |
d43427d3 | 217 | Deepens the history of a shallow repository. |
ef08ef9e SP |
218 | |
219 | 'option followtags' \{'true'|'false'\}:: | |
220 | If enabled the helper should automatically fetch annotated | |
221 | tag objects if the object the tag points at was transferred | |
222 | during the fetch command. If the tag is not fetched by | |
223 | the helper a second fetch command will usually be sent to | |
224 | ask for the tag specifically. Some helpers may be able to | |
225 | use this option to avoid a second network connection. | |
226 | ||
ae4efe19 SP |
227 | 'option dry-run' \{'true'|'false'\}: |
228 | If true, pretend the operation completed successfully, | |
229 | but don't actually change any repository data. For most | |
230 | helpers this only applies to the 'push', if supported. | |
231 | ||
fa8c097c | 232 | 'option servpath <c-style-quoted-path>':: |
d43427d3 RR |
233 | Sets service path (--upload-pack, --receive-pack etc.) for |
234 | next connect. Remote helper may support this option, but | |
235 | must not rely on this option being set before | |
fa8c097c IL |
236 | connect request occurs. |
237 | ||
b6c8d2d6 RR |
238 | SEE ALSO |
239 | -------- | |
240 | linkgit:git-remote[1] | |
241 | ||
6eb996b5 DB |
242 | Documentation |
243 | ------------- | |
fa8c097c | 244 | Documentation by Daniel Barkalow and Ilari Liusvaara |
6eb996b5 DB |
245 | |
246 | GIT | |
247 | --- | |
248 | Part of the linkgit:git[1] suite |