]>
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" |
8f0104ec | 17 | #include "pack.h" |
07bd3e57 | 18 | #include "proxy.h" |
d88d4311 | 19 | |
1e76676f CMN |
20 | /** |
21 | * @file git2/remote.h | |
22 | * @brief Git remote management functions | |
23 | * @defgroup git_remote remote management functions | |
24 | * @ingroup Git | |
25 | * @{ | |
26 | */ | |
27 | GIT_BEGIN_DECL | |
9c82357b | 28 | |
29f27599 | 29 | /** |
a4b6452a | 30 | * Add a remote with the default fetch refspec to the repository's configuration. |
29f27599 BS |
31 | * |
32 | * @param out the resulting remote | |
33 | * @param repo the repository in which to create the remote | |
34 | * @param name the remote's name | |
35 | * @param url the remote's url | |
f19304d2 | 36 | * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code |
29f27599 BS |
37 | */ |
38 | GIT_EXTERN(int) git_remote_create( | |
39 | git_remote **out, | |
40 | git_repository *repo, | |
41 | const char *name, | |
42 | const char *url); | |
43 | ||
ac3d33df JK |
44 | /** |
45 | * Remote creation options flags | |
46 | */ | |
47 | typedef enum { | |
48 | /** Ignore the repository apply.insteadOf configuration */ | |
49 | GIT_REMOTE_CREATE_SKIP_INSTEADOF = (1 << 0), | |
50 | ||
51 | /** Don't build a fetchspec from the name if none is set */ | |
52 | GIT_REMOTE_CREATE_SKIP_DEFAULT_FETCHSPEC = (1 << 1), | |
53 | } git_remote_create_flags; | |
54 | ||
55 | /** | |
56 | * Remote creation options structure | |
57 | * | |
58 | * Initialize with `GIT_REMOTE_CREATE_OPTIONS_INIT`. Alternatively, you can | |
22a2d3d5 | 59 | * use `git_remote_create_options_init`. |
ac3d33df JK |
60 | * |
61 | */ | |
62 | typedef struct git_remote_create_options { | |
63 | unsigned int version; | |
64 | ||
65 | /** | |
66 | * The repository that should own the remote. | |
67 | * Setting this to NULL results in a detached remote. | |
68 | */ | |
69 | git_repository *repository; | |
70 | ||
71 | /** | |
72 | * The remote's name. | |
73 | * Setting this to NULL results in an in-memory/anonymous remote. | |
74 | */ | |
75 | const char *name; | |
76 | ||
77 | /** The fetchspec the remote should use. */ | |
78 | const char *fetchspec; | |
79 | ||
80 | /** Additional flags for the remote. See git_remote_create_flags. */ | |
81 | unsigned int flags; | |
82 | } git_remote_create_options; | |
83 | ||
84 | #define GIT_REMOTE_CREATE_OPTIONS_VERSION 1 | |
85 | #define GIT_REMOTE_CREATE_OPTIONS_INIT {GIT_REMOTE_CREATE_OPTIONS_VERSION} | |
86 | ||
87 | /** | |
88 | * Initialize git_remote_create_options structure | |
89 | * | |
90 | * Initializes a `git_remote_create_options` with default values. Equivalent to | |
91 | * creating an instance with `GIT_REMOTE_CREATE_OPTIONS_INIT`. | |
92 | * | |
93 | * @param opts The `git_remote_create_options` struct to initialize. | |
94 | * @param version The struct version; pass `GIT_REMOTE_CREATE_OPTIONS_VERSION`. | |
95 | * @return Zero on success; -1 on failure. | |
96 | */ | |
22a2d3d5 | 97 | GIT_EXTERN(int) git_remote_create_options_init( |
ac3d33df JK |
98 | git_remote_create_options *opts, |
99 | unsigned int version); | |
100 | ||
101 | /** | |
102 | * Create a remote, with options. | |
103 | * | |
104 | * This function allows more fine-grained control over the remote creation. | |
105 | * | |
106 | * Passing NULL as the opts argument will result in a detached remote. | |
107 | * | |
108 | * @param out the resulting remote | |
109 | * @param url the remote's url | |
110 | * @param opts the remote creation options | |
111 | * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code | |
112 | */ | |
113 | GIT_EXTERN(int) git_remote_create_with_opts( | |
114 | git_remote **out, | |
115 | const char *url, | |
116 | const git_remote_create_options *opts); | |
117 | ||
29f27599 | 118 | /** |
99feb988 | 119 | * Add a remote with the provided fetch refspec (or default if NULL) to the repository's |
a4b6452a | 120 | * configuration. |
29f27599 BS |
121 | * |
122 | * @param out the resulting remote | |
123 | * @param repo the repository in which to create the remote | |
124 | * @param name the remote's name | |
125 | * @param url the remote's url | |
99feb988 | 126 | * @param fetch the remote fetch value |
f19304d2 | 127 | * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code |
29f27599 | 128 | */ |
40b99d05 | 129 | GIT_EXTERN(int) git_remote_create_with_fetchspec( |
29f27599 BS |
130 | git_remote **out, |
131 | git_repository *repo, | |
132 | const char *name, | |
0fe522d1 VG |
133 | const char *url, |
134 | const char *fetch); | |
29f27599 | 135 | |
778e1c73 | 136 | /** |
fd536d29 | 137 | * Create an anonymous remote |
778e1c73 | 138 | * |
ae5b9362 CMN |
139 | * Create a remote with the given url in-memory. You can use this when |
140 | * you have a URL instead of a remote's name. | |
778e1c73 | 141 | * |
ae5b9362 | 142 | * @param out pointer to the new remote objects |
3874f2d5 | 143 | * @param repo the associated repository |
0642c143 | 144 | * @param url the remote repository's URL |
ae35aa07 | 145 | * @return 0 or an error code |
778e1c73 | 146 | */ |
fd536d29 | 147 | GIT_EXTERN(int) git_remote_create_anonymous( |
29f27599 BS |
148 | git_remote **out, |
149 | git_repository *repo, | |
ae5b9362 | 150 | const char *url); |
778e1c73 | 151 | |
eae0bfdc PP |
152 | /** |
153 | * Create a remote without a connected local repo | |
154 | * | |
155 | * Create a remote with the given url in-memory. You can use this when | |
156 | * you have a URL instead of a remote's name. | |
157 | * | |
158 | * Contrasted with git_remote_create_anonymous, a detached remote | |
159 | * will not consider any repo configuration values (such as insteadof url | |
160 | * substitutions). | |
161 | * | |
162 | * @param out pointer to the new remote objects | |
163 | * @param url the remote repository's URL | |
164 | * @return 0 or an error code | |
165 | */ | |
166 | GIT_EXTERN(int) git_remote_create_detached( | |
167 | git_remote **out, | |
168 | const char *url); | |
169 | ||
9c82357b CMN |
170 | /** |
171 | * Get the information for a particular remote | |
172 | * | |
032ba9e4 | 173 | * The name will be checked for validity. |
174 | * See `git_tag_create()` for rules about valid names. | |
175 | * | |
9c82357b | 176 | * @param out pointer to the new remote object |
b0b80658 | 177 | * @param repo the associated repository |
9c82357b | 178 | * @param name the remote's name |
032ba9e4 | 179 | * @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code |
9c82357b | 180 | */ |
209425ce | 181 | GIT_EXTERN(int) git_remote_lookup(git_remote **out, git_repository *repo, const char *name); |
9c82357b | 182 | |
40ef47dd AS |
183 | /** |
184 | * Create a copy of an existing remote. All internal strings are also | |
185 | * duplicated. Callbacks are not duplicated. | |
186 | * | |
187 | * Call `git_remote_free` to free the data. | |
188 | * | |
189 | * @param dest pointer where to store the copy | |
190 | * @param source object to copy | |
191 | * @return 0 or an error code | |
192 | */ | |
991b2840 | 193 | GIT_EXTERN(int) git_remote_dup(git_remote **dest, git_remote *source); |
40ef47dd | 194 | |
85e1eded ES |
195 | /** |
196 | * Get the remote's repository | |
197 | * | |
198 | * @param remote the remote | |
199 | * @return a pointer to the repository | |
200 | */ | |
201 | GIT_EXTERN(git_repository *) git_remote_owner(const git_remote *remote); | |
202 | ||
9c82357b CMN |
203 | /** |
204 | * Get the remote's name | |
205 | * | |
206 | * @param remote the remote | |
b0aa14aa | 207 | * @return a pointer to the name or NULL for in-memory remotes |
9c82357b | 208 | */ |
df705148 | 209 | GIT_EXTERN(const char *) git_remote_name(const git_remote *remote); |
9c82357b CMN |
210 | |
211 | /** | |
212 | * Get the remote's url | |
213 | * | |
ec0c4c40 | 214 | * If url.*.insteadOf has been configured for this URL, it will |
c25aa7cd PP |
215 | * return the modified URL. If `git_remote_set_instance_pushurl` |
216 | * has been called for this remote, then that URL will be returned. | |
ec0c4c40 | 217 | * |
9c82357b CMN |
218 | * @param remote the remote |
219 | * @return a pointer to the url | |
220 | */ | |
df705148 | 221 | GIT_EXTERN(const char *) git_remote_url(const git_remote *remote); |
9c82357b | 222 | |
76501590 | 223 | /** |
c25aa7cd | 224 | * Get the remote's url for pushing. |
76501590 | 225 | * |
ec0c4c40 | 226 | * If url.*.pushInsteadOf has been configured for this URL, it |
c25aa7cd PP |
227 | * will return the modified URL. If `git_remote_set_instance_pushurl` |
228 | * has been called for this remote, then that URL will be returned. | |
ec0c4c40 | 229 | * |
76501590 SC |
230 | * @param remote the remote |
231 | * @return a pointer to the url or NULL if no special url for pushing is set | |
232 | */ | |
df705148 | 233 | GIT_EXTERN(const char *) git_remote_pushurl(const git_remote *remote); |
76501590 SC |
234 | |
235 | /** | |
22261344 | 236 | * Set the remote's url in the configuration |
76501590 | 237 | * |
22261344 CMN |
238 | * Remote objects already in memory will not be affected. This assumes |
239 | * the common case of a single-url remote and will otherwise return an error. | |
76501590 | 240 | * |
22261344 CMN |
241 | * @param repo the repository in which to perform the change |
242 | * @param remote the remote's name | |
76501590 SC |
243 | * @param url the url to set |
244 | * @return 0 or an error value | |
245 | */ | |
c25aa7cd | 246 | GIT_EXTERN(int) git_remote_set_url(git_repository *repo, const char *remote, const char *url); |
76501590 SC |
247 | |
248 | /** | |
22261344 | 249 | * Set the remote's url for pushing in the configuration. |
76501590 | 250 | * |
22261344 CMN |
251 | * Remote objects already in memory will not be affected. This assumes |
252 | * the common case of a single-url remote and will otherwise return an error. | |
76501590 | 253 | * |
22261344 CMN |
254 | * |
255 | * @param repo the repository in which to perform the change | |
256 | * @param remote the remote's name | |
257 | * @param url the url to set | |
c25aa7cd | 258 | * @return 0, or an error code |
76501590 | 259 | */ |
c25aa7cd PP |
260 | GIT_EXTERN(int) git_remote_set_pushurl(git_repository *repo, const char *remote, const char *url); |
261 | ||
262 | /** | |
263 | * Set the url for this particular url instance. The URL in the | |
264 | * configuration will be ignored, and will not be changed. | |
265 | * | |
266 | * @param remote the remote's name | |
267 | * @param url the url to set | |
268 | * @return 0 or an error value | |
269 | */ | |
270 | GIT_EXTERN(int) git_remote_set_instance_url(git_remote *remote, const char *url); | |
271 | ||
272 | /** | |
273 | * Set the push url for this particular url instance. The URL in the | |
274 | * configuration will be ignored, and will not be changed. | |
275 | * | |
276 | * @param remote the remote's name | |
277 | * @param url the url to set | |
278 | * @return 0 or an error value | |
279 | */ | |
280 | GIT_EXTERN(int) git_remote_set_instance_pushurl(git_remote *remote, const char *url); | |
76501590 | 281 | |
bcb8c007 | 282 | /** |
77254990 | 283 | * Add a fetch refspec to the remote's configuration |
bcb8c007 | 284 | * |
77254990 CMN |
285 | * Add the given refspec to the fetch list in the configuration. No |
286 | * loaded remote instances will be affected. | |
266af6d8 | 287 | * |
77254990 CMN |
288 | * @param repo the repository in which to change the configuration |
289 | * @param remote the name of the remote to change | |
266af6d8 | 290 | * @param refspec the new fetch refspec |
c6e942fb | 291 | * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value |
bcb8c007 | 292 | */ |
77254990 | 293 | GIT_EXTERN(int) git_remote_add_fetch(git_repository *repo, const char *remote, const char *refspec); |
bc6374ea CMN |
294 | |
295 | /** | |
296 | * Get the remote's list of fetch refspecs | |
297 | * | |
298 | * The memory is owned by the user and should be freed with | |
299 | * `git_strarray_free`. | |
300 | * | |
301 | * @param array pointer to the array in which to store the strings | |
302 | * @param remote the remote to query | |
303 | */ | |
11f6ad5f | 304 | GIT_EXTERN(int) git_remote_get_fetch_refspecs(git_strarray *array, const git_remote *remote); |
bcb8c007 | 305 | |
9c82357b | 306 | /** |
77254990 | 307 | * Add a push refspec to the remote's configuration |
9c82357b | 308 | * |
77254990 CMN |
309 | * Add the given refspec to the push list in the configuration. No |
310 | * loaded remote instances will be affected. | |
266af6d8 | 311 | * |
77254990 CMN |
312 | * @param repo the repository in which to change the configuration |
313 | * @param remote the name of the remote to change | |
4330ab26 | 314 | * @param refspec the new push refspec |
c6e942fb | 315 | * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value |
bcb8c007 | 316 | */ |
77254990 | 317 | GIT_EXTERN(int) git_remote_add_push(git_repository *repo, const char *remote, const char *refspec); |
bc6374ea CMN |
318 | |
319 | /** | |
320 | * Get the remote's list of push refspecs | |
321 | * | |
322 | * The memory is owned by the user and should be freed with | |
323 | * `git_strarray_free`. | |
324 | * | |
325 | * @param array pointer to the array in which to store the strings | |
326 | * @param remote the remote to query | |
327 | */ | |
11f6ad5f | 328 | GIT_EXTERN(int) git_remote_get_push_refspecs(git_strarray *array, const git_remote *remote); |
bcb8c007 | 329 | |
1ffd0806 CMN |
330 | /** |
331 | * Get the number of refspecs for a remote | |
332 | * | |
333 | * @param remote the remote | |
334 | * @return the amount of refspecs configured in this remote | |
335 | */ | |
11f6ad5f | 336 | GIT_EXTERN(size_t) git_remote_refspec_count(const git_remote *remote); |
1ffd0806 CMN |
337 | |
338 | /** | |
339 | * Get a refspec from the remote | |
340 | * | |
341 | * @param remote the remote to query | |
342 | * @param n the refspec to get | |
343 | * @return the nth refspec | |
344 | */ | |
11f6ad5f | 345 | GIT_EXTERN(const git_refspec *)git_remote_get_refspec(const git_remote *remote, size_t n); |
1ffd0806 | 346 | |
9ba49bb5 CMN |
347 | /** |
348 | * Open a connection to a remote | |
349 | * | |
e1d88030 CMN |
350 | * The transport is selected based on the URL. The direction argument |
351 | * is due to a limitation of the git protocol (over TCP or SSH) which | |
352 | * starts up a specific binary which can only do the one or the other. | |
9ba49bb5 CMN |
353 | * |
354 | * @param remote the remote to connect to | |
4a38143c CMN |
355 | * @param direction GIT_DIRECTION_FETCH if you want to fetch or |
356 | * GIT_DIRECTION_PUSH if you want to push | |
8f0104ec | 357 | * @param callbacks the callbacks to use for this connection |
07bd3e57 | 358 | * @param proxy_opts proxy settings |
4f2b6093 | 359 | * @param custom_headers extra HTTP headers to use in this connection |
e172cf08 | 360 | * @return 0 or an error code |
9ba49bb5 | 361 | */ |
07bd3e57 | 362 | GIT_EXTERN(int) git_remote_connect(git_remote *remote, git_direction direction, const git_remote_callbacks *callbacks, const git_proxy_options *proxy_opts, const git_strarray *custom_headers); |
9ba49bb5 CMN |
363 | |
364 | /** | |
699dfcc3 | 365 | * Get the remote repository's reference advertisement list |
9ba49bb5 | 366 | * |
699dfcc3 CMN |
367 | * Get the list of references with which the server responds to a new |
368 | * connection. | |
9ba49bb5 | 369 | * |
699dfcc3 CMN |
370 | * The remote (or more exactly its transport) must have connected to |
371 | * the remote repository. This list is available as soon as the | |
372 | * connection to the remote is initiated and it remains available | |
373 | * after disconnecting. | |
374 | * | |
375 | * The memory belongs to the remote. The pointer will be valid as long | |
376 | * as a new connection is not initiated, but it is recommended that | |
377 | * you make a copy in order to make use of the data. | |
5dca2010 | 378 | * |
359dce72 CMN |
379 | * @param out pointer to the array |
380 | * @param size the number of remote heads | |
9ba49bb5 | 381 | * @param remote the remote |
359dce72 | 382 | * @return 0 on success, or an error code |
9ba49bb5 | 383 | */ |
359dce72 | 384 | GIT_EXTERN(int) git_remote_ls(const git_remote_head ***out, size_t *size, git_remote *remote); |
9ba49bb5 | 385 | |
6ac3b707 CMN |
386 | /** |
387 | * Check whether the remote is connected | |
388 | * | |
389 | * Check whether the remote's underlying transport is connected to the | |
390 | * remote host. | |
391 | * | |
b0b80658 | 392 | * @param remote the remote |
6ac3b707 CMN |
393 | * @return 1 if it's connected, 0 otherwise. |
394 | */ | |
11f6ad5f | 395 | GIT_EXTERN(int) git_remote_connected(const git_remote *remote); |
6ac3b707 | 396 | |
f0d2ddbb CMN |
397 | /** |
398 | * Cancel the operation | |
399 | * | |
400 | * At certain points in its operation, the network code checks whether | |
401 | * the operation has been cancelled and if so stops the operation. | |
b0b80658 BS |
402 | * |
403 | * @param remote the remote | |
22a2d3d5 | 404 | * @return 0 on success, or an error code |
f0d2ddbb | 405 | */ |
22a2d3d5 | 406 | GIT_EXTERN(int) git_remote_stop(git_remote *remote); |
f0d2ddbb | 407 | |
4cf01e9a CMN |
408 | /** |
409 | * Disconnect from the remote | |
410 | * | |
8fd7dd77 | 411 | * Close the connection to the remote. |
4cf01e9a CMN |
412 | * |
413 | * @param remote the remote to disconnect from | |
22a2d3d5 | 414 | * @return 0 on success, or an error code |
4cf01e9a | 415 | */ |
22a2d3d5 | 416 | GIT_EXTERN(int) git_remote_disconnect(git_remote *remote); |
4cf01e9a | 417 | |
9c82357b CMN |
418 | /** |
419 | * Free the memory associated with a remote | |
420 | * | |
8af503bc MS |
421 | * This also disconnects from the remote, if the connection |
422 | * has not been closed yet (using git_remote_disconnect). | |
423 | * | |
9c82357b CMN |
424 | * @param remote the remote to free |
425 | */ | |
9462c471 | 426 | GIT_EXTERN(void) git_remote_free(git_remote *remote); |
9c82357b | 427 | |
8171998f CMN |
428 | /** |
429 | * Get a list of the configured remotes for a repo | |
430 | * | |
431 | * The string array must be freed by the user. | |
432 | * | |
df705148 | 433 | * @param out a string array which receives the names of the remotes |
8171998f | 434 | * @param repo the repository to query |
e172cf08 | 435 | * @return 0 or an error code |
8171998f | 436 | */ |
df705148 | 437 | GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo); |
8171998f | 438 | |
b3aaa7a7 CMN |
439 | /** |
440 | * Argument to the completion callback which tells it which operation | |
441 | * finished. | |
442 | */ | |
22a2d3d5 | 443 | typedef enum git_remote_completion_t { |
b3aaa7a7 CMN |
444 | GIT_REMOTE_COMPLETION_DOWNLOAD, |
445 | GIT_REMOTE_COMPLETION_INDEXING, | |
446 | GIT_REMOTE_COMPLETION_ERROR, | |
22a2d3d5 | 447 | } git_remote_completion_t; |
b3aaa7a7 | 448 | |
8f0104ec | 449 | /** Push network progress notification function */ |
22a2d3d5 | 450 | typedef int GIT_CALLBACK(git_push_transfer_progress_cb)( |
8f0104ec CMN |
451 | unsigned int current, |
452 | unsigned int total, | |
453 | size_t bytes, | |
c25aa7cd | 454 | void *payload); |
22a2d3d5 | 455 | |
8f0104ec CMN |
456 | /** |
457 | * Represents an update which will be performed on the remote during push | |
458 | */ | |
459 | typedef struct { | |
460 | /** | |
461 | * The source name of the reference | |
462 | */ | |
463 | char *src_refname; | |
464 | /** | |
465 | * The name of the reference to update on the server | |
466 | */ | |
467 | char *dst_refname; | |
468 | /** | |
469 | * The current target of the reference | |
470 | */ | |
471 | git_oid src; | |
472 | /** | |
473 | * The new target for the reference | |
474 | */ | |
475 | git_oid dst; | |
476 | } git_push_update; | |
477 | ||
478 | /** | |
788fcdb8 ES |
479 | * Callback used to inform of upcoming updates. |
480 | * | |
8f0104ec CMN |
481 | * @param updates an array containing the updates which will be sent |
482 | * as commands to the destination. | |
483 | * @param len number of elements in `updates` | |
484 | * @param payload Payload provided by the caller | |
485 | */ | |
ac3d33df | 486 | typedef int GIT_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload); |
8f0104ec | 487 | |
eae0bfdc PP |
488 | /** |
489 | * Callback used to inform of the update status from the remote. | |
490 | * | |
491 | * Called for each updated reference on push. If `status` is | |
492 | * not `NULL`, the update was rejected by the remote server | |
493 | * and `status` contains the reason given. | |
494 | * | |
495 | * @param refname refname specifying to the remote ref | |
496 | * @param status status message sent from the remote | |
497 | * @param data data provided by the caller | |
498 | * @return 0 on success, otherwise an error | |
499 | */ | |
ac3d33df | 500 | typedef int GIT_CALLBACK(git_push_update_reference_cb)(const char *refname, const char *status, void *data); |
eae0bfdc | 501 | |
c25aa7cd | 502 | #ifndef GIT_DEPRECATE_HARD |
22a2d3d5 UG |
503 | /** |
504 | * Callback to resolve URLs before connecting to remote | |
505 | * | |
506 | * If you return GIT_PASSTHROUGH, you don't need to write anything to | |
507 | * url_resolved. | |
508 | * | |
509 | * @param url_resolved The buffer to write the resolved URL to | |
510 | * @param url The URL to resolve | |
511 | * @param direction GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH | |
512 | * @param payload Payload provided by the caller | |
513 | * @return 0 on success, GIT_PASSTHROUGH or an error | |
c25aa7cd | 514 | * @deprecated Use `git_remote_set_instance_url` |
22a2d3d5 UG |
515 | */ |
516 | typedef int GIT_CALLBACK(git_url_resolve_cb)(git_buf *url_resolved, const char *url, int direction, void *payload); | |
c25aa7cd PP |
517 | #endif |
518 | ||
519 | /** | |
520 | * Callback invoked immediately before we attempt to connect to the | |
521 | * given url. Callers may change the URL before the connection by | |
522 | * calling `git_remote_set_instance_url` in the callback. | |
523 | * | |
524 | * @param remote The remote to be connected | |
525 | * @param direction GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH | |
526 | * @param payload Payload provided by the caller | |
527 | * @return 0 on success, or an error | |
528 | */ | |
529 | typedef int GIT_CALLBACK(git_remote_ready_cb)(git_remote *remote, int direction, void *payload); | |
22a2d3d5 | 530 | |
b3aaa7a7 CMN |
531 | /** |
532 | * The callback settings structure | |
533 | * | |
ffc97d51 CMN |
534 | * Set the callbacks to be called by the remote when informing the user |
535 | * about the progress of the network operations. | |
b3aaa7a7 CMN |
536 | */ |
537 | struct git_remote_callbacks { | |
22a2d3d5 UG |
538 | unsigned int version; /**< The version */ |
539 | ||
ffc97d51 CMN |
540 | /** |
541 | * Textual progress from the remote. Text send over the | |
542 | * progress side-band will be passed to this function (this is | |
fc15befd | 543 | * the 'counting objects' output). |
ffc97d51 | 544 | */ |
48e60ae7 | 545 | git_transport_message_cb sideband_progress; |
ffc97d51 CMN |
546 | |
547 | /** | |
548 | * Completion is called when different parts of the download | |
549 | * process are done (currently unused). | |
550 | */ | |
22a2d3d5 | 551 | int GIT_CALLBACK(completion)(git_remote_completion_t type, void *data); |
ffc97d51 CMN |
552 | |
553 | /** | |
554 | * This will be called if the remote host requires | |
555 | * authentication in order to connect to it. | |
bc0a6198 CMN |
556 | * |
557 | * Returning GIT_PASSTHROUGH will make libgit2 behave as | |
558 | * though this field isn't set. | |
ffc97d51 | 559 | */ |
22a2d3d5 | 560 | git_credential_acquire_cb credentials; |
ffc97d51 | 561 | |
9b940586 CMN |
562 | /** |
563 | * If cert verification fails, this will be called to let the | |
564 | * user make the final decision of whether to allow the | |
ac3d33df JK |
565 | * connection to proceed. Returns 0 to allow the connection |
566 | * or a negative value to indicate an error. | |
9b940586 | 567 | */ |
788fcdb8 | 568 | git_transport_certificate_check_cb certificate_check; |
9b940586 | 569 | |
ffc97d51 CMN |
570 | /** |
571 | * During the download of new data, this will be regularly | |
572 | * called with the current count of progress done by the | |
573 | * indexer. | |
574 | */ | |
22a2d3d5 | 575 | git_indexer_progress_cb transfer_progress; |
ffc97d51 CMN |
576 | |
577 | /** | |
578 | * Each time a reference is updated locally, this function | |
579 | * will be called with information about it. | |
580 | */ | |
ac3d33df | 581 | int GIT_CALLBACK(update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data); |
ffc97d51 | 582 | |
3149547b CMN |
583 | /** |
584 | * Function to call with progress information during pack | |
585 | * building. Be aware that this is called inline with pack | |
586 | * building operations, so performance may be affected. | |
587 | */ | |
588 | git_packbuilder_progress pack_progress; | |
589 | ||
590 | /** | |
591 | * Function to call with progress information during the | |
592 | * upload portion of a push. Be aware that this is called | |
593 | * inline with pack building operations, so performance may be | |
594 | * affected. | |
595 | */ | |
22a2d3d5 | 596 | git_push_transfer_progress_cb push_transfer_progress; |
3149547b CMN |
597 | |
598 | /** | |
eae0bfdc | 599 | * See documentation of git_push_update_reference_cb |
3149547b | 600 | */ |
eae0bfdc | 601 | git_push_update_reference_cb push_update_reference; |
3149547b | 602 | |
efc2fec5 CMN |
603 | /** |
604 | * Called once between the negotiation step and the upload. It | |
605 | * provides information about what updates will be performed. | |
606 | */ | |
607 | git_push_negotiation push_negotiation; | |
608 | ||
058b753c CMN |
609 | /** |
610 | * Create the transport to use for this operation. Leave NULL | |
611 | * to auto-detect. | |
612 | */ | |
613 | git_transport_cb transport; | |
614 | ||
c25aa7cd PP |
615 | /** |
616 | * Callback when the remote is ready to connect. | |
617 | */ | |
618 | git_remote_ready_cb remote_ready; | |
619 | ||
ffc97d51 CMN |
620 | /** |
621 | * This will be passed to each of the callbacks in this struct | |
622 | * as the last parameter. | |
623 | */ | |
df705148 | 624 | void *payload; |
22a2d3d5 | 625 | |
c25aa7cd PP |
626 | #ifdef GIT_DEPRECATE_HARD |
627 | void *reserved; | |
628 | #else | |
22a2d3d5 UG |
629 | /** |
630 | * Resolve URL before connecting to remote. | |
631 | * The returned URL will be used to connect to the remote instead. | |
c25aa7cd PP |
632 | * |
633 | * This callback is deprecated; users should use | |
634 | * git_remote_ready_cb and configure the instance URL instead. | |
22a2d3d5 UG |
635 | */ |
636 | git_url_resolve_cb resolve_url; | |
c25aa7cd | 637 | #endif |
b3aaa7a7 CMN |
638 | }; |
639 | ||
bde336ea | 640 | #define GIT_REMOTE_CALLBACKS_VERSION 1 |
fac43c54 | 641 | #define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION} |
bde336ea | 642 | |
b9f81997 MB |
643 | /** |
644 | * Initializes a `git_remote_callbacks` with default values. Equivalent to | |
645 | * creating an instance with GIT_REMOTE_CALLBACKS_INIT. | |
646 | * | |
bc91347b RB |
647 | * @param opts the `git_remote_callbacks` struct to initialize |
648 | * @param version Version of struct; pass `GIT_REMOTE_CALLBACKS_VERSION` | |
b9f81997 MB |
649 | * @return Zero on success; -1 on failure. |
650 | */ | |
651 | GIT_EXTERN(int) git_remote_init_callbacks( | |
bc91347b RB |
652 | git_remote_callbacks *opts, |
653 | unsigned int version); | |
b9f81997 | 654 | |
22a2d3d5 | 655 | /** Acceptable prune settings when fetching */ |
6fb373a0 CMN |
656 | typedef enum { |
657 | /** | |
658 | * Use the setting from the configuration | |
659 | */ | |
c2418f46 | 660 | GIT_FETCH_PRUNE_UNSPECIFIED, |
6fb373a0 CMN |
661 | /** |
662 | * Force pruning on | |
663 | */ | |
664 | GIT_FETCH_PRUNE, | |
665 | /** | |
666 | * Force pruning off | |
667 | */ | |
668 | GIT_FETCH_NO_PRUNE, | |
669 | } git_fetch_prune_t; | |
670 | ||
35a8a8c5 CMN |
671 | /** |
672 | * Automatic tag following option | |
673 | * | |
674 | * Lets us select the --tags option to use. | |
675 | */ | |
676 | typedef enum { | |
677 | /** | |
678 | * Use the setting from the configuration. | |
679 | */ | |
c2418f46 | 680 | GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED = 0, |
35a8a8c5 CMN |
681 | /** |
682 | * Ask the server for tags pointing to objects we're already | |
683 | * downloading. | |
684 | */ | |
685 | GIT_REMOTE_DOWNLOAD_TAGS_AUTO, | |
686 | /** | |
687 | * Don't ask for any tags beyond the refspecs. | |
688 | */ | |
689 | GIT_REMOTE_DOWNLOAD_TAGS_NONE, | |
690 | /** | |
691 | * Ask for the all the tags. | |
692 | */ | |
693 | GIT_REMOTE_DOWNLOAD_TAGS_ALL, | |
694 | } git_remote_autotag_option_t; | |
695 | ||
37996d47 RRC |
696 | /** |
697 | * Fetch options structure. | |
698 | * | |
699 | * Zero out for defaults. Initialize with `GIT_FETCH_OPTIONS_INIT` macro to | |
700 | * correctly set the `version` field. E.g. | |
701 | * | |
702 | * git_fetch_options opts = GIT_FETCH_OPTIONS_INIT; | |
703 | */ | |
8f0104ec CMN |
704 | typedef struct { |
705 | int version; | |
706 | ||
707 | /** | |
708 | * Callbacks to use for this fetch operation | |
709 | */ | |
710 | git_remote_callbacks callbacks; | |
6fb373a0 CMN |
711 | |
712 | /** | |
713 | * Whether to perform a prune after the fetch | |
714 | */ | |
715 | git_fetch_prune_t prune; | |
3eff2a57 CMN |
716 | |
717 | /** | |
718 | * Whether to write the results to FETCH_HEAD. Defaults to | |
719 | * on. Leave this default in order to behave like git. | |
720 | */ | |
721 | int update_fetchhead; | |
35a8a8c5 CMN |
722 | |
723 | /** | |
724 | * Determines how to behave regarding tags on the remote, such | |
725 | * as auto-downloading tags for objects we're downloading or | |
726 | * downloading all of them. | |
727 | * | |
728 | * The default is to auto-follow tags. | |
729 | */ | |
730 | git_remote_autotag_option_t download_tags; | |
c49126c8 | 731 | |
07bd3e57 CMN |
732 | /** |
733 | * Proxy options to use, by default no proxy is used. | |
734 | */ | |
735 | git_proxy_options proxy_opts; | |
736 | ||
c49126c8 MB |
737 | /** |
738 | * Extra headers for this fetch operation | |
739 | */ | |
740 | git_strarray custom_headers; | |
8f0104ec CMN |
741 | } git_fetch_options; |
742 | ||
743 | #define GIT_FETCH_OPTIONS_VERSION 1 | |
07bd3e57 CMN |
744 | #define GIT_FETCH_OPTIONS_INIT { GIT_FETCH_OPTIONS_VERSION, GIT_REMOTE_CALLBACKS_INIT, GIT_FETCH_PRUNE_UNSPECIFIED, 1, \ |
745 | GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED, GIT_PROXY_OPTIONS_INIT } | |
8f0104ec | 746 | |
b3aaa7a7 | 747 | /** |
ac3d33df JK |
748 | * Initialize git_fetch_options structure |
749 | * | |
8f0104ec | 750 | * Initializes a `git_fetch_options` with default values. Equivalent to |
ac3d33df | 751 | * creating an instance with `GIT_FETCH_OPTIONS_INIT`. |
b3aaa7a7 | 752 | * |
ac3d33df JK |
753 | * @param opts The `git_fetch_options` struct to initialize. |
754 | * @param version The struct version; pass `GIT_FETCH_OPTIONS_VERSION`. | |
8f0104ec CMN |
755 | * @return Zero on success; -1 on failure. |
756 | */ | |
22a2d3d5 | 757 | GIT_EXTERN(int) git_fetch_options_init( |
8f0104ec CMN |
758 | git_fetch_options *opts, |
759 | unsigned int version); | |
760 | ||
761 | ||
762 | /** | |
763 | * Controls the behavior of a git_push object. | |
764 | */ | |
765 | typedef struct { | |
766 | unsigned int version; | |
767 | ||
768 | /** | |
769 | * If the transport being used to push to the remote requires the creation | |
770 | * of a pack file, this controls the number of worker threads used by | |
771 | * the packbuilder when creating that pack file to be sent to the remote. | |
772 | * | |
773 | * If set to 0, the packbuilder will auto-detect the number of threads | |
774 | * to create. The default value is 1. | |
775 | */ | |
776 | unsigned int pb_parallelism; | |
777 | ||
778 | /** | |
779 | * Callbacks to use for this push operation | |
780 | */ | |
781 | git_remote_callbacks callbacks; | |
9da32a62 | 782 | |
07bd3e57 CMN |
783 | /** |
784 | * Proxy options to use, by default no proxy is used. | |
785 | */ | |
786 | git_proxy_options proxy_opts; | |
787 | ||
9da32a62 MB |
788 | /** |
789 | * Extra headers for this push operation | |
790 | */ | |
791 | git_strarray custom_headers; | |
8f0104ec CMN |
792 | } git_push_options; |
793 | ||
794 | #define GIT_PUSH_OPTIONS_VERSION 1 | |
ac3d33df | 795 | #define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT } |
8f0104ec CMN |
796 | |
797 | /** | |
ac3d33df JK |
798 | * Initialize git_push_options structure |
799 | * | |
8f0104ec | 800 | * Initializes a `git_push_options` with default values. Equivalent to |
ac3d33df | 801 | * creating an instance with `GIT_PUSH_OPTIONS_INIT`. |
b3aaa7a7 | 802 | * |
ac3d33df JK |
803 | * @param opts The `git_push_options` struct to initialize. |
804 | * @param version The struct version; pass `GIT_PUSH_OPTIONS_VERSION`. | |
8f0104ec CMN |
805 | * @return Zero on success; -1 on failure. |
806 | */ | |
22a2d3d5 | 807 | GIT_EXTERN(int) git_push_options_init( |
8f0104ec CMN |
808 | git_push_options *opts, |
809 | unsigned int version); | |
810 | ||
811 | /** | |
812 | * Download and index the packfile | |
813 | * | |
814 | * Connect to the remote if it hasn't been done yet, negotiate with | |
815 | * the remote git which objects are missing, download and index the | |
816 | * packfile. | |
817 | * | |
818 | * The .idx file will be created and both it and the packfile with be | |
819 | * renamed to their final name. | |
820 | * | |
821 | * @param remote the remote | |
822 | * @param refspecs the refspecs to use for this negotiation and | |
823 | * download. Use NULL or an empty array to use the base refspecs | |
824 | * @param opts the options to use for this fetch | |
9267ff58 | 825 | * @return 0 or an error code |
b3aaa7a7 | 826 | */ |
8f0104ec | 827 | GIT_EXTERN(int) git_remote_download(git_remote *remote, const git_strarray *refspecs, const git_fetch_options *opts); |
b3aaa7a7 | 828 | |
2efd7df6 | 829 | /** |
8f0104ec | 830 | * Create a packfile and send it to the server |
2efd7df6 | 831 | * |
8f0104ec CMN |
832 | * Connect to the remote if it hasn't been done yet, negotiate with |
833 | * the remote git which objects are missing, create a packfile with the missing objects and send it. | |
2efd7df6 | 834 | * |
8f0104ec CMN |
835 | * @param remote the remote |
836 | * @param refspecs the refspecs to use for this negotiation and | |
837 | * upload. Use NULL or an empty array to use the base refspecs | |
838 | * @param opts the options to use for this push | |
839 | * @return 0 or an error code | |
840 | */ | |
841 | GIT_EXTERN(int) git_remote_upload(git_remote *remote, const git_strarray *refspecs, const git_push_options *opts); | |
842 | ||
843 | /** | |
844 | * Update the tips to the new state | |
845 | * | |
846 | * @param remote the remote to update | |
847 | * @param reflog_message The message to insert into the reflogs. If | |
848 | * NULL and fetching, the default is "fetch <name>", where <name> is | |
849 | * the name of the remote (or its url, for in-memory remotes). This | |
850 | * parameter is ignored when pushing. | |
851 | * @param callbacks pointer to the callback structure to use | |
3eff2a57 | 852 | * @param update_fetchhead whether to write to FETCH_HEAD. Pass 1 to behave like git. |
35a8a8c5 CMN |
853 | * @param download_tags what the behaviour for downloading tags is for this fetch. This is |
854 | * ignored for push. This must be the same value passed to `git_remote_download()`. | |
8f0104ec CMN |
855 | * @return 0 or an error code |
856 | */ | |
857 | GIT_EXTERN(int) git_remote_update_tips( | |
858 | git_remote *remote, | |
859 | const git_remote_callbacks *callbacks, | |
3eff2a57 | 860 | int update_fetchhead, |
35a8a8c5 | 861 | git_remote_autotag_option_t download_tags, |
8f0104ec CMN |
862 | const char *reflog_message); |
863 | ||
864 | /** | |
865 | * Download new data and update tips | |
866 | * | |
867 | * Convenience function to connect to a remote, download the data, | |
868 | * disconnect and update the remote-tracking branches. | |
869 | * | |
870 | * @param remote the remote to fetch from | |
871 | * @param refspecs the refspecs to use for this fetch. Pass NULL or an | |
872 | * empty array to use the base refspecs. | |
873 | * @param opts options to use for this fetch | |
874 | * @param reflog_message The message to insert into the reflogs. If NULL, the | |
875 | * default is "fetch" | |
876 | * @return 0 or an error code | |
2efd7df6 | 877 | */ |
8f0104ec CMN |
878 | GIT_EXTERN(int) git_remote_fetch( |
879 | git_remote *remote, | |
880 | const git_strarray *refspecs, | |
881 | const git_fetch_options *opts, | |
882 | const char *reflog_message); | |
883 | ||
884 | /** | |
885 | * Prune tracking refs that are no longer present on remote | |
886 | * | |
887 | * @param remote the remote to prune | |
888 | * @param callbacks callbacks to use for this prune | |
889 | * @return 0 or an error code | |
890 | */ | |
891 | GIT_EXTERN(int) git_remote_prune(git_remote *remote, const git_remote_callbacks *callbacks); | |
892 | ||
893 | /** | |
894 | * Perform a push | |
895 | * | |
896 | * Peform all the steps from a push. | |
897 | * | |
898 | * @param remote the remote to push to | |
45071cec ET |
899 | * @param refspecs the refspecs to use for pushing. If NULL or an empty |
900 | * array, the configured refspecs will be used | |
8f0104ec CMN |
901 | * @param opts options to use for this push |
902 | */ | |
903 | GIT_EXTERN(int) git_remote_push(git_remote *remote, | |
904 | const git_strarray *refspecs, | |
905 | const git_push_options *opts); | |
2efd7df6 | 906 | |
d57c47dc BS |
907 | /** |
908 | * Get the statistics structure that is filled in by the fetch operation. | |
909 | */ | |
22a2d3d5 | 910 | GIT_EXTERN(const git_indexer_progress *) git_remote_stats(git_remote *remote); |
d57c47dc | 911 | |
f70e466f CMN |
912 | /** |
913 | * Retrieve the tag auto-follow setting | |
914 | * | |
915 | * @param remote the remote to query | |
916 | * @return the auto-follow setting | |
917 | */ | |
11f6ad5f | 918 | GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(const git_remote *remote); |
f70e466f CMN |
919 | |
920 | /** | |
35a8a8c5 CMN |
921 | * Set the remote's tag following setting. |
922 | * | |
923 | * The change will be made in the configuration. No loaded remotes | |
924 | * will be affected. | |
f70e466f | 925 | * |
35a8a8c5 CMN |
926 | * @param repo the repository in which to make the change |
927 | * @param remote the name of the remote | |
928 | * @param value the new value to take. | |
c25aa7cd | 929 | * @return 0, or an error code. |
f70e466f | 930 | */ |
35a8a8c5 | 931 | GIT_EXTERN(int) git_remote_set_autotag(git_repository *repo, const char *remote, git_remote_autotag_option_t value); |
c25aa7cd | 932 | |
5f473947 L |
933 | /** |
934 | * Retrieve the ref-prune setting | |
935 | * | |
936 | * @param remote the remote to query | |
937 | * @return the ref-prune setting | |
938 | */ | |
939 | GIT_EXTERN(int) git_remote_prune_refs(const git_remote *remote); | |
940 | ||
fcccf304 | 941 | /** |
942 | * Give the remote a new name | |
943 | * | |
944 | * All remote-tracking branches and configuration settings | |
945 | * for the remote are updated. | |
946 | * | |
032ba9e4 | 947 | * The new name will be checked for validity. |
948 | * See `git_tag_create()` for rules about valid names. | |
949 | * | |
46c8f7f8 CMN |
950 | * No loaded instances of a the remote with the old name will change |
951 | * their name or their list of refspecs. | |
ae35aa07 | 952 | * |
72bca13e CMN |
953 | * @param problems non-default refspecs cannot be renamed and will be |
954 | * stored here for further processing by the caller. Always free this | |
b874629b | 955 | * strarray on successful return. |
46c8f7f8 | 956 | * @param repo the repository in which to rename |
37996d47 | 957 | * @param name the current name of the remote |
fcccf304 | 958 | * @param new_name the new name the remote should bear |
ae35aa07 | 959 | * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code |
fcccf304 | 960 | */ |
961 | GIT_EXTERN(int) git_remote_rename( | |
72bca13e | 962 | git_strarray *problems, |
46c8f7f8 CMN |
963 | git_repository *repo, |
964 | const char *name, | |
72bca13e | 965 | const char *new_name); |
f70e466f | 966 | |
2bca5b67 | 967 | /** |
968 | * Ensure the remote name is well-formed. | |
969 | * | |
c25aa7cd | 970 | * @param valid output pointer to set with validity of given remote name |
2bca5b67 | 971 | * @param remote_name name to be checked. |
c25aa7cd | 972 | * @return 0 on success or an error code |
2bca5b67 | 973 | */ |
c25aa7cd | 974 | GIT_EXTERN(int) git_remote_name_is_valid(int *valid, const char *remote_name); |
2bca5b67 | 975 | |
40e48ea4 | 976 | /** |
977 | * Delete an existing persisted remote. | |
978 | * | |
979 | * All remote-tracking branches and configuration settings | |
980 | * for the remote will be removed. | |
981 | * | |
262eec23 | 982 | * @param repo the repository in which to act |
12b7394c | 983 | * @param name the name of the remote to delete |
40e48ea4 | 984 | * @return 0 on success, or an error code. |
985 | */ | |
262eec23 | 986 | GIT_EXTERN(int) git_remote_delete(git_repository *repo, const char *name); |
40e48ea4 | 987 | |
d22db24f CMN |
988 | /** |
989 | * Retrieve the name of the remote's default branch | |
990 | * | |
991 | * The default branch of a repository is the branch which HEAD points | |
992 | * to. If the remote does not support reporting this information | |
993 | * directly, it performs the guess as git does; that is, if there are | |
994 | * multiple branches which point to the same commit, the first one is | |
995 | * chosen. If the master branch is a candidate, it wins. | |
996 | * | |
997 | * This function must only be called after connecting. | |
998 | * | |
c25aa7cd | 999 | * @param out the buffer in which to store the reference name |
d22db24f CMN |
1000 | * @param remote the remote |
1001 | * @return 0, GIT_ENOTFOUND if the remote does not have any references | |
1002 | * or none of them point to HEAD's commit, or an error message. | |
1003 | */ | |
1004 | GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote); | |
1005 | ||
1e76676f | 1006 | /** @} */ |
bdd18829 | 1007 | GIT_END_DECL |
9c82357b | 1008 | #endif |