/*

 * Copyright (C) the libgit2 contributors. All rights reserved.

 *

 * This file is part of libgit2, distributed under the GNU GPL v2 with

 * a Linking Exception. For full terms see the included COPYING file.

 */

#ifndef INCLUDE_git_remote_h__

#define INCLUDE_git_remote_h__

#include "common.h"

#include "repository.h"

#include "refspec.h"

#include "net.h"

#include "indexer.h"

#include "strarray.h"

#include "transport.h"

#include "pack.h"

#include "proxy.h"

/**

 * @file git2/remote.h

 * @brief Git remote management functions

 * @defgroup git_remote remote management functions

 * @ingroup Git

 * @{

 */

GIT_BEGIN_DECL

/**

 * Add a remote with the default fetch refspec to the repository's configuration.

 *

 * @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

 * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code

 */

GIT_EXTERN(int) git_remote_create(

		git_remote **out,

		git_repository *repo,

		const char *name,

		const char *url);

/**

 * Add a remote with the provided fetch refspec (or default if NULL) to the repository's

 * configuration.

 *

 * @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

 * @param fetch the remote fetch value

 * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code

 */

GIT_EXTERN(int) git_remote_create_with_fetchspec(

		git_remote **out,

		git_repository *repo,

		const char *name,

		const char *url,

		const char *fetch);

/**

 * Create an anonymous remote

 *

 * Create a remote with the given url in-memory. You can use this when

 * you have a URL instead of a remote's name.

 *

 * @param out pointer to the new remote objects

 * @param repo the associated repository

 * @param url the remote repository's URL

 * @return 0 or an error code

 */

GIT_EXTERN(int) git_remote_create_anonymous(

		git_remote **out,

		git_repository *repo,

		const char *url);

/**

 * Get the information for a particular remote

 *

 * The name will be checked for validity.

 * See `git_tag_create()` for rules about valid names.

 *

 * @param out pointer to the new remote object

 * @param repo the associated repository

 * @param name the remote's name

 * @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code

 */

GIT_EXTERN(int) git_remote_lookup(git_remote **out, git_repository *repo, const char *name);

/**

 * 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

 */

GIT_EXTERN(int) git_remote_dup(git_remote **dest, git_remote *source);

/**

 * 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);

/**

 * Get the remote's name

 *

 * @param remote the remote

 * @return a pointer to the name or NULL for in-memory remotes

 */

GIT_EXTERN(const char *) git_remote_name(const git_remote *remote);

/**

 * Get the remote's url

 *

 * If url.*.insteadOf has been configured for this URL, it will

 * return the modified URL.

 *

 * @param remote the remote

 * @return a pointer to the url

 */

GIT_EXTERN(const char *) git_remote_url(const git_remote *remote);

/**

 * Get the remote's url for pushing

 *

 * If url.*.pushInsteadOf has been configured for this URL, it

 * will return the modified URL.

 *

 * @param remote the remote

 * @return a pointer to the url or NULL if no special url for pushing is set

 */

GIT_EXTERN(const char *) git_remote_pushurl(const git_remote *remote);

/**

 * Set the remote's url in the configuration

 *

 * 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.

 *

 * @param repo the repository in which to perform the change

 * @param remote the remote's name

 * @param url the url to set

 * @return 0 or an error value

 */

GIT_EXTERN(int) git_remote_set_url(git_repository *repo, const char *remote, const char* url);

/**

 * Set the remote's url for pushing in the configuration.

 *

 * 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.

 *

 *

 * @param repo the repository in which to perform the change

 * @param remote the remote's name

 * @param url the url to set

 */

GIT_EXTERN(int) git_remote_set_pushurl(git_repository *repo, const char *remote, const char* url);

/**

 * Add a fetch refspec to the remote's configuration

 *

 * Add the given refspec to the fetch list in the configuration. No

 * loaded remote instances will be affected.

 *

 * @param repo the repository in which to change the configuration

 * @param remote the name of the remote to change

 * @param refspec the new fetch refspec

 * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value

 */

GIT_EXTERN(int) git_remote_add_fetch(git_repository *repo, const char *remote, const char *refspec);

/**

 * 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

 */

GIT_EXTERN(int) git_remote_get_fetch_refspecs(git_strarray *array, const git_remote *remote);

/**

 * Add a push refspec to the remote's configuration

 *

 * Add the given refspec to the push list in the configuration. No

 * loaded remote instances will be affected.

 *

 * @param repo the repository in which to change the configuration

 * @param remote the name of the remote to change

 * @param refspec the new push refspec

 * @return 0, GIT_EINVALIDSPEC if refspec is invalid or an error value

 */

GIT_EXTERN(int) git_remote_add_push(git_repository *repo, const char *remote, const char *refspec);

/**

 * 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

 */

GIT_EXTERN(int) git_remote_get_push_refspecs(git_strarray *array, const git_remote *remote);

/**

 * Get the number of refspecs for a remote

 *

 * @param remote the remote

 * @return the amount of refspecs configured in this remote

 */

GIT_EXTERN(size_t) git_remote_refspec_count(const git_remote *remote);

/**

 * Get a refspec from the remote

 *

 * @param remote the remote to query

 * @param n the refspec to get

 * @return the nth refspec

 */

GIT_EXTERN(const git_refspec *)git_remote_get_refspec(const git_remote *remote, size_t n);

/**

 * 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 (over TCP or SSH) 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);

/**

 * Get the remote repository's reference advertisement list

 *

 * Get the list of references with which the server responds to a new

 * connection.

 *

 * 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.

 *

 * @param out pointer to the array

 * @param size the number of remote heads

 * @param remote the remote

 * @return 0 on success, or an error code

 */

GIT_EXTERN(int) git_remote_ls(const git_remote_head ***out,  size_t *size, git_remote *remote);

/**

 * Check whether the remote is connected

 *

 * Check whether the remote's underlying transport is connected to the

 * remote host.

 *

 * @param remote the remote

 * @return 1 if it's connected, 0 otherwise.

 */

GIT_EXTERN(int) git_remote_connected(const git_remote *remote);

/**

 * 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.

 *

 * @param remote the remote

 */

GIT_EXTERN(void) git_remote_stop(git_remote *remote);

/**

 * Disconnect from the remote

 *

 * Close the connection to the remote.

 *

 * @param remote the remote to disconnect from

 */

GIT_EXTERN(void) git_remote_disconnect(git_remote *remote);

/**

 * Free the memory associated with a remote

 *

 * This also disconnects from the remote, if the connection

 * has not been closed yet (using git_remote_disconnect).

 *

 * @param remote the remote to free

 */

GIT_EXTERN(void) git_remote_free(git_remote *remote);

/**

 * Get a list of the configured remotes for a repo

 *

 * The string array must be freed by the user.

 *

 * @param out a string array which receives the names of the remotes

 * @param repo the repository to query

 * @return 0 or an error code

 */

GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo);

/**

 * Argument to the completion callback which tells it which operation

 * finished.

 */

typedef enum git_remote_completion_type {

	GIT_REMOTE_COMPLETION_DOWNLOAD,

	GIT_REMOTE_COMPLETION_INDEXING,

	GIT_REMOTE_COMPLETION_ERROR,

} git_remote_completion_type;

/** Push network progress notification function */

typedef int (*git_push_transfer_progress)(

	unsigned int current,

	unsigned int total,

	size_t bytes,

	void* payload);

/**

 * 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;

/**

 * Callback used to inform of upcoming updates.

 *

 * @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

 */

typedef int (*git_push_negotiation)(const git_push_update **updates, size_t len, void *payload);

/**

 * The callback settings structure

 *

 * Set the callbacks to be called by the remote when informing the user

 * about the progress of the network operations.

 */

struct git_remote_callbacks {

	unsigned int version;

	/**

	 * Textual progress from the remote. Text send over the

	 * progress side-band will be passed to this function (this is

	 * the 'counting objects' output).

	 */

	git_transport_message_cb sideband_progress;

	/**

	 * Completion is called when different parts of the download

	 * process are done (currently unused).

	 */

	int (*completion)(git_remote_completion_type type, void *data);

	/**

	 * This will be called if the remote host requires

	 * authentication in order to connect to it.

	 *

	 * Returning GIT_PASSTHROUGH will make libgit2 behave as

	 * though this field isn't set.

	 */

	git_cred_acquire_cb credentials;

	/**

	 * If cert verification fails, this will be called to let the

	 * user make the final decision of whether to allow the

	 * connection to proceed. Returns 1 to allow the connection, 0

	 * to disallow it or a negative value to indicate an error.

	 */

	git_transport_certificate_check_cb certificate_check;

	/**

	 * During the download of new data, this will be regularly

	 * called with the current count of progress done by the

	 * indexer.

	 */

	git_transfer_progress_cb transfer_progress;

	/**

	 * Each time a reference is updated locally, this function

	 * will be called with information about it.

	 */

	int (*update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data);

	/**

	 * 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.

	 */

	git_push_transfer_progress push_transfer_progress;

	/**

	 * 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.

	 */

	int (*push_update_reference)(const char *refname, const char *status, void *data);

	/**

	 * Called once between the negotiation step and the upload. It

	 * provides information about what updates will be performed.

	 */

	git_push_negotiation push_negotiation;

	/**

	 * Create the transport to use for this operation. Leave NULL

	 * to auto-detect.

	 */

	git_transport_cb transport;

	/**

	 * This will be passed to each of the callbacks in this struct

	 * as the last parameter.

	 */

	void *payload;

};

#define GIT_REMOTE_CALLBACKS_VERSION 1

#define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION}

/**

 * Initializes a `git_remote_callbacks` with default values. Equivalent to

 * creating an instance with GIT_REMOTE_CALLBACKS_INIT.

 *

 * @param opts the `git_remote_callbacks` struct to initialize

 * @param version Version of struct; pass `GIT_REMOTE_CALLBACKS_VERSION`

 * @return Zero on success; -1 on failure.

 */

GIT_EXTERN(int) git_remote_init_callbacks(

	git_remote_callbacks *opts,

	unsigned int version);

typedef enum {

	/**

	 * Use the setting from the configuration

	 */

	GIT_FETCH_PRUNE_UNSPECIFIED,

	/**

	 * Force pruning on

	 */

	GIT_FETCH_PRUNE,

	/**

	 * Force pruning off

	 */

	GIT_FETCH_NO_PRUNE,

} git_fetch_prune_t;

/**

 * Automatic tag following option

 *

 * Lets us select the --tags option to use.

 */

typedef enum {

	/**

	 * Use the setting from the configuration.

	 */

	GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED = 0,

	/**

	 * 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.

	 */

	GIT_REMOTE_DOWNLOAD_TAGS_ALL,

} git_remote_autotag_option_t;

/**

 * 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;

 */

typedef struct {

	int version;

	/**

	 * Callbacks to use for this fetch operation

	 */

	git_remote_callbacks callbacks;

	/**

	 * Whether to perform a prune after the fetch

	 */

	git_fetch_prune_t prune;

	/**

	 * Whether to write the results to FETCH_HEAD. Defaults to

	 * on. Leave this default in order to behave like git.

	 */

	int update_fetchhead;

	/**

	 * 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;

	/**

	 * Proxy options to use, by default no proxy is used.

	 */

	git_proxy_options proxy_opts;

	/**

	 * Extra headers for this fetch operation

	 */

	git_strarray custom_headers;

} git_fetch_options;

#define GIT_FETCH_OPTIONS_VERSION 1

#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 }

/**

 * Initializes a `git_fetch_options` with default values. Equivalent to

 * creating an instance with GIT_FETCH_OPTIONS_INIT.

 *

 * @param opts the `git_fetch_options` instance to initialize.

 * @param version the version of the struct; you should pass

 *        `GIT_FETCH_OPTIONS_VERSION` here.

 * @return Zero on success; -1 on failure.

 */

GIT_EXTERN(int) git_fetch_init_options(

	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;

	/**

	* Proxy options to use, by default no proxy is used.

	*/

	git_proxy_options proxy_opts;

	/**

	 * Extra headers for this push operation

	 */

	git_strarray custom_headers;

} git_push_options;

#define GIT_PUSH_OPTIONS_VERSION 1

#define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 0, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }

/**

 * Initializes a `git_push_options` with default values. Equivalent to

 * creating an instance with GIT_PUSH_OPTIONS_INIT.

 *

 * @param opts the `git_push_options` instance to initialize.

 * @param version the version of the struct; you should pass

 *        `GIT_PUSH_OPTIONS_VERSION` here.

 * @return Zero on success; -1 on failure.

 */

GIT_EXTERN(int) git_push_init_options(

	git_push_options *opts,

	unsigned int version);

/**

 * Download and index the packfile

 *

 * 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.

 *

 * @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

 * @param opts the options to use for this fetch

 * @return 0 or an error code

 */

 GIT_EXTERN(int) git_remote_download(git_remote *remote, const git_strarray *refspecs, const git_fetch_options *opts);

/**

 * Create a packfile and send it to the server

 *

 * Connect to the remote if it hasn't been done yet, negotiate with

 * the remote git which objects are missing, create a packfile with the missing objects and send it.

 *

 * @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

 */

GIT_EXTERN(int) git_remote_upload(git_remote *remote, const git_strarray *refspecs, const git_push_options *opts);

/**

 * Update the tips to the new state

 *

 * @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.

 * @param callbacks  pointer to the callback structure to use

 * @param update_fetchhead whether to write to FETCH_HEAD. Pass 1 to behave like git.

 * @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()`.

 * @return 0 or an error code

 */

GIT_EXTERN(int) git_remote_update_tips(

		git_remote *remote,

		const git_remote_callbacks *callbacks,

		int update_fetchhead,

		git_remote_autotag_option_t download_tags,

		const char *reflog_message);

/**

 * Download new data and update tips

 *

 * Convenience function to connect to a remote, download the data,

 * disconnect and update the remote-tracking branches.

 *

 * @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.

 * @param opts options to use for this fetch

 * @param reflog_message The message to insert into the reflogs. If NULL, the

 *								 default is "fetch"

 * @return 0 or an error code

 */

GIT_EXTERN(int) git_remote_fetch(

		git_remote *remote,

		const git_strarray *refspecs,

		const git_fetch_options *opts,

		const char *reflog_message);

/**

 * Prune tracking refs that are no longer present on remote

 *

 * @param remote the remote to prune

 * @param callbacks callbacks to use for this prune

 * @return 0 or an error code

 */

GIT_EXTERN(int) git_remote_prune(git_remote *remote, const git_remote_callbacks *callbacks);

/**

 * Perform a push

 *

 * Peform all the steps from a push.

 *

 * @param remote the remote to push to

 * @param refspecs the refspecs to use for pushing. If NULL or an empty

 *                 array, the configured refspecs will be used

 * @param opts options to use for this push

 */

GIT_EXTERN(int) git_remote_push(git_remote *remote,

				const git_strarray *refspecs,

				const git_push_options *opts);

/**

 * Get the statistics structure that is filled in by the fetch operation.

 */

GIT_EXTERN(const git_transfer_progress *) git_remote_stats(git_remote *remote);

/**

 * Retrieve the tag auto-follow setting

 *

 * @param remote the remote to query

 * @return the auto-follow setting

 */

GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(const git_remote *remote);

/**

 * Set the remote's tag following setting.

 *

 * The change will be made in the configuration. No loaded remotes

 * will be affected.

 *

 * @param repo the repository in which to make the change

 * @param remote the name of the remote

 * @param value the new value to take.

 */

GIT_EXTERN(int) git_remote_set_autotag(git_repository *repo, const char *remote, git_remote_autotag_option_t value);

/**

 * 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);

/**

 * Give the remote a new name

 *

 * All remote-tracking branches and configuration settings

 * for the remote are updated.

 *

 * The new name will be checked for validity.

 * See `git_tag_create()` for rules about valid names.

 *

 * No loaded instances of a the remote with the old name will change

 * their name or their list of refspecs.

 *

 * @param problems non-default refspecs cannot be renamed and will be

 * stored here for further processing by the caller. Always free this

 * strarray on successful return.

 * @param repo the repository in which to rename

 * @param name the current name of the remote

 * @param new_name the new name the remote should bear

 * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code

 */

GIT_EXTERN(int) git_remote_rename(

	git_strarray *problems,

	git_repository *repo,

	const char *name,

	const char *new_name);

/**

 * Ensure the remote name is well-formed.

 *

 * @param remote_name name to be checked.

 * @return 1 if the reference name is acceptable; 0 if it isn't

 */

GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name);

/**

* Delete an existing persisted remote.

*

* All remote-tracking branches and configuration settings

* for the remote will be removed.

*

* @param repo the repository in which to act

* @param name the name of the remote to delete

* @return 0 on success, or an error code.

*/

GIT_EXTERN(int) git_remote_delete(git_repository *repo, const char *name);

/**

 * 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.

 *

 * @param out the buffern in which to store the reference name

 * @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);

/** @} */

GIT_END_DECL

#endif