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