remote.h 33.9 KB
Newer Older
Vicent Marti committed
1
/*
Edward Thomson committed
2
 * Copyright (C) the libgit2 contributors. All rights reserved.
Vicent Marti committed
3
 *
Vicent Marti committed
4 5
 * This file is part of libgit2, distributed under the GNU GPL v2 with
 * a Linking Exception. For full terms see the included COPYING file.
Vicent Marti committed
6
 */
Carlos Martín Nieto committed
7 8 9
#ifndef INCLUDE_git_remote_h__
#define INCLUDE_git_remote_h__

10 11 12
#include "common.h"
#include "repository.h"
#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 22 23 24 25 26 27
/**
 * @file git2/remote.h
 * @brief Git remote management functions
 * @defgroup git_remote remote management functions
 * @ingroup Git
 * @{
 */
GIT_BEGIN_DECL
Carlos Martín Nieto committed
28 29

/**
30
 * Add a remote with the default fetch refspec to the repository's configuration.
Ben Straub committed
31 32 33 34 35
 *
 * @param out the resulting remote
 * @param repo the repository in which to create the remote
 * @param name the remote's name
 * @param url the remote's url
36
 * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
Ben Straub committed
37 38 39 40 41 42 43 44
 */
GIT_EXTERN(int) git_remote_create(
		git_remote **out,
		git_repository *repo,
		const char *name,
		const char *url);

/**
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
 * Remote redirection settings; whether redirects to another host
 * are permitted.  By default, git will follow a redirect on the
 * initial request (`/info/refs`), but not subsequent requests.
 */
typedef enum {
	/**
	 * Do not follow any off-site redirects at any stage of
	 * the fetch or push.
	 */
	GIT_REMOTE_REDIRECT_NONE = (1 << 0),

	/**
	 * Allow off-site redirects only upon the initial request.
	 * This is the default.
	 */
	GIT_REMOTE_REDIRECT_INITIAL = (1 << 1),

	/**
	 * Allow redirects at any stage in the fetch or push.
	 */
	GIT_REMOTE_REDIRECT_ALL = (1 << 2)
} git_remote_redirect_t;

/**
69 70 71 72 73
 * Remote creation options flags
 */
typedef enum {
	/** Ignore the repository apply.insteadOf configuration */
	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 78 79
} git_remote_create_flags;

/**
80 81 82
 * Remote creation options structure
 *
 * Initialize with `GIT_REMOTE_CREATE_OPTIONS_INIT`. Alternatively, you can
83
 * use `git_remote_create_options_init`.
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
 *
 */
typedef struct git_remote_create_options {
	unsigned int version;

	/**
	 * The repository that should own the remote.
	 * Setting this to NULL results in a detached remote.
	 */
	git_repository *repository;

	/**
	 * The remote's name.
	 * Setting this to NULL results in an in-memory/anonymous remote.
	 */
	const char *name;

	/** The fetchspec the remote should use. */
	const char *fetchspec;
103 104 105

	/** Additional flags for the remote. See git_remote_create_flags. */
	unsigned int flags;
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120
} git_remote_create_options;

#define GIT_REMOTE_CREATE_OPTIONS_VERSION 1
#define GIT_REMOTE_CREATE_OPTIONS_INIT {GIT_REMOTE_CREATE_OPTIONS_VERSION}

/**
 * Initialize git_remote_create_options structure
 *
 * Initializes a `git_remote_create_options` with default values. Equivalent to
 * creating an instance with `GIT_REMOTE_CREATE_OPTIONS_INIT`.
 *
 * @param opts The `git_remote_create_options` struct to initialize.
 * @param version The struct version; pass `GIT_REMOTE_CREATE_OPTIONS_VERSION`.
 * @return Zero on success; -1 on failure.
 */
121
GIT_EXTERN(int) git_remote_create_options_init(
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
		git_remote_create_options *opts,
		unsigned int version);

/**
 * Create a remote, with options.
 *
 * This function allows more fine-grained control over the remote creation.
 *
 * Passing NULL as the opts argument will result in a detached remote.
 *
 * @param out the resulting remote
 * @param url the remote's url
 * @param opts the remote creation options
 * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
 */
GIT_EXTERN(int) git_remote_create_with_opts(
		git_remote **out,
		const char *url,
		const git_remote_create_options *opts);

/**
143
 * Add a remote with the provided fetch refspec (or default if NULL) to the repository's
144
 * configuration.
Ben Straub committed
145 146 147 148 149
 *
 * @param out the resulting remote
 * @param repo the repository in which to create the remote
 * @param name the remote's name
 * @param url the remote's url
150
 * @param fetch the remote fetch value
151
 * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
Ben Straub committed
152
 */
153
GIT_EXTERN(int) git_remote_create_with_fetchspec(
Ben Straub committed
154 155 156
		git_remote **out,
		git_repository *repo,
		const char *name,
157 158
		const char *url,
		const char *fetch);
Ben Straub committed
159 160

/**
161
 * Create an anonymous remote
162
 *
163 164
 * Create a remote with the given url in-memory. You can use this when
 * 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(
Ben Straub committed
172 173
		git_remote **out,
		git_repository *repo,
174
		const char *url);
175 176

/**
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
 * Create a remote without a connected local repo
 *
 * Create a remote with the given url in-memory. You can use this when
 * you have a URL instead of a remote's name.
 *
 * Contrasted with git_remote_create_anonymous, a detached remote
 * will not consider any repo configuration values (such as insteadof url
 * substitutions).
 *
 * @param out pointer to the new remote objects
 * @param url the remote repository's URL
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_remote_create_detached(
		git_remote **out,
		const char *url);

/**
Carlos Martín Nieto committed
195 196
 * Get the information for a particular remote
 *
197 198 199
 * The name will be checked for validity.
 * See `git_tag_create()` for rules about valid names.
 *
Carlos Martín Nieto committed
200
 * @param out pointer to the new remote object
201
 * @param repo the associated repository
Carlos Martín Nieto committed
202
 * @param name the remote's name
203
 * @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code
Carlos Martín Nieto committed
204
 */
205
GIT_EXTERN(int) git_remote_lookup(git_remote **out, git_repository *repo, const char *name);
Carlos Martín Nieto committed
206 207

/**
Arthur Schreiber committed
208 209 210 211 212 213 214 215 216
 * Create a copy of an existing remote.  All internal strings are also
 * duplicated. Callbacks are not duplicated.
 *
 * Call `git_remote_free` to free the data.
 *
 * @param dest pointer where to store the copy
 * @param source object to copy
 * @return 0 or an error code
 */
217
GIT_EXTERN(int) git_remote_dup(git_remote **dest, git_remote *source);
Arthur Schreiber committed
218 219

/**
Etienne Samson committed
220 221 222 223 224 225 226 227
 * Get the remote's repository
 *
 * @param remote the remote
 * @return a pointer to the repository
 */
GIT_EXTERN(git_repository *) git_remote_owner(const git_remote *remote);

/**
Carlos Martín Nieto committed
228 229 230
 * Get the remote's name
 *
 * @param remote the remote
231
 * @return a pointer to the name or NULL for in-memory remotes
Carlos Martín Nieto committed
232
 */
Ben Straub committed
233
GIT_EXTERN(const char *) git_remote_name(const git_remote *remote);
Carlos Martín Nieto committed
234 235 236 237

/**
 * Get the remote's url
 *
238
 * If url.*.insteadOf has been configured for this URL, it will
239 240
 * return the modified URL.  If `git_remote_set_instance_pushurl`
 * has been called for this remote, then that URL will be returned.
241
 *
Carlos Martín Nieto committed
242 243 244
 * @param remote the remote
 * @return a pointer to the url
 */
Ben Straub committed
245
GIT_EXTERN(const char *) git_remote_url(const git_remote *remote);
Carlos Martín Nieto committed
246 247

/**
248
 * Get the remote's url for pushing.
249
 *
250
 * If url.*.pushInsteadOf has been configured for this URL, it
251 252
 * will return the modified URL.  If `git_remote_set_instance_pushurl`
 * has been called for this remote, then that URL will be returned.
253
 *
254 255 256
 * @param remote the remote
 * @return a pointer to the url or NULL if no special url for pushing is set
 */
Ben Straub committed
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 263
 * Remote objects already in memory will not be affected. This assumes
 * the common case of a single-url remote and will otherwise return an error.
264
 *
265 266
 * @param repo the repository in which to perform the change
 * @param remote the remote's name
267 268 269
 * @param url the url to set
 * @return 0 or an error value
 */
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 276
 * Remote objects already in memory will not be affected. This assumes
 * the common case of a single-url remote and will otherwise return an error.
277
 *
278 279 280 281
 *
 * @param repo the repository in which to perform the change
 * @param remote the remote's name
 * @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 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306
 * Set the url for this particular url instance.  The URL in the
 * configuration will be ignored, and will not be changed.
 *
 * @param remote the remote's name
 * @param url the url to set
 * @return 0 or an error value
 */
GIT_EXTERN(int) git_remote_set_instance_url(git_remote *remote, const char *url);

/**
 * Set the push url for this particular url instance.  The URL in the
 * configuration will be ignored, and will not be changed.
 *
 * @param remote the remote's name
 * @param url the url to set
 * @return 0 or an error value
 */
GIT_EXTERN(int) git_remote_set_instance_pushurl(git_remote *remote, const char *url);

/**
307
 * Add a fetch refspec to the remote's configuration
308
 *
309 310
 * Add the given refspec to the fetch list in the configuration. No
 * loaded remote instances will be affected.
311
 *
312 313
 * @param repo the repository in which to change the configuration
 * @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 321 322 323 324 325 326

/**
 * Get the remote's list of fetch refspecs
 *
 * The memory is owned by the user and should be freed with
 * `git_strarray_free`.
 *
 * @param array pointer to the array in which to store the strings
 * @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
Carlos Martín Nieto committed
333
 *
334 335
 * Add the given refspec to the push list in the configuration. No
 * loaded remote instances will be affected.
336
 *
337 338
 * @param repo the repository in which to change the configuration
 * @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 346 347 348 349 350 351

/**
 * Get the remote's list of push refspecs
 *
 * The memory is owned by the user and should be freed with
 * `git_strarray_free`.
 *
 * @param array pointer to the array in which to store the strings
 * @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 358 359 360 361
 * Get the number of refspecs for a remote
 *
 * @param remote the remote
 * @return the amount of refspecs configured in this remote
 */
362
GIT_EXTERN(size_t) git_remote_refspec_count(const git_remote *remote);
363 364 365 366 367 368 369 370

/**
 * Get a refspec from the remote
 *
 * @param remote the remote to query
 * @param n the refspec to get
 * @return the nth refspec
 */
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 377
 * Get the list of references with which the server responds to a new
 * connection.
378
 *
379 380 381 382 383 384 385 386
 * The remote (or more exactly its transport) must have connected to
 * the remote repository. This list is available as soon as the
 * connection to the remote is initiated and it remains available
 * after disconnecting.
 *
 * The memory belongs to the remote. The pointer will be valid as long
 * as a new connection is not initiated, but it is recommended that
 * you make a copy in order to make use of the data.
387
 *
388 389
 * @param out pointer to the array
 * @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 397 398 399 400
 * Check whether the remote is connected
 *
 * Check whether the remote's underlying transport is connected to the
 * remote host.
 *
401
 * @param remote the remote
402 403
 * @return 1 if it's connected, 0 otherwise.
 */
404
GIT_EXTERN(int) git_remote_connected(const git_remote *remote);
405 406

/**
407 408 409 410
 * Cancel the operation
 *
 * At certain points in its operation, the network code checks whether
 * 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 419
 * Disconnect from the remote
 *
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

/**
Carlos Martín Nieto committed
428 429
 * Free the memory associated with a remote
 *
430 431 432
 * This also disconnects from the remote, if the connection
 * has not been closed yet (using git_remote_disconnect).
 *
Carlos Martín Nieto committed
433 434
 * @param remote the remote to free
 */
435
GIT_EXTERN(void) git_remote_free(git_remote *remote);
Carlos Martín Nieto committed
436

437
/**
438 439 440 441
 * Get a list of the configured remotes for a repo
 *
 * The string array must be freed by the user.
 *
Ben Straub committed
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
 */
Ben Straub committed
446
GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo);
447

448
/**
449 450 451
 * Argument to the completion callback which tells it which operation
 * finished.
 */
452
typedef enum git_remote_completion_t {
453 454
	GIT_REMOTE_COMPLETION_DOWNLOAD,
	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 461 462
	unsigned int current,
	unsigned int total,
	size_t bytes,
463
	void *payload);
464

465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487
/**
 * Represents an update which will be performed on the remote during push
 */
typedef struct {
	/**
	 * The source name of the reference
	 */
	char *src_refname;
	/**
	 * The name of the reference to update on the server
	 */
	char *dst_refname;
	/**
	 * The current target of the reference
	 */
	git_oid src;
	/**
	 * The new target for the reference
	 */
	git_oid dst;
} git_push_update;

/**
488 489
 * Callback used to inform of upcoming updates.
 *
490 491 492 493 494
 * @param updates an array containing the updates which will be sent
 * as commands to the destination.
 * @param len number of elements in `updates`
 * @param payload Payload provided by the caller
 */
495
typedef int GIT_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload);
496

497
/**
498 499 500 501 502 503 504 505 506 507 508
 * Callback used to inform of the update status from the remote.
 *
 * Called for each updated reference on push. If `status` is
 * not `NULL`, the update was rejected by the remote server
 * and `status` contains the reason given.
 *
 * @param refname refname specifying to the remote ref
 * @param status status message sent from the remote
 * @param data data provided by the caller
 * @return 0 on success, otherwise an error
 */
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 514 515 516 517 518 519 520 521 522
 * Callback to resolve URLs before connecting to remote
 *
 * If you return GIT_PASSTHROUGH, you don't need to write anything to
 * url_resolved.
 *
 * @param url_resolved The buffer to write the resolved URL to
 * @param url The URL to resolve
 * @param direction GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH
 * @param payload Payload provided by the caller
 * @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 530 531 532 533 534 535 536 537 538 539 540
 * Callback invoked immediately before we attempt to connect to the
 * given url.  Callers may change the URL before the connection by
 * calling `git_remote_set_instance_url` in the callback.
 *
 * @param remote The remote to be connected
 * @param direction GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH
 * @param payload Payload provided by the caller
 * @return 0 on success, or an error
 */
typedef int GIT_CALLBACK(git_remote_ready_cb)(git_remote *remote, int direction, void *payload);

/**
541 542
 * The callback settings structure
 *
543 544
 * Set the callbacks to be called by the remote when informing the user
 * about the progress of the network operations.
545 546
 */
struct git_remote_callbacks {
Etienne Samson committed
547 548
	unsigned int version; /**< The version */

549 550 551
	/**
	 * Textual progress from the remote. Text send over the
	 * 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 558 559

	/**
	 * Completion is called when different parts of the download
	 * process are done (currently unused).
	 */
560
	int GIT_CALLBACK(completion)(git_remote_completion_t type, void *data);
561 562 563 564

	/**
	 * This will be called if the remote host requires
	 * authentication in order to connect to it.
565 566 567
	 *
	 * Returning GIT_PASSTHROUGH will make libgit2 behave as
	 * though this field isn't set.
568
	 */
569
	git_credential_acquire_cb credentials;
570 571

	/**
572 573
	 * If cert verification fails, this will be called to let the
	 * user make the final decision of whether to allow the
574 575
	 * connection to proceed. Returns 0 to allow the connection
	 * or a negative value to indicate an error.
576
	 */
577
	git_transport_certificate_check_cb certificate_check;
578 579

	/**
580 581 582 583
	 * During the download of new data, this will be regularly
	 * called with the current count of progress done by the
	 * indexer.
	 */
584
	git_indexer_progress_cb transfer_progress;
585 586 587 588 589

	/**
	 * Each time a reference is updated locally, this function
	 * will be called with information about it.
	 */
590
	int GIT_CALLBACK(update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data);
591 592

	/**
593 594 595 596 597 598 599 600 601 602 603 604
	 * Function to call with progress information during pack
	 * building. Be aware that this is called inline with pack
	 * building operations, so performance may be affected.
	 */
	git_packbuilder_progress pack_progress;

	/**
	 * Function to call with progress information during the
	 * upload portion of a push. Be aware that this is called
	 * inline with pack building operations, so performance may be
	 * affected.
	 */
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 614 615 616 617 618
	 * Called once between the negotiation step and the upload. It
	 * provides information about what updates will be performed.
	 */
	git_push_negotiation push_negotiation;

	/**
619 620 621 622 623 624
	 * Create the transport to use for this operation. Leave NULL
	 * to auto-detect.
	 */
	git_transport_cb transport;

	/**
625 626 627 628 629
	 * Callback when the remote is ready to connect.
	 */
	git_remote_ready_cb remote_ready;

	/**
630 631 632
	 * This will be passed to each of the callbacks in this struct
	 * as the last parameter.
	 */
Ben Straub committed
633
	void *payload;
634

635 636 637
#ifdef GIT_DEPRECATE_HARD
	void *reserved;
#else
638 639 640
	/**
	 * Resolve URL before connecting to remote.
	 * The returned URL will be used to connect to the remote instead.
641 642 643
	 *
	 * This callback is deprecated; users should use
	 * 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
Ben Straub committed
650
#define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION}
651

652
/**
653 654 655
 * Initializes a `git_remote_callbacks` with default values. Equivalent to
 * creating an instance with GIT_REMOTE_CALLBACKS_INIT.
 *
656 657
 * @param opts the `git_remote_callbacks` struct to initialize
 * @param version Version of struct; pass `GIT_REMOTE_CALLBACKS_VERSION`
658 659 660
 * @return Zero on success; -1 on failure.
 */
GIT_EXTERN(int) git_remote_init_callbacks(
661 662
	git_remote_callbacks *opts,
	unsigned int version);
663

664
/** Acceptable prune settings when fetching */
665 666 667 668
typedef enum {
	/**
	 * Use the setting from the configuration
	 */
669
	GIT_FETCH_PRUNE_UNSPECIFIED,
670 671 672 673 674 675 676
	/**
	 * Force pruning on
	 */
	GIT_FETCH_PRUNE,
	/**
	 * Force pruning off
	 */
677
	GIT_FETCH_NO_PRUNE
678 679
} git_fetch_prune_t;

680 681 682 683 684 685 686 687 688
/**
 * Automatic tag following option
 *
 * Lets us select the --tags option to use.
 */
typedef enum {
	/**
	 * Use the setting from the configuration.
	 */
689
	GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED = 0,
690 691 692 693 694 695 696 697 698 699 700 701
	/**
	 * Ask the server for tags pointing to objects we're already
	 * downloading.
	 */
	GIT_REMOTE_DOWNLOAD_TAGS_AUTO,
	/**
	 * Don't ask for any tags beyond the refspecs.
	 */
	GIT_REMOTE_DOWNLOAD_TAGS_NONE,
	/**
	 * Ask for the all the tags.
	 */
702
	GIT_REMOTE_DOWNLOAD_TAGS_ALL
703 704
} git_remote_autotag_option_t;

705 706 707 708 709 710 711 712
/**
 * Fetch options structure.
 *
 * Zero out for defaults.  Initialize with `GIT_FETCH_OPTIONS_INIT` macro to
 * correctly set the `version` field.  E.g.
 *
 *		git_fetch_options opts = GIT_FETCH_OPTIONS_INIT;
 */
713 714 715 716 717 718 719
typedef struct {
	int version;

	/**
	 * Callbacks to use for this fetch operation
	 */
	git_remote_callbacks callbacks;
720 721 722 723 724

	/**
	 * Whether to perform a prune after the fetch
	 */
	git_fetch_prune_t prune;
725 726 727 728 729 730

	/**
	 * Whether to write the results to FETCH_HEAD. Defaults to
	 * on. Leave this default in order to behave like git.
	 */
	int update_fetchhead;
731 732 733 734 735 736 737 738 739

	/**
	 * Determines how to behave regarding tags on the remote, such
	 * as auto-downloading tags for objects we're downloading or
	 * downloading all of them.
	 *
	 * The default is to auto-follow tags.
	 */
	git_remote_autotag_option_t download_tags;
740 741

	/**
742 743 744 745 746
	 * Proxy options to use, by default no proxy is used.
	 */
	git_proxy_options proxy_opts;

	/**
747 748 749 750 751 752 753
	 * Whether to allow off-site redirects.  If this is not
	 * specified, the `http.followRedirects` configuration setting
	 * will be consulted.
	 */
	git_remote_redirect_t follow_redirects;

	/**
754 755 756
	 * Extra headers for this fetch operation
	 */
	git_strarray custom_headers;
757 758 759
} git_fetch_options;

#define GIT_FETCH_OPTIONS_VERSION 1
760 761
#define GIT_FETCH_OPTIONS_INIT { GIT_FETCH_OPTIONS_VERSION, GIT_REMOTE_CALLBACKS_INIT, GIT_FETCH_PRUNE_UNSPECIFIED, 1, \
				 GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED, GIT_PROXY_OPTIONS_INIT }
762

763
/**
764 765
 * Initialize git_fetch_options structure
 *
766
 * Initializes a `git_fetch_options` with default values. Equivalent to
767
 * creating an instance with `GIT_FETCH_OPTIONS_INIT`.
768
 *
769 770
 * @param opts The `git_fetch_options` struct to initialize.
 * @param version The struct version; pass `GIT_FETCH_OPTIONS_VERSION`.
771 772
 * @return Zero on success; -1 on failure.
 */
773
GIT_EXTERN(int) git_fetch_options_init(
774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797
	git_fetch_options *opts,
	unsigned int version);


/**
 * Controls the behavior of a git_push object.
 */
typedef struct {
	unsigned int version;

	/**
	 * If the transport being used to push to the remote requires the creation
	 * of a pack file, this controls the number of worker threads used by
	 * the packbuilder when creating that pack file to be sent to the remote.
	 *
	 * If set to 0, the packbuilder will auto-detect the number of threads
	 * to create. The default value is 1.
	 */
	unsigned int pb_parallelism;

	/**
	 * Callbacks to use for this push operation
	 */
	git_remote_callbacks callbacks;
798 799

	/**
800 801 802 803 804
	* Proxy options to use, by default no proxy is used.
	*/
	git_proxy_options proxy_opts;

	/**
805 806 807 808 809 810 811
	 * Whether to allow off-site redirects.  If this is not
	 * specified, the `http.followRedirects` configuration setting
	 * will be consulted.
	 */
	git_remote_redirect_t follow_redirects;

	/**
812 813 814
	 * Extra headers for this push operation
	 */
	git_strarray custom_headers;
815 816 817
} git_push_options;

#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 822
 * Initialize git_push_options structure
 *
823
 * Initializes a `git_push_options` with default values. Equivalent to
824
 * creating an instance with `GIT_PUSH_OPTIONS_INIT`.
825
 *
826 827
 * @param opts The `git_push_options` struct to initialize.
 * @param version The struct version; pass `GIT_PUSH_OPTIONS_VERSION`.
828 829
 * @return Zero on success; -1 on failure.
 */
830
GIT_EXTERN(int) git_push_options_init(
831 832 833 834
	git_push_options *opts,
	unsigned int version);

/**
835 836 837 838 839 840 841 842 843 844 845 846 847 848 849
 * Remote creation options structure
 *
 * Initialize with `GIT_REMOTE_CREATE_OPTIONS_INIT`. Alternatively, you can
 * use `git_remote_create_options_init`.
 *
 */
typedef struct {
	unsigned int version;

	/** Callbacks to use for this connection */
	git_remote_callbacks callbacks;

	/** HTTP Proxy settings */
	git_proxy_options proxy_opts;

850 851 852 853 854 855 856
	/**
	 * Whether to allow off-site redirects.  If this is not
	 * specified, the `http.followRedirects` configuration setting
	 * will be consulted.
	 */
	git_remote_redirect_t follow_redirects;

857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928
	/** Extra HTTP headers to use in this connection */
	git_strarray custom_headers;
} git_remote_connect_options;

#define GIT_REMOTE_CONNECT_OPTIONS_VERSION 1
#define GIT_REMOTE_CONNECT_OPTIONS_INIT { \
	GIT_REMOTE_CONNECT_OPTIONS_VERSION, \
	GIT_REMOTE_CALLBACKS_INIT, \
	GIT_PROXY_OPTIONS_INIT }

/**
 * Initialize git_remote_connect_options structure.
 *
 * Initializes a `git_remote_connect_options` with default values.
 * Equivalent to creating an instance with
 * `GIT_REMOTE_CONNECT_OPTIONS_INIT`.
 *
 * @param opts The `git_remote_connect_options` struct to initialize.
 * @param version The struct version; pass `GIT_REMOTE_CONNECT_OPTIONS_VERSION`.
 * @return Zero on success; -1 on failure.
 */
GIT_EXTERN(int) git_remote_connect_options_init(
		git_remote_connect_options *opts,
		unsigned int version);

/**
 * Open a connection to a remote.
 *
 * The transport is selected based on the URL; the direction argument
 * is due to a limitation of the git protocol which starts up a
 * specific binary which can only do the one or the other.
 *
 * @param remote the remote to connect to
 * @param direction GIT_DIRECTION_FETCH if you want to fetch or
 * GIT_DIRECTION_PUSH if you want to push
 * @param callbacks the callbacks to use for this connection
 * @param proxy_opts proxy settings
 * @param custom_headers extra HTTP headers to use in this connection
 * @return 0 or an error code
 */
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);

/**
 * Open a connection to a remote with extended options.
 *
 * The transport is selected based on the URL; the direction argument
 * is due to a limitation of the git protocol which starts up a
 * specific binary which can only do the one or the other.
 *
 * The given options structure will form the defaults for connection
 * options and callback setup.  Callers may override these defaults
 * by specifying `git_fetch_options` or `git_push_options` in
 * subsequent calls.
 *
 * @param remote the remote to connect to
 * @param direction GIT_DIRECTION_FETCH if you want to fetch or
 * GIT_DIRECTION_PUSH if you want to push
 * @param opts the remote connection options
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_remote_connect_ext(
	git_remote *remote,
	git_direction direction,
	const git_remote_connect_options *opts);

/**
 * Download and index the packfile.
929 930 931 932 933 934 935 936
 *
 * Connect to the remote if it hasn't been done yet, negotiate with
 * the remote git which objects are missing, download and index the
 * packfile.
 *
 * The .idx file will be created and both it and the packfile with be
 * renamed to their final name.
 *
937 938 939 940
 * If options are specified and this remote is already connected then
 * the existing remote connection options will be discarded and the
 * remote will now use the new options.
 *
941 942 943
 * @param remote the remote
 * @param refspecs the refspecs to use for this negotiation and
 * 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 948 949 950
 GIT_EXTERN(int) git_remote_download(
	git_remote *remote,
	const git_strarray *refspecs,
	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 957 958 959 960 961
 * the remote git which objects are missing, create a packfile with
 * the missing objects and send it.
 *
 * If options are specified and this remote is already connected then
 * the existing remote connection options will be discarded and the
 * remote will now use the new options.
962
 *
963 964 965 966 967 968
 * @param remote the remote
 * @param refspecs the refspecs to use for this negotiation and
 * upload. Use NULL or an empty array to use the base refspecs
 * @param opts the options to use for this push
 * @return 0 or an error code
 */
969 970 971 972
GIT_EXTERN(int) git_remote_upload(
	git_remote *remote,
	const git_strarray *refspecs,
	const git_push_options *opts);
973 974

/**
975 976 977 978
 * Update the tips to the new state.
 *
 * If callbacks are not specified then the callbacks specified to
 * `git_remote_connect` will be used (if it was called).
979 980 981 982 983 984
 *
 * @param remote the remote to update
 * @param reflog_message The message to insert into the reflogs. If
 * NULL and fetching, the default is "fetch <name>", where <name> is
 * the name of the remote (or its url, for in-memory remotes). This
 * 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 988
 * @param download_tags what the behaviour for downloading tags is for this fetch. This is
 * ignored for push. This must be the same value passed to `git_remote_download()`.
989 990 991 992 993
 * @return 0 or an error code
 */
GIT_EXTERN(int) git_remote_update_tips(
		git_remote *remote,
		const git_remote_callbacks *callbacks,
994
		int update_fetchhead,
995
		git_remote_autotag_option_t download_tags,
996 997 998
		const char *reflog_message);

/**
999
 * Download new data and update tips.
1000 1001 1002 1003
 *
 * Convenience function to connect to a remote, download the data,
 * disconnect and update the remote-tracking branches.
 *
1004 1005 1006 1007
 * If options are specified and this remote is already connected then
 * the existing remote connection options will be discarded and the
 * remote will now use the new options.
 *
1008 1009 1010
 * @param remote the remote to fetch from
 * @param refspecs the refspecs to use for this fetch. Pass NULL or an
 *                 empty array to use the base refspecs.
1011
 * @param opts options to use for this fetch or NULL
1012 1013 1014
 * @param reflog_message The message to insert into the reflogs. If NULL, the
 *								 default is "fetch"
 * @return 0 or an error code
1015
 */
1016 1017 1018 1019 1020 1021 1022
GIT_EXTERN(int) git_remote_fetch(
		git_remote *remote,
		const git_strarray *refspecs,
		const git_fetch_options *opts,
		const char *reflog_message);

/**
1023 1024 1025 1026
 * Prune tracking refs that are no longer present on remote.
 *
 * If callbacks are not specified then the callbacks specified to
 * `git_remote_connect` will be used (if it was called).
1027 1028 1029 1030 1031
 *
 * @param remote the remote to prune
 * @param callbacks callbacks to use for this prune
 * @return 0 or an error code
 */
1032 1033 1034
GIT_EXTERN(int) git_remote_prune(
	git_remote *remote,
	const git_remote_callbacks *callbacks);
1035 1036

/**
1037
 * Perform a push.
1038
 *
1039 1040 1041
 * If options are specified and this remote is already connected then
 * the existing remote connection options will be discarded and the
 * remote will now use the new options.
1042 1043
 *
 * @param remote the remote to push to
1044 1045
 * @param refspecs the refspecs to use for pushing. If NULL or an empty
 *                 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 1050 1051 1052
GIT_EXTERN(int) git_remote_push(
	git_remote *remote,
	const git_strarray *refspecs,
	const git_push_options *opts);
1053 1054

/**
1055 1056
 * Get the statistics structure that is filled in by the fetch operation.
 */
1057
GIT_EXTERN(const git_indexer_progress *) git_remote_stats(git_remote *remote);
1058

1059
/**
1060 1061 1062 1063 1064
 * Retrieve the tag auto-follow setting
 *
 * @param remote the remote to query
 * @return the auto-follow setting
 */
1065
GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(const git_remote *remote);
1066 1067

/**
1068 1069 1070 1071
 * Set the remote's tag following setting.
 *
 * The change will be made in the configuration. No loaded remotes
 * will be affected.
1072
 *
1073 1074 1075
 * @param repo the repository in which to make the change
 * @param remote the name of the remote
 * @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);
punkymaniac committed
1079

1080
/**
1081 1082 1083 1084 1085 1086 1087 1088
 * Retrieve the ref-prune setting
 *
 * @param remote the remote to query
 * @return the ref-prune setting
 */
GIT_EXTERN(int) git_remote_prune_refs(const git_remote *remote);

/**
1089 1090 1091 1092 1093
 * Give the remote a new name
 *
 * All remote-tracking branches and configuration settings
 * for the remote are updated.
 *
1094 1095 1096
 * The new name will be checked for validity.
 * See `git_tag_create()` for rules about valid names.
 *
1097 1098
 * No loaded instances of a the remote with the old name will change
 * their name or their list of refspecs.
1099
 *
1100 1101
 * @param problems non-default refspecs cannot be renamed and will be
 * stored here for further processing by the caller. Always free this
Will Stamper committed
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 1111
	git_repository *repo,
	const char *name,
1112
	const char *new_name);
1113

1114
/**
1115 1116
 * Ensure the remote name is well-formed.
 *
1117 1118 1119 1120
 * @param valid output pointer to set with validity of given remote name
 * @param remote_name name to be checked.
 * @return 0 on success or an error code
 */
1121
GIT_EXTERN(int) git_remote_name_is_valid(int *valid, const char *remote_name);
1122 1123

/**
1124 1125 1126 1127 1128
* Delete an existing persisted remote.
*
* All remote-tracking branches and configuration settings
* for the remote will be removed.
*
1129
* @param repo the repository in which to act
Remy Suen committed
1130
* @param name the name of the remote to delete
1131 1132
* @return 0 on success, or an error code.
*/
1133
GIT_EXTERN(int) git_remote_delete(git_repository *repo, const char *name);
1134

1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145
/**
 * Retrieve the name of the remote's default branch
 *
 * The default branch of a repository is the branch which HEAD points
 * to. If the remote does not support reporting this information
 * directly, it performs the guess as git does; that is, if there are
 * multiple branches which point to the same commit, the first one is
 * chosen. If the master branch is a candidate, it wins.
 *
 * This function must only be called after connecting.
 *
1146
 * @param out the buffer in which to store the reference name
1147 1148 1149 1150 1151 1152
 * @param remote the remote
 * @return 0, GIT_ENOTFOUND if the remote does not have any references
 * or none of them point to HEAD's commit, or an error message.
 */
GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote);

1153
/** @} */
Vicent Marti committed
1154
GIT_END_DECL
Carlos Martín Nieto committed
1155
#endif