]>
Commit | Line | Data |
---|---|---|
6eb996b5 DB |
1 | git-remote-helpers(1) |
2 | ===================== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-remote-helpers - Helper programs for interoperation with remote git | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | 'git remote-<transport>' <remote> | |
11 | ||
12 | DESCRIPTION | |
13 | ----------- | |
14 | ||
15 | These programs are normally not used directly by end users, but are | |
16 | invoked by various git programs that interact with remote repositories | |
17 | when the repository they would operate on will be accessed using | |
18 | transport code not linked into the main git binary. Various particular | |
19 | helper programs will behave as documented here. | |
20 | ||
21 | COMMANDS | |
22 | -------- | |
23 | ||
24 | Commands are given by the caller on the helper's standard input, one per line. | |
25 | ||
26 | 'capabilities':: | |
27 | Lists the capabilities of the helper, one per line, ending | |
6a5d0b0a | 28 | with a blank line. Each capability may be preceded with '*'. |
28ed5b35 IL |
29 | This marks them mandatory for git version using the remote |
30 | helper to understand (unknown mandatory capability is fatal | |
31 | error). | |
6eb996b5 DB |
32 | |
33 | 'list':: | |
34 | Lists the refs, one per line, in the format "<value> <name> | |
35 | [<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for | |
36 | a symref, or "?" to indicate that the helper could not get the | |
37 | value of the ref. A space-separated list of attributes follows | |
38 | the name; unrecognized attributes are ignored. After the | |
39 | complete list, outputs a blank line. | |
ae4efe19 SP |
40 | + |
41 | If 'push' is supported this may be called as 'list for-push' | |
42 | to obtain the current refs prior to sending one or more 'push' | |
43 | commands to the helper. | |
6eb996b5 | 44 | |
ef08ef9e SP |
45 | 'option' <name> <value>:: |
46 | Set the transport helper option <name> to <value>. Outputs a | |
47 | single line containing one of 'ok' (option successfully set), | |
48 | 'unsupported' (option not recognized) or 'error <msg>' | |
49 | (option <name> is supported but <value> is not correct | |
50 | for it). Options should be set before other commands, | |
51 | and may how those commands behave. | |
52 | + | |
53 | Supported if the helper has the "option" capability. | |
6eb996b5 DB |
54 | |
55 | 'fetch' <sha1> <name>:: | |
292ce46b SP |
56 | Fetches the given object, writing the necessary objects |
57 | to the database. Fetch commands are sent in a batch, one | |
58 | per line, and the batch is terminated with a blank line. | |
59 | Outputs a single blank line when all fetch commands in the | |
60 | same batch are complete. Only objects which were reported | |
61 | in the ref list with a sha1 may be fetched this way. | |
62 | + | |
63 | Optionally may output a 'lock <file>' line indicating a file under | |
64 | GIT_DIR/objects/pack which is keeping a pack until refs can be | |
65 | suitably updated. | |
6eb996b5 DB |
66 | + |
67 | Supported if the helper has the "fetch" capability. | |
68 | ||
ae4efe19 SP |
69 | 'push' +<src>:<dst>:: |
70 | Pushes the given <src> commit or branch locally to the | |
71 | remote branch described by <dst>. A batch sequence of | |
72 | one or more push commands is terminated with a blank line. | |
73 | + | |
74 | Zero or more protocol options may be entered after the last 'push' | |
75 | command, before the batch's terminating blank line. | |
76 | + | |
77 | When the push is complete, outputs one or more 'ok <dst>' or | |
78 | 'error <dst> <why>?' lines to indicate success or failure of | |
79 | each pushed ref. The status report output is terminated by | |
80 | a blank line. The option field <why> may be quoted in a C | |
81 | style string if it contains an LF. | |
82 | + | |
83 | Supported if the helper has the "push" capability. | |
84 | ||
e65e91ed DB |
85 | 'import' <name>:: |
86 | Produces a fast-import stream which imports the current value | |
87 | of the named ref. It may additionally import other refs as | |
72ff8943 DB |
88 | needed to construct the history efficiently. The script writes |
89 | to a helper-specific private namespace. The value of the named | |
90 | ref should be written to a location in this namespace derived | |
91 | by applying the refspecs from the "refspec" capability to the | |
92 | name of the ref. | |
e65e91ed DB |
93 | + |
94 | Supported if the helper has the "import" capability. | |
95 | ||
fa8c097c IL |
96 | 'connect' <service>:: |
97 | Connects to given service. Standard input and standard output | |
98 | of helper are connected to specified service (git prefix is | |
99 | included in service name so e.g. fetching uses 'git-upload-pack' | |
100 | as service) on remote side. Valid replies to this command are | |
101 | empty line (connection established), 'fallback' (no smart | |
102 | transport support, fall back to dumb transports) and just | |
103 | exiting with error message printed (can't connect, don't | |
104 | bother trying to fall back). After line feed terminating the | |
105 | positive (empty) response, the output of service starts. After | |
106 | the connection ends, the remote helper exits. | |
107 | + | |
108 | Supported if the helper has the "connect" capability. | |
109 | ||
6eb996b5 DB |
110 | If a fatal error occurs, the program writes the error message to |
111 | stderr and exits. The caller should expect that a suitable error | |
112 | message has been printed if the child closes the connection without | |
113 | completing a valid response for the current command. | |
114 | ||
115 | Additional commands may be supported, as may be determined from | |
116 | capabilities reported by the helper. | |
117 | ||
118 | CAPABILITIES | |
119 | ------------ | |
120 | ||
121 | 'fetch':: | |
122 | This helper supports the 'fetch' command. | |
123 | ||
ef08ef9e SP |
124 | 'option':: |
125 | This helper supports the option command. | |
126 | ||
ae4efe19 SP |
127 | 'push':: |
128 | This helper supports the 'push' command. | |
129 | ||
e65e91ed DB |
130 | 'import':: |
131 | This helper supports the 'import' command. | |
132 | ||
72ff8943 DB |
133 | 'refspec' 'spec':: |
134 | When using the import command, expect the source ref to have | |
135 | been written to the destination ref. The earliest applicable | |
136 | refspec takes precedence. For example | |
137 | "refs/heads/*:refs/svn/origin/branches/*" means that, after an | |
138 | "import refs/heads/name", the script has written to | |
139 | refs/svn/origin/branches/name. If this capability is used at | |
140 | all, it must cover all refs reported by the list command; if | |
141 | it is not used, it is effectively "*:*" | |
142 | ||
fa8c097c IL |
143 | 'connect':: |
144 | This helper supports the 'connect' command. | |
145 | ||
6eb996b5 DB |
146 | REF LIST ATTRIBUTES |
147 | ------------------- | |
148 | ||
ae4efe19 SP |
149 | 'for-push':: |
150 | The caller wants to use the ref list to prepare push | |
151 | commands. A helper might chose to acquire the ref list by | |
152 | opening a different type of connection to the destination. | |
6eb996b5 | 153 | |
f8ec9167 DB |
154 | 'unchanged':: |
155 | This ref is unchanged since the last import or fetch, although | |
156 | the helper cannot necessarily determine what value that produced. | |
6eb996b5 | 157 | |
ef08ef9e SP |
158 | OPTIONS |
159 | ------- | |
160 | 'option verbosity' <N>:: | |
161 | Change the level of messages displayed by the helper. | |
162 | When N is 0 the end-user has asked the process to be | |
163 | quiet, and the helper should produce only error output. | |
164 | N of 1 is the default level of verbosity, higher values | |
165 | of N correspond to the number of -v flags passed on the | |
166 | command line. | |
167 | ||
168 | 'option progress' \{'true'|'false'\}:: | |
169 | Enable (or disable) progress messages displayed by the | |
170 | transport helper during a command. | |
171 | ||
172 | 'option depth' <depth>:: | |
173 | Deepen the history of a shallow repository. | |
174 | ||
175 | 'option followtags' \{'true'|'false'\}:: | |
176 | If enabled the helper should automatically fetch annotated | |
177 | tag objects if the object the tag points at was transferred | |
178 | during the fetch command. If the tag is not fetched by | |
179 | the helper a second fetch command will usually be sent to | |
180 | ask for the tag specifically. Some helpers may be able to | |
181 | use this option to avoid a second network connection. | |
182 | ||
ae4efe19 SP |
183 | 'option dry-run' \{'true'|'false'\}: |
184 | If true, pretend the operation completed successfully, | |
185 | but don't actually change any repository data. For most | |
186 | helpers this only applies to the 'push', if supported. | |
187 | ||
fa8c097c IL |
188 | 'option servpath <c-style-quoted-path>':: |
189 | Set service path (--upload-pack, --receive-pack etc.) for | |
190 | next connect. Remote helper MAY support this option. Remote | |
191 | helper MUST NOT rely on this option being set before | |
192 | connect request occurs. | |
193 | ||
6eb996b5 DB |
194 | Documentation |
195 | ------------- | |
fa8c097c | 196 | Documentation by Daniel Barkalow and Ilari Liusvaara |
6eb996b5 DB |
197 | |
198 | GIT | |
199 | --- | |
200 | Part of the linkgit:git[1] suite |