]>
Commit | Line | Data |
---|---|---|
bdd18829 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
bdd18829 | 3 | * |
bb742ede VM |
4 | * This file is part of libgit2, distributed under the GNU GPL v2 with |
5 | * a Linking Exception. For full terms see the included COPYING file. | |
bdd18829 | 6 | */ |
9c82357b CMN |
7 | #ifndef INCLUDE_git_remote_h__ |
8 | #define INCLUDE_git_remote_h__ | |
9 | ||
2cbca8b0 VM |
10 | #include "common.h" |
11 | #include "repository.h" | |
12 | #include "refspec.h" | |
d88d4311 | 13 | #include "net.h" |
dee5515a | 14 | #include "indexer.h" |
b46708aa | 15 | #include "strarray.h" |
41fb1ca0 | 16 | #include "transport.h" |
d88d4311 | 17 | |
1e76676f CMN |
18 | /** |
19 | * @file git2/remote.h | |
20 | * @brief Git remote management functions | |
21 | * @defgroup git_remote remote management functions | |
22 | * @ingroup Git | |
23 | * @{ | |
24 | */ | |
25 | GIT_BEGIN_DECL | |
9c82357b | 26 | |
df705148 | 27 | typedef int (*git_remote_rename_problem_cb)(const char *problematic_refspec, void *payload); |
f8f3feb0 CMN |
28 | /* |
29 | * TODO: This functions still need to be implemented: | |
30 | * - _listcb/_foreach | |
31 | * - _add | |
32 | * - _rename | |
33 | * - _del (needs support from config) | |
34 | */ | |
35 | ||
29f27599 | 36 | /** |
87bc689f BS |
37 | * Add a remote with the default fetch refspec to the repository's configuration. This |
38 | * calls git_remote_save before returning. | |
29f27599 BS |
39 | * |
40 | * @param out the resulting remote | |
41 | * @param repo the repository in which to create the remote | |
42 | * @param name the remote's name | |
43 | * @param url the remote's url | |
f19304d2 | 44 | * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code |
29f27599 BS |
45 | */ |
46 | GIT_EXTERN(int) git_remote_create( | |
47 | git_remote **out, | |
48 | git_repository *repo, | |
49 | const char *name, | |
50 | const char *url); | |
51 | ||
778e1c73 | 52 | /** |
617bfdf4 | 53 | * Create a remote in memory |
778e1c73 | 54 | * |
29f27599 | 55 | * Create a remote with the given refspec in memory. You can use |
87bc689f BS |
56 | * this when you have a URL instead of a remote's name. Note that in-memory |
57 | * remotes cannot be converted to persisted remotes. | |
778e1c73 | 58 | * |
032ba9e4 | 59 | * The name, when provided, will be checked for validity. |
60 | * See `git_tag_create()` for rules about valid names. | |
61 | * | |
778e1c73 | 62 | * @param out pointer to the new remote object |
3874f2d5 | 63 | * @param repo the associated repository |
a71c27cc | 64 | * @param fetch the fetch refspec to use for this remote. May be NULL for defaults. |
0642c143 | 65 | * @param url the remote repository's URL |
ae35aa07 | 66 | * @return 0 or an error code |
778e1c73 | 67 | */ |
29f27599 BS |
68 | GIT_EXTERN(int) git_remote_create_inmemory( |
69 | git_remote **out, | |
70 | git_repository *repo, | |
0642c143 BS |
71 | const char *fetch, |
72 | const char *url); | |
778e1c73 | 73 | |
9c82357b CMN |
74 | /** |
75 | * Get the information for a particular remote | |
76 | * | |
032ba9e4 | 77 | * The name will be checked for validity. |
78 | * See `git_tag_create()` for rules about valid names. | |
79 | * | |
9c82357b | 80 | * @param out pointer to the new remote object |
b0b80658 | 81 | * @param repo the associated repository |
9c82357b | 82 | * @param name the remote's name |
032ba9e4 | 83 | * @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code |
9c82357b | 84 | */ |
9462c471 | 85 | GIT_EXTERN(int) git_remote_load(git_remote **out, git_repository *repo, const char *name); |
9c82357b | 86 | |
89e5ed98 CMN |
87 | /** |
88 | * Save a remote to its repository's configuration | |
89 | * | |
ae35aa07 | 90 | * One can't save a in-memory remote. Doing so will |
032ba9e4 | 91 | * result in a GIT_EINVALIDSPEC being returned. |
92 | * | |
89e5ed98 | 93 | * @param remote the remote to save to config |
032ba9e4 | 94 | * @return 0, GIT_EINVALIDSPEC or an error code |
89e5ed98 CMN |
95 | */ |
96 | GIT_EXTERN(int) git_remote_save(const git_remote *remote); | |
97 | ||
9c82357b CMN |
98 | /** |
99 | * Get the remote's name | |
100 | * | |
101 | * @param remote the remote | |
b0aa14aa | 102 | * @return a pointer to the name or NULL for in-memory remotes |
9c82357b | 103 | */ |
df705148 | 104 | GIT_EXTERN(const char *) git_remote_name(const git_remote *remote); |
9c82357b CMN |
105 | |
106 | /** | |
107 | * Get the remote's url | |
108 | * | |
109 | * @param remote the remote | |
110 | * @return a pointer to the url | |
111 | */ | |
df705148 | 112 | GIT_EXTERN(const char *) git_remote_url(const git_remote *remote); |
9c82357b | 113 | |
76501590 SC |
114 | /** |
115 | * Get the remote's url for pushing | |
116 | * | |
117 | * @param remote the remote | |
118 | * @return a pointer to the url or NULL if no special url for pushing is set | |
119 | */ | |
df705148 | 120 | GIT_EXTERN(const char *) git_remote_pushurl(const git_remote *remote); |
76501590 SC |
121 | |
122 | /** | |
123 | * Set the remote's url | |
124 | * | |
125 | * Existing connections will not be updated. | |
126 | * | |
127 | * @param remote the remote | |
128 | * @param url the url to set | |
129 | * @return 0 or an error value | |
130 | */ | |
131 | GIT_EXTERN(int) git_remote_set_url(git_remote *remote, const char* url); | |
132 | ||
133 | /** | |
134 | * Set the remote's url for pushing | |
135 | * | |
136 | * Existing connections will not be updated. | |
137 | * | |
138 | * @param remote the remote | |
139 | * @param url the url to set or NULL to clear the pushurl | |
140 | * @return 0 or an error value | |
141 | */ | |
142 | GIT_EXTERN(int) git_remote_set_pushurl(git_remote *remote, const char* url); | |
143 | ||
bcb8c007 | 144 | /** |
4330ab26 | 145 | * Add a fetch refspec to the remote |
bcb8c007 CMN |
146 | * |
147 | * @param remote the remote | |
4330ab26 | 148 | * @apram refspec the new fetch refspec |
e172cf08 | 149 | * @return 0 or an error value |
bcb8c007 | 150 | */ |
bc6374ea CMN |
151 | GIT_EXTERN(int) git_remote_add_fetch(git_remote *remote, const char *refspec); |
152 | ||
153 | /** | |
154 | * Get the remote's list of fetch refspecs | |
155 | * | |
156 | * The memory is owned by the user and should be freed with | |
157 | * `git_strarray_free`. | |
158 | * | |
159 | * @param array pointer to the array in which to store the strings | |
160 | * @param remote the remote to query | |
161 | */ | |
162 | GIT_EXTERN(int) git_remote_get_fetch_refspecs(git_strarray *array, git_remote *remote); | |
bcb8c007 | 163 | |
9c82357b | 164 | /** |
4330ab26 | 165 | * Add a push refspec to the remote |
9c82357b CMN |
166 | * |
167 | * @param remote the remote | |
4330ab26 | 168 | * @param refspec the new push refspec |
e172cf08 | 169 | * @return 0 or an error value |
bcb8c007 | 170 | */ |
bc6374ea CMN |
171 | GIT_EXTERN(int) git_remote_add_push(git_remote *remote, const char *refspec); |
172 | ||
173 | /** | |
174 | * Get the remote's list of push refspecs | |
175 | * | |
176 | * The memory is owned by the user and should be freed with | |
177 | * `git_strarray_free`. | |
178 | * | |
179 | * @param array pointer to the array in which to store the strings | |
180 | * @param remote the remote to query | |
181 | */ | |
182 | GIT_EXTERN(int) git_remote_get_push_refspecs(git_strarray *array, git_remote *remote); | |
bcb8c007 | 183 | |
4330ab26 CMN |
184 | /** |
185 | * Clear the refspecs | |
186 | * | |
187 | * Remove all configured fetch and push refspecs from the remote. | |
188 | * | |
189 | * @param remote the remote | |
190 | */ | |
191 | GIT_EXTERN(void) git_remote_clear_refspecs(git_remote *remote); | |
192 | ||
9ba49bb5 CMN |
193 | /** |
194 | * Open a connection to a remote | |
195 | * | |
e1d88030 CMN |
196 | * The transport is selected based on the URL. The direction argument |
197 | * is due to a limitation of the git protocol (over TCP or SSH) which | |
198 | * starts up a specific binary which can only do the one or the other. | |
9ba49bb5 CMN |
199 | * |
200 | * @param remote the remote to connect to | |
4a38143c CMN |
201 | * @param direction GIT_DIRECTION_FETCH if you want to fetch or |
202 | * GIT_DIRECTION_PUSH if you want to push | |
e172cf08 | 203 | * @return 0 or an error code |
9ba49bb5 | 204 | */ |
df705148 | 205 | GIT_EXTERN(int) git_remote_connect(git_remote *remote, git_direction direction); |
9ba49bb5 CMN |
206 | |
207 | /** | |
208 | * Get a list of refs at the remote | |
209 | * | |
6616e207 CMN |
210 | * The remote (or more exactly its transport) must be connected. The |
211 | * memory belongs to the remote. | |
9ba49bb5 | 212 | * |
5dca2010 RB |
213 | * If you a return a non-zero value from the callback, this will stop |
214 | * looping over the refs. | |
215 | * | |
9ba49bb5 | 216 | * @param remote the remote |
b0b80658 BS |
217 | * @param list_cb function to call with each ref discovered at the remote |
218 | * @param payload additional data to pass to the callback | |
5dca2010 | 219 | * @return 0 on success, GIT_EUSER on non-zero callback, or error code |
9ba49bb5 | 220 | */ |
d88d4311 | 221 | GIT_EXTERN(int) git_remote_ls(git_remote *remote, git_headlist_cb list_cb, void *payload); |
9ba49bb5 | 222 | |
48a65a07 CMN |
223 | /** |
224 | * Download the packfile | |
225 | * | |
95057b85 CMN |
226 | * Negotiate what objects should be downloaded and download the |
227 | * packfile with those objects. The packfile is downloaded with a | |
228 | * temporary filename, as it's final name is not known yet. If there | |
229 | * was no packfile needed (all the objects were available locally), | |
230 | * filename will be NULL and the function will return success. | |
48a65a07 CMN |
231 | * |
232 | * @param remote the remote to download from | |
c70ad945 BS |
233 | * @param progress_cb function to call with progress information. Be aware that |
234 | * this is called inline with network and indexing operations, so performance | |
235 | * may be affected. | |
216863c4 | 236 | * @param progress_payload payload for the progress callback |
e172cf08 | 237 | * @return 0 or an error code |
48a65a07 | 238 | */ |
216863c4 BS |
239 | GIT_EXTERN(int) git_remote_download( |
240 | git_remote *remote, | |
7d222e13 | 241 | git_transfer_progress_callback progress_cb, |
df705148 | 242 | void *payload); |
48a65a07 | 243 | |
6ac3b707 CMN |
244 | /** |
245 | * Check whether the remote is connected | |
246 | * | |
247 | * Check whether the remote's underlying transport is connected to the | |
248 | * remote host. | |
249 | * | |
b0b80658 | 250 | * @param remote the remote |
6ac3b707 CMN |
251 | * @return 1 if it's connected, 0 otherwise. |
252 | */ | |
253 | GIT_EXTERN(int) git_remote_connected(git_remote *remote); | |
254 | ||
f0d2ddbb CMN |
255 | /** |
256 | * Cancel the operation | |
257 | * | |
258 | * At certain points in its operation, the network code checks whether | |
259 | * the operation has been cancelled and if so stops the operation. | |
b0b80658 BS |
260 | * |
261 | * @param remote the remote | |
f0d2ddbb CMN |
262 | */ |
263 | GIT_EXTERN(void) git_remote_stop(git_remote *remote); | |
264 | ||
4cf01e9a CMN |
265 | /** |
266 | * Disconnect from the remote | |
267 | * | |
268 | * Close the connection to the remote and free the underlying | |
269 | * transport. | |
270 | * | |
271 | * @param remote the remote to disconnect from | |
272 | */ | |
273 | GIT_EXTERN(void) git_remote_disconnect(git_remote *remote); | |
274 | ||
9c82357b CMN |
275 | /** |
276 | * Free the memory associated with a remote | |
277 | * | |
8af503bc MS |
278 | * This also disconnects from the remote, if the connection |
279 | * has not been closed yet (using git_remote_disconnect). | |
280 | * | |
9c82357b CMN |
281 | * @param remote the remote to free |
282 | */ | |
9462c471 | 283 | GIT_EXTERN(void) git_remote_free(git_remote *remote); |
9c82357b | 284 | |
441f57c2 CMN |
285 | /** |
286 | * Update the tips to the new state | |
287 | * | |
441f57c2 | 288 | * @param remote the remote to update |
b0b80658 | 289 | * @return 0 or an error code |
441f57c2 | 290 | */ |
b3aaa7a7 | 291 | GIT_EXTERN(int) git_remote_update_tips(git_remote *remote); |
441f57c2 | 292 | |
d88d4311 VM |
293 | /** |
294 | * Return whether a string is a valid remote URL | |
295 | * | |
d73c94b2 | 296 | * @param url the url to check |
d88d4311 VM |
297 | * @param 1 if the url is valid, 0 otherwise |
298 | */ | |
299 | GIT_EXTERN(int) git_remote_valid_url(const char *url); | |
300 | ||
4f8efc97 CMN |
301 | /** |
302 | * Return whether the passed URL is supported by this version of the library. | |
303 | * | |
304 | * @param url the url to check | |
305 | * @return 1 if the url is supported, 0 otherwise | |
306 | */ | |
307 | GIT_EXTERN(int) git_remote_supported_url(const char* url); | |
308 | ||
8171998f CMN |
309 | /** |
310 | * Get a list of the configured remotes for a repo | |
311 | * | |
312 | * The string array must be freed by the user. | |
313 | * | |
df705148 | 314 | * @param out a string array which receives the names of the remotes |
8171998f | 315 | * @param repo the repository to query |
e172cf08 | 316 | * @return 0 or an error code |
8171998f | 317 | */ |
df705148 | 318 | GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo); |
8171998f | 319 | |
250b95b2 CMN |
320 | /** |
321 | * Choose whether to check the server's certificate (applies to HTTPS only) | |
322 | * | |
323 | * @param remote the remote to configure | |
324 | * @param check whether to check the server's certificate (defaults to yes) | |
325 | */ | |
250b95b2 CMN |
326 | GIT_EXTERN(void) git_remote_check_cert(git_remote *remote, int check); |
327 | ||
091361f5 PK |
328 | /** |
329 | * Set a credentials acquisition callback for this remote. If the remote is | |
330 | * not available for anonymous access, then you must set this callback in order | |
331 | * to provide credentials to the transport at the time of authentication | |
332 | * failure so that retry can be performed. | |
333 | * | |
334 | * @param remote the remote to configure | |
b0b80658 BS |
335 | * @param cred_acquire_cb The credentials acquisition callback to use (defaults |
336 | * to NULL) | |
091361f5 PK |
337 | */ |
338 | GIT_EXTERN(void) git_remote_set_cred_acquire_cb( | |
339 | git_remote *remote, | |
59bccf33 BS |
340 | git_cred_acquire_cb cred_acquire_cb, |
341 | void *payload); | |
091361f5 | 342 | |
41fb1ca0 PK |
343 | /** |
344 | * Sets a custom transport for the remote. The caller can use this function | |
345 | * to bypass the automatic discovery of a transport by URL scheme (i.e. | |
346 | * http://, https://, git://) and supply their own transport to be used | |
347 | * instead. After providing the transport to a remote using this function, | |
348 | * the transport object belongs exclusively to that remote, and the remote will | |
349 | * free it when it is freed with git_remote_free. | |
350 | * | |
351 | * @param remote the remote to configure | |
352 | * @param transport the transport object for the remote to use | |
b0b80658 | 353 | * @return 0 or an error code |
41fb1ca0 | 354 | */ |
091361f5 PK |
355 | GIT_EXTERN(int) git_remote_set_transport( |
356 | git_remote *remote, | |
357 | git_transport *transport); | |
41fb1ca0 | 358 | |
b3aaa7a7 CMN |
359 | /** |
360 | * Argument to the completion callback which tells it which operation | |
361 | * finished. | |
362 | */ | |
363 | typedef enum git_remote_completion_type { | |
364 | GIT_REMOTE_COMPLETION_DOWNLOAD, | |
365 | GIT_REMOTE_COMPLETION_INDEXING, | |
366 | GIT_REMOTE_COMPLETION_ERROR, | |
367 | } git_remote_completion_type; | |
368 | ||
369 | /** | |
370 | * The callback settings structure | |
371 | * | |
372 | * Set the calbacks to be called by the remote. | |
373 | */ | |
374 | struct git_remote_callbacks { | |
bde336ea | 375 | unsigned int version; |
e03e71da | 376 | void (*progress)(const char *str, int len, void *data); |
b3aaa7a7 CMN |
377 | int (*completion)(git_remote_completion_type type, void *data); |
378 | int (*update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data); | |
df705148 | 379 | void *payload; |
b3aaa7a7 CMN |
380 | }; |
381 | ||
bde336ea | 382 | #define GIT_REMOTE_CALLBACKS_VERSION 1 |
fac43c54 | 383 | #define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION} |
bde336ea | 384 | |
b3aaa7a7 CMN |
385 | /** |
386 | * Set the callbacks for a remote | |
387 | * | |
388 | * Note that the remote keeps its own copy of the data and you need to | |
389 | * call this function again if you want to change the callbacks. | |
390 | * | |
391 | * @param remote the remote to configure | |
392 | * @param callbacks a pointer to the user's callback settings | |
9267ff58 | 393 | * @return 0 or an error code |
b3aaa7a7 | 394 | */ |
9267ff58 | 395 | GIT_EXTERN(int) git_remote_set_callbacks(git_remote *remote, git_remote_callbacks *callbacks); |
b3aaa7a7 | 396 | |
d57c47dc BS |
397 | /** |
398 | * Get the statistics structure that is filled in by the fetch operation. | |
399 | */ | |
7d222e13 | 400 | GIT_EXTERN(const git_transfer_progress *) git_remote_stats(git_remote *remote); |
d57c47dc | 401 | |
f4a62c30 | 402 | typedef enum { |
24f2f94e CMN |
403 | GIT_REMOTE_DOWNLOAD_TAGS_UNSET, |
404 | GIT_REMOTE_DOWNLOAD_TAGS_NONE, | |
3230a44f CMN |
405 | GIT_REMOTE_DOWNLOAD_TAGS_AUTO, |
406 | GIT_REMOTE_DOWNLOAD_TAGS_ALL | |
f4a62c30 | 407 | } git_remote_autotag_option_t; |
24f2f94e | 408 | |
f70e466f CMN |
409 | /** |
410 | * Retrieve the tag auto-follow setting | |
411 | * | |
412 | * @param remote the remote to query | |
413 | * @return the auto-follow setting | |
414 | */ | |
f4a62c30 | 415 | GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(git_remote *remote); |
f70e466f CMN |
416 | |
417 | /** | |
418 | * Set the tag auto-follow setting | |
419 | * | |
420 | * @param remote the remote to configure | |
421 | * @param value a GIT_REMOTE_DOWNLOAD_TAGS value | |
422 | */ | |
f4a62c30 BS |
423 | GIT_EXTERN(void) git_remote_set_autotag( |
424 | git_remote *remote, | |
425 | git_remote_autotag_option_t value); | |
f70e466f | 426 | |
fcccf304 | 427 | /** |
428 | * Give the remote a new name | |
429 | * | |
430 | * All remote-tracking branches and configuration settings | |
431 | * for the remote are updated. | |
432 | * | |
032ba9e4 | 433 | * The new name will be checked for validity. |
434 | * See `git_tag_create()` for rules about valid names. | |
435 | * | |
ae35aa07 | 436 | * A temporary in-memory remote cannot be given a name with this method. |
437 | * | |
fcccf304 | 438 | * @param remote the remote to rename |
439 | * @param new_name the new name the remote should bear | |
440 | * @param callback Optional callback to notify the consumer of fetch refspecs | |
441 | * that haven't been automatically updated and need potential manual tweaking. | |
442 | * @param payload Additional data to pass to the callback | |
ae35aa07 | 443 | * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code |
fcccf304 | 444 | */ |
445 | GIT_EXTERN(int) git_remote_rename( | |
446 | git_remote *remote, | |
447 | const char *new_name, | |
df705148 | 448 | git_remote_rename_problem_cb callback, |
fcccf304 | 449 | void *payload); |
f70e466f | 450 | |
b0f6e45d ET |
451 | /** |
452 | * Retrieve the update FETCH_HEAD setting. | |
453 | * | |
454 | * @param remote the remote to query | |
455 | * @return the update FETCH_HEAD setting | |
456 | */ | |
457 | GIT_EXTERN(int) git_remote_update_fetchhead(git_remote *remote); | |
458 | ||
459 | /** | |
460 | * Sets the update FETCH_HEAD setting. By default, FETCH_HEAD will be | |
461 | * updated on every fetch. Set to 0 to disable. | |
462 | * | |
463 | * @param remote the remote to configure | |
464 | * @param value 0 to disable updating FETCH_HEAD | |
465 | */ | |
466 | GIT_EXTERN(void) git_remote_set_update_fetchhead(git_remote *remote, int value); | |
467 | ||
2bca5b67 | 468 | /** |
469 | * Ensure the remote name is well-formed. | |
470 | * | |
471 | * @param remote_name name to be checked. | |
472 | * @return 1 if the reference name is acceptable; 0 if it isn't | |
473 | */ | |
474 | GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name); | |
475 | ||
1e76676f | 476 | /** @} */ |
bdd18829 | 477 | GIT_END_DECL |
9c82357b | 478 | #endif |