include/git2/remote.h

   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 GIT_EXTERN(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