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  * Add a remote with the provided fetch refspec (or default if NULL) to the repository's
  46  * configuration.
  47  *
  48  * @param out the resulting remote
  49  * @param repo the repository in which to create the remote
  50  * @param name the remote's name
  51  * @param url the remote's url
  52  * @param fetch the remote fetch value
  53  * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
  54  */
  55 GIT_EXTERN(int) git_remote_create_with_fetchspec(
  56                 git_remote **out,
  57                 git_repository *repo,
  58                 const char *name,
  59                 const char *url,
  60                 const char *fetch);
  61
  62 /**
  63  * Create an anonymous remote
  64  *
  65  * Create a remote with the given url in-memory. You can use this when
  66  * you have a URL instead of a remote's name.
  67  *
  68  * @param out pointer to the new remote objects
  69  * @param repo the associated repository
  70  * @param url the remote repository's URL
  71  * @return 0 or an error code
  72  */
  73 GIT_EXTERN(int) git_remote_create_anonymous(
  74                 git_remote **out,
  75                 git_repository *repo,
  76                 const char *url);
  77
  78 /**
  79  * Get the information for a particular remote
  80  *
  81  * The name will be checked for validity.
  82  * See `git_tag_create()` for rules about valid names.
  83  *
  84  * @param out pointer to the new remote object
  85  * @param repo the associated repository
  86  * @param name the remote's name
  87  * @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code
  88  */
  89 GIT_EXTERN(int) git_remote_lookup(git_remote **out, git_repository *repo, const char *name);
  90
  91 /**
  92  * Create a copy of an existing remote.  All internal strings are also
  93  * duplicated. Callbacks are not duplicated.
  94  *
  95  * Call `git_remote_free` to free the data.
  96  *
  97  * @param dest pointer where to store the copy
  98  * @param source object to copy
  99  * @return 0 or an error code
 100  */
 101 GIT_EXTERN(int) git_remote_dup(git_remote **dest, git_remote *source);
 102
 103 /**
 104  * Get the remote's repository
 105  *
 106  * @param remote the remote
 107  * @return a pointer to the repository
 108  */
 109 GIT_EXTERN(git_repository *) git_remote_owner(const git_remote *remote);
 110
 111 /**
 112  * Get the remote's name
 113  *
 114  * @param remote the remote
 115  * @return a pointer to the name or NULL for in-memory remotes
 116  */
 117 GIT_EXTERN(const char *) git_remote_name(const git_remote *remote);
 118
 119 /**
 120  * Get the remote's url
 121  *
 122  * If url.*.insteadOf has been configured for this URL, it will
 123  * return the modified URL.
 124  *
 125  * @param remote the remote
 126  * @return a pointer to the url
 127  */
 128 GIT_EXTERN(const char *) git_remote_url(const git_remote *remote);
 129
 130 /**
 131  * Get the remote's url for pushing
 132  *
 133  * If url.*.pushInsteadOf has been configured for this URL, it
 134  * will return the modified URL.
 135  *
 136  * @param remote the remote
 137  * @return a pointer to the url or NULL if no special url for pushing is set
 138  */
 139 GIT_EXTERN(const char *) git_remote_pushurl(const git_remote *remote);
 140
 141 /**
 142  * Set the remote's url in the configuration
 143  *
 144  * Remote objects already in memory will not be affected. This assumes
 145  * the common case of a single-url remote and will otherwise return an error.
 146  *
 147  * @param repo the repository in which to perform the change
 148  * @param remote the remote's name
 149  * @param url the url to set
 150  * @return 0 or an error value
 151  */
 152 GIT_EXTERN(int) git_remote_set_url(git_repository *repo, const char *remote, const char* url);
 153
 154 /**
 155  * Set the remote's url for pushing in the configuration.
 156  *
 157  * Remote objects already in memory will not be affected. This assumes
 158  * the common case of a single-url remote and will otherwise return an error.
 159  *
 160  *
 161  * @param repo the repository in which to perform the change
 162  * @param remote the remote's name
 163  * @param url the url to set
 164  */
 165 GIT_EXTERN(int) git_remote_set_pushurl(git_repository *repo, const char *remote, const char* url);
 166
 167 /**
 168  * Add a fetch refspec to the remote's configuration
 169  *
 170  * Add the given refspec to the fetch list in the configuration. No
 171  * loaded remote instances will be affected.
 172  *
 173  * @param repo the repository in which to change the configuration
 174  * @param remote the name of the remote to change
 175  * @param refspec the new fetch refspec
 176  * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value
 177  */
 178 GIT_EXTERN(int) git_remote_add_fetch(git_repository *repo, const char *remote, const char *refspec);
 179
 180 /**
 181  * Get the remote's list of fetch refspecs
 182  *
 183  * The memory is owned by the user and should be freed with
 184  * `git_strarray_free`.
 185  *
 186  * @param array pointer to the array in which to store the strings
 187  * @param remote the remote to query
 188  */
 189 GIT_EXTERN(int) git_remote_get_fetch_refspecs(git_strarray *array, const git_remote *remote);
 190
 191 /**
 192  * Add a push refspec to the remote's configuration
 193  *
 194  * Add the given refspec to the push list in the configuration. No
 195  * loaded remote instances will be affected.
 196  *
 197  * @param repo the repository in which to change the configuration
 198  * @param remote the name of the remote to change
 199  * @param refspec the new push refspec
 200  * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value
 201  */
 202 GIT_EXTERN(int) git_remote_add_push(git_repository *repo, const char *remote, const char *refspec);
 203
 204 /**
 205  * Get the remote's list of push refspecs
 206  *
 207  * The memory is owned by the user and should be freed with
 208  * `git_strarray_free`.
 209  *
 210  * @param array pointer to the array in which to store the strings
 211  * @param remote the remote to query
 212  */
 213 GIT_EXTERN(int) git_remote_get_push_refspecs(git_strarray *array, const git_remote *remote);
 214
 215 /**
 216  * Get the number of refspecs for a remote
 217  *
 218  * @param remote the remote
 219  * @return the amount of refspecs configured in this remote
 220  */
 221 GIT_EXTERN(size_t) git_remote_refspec_count(const git_remote *remote);
 222
 223 /**
 224  * Get a refspec from the remote
 225  *
 226  * @param remote the remote to query
 227  * @param n the refspec to get
 228  * @return the nth refspec
 229  */
 230 GIT_EXTERN(const git_refspec *)git_remote_get_refspec(const git_remote *remote, size_t n);
 231
 232 /**
 233  * Open a connection to a remote
 234  *
 235  * The transport is selected based on the URL. The direction argument
 236  * is due to a limitation of the git protocol (over TCP or SSH) which
 237  * starts up a specific binary which can only do the one or the other.
 238  *
 239  * @param remote the remote to connect to
 240  * @param direction GIT_DIRECTION_FETCH if you want to fetch or
 241  * GIT_DIRECTION_PUSH if you want to push
 242  * @param callbacks the callbacks to use for this connection
 243  * @param proxy_opts proxy settings
 244  * @param custom_headers extra HTTP headers to use in this connection
 245  * @return 0 or an error code
 246  */
 247 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);
 248
 249 /**
 250  * Get the remote repository's reference advertisement list
 251  *
 252  * Get the list of references with which the server responds to a new
 253  * connection.
 254  *
 255  * The remote (or more exactly its transport) must have connected to
 256  * the remote repository. This list is available as soon as the
 257  * connection to the remote is initiated and it remains available
 258  * after disconnecting.
 259  *
 260  * The memory belongs to the remote. The pointer will be valid as long
 261  * as a new connection is not initiated, but it is recommended that
 262  * you make a copy in order to make use of the data.
 263  *
 264  * @param out pointer to the array
 265  * @param size the number of remote heads
 266  * @param remote the remote
 267  * @return 0 on success, or an error code
 268  */
 269 GIT_EXTERN(int) git_remote_ls(const git_remote_head ***out,  size_t *size, git_remote *remote);
 270
 271 /**
 272  * Check whether the remote is connected
 273  *
 274  * Check whether the remote's underlying transport is connected to the
 275  * remote host.
 276  *
 277  * @param remote the remote
 278  * @return 1 if it's connected, 0 otherwise.
 279  */
 280 GIT_EXTERN(int) git_remote_connected(const git_remote *remote);
 281
 282 /**
 283  * Cancel the operation
 284  *
 285  * At certain points in its operation, the network code checks whether
 286  * the operation has been cancelled and if so stops the operation.
 287  *
 288  * @param remote the remote
 289  */
 290 GIT_EXTERN(void) git_remote_stop(git_remote *remote);
 291
 292 /**
 293  * Disconnect from the remote
 294  *
 295  * Close the connection to the remote.
 296  *
 297  * @param remote the remote to disconnect from
 298  */
 299 GIT_EXTERN(void) git_remote_disconnect(git_remote *remote);
 300
 301 /**
 302  * Free the memory associated with a remote
 303  *
 304  * This also disconnects from the remote, if the connection
 305  * has not been closed yet (using git_remote_disconnect).
 306  *
 307  * @param remote the remote to free
 308  */
 309 GIT_EXTERN(void) git_remote_free(git_remote *remote);
 310
 311 /**
 312  * Get a list of the configured remotes for a repo
 313  *
 314  * The string array must be freed by the user.
 315  *
 316  * @param out a string array which receives the names of the remotes
 317  * @param repo the repository to query
 318  * @return 0 or an error code
 319  */
 320 GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo);
 321
 322 /**
 323  * Argument to the completion callback which tells it which operation
 324  * finished.
 325  */
 326 typedef enum git_remote_completion_type {
 327         GIT_REMOTE_COMPLETION_DOWNLOAD,
 328         GIT_REMOTE_COMPLETION_INDEXING,
 329         GIT_REMOTE_COMPLETION_ERROR,
 330 } git_remote_completion_type;
 331
 332 /** Push network progress notification function */
 333 typedef int (*git_push_transfer_progress)(
 334         unsigned int current,
 335         unsigned int total,
 336         size_t bytes,
 337         void* payload);
 338 /**
 339  * Represents an update which will be performed on the remote during push
 340  */
 341 typedef struct {
 342         /**
 343          * The source name of the reference
 344          */
 345         char *src_refname;
 346         /**
 347          * The name of the reference to update on the server
 348          */
 349         char *dst_refname;
 350         /**
 351          * The current target of the reference
 352          */
 353         git_oid src;
 354         /**
 355          * The new target for the reference
 356          */
 357         git_oid dst;
 358 } git_push_update;
 359
 360 /**
 361  * Callback used to inform of upcoming updates.
 362  *
 363  * @param updates an array containing the updates which will be sent
 364  * as commands to the destination.
 365  * @param len number of elements in `updates`
 366  * @param payload Payload provided by the caller
 367  */
 368 typedef int (*git_push_negotiation)(const git_push_update **updates, size_t len, void *payload);
 369
 370 /**
 371  * The callback settings structure
 372  *
 373  * Set the callbacks to be called by the remote when informing the user
 374  * about the progress of the network operations.
 375  */
 376 struct git_remote_callbacks {
 377         unsigned int version;
 378         /**
 379          * Textual progress from the remote. Text send over the
 380          * progress side-band will be passed to this function (this is
 381          * the 'counting objects' output).
 382          */
 383         git_transport_message_cb sideband_progress;
 384
 385         /**
 386          * Completion is called when different parts of the download
 387          * process are done (currently unused).
 388          */
 389         int (*completion)(git_remote_completion_type type, void *data);
 390
 391         /**
 392          * This will be called if the remote host requires
 393          * authentication in order to connect to it.
 394          *
 395          * Returning GIT_PASSTHROUGH will make libgit2 behave as
 396          * though this field isn't set.
 397          */
 398         git_cred_acquire_cb credentials;
 399
 400         /**
 401          * If cert verification fails, this will be called to let the
 402          * user make the final decision of whether to allow the
 403          * connection to proceed. Returns 1 to allow the connection, 0
 404          * to disallow it or a negative value to indicate an error.
 405          */
 406         git_transport_certificate_check_cb certificate_check;
 407
 408         /**
 409          * During the download of new data, this will be regularly
 410          * called with the current count of progress done by the
 411          * indexer.
 412          */
 413         git_transfer_progress_cb transfer_progress;
 414
 415         /**
 416          * Each time a reference is updated locally, this function
 417          * will be called with information about it.
 418          */
 419         int (*update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data);
 420
 421         /**
 422          * Function to call with progress information during pack
 423          * building. Be aware that this is called inline with pack
 424          * building operations, so performance may be affected.
 425          */
 426         git_packbuilder_progress pack_progress;
 427
 428         /**
 429          * Function to call with progress information during the
 430          * upload portion of a push. Be aware that this is called
 431          * inline with pack building operations, so performance may be
 432          * affected.
 433          */
 434         git_push_transfer_progress push_transfer_progress;
 435
 436         /**
 437          * Called for each updated reference on push. If `status` is
 438          * not `NULL`, the update was rejected by the remote server
 439          * and `status` contains the reason given.
 440          */
 441         int (*push_update_reference)(const char *refname, const char *status, void *data);
 442
 443         /**
 444          * Called once between the negotiation step and the upload. It
 445          * provides information about what updates will be performed.
 446          */
 447         git_push_negotiation push_negotiation;
 448
 449         /**
 450          * Create the transport to use for this operation. Leave NULL
 451          * to auto-detect.
 452          */
 453         git_transport_cb transport;
 454
 455         /**
 456          * This will be passed to each of the callbacks in this struct
 457          * as the last parameter.
 458          */
 459         void *payload;
 460 };
 461
 462 #define GIT_REMOTE_CALLBACKS_VERSION 1
 463 #define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION}
 464
 465 /**
 466  * Initializes a `git_remote_callbacks` with default values. Equivalent to
 467  * creating an instance with GIT_REMOTE_CALLBACKS_INIT.
 468  *
 469  * @param opts the `git_remote_callbacks` struct to initialize
 470  * @param version Version of struct; pass `GIT_REMOTE_CALLBACKS_VERSION`
 471  * @return Zero on success; -1 on failure.
 472  */
 473 GIT_EXTERN(int) git_remote_init_callbacks(
 474         git_remote_callbacks *opts,
 475         unsigned int version);
 476
 477 typedef enum {
 478         /**
 479          * Use the setting from the configuration
 480          */
 481         GIT_FETCH_PRUNE_UNSPECIFIED,
 482         /**
 483          * Force pruning on
 484          */
 485         GIT_FETCH_PRUNE,
 486         /**
 487          * Force pruning off
 488          */
 489         GIT_FETCH_NO_PRUNE,
 490 } git_fetch_prune_t;
 491
 492 /**
 493  * Automatic tag following option
 494  *
 495  * Lets us select the --tags option to use.
 496  */
 497 typedef enum {
 498         /**
 499          * Use the setting from the configuration.
 500          */
 501         GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED = 0,
 502         /**
 503          * Ask the server for tags pointing to objects we're already
 504          * downloading.
 505          */
 506         GIT_REMOTE_DOWNLOAD_TAGS_AUTO,
 507         /**
 508          * Don't ask for any tags beyond the refspecs.
 509          */
 510         GIT_REMOTE_DOWNLOAD_TAGS_NONE,
 511         /**
 512          * Ask for the all the tags.
 513          */
 514         GIT_REMOTE_DOWNLOAD_TAGS_ALL,
 515 } git_remote_autotag_option_t;
 516
 517 /**
 518  * Fetch options structure.
 519  *
 520  * Zero out for defaults.  Initialize with `GIT_FETCH_OPTIONS_INIT` macro to
 521  * correctly set the `version` field.  E.g.
 522  *
 523  *              git_fetch_options opts = GIT_FETCH_OPTIONS_INIT;
 524  */
 525 typedef struct {
 526         int version;
 527
 528         /**
 529          * Callbacks to use for this fetch operation
 530          */
 531         git_remote_callbacks callbacks;
 532
 533         /**
 534          * Whether to perform a prune after the fetch
 535          */
 536         git_fetch_prune_t prune;
 537
 538         /**
 539          * Whether to write the results to FETCH_HEAD. Defaults to
 540          * on. Leave this default in order to behave like git.
 541          */
 542         int update_fetchhead;
 543
 544         /**
 545          * Determines how to behave regarding tags on the remote, such
 546          * as auto-downloading tags for objects we're downloading or
 547          * downloading all of them.
 548          *
 549          * The default is to auto-follow tags.
 550          */
 551         git_remote_autotag_option_t download_tags;
 552
 553         /**
 554          * Proxy options to use, by default no proxy is used.
 555          */
 556         git_proxy_options proxy_opts;
 557
 558         /**
 559          * Extra headers for this fetch operation
 560          */
 561         git_strarray custom_headers;
 562 } git_fetch_options;
 563
 564 #define GIT_FETCH_OPTIONS_VERSION 1
 565 #define GIT_FETCH_OPTIONS_INIT { GIT_FETCH_OPTIONS_VERSION, GIT_REMOTE_CALLBACKS_INIT, GIT_FETCH_PRUNE_UNSPECIFIED, 1, \
 566                                  GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED, GIT_PROXY_OPTIONS_INIT }
 567
 568 /**
 569  * Initializes a `git_fetch_options` with default values. Equivalent to
 570  * creating an instance with GIT_FETCH_OPTIONS_INIT.
 571  *
 572  * @param opts the `git_fetch_options` instance to initialize.
 573  * @param version the version of the struct; you should pass
 574  *        `GIT_FETCH_OPTIONS_VERSION` here.
 575  * @return Zero on success; -1 on failure.
 576  */
 577 GIT_EXTERN(int) git_fetch_init_options(
 578         git_fetch_options *opts,
 579         unsigned int version);
 580
 581
 582 /**
 583  * Controls the behavior of a git_push object.
 584  */
 585 typedef struct {
 586         unsigned int version;
 587
 588         /**
 589          * If the transport being used to push to the remote requires the creation
 590          * of a pack file, this controls the number of worker threads used by
 591          * the packbuilder when creating that pack file to be sent to the remote.
 592          *
 593          * If set to 0, the packbuilder will auto-detect the number of threads
 594          * to create. The default value is 1.
 595          */
 596         unsigned int pb_parallelism;
 597
 598         /**
 599          * Callbacks to use for this push operation
 600          */
 601         git_remote_callbacks callbacks;
 602
 603         /**
 604         * Proxy options to use, by default no proxy is used.
 605         */
 606         git_proxy_options proxy_opts;
 607
 608         /**
 609          * Extra headers for this push operation
 610          */
 611         git_strarray custom_headers;
 612 } git_push_options;
 613
 614 #define GIT_PUSH_OPTIONS_VERSION 1
 615 #define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 0, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }
 616
 617 /**
 618  * Initializes a `git_push_options` with default values. Equivalent to
 619  * creating an instance with GIT_PUSH_OPTIONS_INIT.
 620  *
 621  * @param opts the `git_push_options` instance to initialize.
 622  * @param version the version of the struct; you should pass
 623  *        `GIT_PUSH_OPTIONS_VERSION` here.
 624  * @return Zero on success; -1 on failure.
 625  */
 626 GIT_EXTERN(int) git_push_init_options(
 627         git_push_options *opts,
 628         unsigned int version);
 629
 630 /**
 631  * Download and index the packfile
 632  *
 633  * Connect to the remote if it hasn't been done yet, negotiate with
 634  * the remote git which objects are missing, download and index the
 635  * packfile.
 636  *
 637  * The .idx file will be created and both it and the packfile with be
 638  * renamed to their final name.
 639  *
 640  * @param remote the remote
 641  * @param refspecs the refspecs to use for this negotiation and
 642  * download. Use NULL or an empty array to use the base refspecs
 643  * @param opts the options to use for this fetch
 644  * @return 0 or an error code
 645  */
 646  GIT_EXTERN(int) git_remote_download(git_remote *remote, const git_strarray *refspecs, const git_fetch_options *opts);
 647
 648 /**
 649  * Create a packfile and send it to the server
 650  *
 651  * Connect to the remote if it hasn't been done yet, negotiate with
 652  * the remote git which objects are missing, create a packfile with the missing objects and send it.
 653  *
 654  * @param remote the remote
 655  * @param refspecs the refspecs to use for this negotiation and
 656  * upload. Use NULL or an empty array to use the base refspecs
 657  * @param opts the options to use for this push
 658  * @return 0 or an error code
 659  */
 660 GIT_EXTERN(int) git_remote_upload(git_remote *remote, const git_strarray *refspecs, const git_push_options *opts);
 661
 662 /**
 663  * Update the tips to the new state
 664  *
 665  * @param remote the remote to update
 666  * @param reflog_message The message to insert into the reflogs. If
 667  * NULL and fetching, the default is "fetch <name>", where <name> is
 668  * the name of the remote (or its url, for in-memory remotes). This
 669  * parameter is ignored when pushing.
 670  * @param callbacks  pointer to the callback structure to use
 671  * @param update_fetchhead whether to write to FETCH_HEAD. Pass 1 to behave like git.
 672  * @param download_tags what the behaviour for downloading tags is for this fetch. This is
 673  * ignored for push. This must be the same value passed to `git_remote_download()`.
 674  * @return 0 or an error code
 675  */
 676 GIT_EXTERN(int) git_remote_update_tips(
 677                 git_remote *remote,
 678                 const git_remote_callbacks *callbacks,
 679                 int update_fetchhead,
 680                 git_remote_autotag_option_t download_tags,
 681                 const char *reflog_message);
 682
 683 /**
 684  * Download new data and update tips
 685  *
 686  * Convenience function to connect to a remote, download the data,
 687  * disconnect and update the remote-tracking branches.
 688  *
 689  * @param remote the remote to fetch from
 690  * @param refspecs the refspecs to use for this fetch. Pass NULL or an
 691  *                 empty array to use the base refspecs.
 692  * @param opts options to use for this fetch
 693  * @param reflog_message The message to insert into the reflogs. If NULL, the
 694  *                                                               default is "fetch"
 695  * @return 0 or an error code
 696  */
 697 GIT_EXTERN(int) git_remote_fetch(
 698                 git_remote *remote,
 699                 const git_strarray *refspecs,
 700                 const git_fetch_options *opts,
 701                 const char *reflog_message);
 702
 703 /**
 704  * Prune tracking refs that are no longer present on remote
 705  *
 706  * @param remote the remote to prune
 707  * @param callbacks callbacks to use for this prune
 708  * @return 0 or an error code
 709  */
 710 GIT_EXTERN(int) git_remote_prune(git_remote *remote, const git_remote_callbacks *callbacks);
 711
 712 /**
 713  * Perform a push
 714  *
 715  * Peform all the steps from a push.
 716  *
 717  * @param remote the remote to push to
 718  * @param refspecs the refspecs to use for pushing. If NULL or an empty
 719  *                 array, the configured refspecs will be used
 720  * @param opts options to use for this push
 721  */
 722 GIT_EXTERN(int) git_remote_push(git_remote *remote,
 723                                 const git_strarray *refspecs,
 724                                 const git_push_options *opts);
 725
 726 /**
 727  * Get the statistics structure that is filled in by the fetch operation.
 728  */
 729 GIT_EXTERN(const git_transfer_progress *) git_remote_stats(git_remote *remote);
 730
 731 /**
 732  * Retrieve the tag auto-follow setting
 733  *
 734  * @param remote the remote to query
 735  * @return the auto-follow setting
 736  */
 737 GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(const git_remote *remote);
 738
 739 /**
 740  * Set the remote's tag following setting.
 741  *
 742  * The change will be made in the configuration. No loaded remotes
 743  * will be affected.
 744  *
 745  * @param repo the repository in which to make the change
 746  * @param remote the name of the remote
 747  * @param value the new value to take.
 748  */
 749 GIT_EXTERN(int) git_remote_set_autotag(git_repository *repo, const char *remote, git_remote_autotag_option_t value);
 750 /**
 751  * Retrieve the ref-prune setting
 752  *
 753  * @param remote the remote to query
 754  * @return the ref-prune setting
 755  */
 756 GIT_EXTERN(int) git_remote_prune_refs(const git_remote *remote);
 757
 758 /**
 759  * Give the remote a new name
 760  *
 761  * All remote-tracking branches and configuration settings
 762  * for the remote are updated.
 763  *
 764  * The new name will be checked for validity.
 765  * See `git_tag_create()` for rules about valid names.
 766  *
 767  * No loaded instances of a the remote with the old name will change
 768  * their name or their list of refspecs.
 769  *
 770  * @param problems non-default refspecs cannot be renamed and will be
 771  * stored here for further processing by the caller. Always free this
 772  * strarray on successful return.
 773  * @param repo the repository in which to rename
 774  * @param name the current name of the remote
 775  * @param new_name the new name the remote should bear
 776  * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
 777  */
 778 GIT_EXTERN(int) git_remote_rename(
 779         git_strarray *problems,
 780         git_repository *repo,
 781         const char *name,
 782         const char *new_name);
 783
 784 /**
 785  * Ensure the remote name is well-formed.
 786  *
 787  * @param remote_name name to be checked.
 788  * @return 1 if the reference name is acceptable; 0 if it isn't
 789  */
 790 GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name);
 791
 792 /**
 793 * Delete an existing persisted remote.
 794 *
 795 * All remote-tracking branches and configuration settings
 796 * for the remote will be removed.
 797 *
 798 * @param repo the repository in which to act
 799 * @param name the name of the remote to delete
 800 * @return 0 on success, or an error code.
 801 */
 802 GIT_EXTERN(int) git_remote_delete(git_repository *repo, const char *name);
 803
 804 /**
 805  * Retrieve the name of the remote's default branch
 806  *
 807  * The default branch of a repository is the branch which HEAD points
 808  * to. If the remote does not support reporting this information
 809  * directly, it performs the guess as git does; that is, if there are
 810  * multiple branches which point to the same commit, the first one is
 811  * chosen. If the master branch is a candidate, it wins.
 812  *
 813  * This function must only be called after connecting.
 814  *
 815  * @param out the buffern in which to store the reference name
 816  * @param remote the remote
 817  * @return 0, GIT_ENOTFOUND if the remote does not have any references
 818  * or none of them point to HEAD's commit, or an error message.
 819  */
 820 GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote);
 821
 822 /** @} */
 823 GIT_END_DECL
 824 #endif