1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 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. 6 */ 7 #ifndef INCLUDE_git_remote_h__ 8 #define INCLUDE_git_remote_h__ 9 10 #include "common.h" 11 #include "repository.h" 12 #include "refspec.h" 13 #include "net.h" 14 #include "indexer.h" 15 #include "strarray.h" 16 #include "transport.h" 17 #include "pack.h" 18 #include "proxy.h" 19 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 28 29 /** 30 * Add a remote with the default fetch refspec to the repository's configuration. 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 36 * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code 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 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_options_init`. 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_options_init( 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 118 /** 119 * Add a remote with the provided fetch refspec (or default if NULL) to the repository's 120 * configuration. 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 126 * @param fetch the remote fetch value 127 * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code 128 */ 129 GIT_EXTERN(int) git_remote_create_with_fetchspec( 130 git_remote **out, 131 git_repository *repo, 132 const char *name, 133 const char *url, 134 const char *fetch); 135 136 /** 137 * Create an anonymous remote 138 * 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. 141 * 142 * @param out pointer to the new remote objects 143 * @param repo the associated repository 144 * @param url the remote repository's URL 145 * @return 0 or an error code 146 */ 147 GIT_EXTERN(int) git_remote_create_anonymous( 148 git_remote **out, 149 git_repository *repo, 150 const char *url); 151 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 170 /** 171 * Get the information for a particular remote 172 * 173 * The name will be checked for validity. 174 * See `git_tag_create()` for rules about valid names. 175 * 176 * @param out pointer to the new remote object 177 * @param repo the associated repository 178 * @param name the remote's name 179 * @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code 180 */ 181 GIT_EXTERN(int) git_remote_lookup(git_remote **out, git_repository *repo, const char *name); 182 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 */ 193 GIT_EXTERN(int) git_remote_dup(git_remote **dest, git_remote *source); 194 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 203 /** 204 * Get the remote's name 205 * 206 * @param remote the remote 207 * @return a pointer to the name or NULL for in-memory remotes 208 */ 209 GIT_EXTERN(const char *) git_remote_name(const git_remote *remote); 210 211 /** 212 * Get the remote's url 213 * 214 * If url.*.insteadOf has been configured for this URL, it will 215 * return the modified URL. If `git_remote_set_instance_pushurl` 216 * has been called for this remote, then that URL will be returned. 217 * 218 * @param remote the remote 219 * @return a pointer to the url 220 */ 221 GIT_EXTERN(const char *) git_remote_url(const git_remote *remote); 222 223 /** 224 * Get the remote's url for pushing. 225 * 226 * If url.*.pushInsteadOf has been configured for this URL, it 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. 229 * 230 * @param remote the remote 231 * @return a pointer to the url or NULL if no special url for pushing is set 232 */ 233 GIT_EXTERN(const char *) git_remote_pushurl(const git_remote *remote); 234 235 /** 236 * Set the remote's url in the configuration 237 * 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. 240 * 241 * @param repo the repository in which to perform the change 242 * @param remote the remote's name 243 * @param url the url to set 244 * @return 0 or an error value 245 */ 246 GIT_EXTERN(int) git_remote_set_url(git_repository *repo, const char *remote, const char* url); 247 248 /** 249 * Set the remote's url for pushing in the configuration. 250 * 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. 253 * 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 258 * @return 0, or an error code 259 */ 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); 281 282 /** 283 * Add a fetch refspec to the remote's configuration 284 * 285 * Add the given refspec to the fetch list in the configuration. No 286 * loaded remote instances will be affected. 287 * 288 * @param repo the repository in which to change the configuration 289 * @param remote the name of the remote to change 290 * @param refspec the new fetch refspec 291 * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value 292 */ 293 GIT_EXTERN(int) git_remote_add_fetch(git_repository *repo, const char *remote, const char *refspec); 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 */ 304 GIT_EXTERN(int) git_remote_get_fetch_refspecs(git_strarray *array, const git_remote *remote); 305 306 /** 307 * Add a push refspec to the remote's configuration 308 * 309 * Add the given refspec to the push list in the configuration. No 310 * loaded remote instances will be affected. 311 * 312 * @param repo the repository in which to change the configuration 313 * @param remote the name of the remote to change 314 * @param refspec the new push refspec 315 * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value 316 */ 317 GIT_EXTERN(int) git_remote_add_push(git_repository *repo, const char *remote, const char *refspec); 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 */ 328 GIT_EXTERN(int) git_remote_get_push_refspecs(git_strarray *array, const git_remote *remote); 329 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 */ 336 GIT_EXTERN(size_t) git_remote_refspec_count(const git_remote *remote); 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 */ 345 GIT_EXTERN(const git_refspec *)git_remote_get_refspec(const git_remote *remote, size_t n); 346 347 /** 348 * Open a connection to a remote 349 * 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. 353 * 354 * @param remote the remote to connect to 355 * @param direction GIT_DIRECTION_FETCH if you want to fetch or 356 * GIT_DIRECTION_PUSH if you want to push 357 * @param callbacks the callbacks to use for this connection 358 * @param proxy_opts proxy settings 359 * @param custom_headers extra HTTP headers to use in this connection 360 * @return 0 or an error code 361 */ 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); 363 364 /** 365 * Get the remote repository's reference advertisement list 366 * 367 * Get the list of references with which the server responds to a new 368 * connection. 369 * 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. 378 * 379 * @param out pointer to the array 380 * @param size the number of remote heads 381 * @param remote the remote 382 * @return 0 on success, or an error code 383 */ 384 GIT_EXTERN(int) git_remote_ls(const git_remote_head ***out, size_t *size, git_remote *remote); 385 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 * 392 * @param remote the remote 393 * @return 1 if it's connected, 0 otherwise. 394 */ 395 GIT_EXTERN(int) git_remote_connected(const git_remote *remote); 396 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. 402 * 403 * @param remote the remote 404 * @return 0 on success, or an error code 405 */ 406 GIT_EXTERN(int) git_remote_stop(git_remote *remote); 407 408 /** 409 * Disconnect from the remote 410 * 411 * Close the connection to the remote. 412 * 413 * @param remote the remote to disconnect from 414 * @return 0 on success, or an error code 415 */ 416 GIT_EXTERN(int) git_remote_disconnect(git_remote *remote); 417 418 /** 419 * Free the memory associated with a remote 420 * 421 * This also disconnects from the remote, if the connection 422 * has not been closed yet (using git_remote_disconnect). 423 * 424 * @param remote the remote to free 425 */ 426 GIT_EXTERN(void) git_remote_free(git_remote *remote); 427 428 /** 429 * Get a list of the configured remotes for a repo 430 * 431 * The string array must be freed by the user. 432 * 433 * @param out a string array which receives the names of the remotes 434 * @param repo the repository to query 435 * @return 0 or an error code 436 */ 437 GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo); 438 439 /** 440 * Argument to the completion callback which tells it which operation 441 * finished. 442 */ 443 typedef enum git_remote_completion_t { 444 GIT_REMOTE_COMPLETION_DOWNLOAD, 445 GIT_REMOTE_COMPLETION_INDEXING, 446 GIT_REMOTE_COMPLETION_ERROR, 447 } git_remote_completion_t; 448 449 /** Push network progress notification function */ 450 typedef int GIT_CALLBACK(git_push_transfer_progress_cb)( 451 unsigned int current, 452 unsigned int total, 453 size_t bytes, 454 void* payload); 455 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 /** 479 * Callback used to inform of upcoming updates. 480 * 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 */ 486 typedef int GIT_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload); 487 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 */ 500 typedef int GIT_CALLBACK(git_push_update_reference_cb)(const char *refname, const char *status, void *data); 501 502 #ifndef GIT_DEPRECATE_HARD 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 514 * @deprecated Use `git_remote_set_instance_url` 515 */ 516 typedef int GIT_CALLBACK(git_url_resolve_cb)(git_buf *url_resolved, const char *url, int direction, void *payload); 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); 530 531 /** 532 * The callback settings structure 533 * 534 * Set the callbacks to be called by the remote when informing the user 535 * about the progress of the network operations. 536 */ 537 struct git_remote_callbacks { 538 unsigned int version; /**< The version */ 539 540 /** 541 * Textual progress from the remote. Text send over the 542 * progress side-band will be passed to this function (this is 543 * the 'counting objects' output). 544 */ 545 git_transport_message_cb sideband_progress; 546 547 /** 548 * Completion is called when different parts of the download 549 * process are done (currently unused). 550 */ 551 int GIT_CALLBACK(completion)(git_remote_completion_t type, void *data); 552 553 /** 554 * This will be called if the remote host requires 555 * authentication in order to connect to it. 556 * 557 * Returning GIT_PASSTHROUGH will make libgit2 behave as 558 * though this field isn't set. 559 */ 560 git_credential_acquire_cb credentials; 561 562 /** 563 * If cert verification fails, this will be called to let the 564 * user make the final decision of whether to allow the 565 * connection to proceed. Returns 0 to allow the connection 566 * or a negative value to indicate an error. 567 */ 568 git_transport_certificate_check_cb certificate_check; 569 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 */ 575 git_indexer_progress_cb transfer_progress; 576 577 /** 578 * Each time a reference is updated locally, this function 579 * will be called with information about it. 580 */ 581 int GIT_CALLBACK(update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data); 582 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 */ 596 git_push_transfer_progress_cb push_transfer_progress; 597 598 /** 599 * See documentation of git_push_update_reference_cb 600 */ 601 git_push_update_reference_cb push_update_reference; 602 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 609 /** 610 * Create the transport to use for this operation. Leave NULL 611 * to auto-detect. 612 */ 613 git_transport_cb transport; 614 615 /** 616 * Callback when the remote is ready to connect. 617 */ 618 git_remote_ready_cb remote_ready; 619 620 /** 621 * This will be passed to each of the callbacks in this struct 622 * as the last parameter. 623 */ 624 void *payload; 625 626 #ifdef GIT_DEPRECATE_HARD 627 void *reserved; 628 #else 629 /** 630 * Resolve URL before connecting to remote. 631 * The returned URL will be used to connect to the remote instead. 632 * 633 * This callback is deprecated; users should use 634 * git_remote_ready_cb and configure the instance URL instead. 635 */ 636 git_url_resolve_cb resolve_url; 637 #endif 638 }; 639 640 #define GIT_REMOTE_CALLBACKS_VERSION 1 641 #define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION} 642 643 /** 644 * Initializes a `git_remote_callbacks` with default values. Equivalent to 645 * creating an instance with GIT_REMOTE_CALLBACKS_INIT. 646 * 647 * @param opts the `git_remote_callbacks` struct to initialize 648 * @param version Version of struct; pass `GIT_REMOTE_CALLBACKS_VERSION` 649 * @return Zero on success; -1 on failure. 650 */ 651 GIT_EXTERN(int) git_remote_init_callbacks( 652 git_remote_callbacks *opts, 653 unsigned int version); 654 655 /** Acceptable prune settings when fetching */ 656 typedef enum { 657 /** 658 * Use the setting from the configuration 659 */ 660 GIT_FETCH_PRUNE_UNSPECIFIED, 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 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 */ 680 GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED = 0, 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 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 */ 704 typedef struct { 705 int version; 706 707 /** 708 * Callbacks to use for this fetch operation 709 */ 710 git_remote_callbacks callbacks; 711 712 /** 713 * Whether to perform a prune after the fetch 714 */ 715 git_fetch_prune_t prune; 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; 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; 731 732 /** 733 * Proxy options to use, by default no proxy is used. 734 */ 735 git_proxy_options proxy_opts; 736 737 /** 738 * Extra headers for this fetch operation 739 */ 740 git_strarray custom_headers; 741 } git_fetch_options; 742 743 #define GIT_FETCH_OPTIONS_VERSION 1 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 } 746 747 /** 748 * Initialize git_fetch_options structure 749 * 750 * Initializes a `git_fetch_options` with default values. Equivalent to 751 * creating an instance with `GIT_FETCH_OPTIONS_INIT`. 752 * 753 * @param opts The `git_fetch_options` struct to initialize. 754 * @param version The struct version; pass `GIT_FETCH_OPTIONS_VERSION`. 755 * @return Zero on success; -1 on failure. 756 */ 757 GIT_EXTERN(int) git_fetch_options_init( 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; 782 783 /** 784 * Proxy options to use, by default no proxy is used. 785 */ 786 git_proxy_options proxy_opts; 787 788 /** 789 * Extra headers for this push operation 790 */ 791 git_strarray custom_headers; 792 } git_push_options; 793 794 #define GIT_PUSH_OPTIONS_VERSION 1 795 #define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT } 796 797 /** 798 * Initialize git_push_options structure 799 * 800 * Initializes a `git_push_options` with default values. Equivalent to 801 * creating an instance with `GIT_PUSH_OPTIONS_INIT`. 802 * 803 * @param opts The `git_push_options` struct to initialize. 804 * @param version The struct version; pass `GIT_PUSH_OPTIONS_VERSION`. 805 * @return Zero on success; -1 on failure. 806 */ 807 GIT_EXTERN(int) git_push_options_init( 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 825 * @return 0 or an error code 826 */ 827 GIT_EXTERN(int) git_remote_download(git_remote *remote, const git_strarray *refspecs, const git_fetch_options *opts); 828 829 /** 830 * Create a packfile and send it to the server 831 * 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. 834 * 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 852 * @param update_fetchhead whether to write to FETCH_HEAD. Pass 1 to behave like git. 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()`. 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, 860 int update_fetchhead, 861 git_remote_autotag_option_t download_tags, 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 877 */ 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 899 * @param refspecs the refspecs to use for pushing. If NULL or an empty 900 * array, the configured refspecs will be used 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); 906 907 /** 908 * Get the statistics structure that is filled in by the fetch operation. 909 */ 910 GIT_EXTERN(const git_indexer_progress *) git_remote_stats(git_remote *remote); 911 912 /** 913 * Retrieve the tag auto-follow setting 914 * 915 * @param remote the remote to query 916 * @return the auto-follow setting 917 */ 918 GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(const git_remote *remote); 919 920 /** 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. 925 * 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. 929 * @return 0, or an error code. 930 */ 931 GIT_EXTERN(int) git_remote_set_autotag(git_repository *repo, const char *remote, git_remote_autotag_option_t value); 932 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 941 /** 942 * Give the remote a new name 943 * 944 * All remote-tracking branches and configuration settings 945 * for the remote are updated. 946 * 947 * The new name will be checked for validity. 948 * See `git_tag_create()` for rules about valid names. 949 * 950 * No loaded instances of a the remote with the old name will change 951 * their name or their list of refspecs. 952 * 953 * @param problems non-default refspecs cannot be renamed and will be 954 * stored here for further processing by the caller. Always free this 955 * strarray on successful return. 956 * @param repo the repository in which to rename 957 * @param name the current name of the remote 958 * @param new_name the new name the remote should bear 959 * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code 960 */ 961 GIT_EXTERN(int) git_remote_rename( 962 git_strarray *problems, 963 git_repository *repo, 964 const char *name, 965 const char *new_name); 966 967 /** 968 * Ensure the remote name is well-formed. 969 * 970 * @param valid output pointer to set with validity of given remote name 971 * @param remote_name name to be checked. 972 * @return 0 on success or an error code 973 */ 974 int git_remote_name_is_valid(int *valid, const char *remote_name); 975 976 /** 977 * Delete an existing persisted remote. 978 * 979 * All remote-tracking branches and configuration settings 980 * for the remote will be removed. 981 * 982 * @param repo the repository in which to act 983 * @param name the name of the remote to delete 984 * @return 0 on success, or an error code. 985 */ 986 GIT_EXTERN(int) git_remote_delete(git_repository *repo, const char *name); 987 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 * 999 * @param out the buffer in which to store the reference name 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 1006 /** @} */ 1007 GIT_END_DECL 1008 #endif 1009