]>
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 | |
59 | * use `git_remote_create_init_options`. | |
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 | */ | |
97 | GIT_EXTERN(int) git_remote_create_init_options( | |
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 PS |
214 | * If url.*.insteadOf has been configured for this URL, it will |
215 | * return the modified URL. | |
216 | * | |
9c82357b CMN |
217 | * @param remote the remote |
218 | * @return a pointer to the url | |
219 | */ | |
df705148 | 220 | GIT_EXTERN(const char *) git_remote_url(const git_remote *remote); |
9c82357b | 221 | |
76501590 SC |
222 | /** |
223 | * Get the remote's url for pushing | |
224 | * | |
ec0c4c40 PS |
225 | * If url.*.pushInsteadOf has been configured for this URL, it |
226 | * will return the modified URL. | |
227 | * | |
76501590 SC |
228 | * @param remote the remote |
229 | * @return a pointer to the url or NULL if no special url for pushing is set | |
230 | */ | |
df705148 | 231 | GIT_EXTERN(const char *) git_remote_pushurl(const git_remote *remote); |
76501590 SC |
232 | |
233 | /** | |
22261344 | 234 | * Set the remote's url in the configuration |
76501590 | 235 | * |
22261344 CMN |
236 | * Remote objects already in memory will not be affected. This assumes |
237 | * the common case of a single-url remote and will otherwise return an error. | |
76501590 | 238 | * |
22261344 CMN |
239 | * @param repo the repository in which to perform the change |
240 | * @param remote the remote's name | |
76501590 SC |
241 | * @param url the url to set |
242 | * @return 0 or an error value | |
243 | */ | |
22261344 | 244 | GIT_EXTERN(int) git_remote_set_url(git_repository *repo, const char *remote, const char* url); |
76501590 SC |
245 | |
246 | /** | |
22261344 | 247 | * Set the remote's url for pushing in the configuration. |
76501590 | 248 | * |
22261344 CMN |
249 | * Remote objects already in memory will not be affected. This assumes |
250 | * the common case of a single-url remote and will otherwise return an error. | |
76501590 | 251 | * |
22261344 CMN |
252 | * |
253 | * @param repo the repository in which to perform the change | |
254 | * @param remote the remote's name | |
255 | * @param url the url to set | |
76501590 | 256 | */ |
22261344 | 257 | GIT_EXTERN(int) git_remote_set_pushurl(git_repository *repo, const char *remote, const char* url); |
76501590 | 258 | |
bcb8c007 | 259 | /** |
77254990 | 260 | * Add a fetch refspec to the remote's configuration |
bcb8c007 | 261 | * |
77254990 CMN |
262 | * Add the given refspec to the fetch list in the configuration. No |
263 | * loaded remote instances will be affected. | |
266af6d8 | 264 | * |
77254990 CMN |
265 | * @param repo the repository in which to change the configuration |
266 | * @param remote the name of the remote to change | |
266af6d8 | 267 | * @param refspec the new fetch refspec |
c6e942fb | 268 | * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value |
bcb8c007 | 269 | */ |
77254990 | 270 | GIT_EXTERN(int) git_remote_add_fetch(git_repository *repo, const char *remote, const char *refspec); |
bc6374ea CMN |
271 | |
272 | /** | |
273 | * Get the remote's list of fetch refspecs | |
274 | * | |
275 | * The memory is owned by the user and should be freed with | |
276 | * `git_strarray_free`. | |
277 | * | |
278 | * @param array pointer to the array in which to store the strings | |
279 | * @param remote the remote to query | |
280 | */ | |
11f6ad5f | 281 | GIT_EXTERN(int) git_remote_get_fetch_refspecs(git_strarray *array, const git_remote *remote); |
bcb8c007 | 282 | |
9c82357b | 283 | /** |
77254990 | 284 | * Add a push refspec to the remote's configuration |
9c82357b | 285 | * |
77254990 CMN |
286 | * Add the given refspec to the push list in the configuration. No |
287 | * loaded remote instances will be affected. | |
266af6d8 | 288 | * |
77254990 CMN |
289 | * @param repo the repository in which to change the configuration |
290 | * @param remote the name of the remote to change | |
4330ab26 | 291 | * @param refspec the new push refspec |
c6e942fb | 292 | * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value |
bcb8c007 | 293 | */ |
77254990 | 294 | GIT_EXTERN(int) git_remote_add_push(git_repository *repo, const char *remote, const char *refspec); |
bc6374ea CMN |
295 | |
296 | /** | |
297 | * Get the remote's list of push refspecs | |
298 | * | |
299 | * The memory is owned by the user and should be freed with | |
300 | * `git_strarray_free`. | |
301 | * | |
302 | * @param array pointer to the array in which to store the strings | |
303 | * @param remote the remote to query | |
304 | */ | |
11f6ad5f | 305 | GIT_EXTERN(int) git_remote_get_push_refspecs(git_strarray *array, const git_remote *remote); |
bcb8c007 | 306 | |
1ffd0806 CMN |
307 | /** |
308 | * Get the number of refspecs for a remote | |
309 | * | |
310 | * @param remote the remote | |
311 | * @return the amount of refspecs configured in this remote | |
312 | */ | |
11f6ad5f | 313 | GIT_EXTERN(size_t) git_remote_refspec_count(const git_remote *remote); |
1ffd0806 CMN |
314 | |
315 | /** | |
316 | * Get a refspec from the remote | |
317 | * | |
318 | * @param remote the remote to query | |
319 | * @param n the refspec to get | |
320 | * @return the nth refspec | |
321 | */ | |
11f6ad5f | 322 | GIT_EXTERN(const git_refspec *)git_remote_get_refspec(const git_remote *remote, size_t n); |
1ffd0806 | 323 | |
9ba49bb5 CMN |
324 | /** |
325 | * Open a connection to a remote | |
326 | * | |
e1d88030 CMN |
327 | * The transport is selected based on the URL. The direction argument |
328 | * is due to a limitation of the git protocol (over TCP or SSH) which | |
329 | * starts up a specific binary which can only do the one or the other. | |
9ba49bb5 CMN |
330 | * |
331 | * @param remote the remote to connect to | |
4a38143c CMN |
332 | * @param direction GIT_DIRECTION_FETCH if you want to fetch or |
333 | * GIT_DIRECTION_PUSH if you want to push | |
8f0104ec | 334 | * @param callbacks the callbacks to use for this connection |
07bd3e57 | 335 | * @param proxy_opts proxy settings |
4f2b6093 | 336 | * @param custom_headers extra HTTP headers to use in this connection |
e172cf08 | 337 | * @return 0 or an error code |
9ba49bb5 | 338 | */ |
07bd3e57 | 339 | 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 |
340 | |
341 | /** | |
699dfcc3 | 342 | * Get the remote repository's reference advertisement list |
9ba49bb5 | 343 | * |
699dfcc3 CMN |
344 | * Get the list of references with which the server responds to a new |
345 | * connection. | |
9ba49bb5 | 346 | * |
699dfcc3 CMN |
347 | * The remote (or more exactly its transport) must have connected to |
348 | * the remote repository. This list is available as soon as the | |
349 | * connection to the remote is initiated and it remains available | |
350 | * after disconnecting. | |
351 | * | |
352 | * The memory belongs to the remote. The pointer will be valid as long | |
353 | * as a new connection is not initiated, but it is recommended that | |
354 | * you make a copy in order to make use of the data. | |
5dca2010 | 355 | * |
359dce72 CMN |
356 | * @param out pointer to the array |
357 | * @param size the number of remote heads | |
9ba49bb5 | 358 | * @param remote the remote |
359dce72 | 359 | * @return 0 on success, or an error code |
9ba49bb5 | 360 | */ |
359dce72 | 361 | GIT_EXTERN(int) git_remote_ls(const git_remote_head ***out, size_t *size, git_remote *remote); |
9ba49bb5 | 362 | |
6ac3b707 CMN |
363 | /** |
364 | * Check whether the remote is connected | |
365 | * | |
366 | * Check whether the remote's underlying transport is connected to the | |
367 | * remote host. | |
368 | * | |
b0b80658 | 369 | * @param remote the remote |
6ac3b707 CMN |
370 | * @return 1 if it's connected, 0 otherwise. |
371 | */ | |
11f6ad5f | 372 | GIT_EXTERN(int) git_remote_connected(const git_remote *remote); |
6ac3b707 | 373 | |
f0d2ddbb CMN |
374 | /** |
375 | * Cancel the operation | |
376 | * | |
377 | * At certain points in its operation, the network code checks whether | |
378 | * the operation has been cancelled and if so stops the operation. | |
b0b80658 BS |
379 | * |
380 | * @param remote the remote | |
f0d2ddbb CMN |
381 | */ |
382 | GIT_EXTERN(void) git_remote_stop(git_remote *remote); | |
383 | ||
4cf01e9a CMN |
384 | /** |
385 | * Disconnect from the remote | |
386 | * | |
8fd7dd77 | 387 | * Close the connection to the remote. |
4cf01e9a CMN |
388 | * |
389 | * @param remote the remote to disconnect from | |
390 | */ | |
391 | GIT_EXTERN(void) git_remote_disconnect(git_remote *remote); | |
392 | ||
9c82357b CMN |
393 | /** |
394 | * Free the memory associated with a remote | |
395 | * | |
8af503bc MS |
396 | * This also disconnects from the remote, if the connection |
397 | * has not been closed yet (using git_remote_disconnect). | |
398 | * | |
9c82357b CMN |
399 | * @param remote the remote to free |
400 | */ | |
9462c471 | 401 | GIT_EXTERN(void) git_remote_free(git_remote *remote); |
9c82357b | 402 | |
8171998f CMN |
403 | /** |
404 | * Get a list of the configured remotes for a repo | |
405 | * | |
406 | * The string array must be freed by the user. | |
407 | * | |
df705148 | 408 | * @param out a string array which receives the names of the remotes |
8171998f | 409 | * @param repo the repository to query |
e172cf08 | 410 | * @return 0 or an error code |
8171998f | 411 | */ |
df705148 | 412 | GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo); |
8171998f | 413 | |
b3aaa7a7 CMN |
414 | /** |
415 | * Argument to the completion callback which tells it which operation | |
416 | * finished. | |
417 | */ | |
418 | typedef enum git_remote_completion_type { | |
419 | GIT_REMOTE_COMPLETION_DOWNLOAD, | |
420 | GIT_REMOTE_COMPLETION_INDEXING, | |
421 | GIT_REMOTE_COMPLETION_ERROR, | |
422 | } git_remote_completion_type; | |
423 | ||
8f0104ec | 424 | /** Push network progress notification function */ |
ac3d33df | 425 | typedef int GIT_CALLBACK(git_push_transfer_progress)( |
8f0104ec CMN |
426 | unsigned int current, |
427 | unsigned int total, | |
428 | size_t bytes, | |
429 | void* payload); | |
430 | /** | |
431 | * Represents an update which will be performed on the remote during push | |
432 | */ | |
433 | typedef struct { | |
434 | /** | |
435 | * The source name of the reference | |
436 | */ | |
437 | char *src_refname; | |
438 | /** | |
439 | * The name of the reference to update on the server | |
440 | */ | |
441 | char *dst_refname; | |
442 | /** | |
443 | * The current target of the reference | |
444 | */ | |
445 | git_oid src; | |
446 | /** | |
447 | * The new target for the reference | |
448 | */ | |
449 | git_oid dst; | |
450 | } git_push_update; | |
451 | ||
452 | /** | |
788fcdb8 ES |
453 | * Callback used to inform of upcoming updates. |
454 | * | |
8f0104ec CMN |
455 | * @param updates an array containing the updates which will be sent |
456 | * as commands to the destination. | |
457 | * @param len number of elements in `updates` | |
458 | * @param payload Payload provided by the caller | |
459 | */ | |
ac3d33df | 460 | typedef int GIT_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload); |
8f0104ec | 461 | |
eae0bfdc PP |
462 | /** |
463 | * Callback used to inform of the update status from the remote. | |
464 | * | |
465 | * Called for each updated reference on push. If `status` is | |
466 | * not `NULL`, the update was rejected by the remote server | |
467 | * and `status` contains the reason given. | |
468 | * | |
469 | * @param refname refname specifying to the remote ref | |
470 | * @param status status message sent from the remote | |
471 | * @param data data provided by the caller | |
472 | * @return 0 on success, otherwise an error | |
473 | */ | |
ac3d33df | 474 | typedef int GIT_CALLBACK(git_push_update_reference_cb)(const char *refname, const char *status, void *data); |
eae0bfdc | 475 | |
b3aaa7a7 CMN |
476 | /** |
477 | * The callback settings structure | |
478 | * | |
ffc97d51 CMN |
479 | * Set the callbacks to be called by the remote when informing the user |
480 | * about the progress of the network operations. | |
b3aaa7a7 CMN |
481 | */ |
482 | struct git_remote_callbacks { | |
bde336ea | 483 | unsigned int version; |
ffc97d51 CMN |
484 | /** |
485 | * Textual progress from the remote. Text send over the | |
486 | * progress side-band will be passed to this function (this is | |
fc15befd | 487 | * the 'counting objects' output). |
ffc97d51 | 488 | */ |
48e60ae7 | 489 | git_transport_message_cb sideband_progress; |
ffc97d51 CMN |
490 | |
491 | /** | |
492 | * Completion is called when different parts of the download | |
493 | * process are done (currently unused). | |
494 | */ | |
ac3d33df | 495 | int GIT_CALLBACK(completion)(git_remote_completion_type type, void *data); |
ffc97d51 CMN |
496 | |
497 | /** | |
498 | * This will be called if the remote host requires | |
499 | * authentication in order to connect to it. | |
bc0a6198 CMN |
500 | * |
501 | * Returning GIT_PASSTHROUGH will make libgit2 behave as | |
502 | * though this field isn't set. | |
ffc97d51 | 503 | */ |
48e60ae7 | 504 | git_cred_acquire_cb credentials; |
ffc97d51 | 505 | |
9b940586 CMN |
506 | /** |
507 | * If cert verification fails, this will be called to let the | |
508 | * user make the final decision of whether to allow the | |
ac3d33df JK |
509 | * connection to proceed. Returns 0 to allow the connection |
510 | * or a negative value to indicate an error. | |
9b940586 | 511 | */ |
788fcdb8 | 512 | git_transport_certificate_check_cb certificate_check; |
9b940586 | 513 | |
ffc97d51 CMN |
514 | /** |
515 | * During the download of new data, this will be regularly | |
516 | * called with the current count of progress done by the | |
517 | * indexer. | |
518 | */ | |
48e60ae7 | 519 | git_transfer_progress_cb transfer_progress; |
ffc97d51 CMN |
520 | |
521 | /** | |
522 | * Each time a reference is updated locally, this function | |
523 | * will be called with information about it. | |
524 | */ | |
ac3d33df | 525 | int GIT_CALLBACK(update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data); |
ffc97d51 | 526 | |
3149547b CMN |
527 | /** |
528 | * Function to call with progress information during pack | |
529 | * building. Be aware that this is called inline with pack | |
530 | * building operations, so performance may be affected. | |
531 | */ | |
532 | git_packbuilder_progress pack_progress; | |
533 | ||
534 | /** | |
535 | * Function to call with progress information during the | |
536 | * upload portion of a push. Be aware that this is called | |
537 | * inline with pack building operations, so performance may be | |
538 | * affected. | |
539 | */ | |
540 | git_push_transfer_progress push_transfer_progress; | |
541 | ||
542 | /** | |
eae0bfdc | 543 | * See documentation of git_push_update_reference_cb |
3149547b | 544 | */ |
eae0bfdc | 545 | git_push_update_reference_cb push_update_reference; |
3149547b | 546 | |
efc2fec5 CMN |
547 | /** |
548 | * Called once between the negotiation step and the upload. It | |
549 | * provides information about what updates will be performed. | |
550 | */ | |
551 | git_push_negotiation push_negotiation; | |
552 | ||
058b753c CMN |
553 | /** |
554 | * Create the transport to use for this operation. Leave NULL | |
555 | * to auto-detect. | |
556 | */ | |
557 | git_transport_cb transport; | |
558 | ||
ffc97d51 CMN |
559 | /** |
560 | * This will be passed to each of the callbacks in this struct | |
561 | * as the last parameter. | |
562 | */ | |
df705148 | 563 | void *payload; |
b3aaa7a7 CMN |
564 | }; |
565 | ||
bde336ea | 566 | #define GIT_REMOTE_CALLBACKS_VERSION 1 |
fac43c54 | 567 | #define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION} |
bde336ea | 568 | |
b9f81997 MB |
569 | /** |
570 | * Initializes a `git_remote_callbacks` with default values. Equivalent to | |
571 | * creating an instance with GIT_REMOTE_CALLBACKS_INIT. | |
572 | * | |
bc91347b RB |
573 | * @param opts the `git_remote_callbacks` struct to initialize |
574 | * @param version Version of struct; pass `GIT_REMOTE_CALLBACKS_VERSION` | |
b9f81997 MB |
575 | * @return Zero on success; -1 on failure. |
576 | */ | |
577 | GIT_EXTERN(int) git_remote_init_callbacks( | |
bc91347b RB |
578 | git_remote_callbacks *opts, |
579 | unsigned int version); | |
b9f81997 | 580 | |
6fb373a0 CMN |
581 | typedef enum { |
582 | /** | |
583 | * Use the setting from the configuration | |
584 | */ | |
c2418f46 | 585 | GIT_FETCH_PRUNE_UNSPECIFIED, |
6fb373a0 CMN |
586 | /** |
587 | * Force pruning on | |
588 | */ | |
589 | GIT_FETCH_PRUNE, | |
590 | /** | |
591 | * Force pruning off | |
592 | */ | |
593 | GIT_FETCH_NO_PRUNE, | |
594 | } git_fetch_prune_t; | |
595 | ||
35a8a8c5 CMN |
596 | /** |
597 | * Automatic tag following option | |
598 | * | |
599 | * Lets us select the --tags option to use. | |
600 | */ | |
601 | typedef enum { | |
602 | /** | |
603 | * Use the setting from the configuration. | |
604 | */ | |
c2418f46 | 605 | GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED = 0, |
35a8a8c5 CMN |
606 | /** |
607 | * Ask the server for tags pointing to objects we're already | |
608 | * downloading. | |
609 | */ | |
610 | GIT_REMOTE_DOWNLOAD_TAGS_AUTO, | |
611 | /** | |
612 | * Don't ask for any tags beyond the refspecs. | |
613 | */ | |
614 | GIT_REMOTE_DOWNLOAD_TAGS_NONE, | |
615 | /** | |
616 | * Ask for the all the tags. | |
617 | */ | |
618 | GIT_REMOTE_DOWNLOAD_TAGS_ALL, | |
619 | } git_remote_autotag_option_t; | |
620 | ||
37996d47 RRC |
621 | /** |
622 | * Fetch options structure. | |
623 | * | |
624 | * Zero out for defaults. Initialize with `GIT_FETCH_OPTIONS_INIT` macro to | |
625 | * correctly set the `version` field. E.g. | |
626 | * | |
627 | * git_fetch_options opts = GIT_FETCH_OPTIONS_INIT; | |
628 | */ | |
8f0104ec CMN |
629 | typedef struct { |
630 | int version; | |
631 | ||
632 | /** | |
633 | * Callbacks to use for this fetch operation | |
634 | */ | |
635 | git_remote_callbacks callbacks; | |
6fb373a0 CMN |
636 | |
637 | /** | |
638 | * Whether to perform a prune after the fetch | |
639 | */ | |
640 | git_fetch_prune_t prune; | |
3eff2a57 CMN |
641 | |
642 | /** | |
643 | * Whether to write the results to FETCH_HEAD. Defaults to | |
644 | * on. Leave this default in order to behave like git. | |
645 | */ | |
646 | int update_fetchhead; | |
35a8a8c5 CMN |
647 | |
648 | /** | |
649 | * Determines how to behave regarding tags on the remote, such | |
650 | * as auto-downloading tags for objects we're downloading or | |
651 | * downloading all of them. | |
652 | * | |
653 | * The default is to auto-follow tags. | |
654 | */ | |
655 | git_remote_autotag_option_t download_tags; | |
c49126c8 | 656 | |
07bd3e57 CMN |
657 | /** |
658 | * Proxy options to use, by default no proxy is used. | |
659 | */ | |
660 | git_proxy_options proxy_opts; | |
661 | ||
c49126c8 MB |
662 | /** |
663 | * Extra headers for this fetch operation | |
664 | */ | |
665 | git_strarray custom_headers; | |
8f0104ec CMN |
666 | } git_fetch_options; |
667 | ||
668 | #define GIT_FETCH_OPTIONS_VERSION 1 | |
07bd3e57 CMN |
669 | #define GIT_FETCH_OPTIONS_INIT { GIT_FETCH_OPTIONS_VERSION, GIT_REMOTE_CALLBACKS_INIT, GIT_FETCH_PRUNE_UNSPECIFIED, 1, \ |
670 | GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED, GIT_PROXY_OPTIONS_INIT } | |
8f0104ec | 671 | |
b3aaa7a7 | 672 | /** |
ac3d33df JK |
673 | * Initialize git_fetch_options structure |
674 | * | |
8f0104ec | 675 | * Initializes a `git_fetch_options` with default values. Equivalent to |
ac3d33df | 676 | * creating an instance with `GIT_FETCH_OPTIONS_INIT`. |
b3aaa7a7 | 677 | * |
ac3d33df JK |
678 | * @param opts The `git_fetch_options` struct to initialize. |
679 | * @param version The struct version; pass `GIT_FETCH_OPTIONS_VERSION`. | |
8f0104ec CMN |
680 | * @return Zero on success; -1 on failure. |
681 | */ | |
682 | GIT_EXTERN(int) git_fetch_init_options( | |
683 | git_fetch_options *opts, | |
684 | unsigned int version); | |
685 | ||
686 | ||
687 | /** | |
688 | * Controls the behavior of a git_push object. | |
689 | */ | |
690 | typedef struct { | |
691 | unsigned int version; | |
692 | ||
693 | /** | |
694 | * If the transport being used to push to the remote requires the creation | |
695 | * of a pack file, this controls the number of worker threads used by | |
696 | * the packbuilder when creating that pack file to be sent to the remote. | |
697 | * | |
698 | * If set to 0, the packbuilder will auto-detect the number of threads | |
699 | * to create. The default value is 1. | |
700 | */ | |
701 | unsigned int pb_parallelism; | |
702 | ||
703 | /** | |
704 | * Callbacks to use for this push operation | |
705 | */ | |
706 | git_remote_callbacks callbacks; | |
9da32a62 | 707 | |
07bd3e57 CMN |
708 | /** |
709 | * Proxy options to use, by default no proxy is used. | |
710 | */ | |
711 | git_proxy_options proxy_opts; | |
712 | ||
9da32a62 MB |
713 | /** |
714 | * Extra headers for this push operation | |
715 | */ | |
716 | git_strarray custom_headers; | |
8f0104ec CMN |
717 | } git_push_options; |
718 | ||
719 | #define GIT_PUSH_OPTIONS_VERSION 1 | |
ac3d33df | 720 | #define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT } |
8f0104ec CMN |
721 | |
722 | /** | |
ac3d33df JK |
723 | * Initialize git_push_options structure |
724 | * | |
8f0104ec | 725 | * Initializes a `git_push_options` with default values. Equivalent to |
ac3d33df | 726 | * creating an instance with `GIT_PUSH_OPTIONS_INIT`. |
b3aaa7a7 | 727 | * |
ac3d33df JK |
728 | * @param opts The `git_push_options` struct to initialize. |
729 | * @param version The struct version; pass `GIT_PUSH_OPTIONS_VERSION`. | |
8f0104ec CMN |
730 | * @return Zero on success; -1 on failure. |
731 | */ | |
732 | GIT_EXTERN(int) git_push_init_options( | |
733 | git_push_options *opts, | |
734 | unsigned int version); | |
735 | ||
736 | /** | |
737 | * Download and index the packfile | |
738 | * | |
739 | * Connect to the remote if it hasn't been done yet, negotiate with | |
740 | * the remote git which objects are missing, download and index the | |
741 | * packfile. | |
742 | * | |
743 | * The .idx file will be created and both it and the packfile with be | |
744 | * renamed to their final name. | |
745 | * | |
746 | * @param remote the remote | |
747 | * @param refspecs the refspecs to use for this negotiation and | |
748 | * download. Use NULL or an empty array to use the base refspecs | |
749 | * @param opts the options to use for this fetch | |
9267ff58 | 750 | * @return 0 or an error code |
b3aaa7a7 | 751 | */ |
8f0104ec | 752 | GIT_EXTERN(int) git_remote_download(git_remote *remote, const git_strarray *refspecs, const git_fetch_options *opts); |
b3aaa7a7 | 753 | |
2efd7df6 | 754 | /** |
8f0104ec | 755 | * Create a packfile and send it to the server |
2efd7df6 | 756 | * |
8f0104ec CMN |
757 | * Connect to the remote if it hasn't been done yet, negotiate with |
758 | * the remote git which objects are missing, create a packfile with the missing objects and send it. | |
2efd7df6 | 759 | * |
8f0104ec CMN |
760 | * @param remote the remote |
761 | * @param refspecs the refspecs to use for this negotiation and | |
762 | * upload. Use NULL or an empty array to use the base refspecs | |
763 | * @param opts the options to use for this push | |
764 | * @return 0 or an error code | |
765 | */ | |
766 | GIT_EXTERN(int) git_remote_upload(git_remote *remote, const git_strarray *refspecs, const git_push_options *opts); | |
767 | ||
768 | /** | |
769 | * Update the tips to the new state | |
770 | * | |
771 | * @param remote the remote to update | |
772 | * @param reflog_message The message to insert into the reflogs. If | |
773 | * NULL and fetching, the default is "fetch <name>", where <name> is | |
774 | * the name of the remote (or its url, for in-memory remotes). This | |
775 | * parameter is ignored when pushing. | |
776 | * @param callbacks pointer to the callback structure to use | |
3eff2a57 | 777 | * @param update_fetchhead whether to write to FETCH_HEAD. Pass 1 to behave like git. |
35a8a8c5 CMN |
778 | * @param download_tags what the behaviour for downloading tags is for this fetch. This is |
779 | * ignored for push. This must be the same value passed to `git_remote_download()`. | |
8f0104ec CMN |
780 | * @return 0 or an error code |
781 | */ | |
782 | GIT_EXTERN(int) git_remote_update_tips( | |
783 | git_remote *remote, | |
784 | const git_remote_callbacks *callbacks, | |
3eff2a57 | 785 | int update_fetchhead, |
35a8a8c5 | 786 | git_remote_autotag_option_t download_tags, |
8f0104ec CMN |
787 | const char *reflog_message); |
788 | ||
789 | /** | |
790 | * Download new data and update tips | |
791 | * | |
792 | * Convenience function to connect to a remote, download the data, | |
793 | * disconnect and update the remote-tracking branches. | |
794 | * | |
795 | * @param remote the remote to fetch from | |
796 | * @param refspecs the refspecs to use for this fetch. Pass NULL or an | |
797 | * empty array to use the base refspecs. | |
798 | * @param opts options to use for this fetch | |
799 | * @param reflog_message The message to insert into the reflogs. If NULL, the | |
800 | * default is "fetch" | |
801 | * @return 0 or an error code | |
2efd7df6 | 802 | */ |
8f0104ec CMN |
803 | GIT_EXTERN(int) git_remote_fetch( |
804 | git_remote *remote, | |
805 | const git_strarray *refspecs, | |
806 | const git_fetch_options *opts, | |
807 | const char *reflog_message); | |
808 | ||
809 | /** | |
810 | * Prune tracking refs that are no longer present on remote | |
811 | * | |
812 | * @param remote the remote to prune | |
813 | * @param callbacks callbacks to use for this prune | |
814 | * @return 0 or an error code | |
815 | */ | |
816 | GIT_EXTERN(int) git_remote_prune(git_remote *remote, const git_remote_callbacks *callbacks); | |
817 | ||
818 | /** | |
819 | * Perform a push | |
820 | * | |
821 | * Peform all the steps from a push. | |
822 | * | |
823 | * @param remote the remote to push to | |
45071cec ET |
824 | * @param refspecs the refspecs to use for pushing. If NULL or an empty |
825 | * array, the configured refspecs will be used | |
8f0104ec CMN |
826 | * @param opts options to use for this push |
827 | */ | |
828 | GIT_EXTERN(int) git_remote_push(git_remote *remote, | |
829 | const git_strarray *refspecs, | |
830 | const git_push_options *opts); | |
2efd7df6 | 831 | |
d57c47dc BS |
832 | /** |
833 | * Get the statistics structure that is filled in by the fetch operation. | |
834 | */ | |
7d222e13 | 835 | GIT_EXTERN(const git_transfer_progress *) git_remote_stats(git_remote *remote); |
d57c47dc | 836 | |
f70e466f CMN |
837 | /** |
838 | * Retrieve the tag auto-follow setting | |
839 | * | |
840 | * @param remote the remote to query | |
841 | * @return the auto-follow setting | |
842 | */ | |
11f6ad5f | 843 | GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(const git_remote *remote); |
f70e466f CMN |
844 | |
845 | /** | |
35a8a8c5 CMN |
846 | * Set the remote's tag following setting. |
847 | * | |
848 | * The change will be made in the configuration. No loaded remotes | |
849 | * will be affected. | |
f70e466f | 850 | * |
35a8a8c5 CMN |
851 | * @param repo the repository in which to make the change |
852 | * @param remote the name of the remote | |
853 | * @param value the new value to take. | |
f70e466f | 854 | */ |
35a8a8c5 | 855 | GIT_EXTERN(int) git_remote_set_autotag(git_repository *repo, const char *remote, git_remote_autotag_option_t value); |
5f473947 L |
856 | /** |
857 | * Retrieve the ref-prune setting | |
858 | * | |
859 | * @param remote the remote to query | |
860 | * @return the ref-prune setting | |
861 | */ | |
862 | GIT_EXTERN(int) git_remote_prune_refs(const git_remote *remote); | |
863 | ||
fcccf304 | 864 | /** |
865 | * Give the remote a new name | |
866 | * | |
867 | * All remote-tracking branches and configuration settings | |
868 | * for the remote are updated. | |
869 | * | |
032ba9e4 | 870 | * The new name will be checked for validity. |
871 | * See `git_tag_create()` for rules about valid names. | |
872 | * | |
46c8f7f8 CMN |
873 | * No loaded instances of a the remote with the old name will change |
874 | * their name or their list of refspecs. | |
ae35aa07 | 875 | * |
72bca13e CMN |
876 | * @param problems non-default refspecs cannot be renamed and will be |
877 | * stored here for further processing by the caller. Always free this | |
b874629b | 878 | * strarray on successful return. |
46c8f7f8 | 879 | * @param repo the repository in which to rename |
37996d47 | 880 | * @param name the current name of the remote |
fcccf304 | 881 | * @param new_name the new name the remote should bear |
ae35aa07 | 882 | * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code |
fcccf304 | 883 | */ |
884 | GIT_EXTERN(int) git_remote_rename( | |
72bca13e | 885 | git_strarray *problems, |
46c8f7f8 CMN |
886 | git_repository *repo, |
887 | const char *name, | |
72bca13e | 888 | const char *new_name); |
f70e466f | 889 | |
2bca5b67 | 890 | /** |
891 | * Ensure the remote name is well-formed. | |
892 | * | |
893 | * @param remote_name name to be checked. | |
894 | * @return 1 if the reference name is acceptable; 0 if it isn't | |
895 | */ | |
896 | GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name); | |
897 | ||
40e48ea4 | 898 | /** |
899 | * Delete an existing persisted remote. | |
900 | * | |
901 | * All remote-tracking branches and configuration settings | |
902 | * for the remote will be removed. | |
903 | * | |
262eec23 | 904 | * @param repo the repository in which to act |
12b7394c | 905 | * @param name the name of the remote to delete |
40e48ea4 | 906 | * @return 0 on success, or an error code. |
907 | */ | |
262eec23 | 908 | GIT_EXTERN(int) git_remote_delete(git_repository *repo, const char *name); |
40e48ea4 | 909 | |
d22db24f CMN |
910 | /** |
911 | * Retrieve the name of the remote's default branch | |
912 | * | |
913 | * The default branch of a repository is the branch which HEAD points | |
914 | * to. If the remote does not support reporting this information | |
915 | * directly, it performs the guess as git does; that is, if there are | |
916 | * multiple branches which point to the same commit, the first one is | |
917 | * chosen. If the master branch is a candidate, it wins. | |
918 | * | |
919 | * This function must only be called after connecting. | |
920 | * | |
921 | * @param out the buffern in which to store the reference name | |
922 | * @param remote the remote | |
923 | * @return 0, GIT_ENOTFOUND if the remote does not have any references | |
924 | * or none of them point to HEAD's commit, or an error message. | |
925 | */ | |
926 | GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote); | |
927 | ||
1e76676f | 928 | /** @} */ |
bdd18829 | 929 | GIT_END_DECL |
9c82357b | 930 | #endif |