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