* 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__
* @brief Git remote management functions
* @defgroup git_remote remote management functions
* 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(
* Remote creation options flags
/** Ignore the repository apply.insteadOf configuration */
GIT_REMOTE_CREATE_SKIP_INSTEADOF = (1 << 0),
/** Don't build a fetchspec from the name if none is set */
GIT_REMOTE_CREATE_SKIP_DEFAULT_FETCHSPEC = (1 << 1),
} git_remote_create_flags;
* Remote creation options structure
* Initialize with `GIT_REMOTE_CREATE_OPTIONS_INIT`. Alternatively, you can
* use `git_remote_create_options_init`.
typedef struct git_remote_create_options {
* The repository that should own the remote.
* Setting this to NULL results in a detached remote.
git_repository *repository;
* Setting this to NULL results in an in-memory/anonymous remote.
/** The fetchspec the remote should use. */
/** Additional flags for the remote. See git_remote_create_flags. */
} 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.
GIT_EXTERN(int) git_remote_create_options_init(
git_remote_create_options *opts,
* 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(
const git_remote_create_options *opts);
* Add a remote with the provided fetch refspec (or default if NULL) to the repository's
* @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(
* 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(
* 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
* @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(
* 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);
* @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);
* 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
* @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
* @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
* 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
* 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
* @param remote the remote
* @return 1 if it's connected, 0 otherwise.
GIT_EXTERN(int) git_remote_connected(const git_remote *remote);
* 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
* @return 0 on success, or an error code
GIT_EXTERN(int) git_remote_stop(git_remote *remote);
* Disconnect from the remote
* Close the connection to the remote.
* @param remote the remote to disconnect from
* @return 0 on success, or an error code
GIT_EXTERN(int) 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
typedef enum git_remote_completion_t {
GIT_REMOTE_COMPLETION_DOWNLOAD,
GIT_REMOTE_COMPLETION_INDEXING,
GIT_REMOTE_COMPLETION_ERROR,
} git_remote_completion_t;
/** Push network progress notification function */
typedef int GIT_CALLBACK(git_push_transfer_progress_cb)(
* Represents an update which will be performed on the remote during push
* The source name of the reference
* The name of the reference to update on the server
* The current target of the reference
* The new target for the reference
* 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_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload);
* 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
typedef int GIT_CALLBACK(git_push_update_reference_cb)(const char *refname, const char *status, void *data);
* Callback to resolve URLs before connecting to remote
* If you return GIT_PASSTHROUGH, you don't need to write anything to
* @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
typedef int GIT_CALLBACK(git_url_resolve_cb)(git_buf *url_resolved, const char *url, int direction, 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; /**< The version */
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
