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