Merge branch 'development'v0.18.0

1 files changed, 261 insertions, 32 deletions

diff --git a/include/git2/remote.h b/include/git2/remote.h
index 865dfef04..6f36a3999 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2009-2012 the libgit2 contributors
+ * 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.
@@ -12,6 +12,8 @@
 #include "refspec.h"
 #include "net.h"
 #include "indexer.h"
+#include "strarray.h"
+#include "transport.h"
 
 /**
  * @file git2/remote.h
@@ -22,6 +24,7 @@
  */
 GIT_BEGIN_DECL
 
+typedef int (*git_remote_rename_problem_cb)(const char *problematic_refspec, void *payload);
 /*
  * TODO: This functions still need to be implemented:
  * - _listcb/_foreach
@@ -31,35 +34,64 @@ GIT_BEGIN_DECL
  */
 
 /**
+ * Add a remote with the default fetch refspec to the repository's configuration.  This
+ * calls git_remote_save before returning.
+ *
+ * @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);
+
+/**
  * Create a remote in memory
  *
- * Create a remote with the default refspecs in memory. You can use
- * this when you have a URL instead of a remote's name.
+ * Create a remote with the given refspec in memory. You can use
+ * this when you have a URL instead of a remote's name.  Note that in-memory
+ * remotes cannot be converted to persisted remotes.
+ *
+ * The name, when provided, 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 associtated repository
- * @param name the remote's name
+ * @param repo the associated repository
+ * @param fetch the fetch refspec to use for this remote. May be NULL for defaults.
  * @param url the remote repository's URL
- * @param fetch the fetch refspec to use for this remote
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_remote_new(git_remote **out, git_repository *repo, const char *name, const char *url, const char *fetch);
+GIT_EXTERN(int) git_remote_create_inmemory(
+		git_remote **out,
+		git_repository *repo,
+		const char *fetch,
+		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 cfg the repository's configuration
+ * @param repo the associated repository
  * @param name the remote's name
- * @return 0 or an error code
+ * @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code
  */
 GIT_EXTERN(int) git_remote_load(git_remote **out, git_repository *repo, const char *name);
 
 /**
  * Save a remote to its repository's configuration
  *
+ * One can't save a in-memory remote. Doing so will
+ * result in a GIT_EINVALIDSPEC being returned.
+ *
  * @param remote the remote to save to config
- * @return 0 or an error code
+ * @return 0, GIT_EINVALIDSPEC or an error code
  */
 GIT_EXTERN(int) git_remote_save(const git_remote *remote);
 
@@ -67,9 +99,9 @@ GIT_EXTERN(int) git_remote_save(const git_remote *remote);
  * Get the remote's name
  *
  * @param remote the remote
- * @return a pointer to the name
+ * @return a pointer to the name or NULL for in-memory remotes
  */
-GIT_EXTERN(const char *) git_remote_name(git_remote *remote);
+GIT_EXTERN(const char *) git_remote_name(const git_remote *remote);
 
 /**
  * Get the remote's url
@@ -77,7 +109,37 @@ GIT_EXTERN(const char *) git_remote_name(git_remote *remote);
  * @param remote the remote
  * @return a pointer to the url
  */
-GIT_EXTERN(const char *) git_remote_url(git_remote *remote);
+GIT_EXTERN(const char *) git_remote_url(const git_remote *remote);
+
+/**
+ * Get the remote's url for pushing
+ *
+ * @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
+ *
+ * Existing connections will not be updated.
+ *
+ * @param remote the remote
+ * @param url the url to set
+ * @return 0 or an error value
+ */
+GIT_EXTERN(int) git_remote_set_url(git_remote *remote, const char* url);
+
+/**
+ * Set the remote's url for pushing
+ *
+ * Existing connections will not be updated.
+ *
+ * @param remote the remote
+ * @param url the url to set or NULL to clear the pushurl
+ * @return 0 or an error value
+ */
+GIT_EXTERN(int) git_remote_set_pushurl(git_remote *remote, const char* url);
 
 /**
  * Set the remote's fetch refspec
@@ -94,13 +156,13 @@ GIT_EXTERN(int) git_remote_set_fetchspec(git_remote *remote, const char *spec);
  * @param remote the remote
  * @return a pointer to the fetch refspec or NULL if it doesn't exist
  */
-GIT_EXTERN(const git_refspec *) git_remote_fetchspec(git_remote *remote);
+GIT_EXTERN(const git_refspec *) git_remote_fetchspec(const git_remote *remote);
 
 /**
  * Set the remote's push refspec
  *
  * @param remote the remote
- * @apram spec the new push refspec
+ * @param spec the new push refspec
  * @return 0 or an error value
  */
 GIT_EXTERN(int) git_remote_set_pushspec(git_remote *remote, const char *spec);
@@ -112,7 +174,7 @@ GIT_EXTERN(int) git_remote_set_pushspec(git_remote *remote, const char *spec);
  * @return a pointer to the push refspec or NULL if it doesn't exist
  */
 
-GIT_EXTERN(const git_refspec *) git_remote_pushspec(git_remote *remote);
+GIT_EXTERN(const git_refspec *) git_remote_pushspec(const git_remote *remote);
 
 /**
  * Open a connection to a remote
@@ -125,7 +187,7 @@ GIT_EXTERN(const git_refspec *) git_remote_pushspec(git_remote *remote);
  * @param direction whether you want to receive or send data
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_remote_connect(git_remote *remote, int direction);
+GIT_EXTERN(int) git_remote_connect(git_remote *remote, git_direction direction);
 
 /**
  * Get a list of refs at the remote
@@ -133,9 +195,13 @@ GIT_EXTERN(int) git_remote_connect(git_remote *remote, int direction);
  * The remote (or more exactly its transport) must be connected. The
  * memory belongs to the remote.
  *
- * @param refs where to store the refs
+ * If you a return a non-zero value from the callback, this will stop
+ * looping over the refs.
+ *
  * @param remote the remote
- * @return 0 or an error code
+ * @param list_cb function to call with each ref discovered at the remote
+ * @param payload additional data to pass to the callback
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_remote_ls(git_remote *remote, git_headlist_cb list_cb, void *payload);
 
@@ -149,10 +215,16 @@ GIT_EXTERN(int) git_remote_ls(git_remote *remote, git_headlist_cb list_cb, void
  * filename will be NULL and the function will return success.
  *
  * @param remote the remote to download from
- * @param filename where to store the temproray filename
+ * @param progress_cb function to call with progress information.  Be aware that
+ * this is called inline with network and indexing operations, so performance
+ * may be affected.
+ * @param progress_payload payload for the progress callback
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_remote_download(git_remote *remote, git_off_t *bytes, git_indexer_stats *stats);
+GIT_EXTERN(int) git_remote_download(
+		git_remote *remote,
+		git_transfer_progress_callback progress_cb,
+		void *payload);
 
 /**
  * Check whether the remote is connected
@@ -160,11 +232,22 @@ GIT_EXTERN(int) git_remote_download(git_remote *remote, git_off_t *bytes, git_in
  * 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(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 and free the underlying
@@ -188,14 +271,14 @@ GIT_EXTERN(void) git_remote_free(git_remote *remote);
  * Update the tips to the new state
  *
  * @param remote the remote to update
- * @param cb callback to run on each ref update. 'a' is the old value, 'b' is then new value
+ * @return 0 or an error code
  */
-GIT_EXTERN(int) git_remote_update_tips(git_remote *remote, int (*cb)(const char *refname, const git_oid *a, const git_oid *b));
+GIT_EXTERN(int) git_remote_update_tips(git_remote *remote);
 
 /**
  * Return whether a string is a valid remote URL
  *
- * @param tranport the url to check
+ * @param url the url to check
  * @param 1 if the url is valid, 0 otherwise
  */
 GIT_EXTERN(int) git_remote_valid_url(const char *url);
@@ -213,21 +296,167 @@ GIT_EXTERN(int) git_remote_supported_url(const char* url);
  *
  * The string array must be freed by the user.
  *
- * @param remotes_list a string array with the names of the remotes
+ * @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 *remotes_list, git_repository *repo);
+GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo);
 
 /**
- * Add a remote with the default fetch refspec to the repository's configuration
+ * Choose whether to check the server's certificate (applies to HTTPS only)
  *
- * @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 remote the remote to configure
+ * @param check whether to check the server's certificate (defaults to yes)
+ */
+GIT_EXTERN(void) git_remote_check_cert(git_remote *remote, int check);
+
+/**
+ * Set a credentials acquisition callback for this remote. If the remote is
+ * not available for anonymous access, then you must set this callback in order
+ * to provide credentials to the transport at the time of authentication
+ * failure so that retry can be performed.
+ *
+ * @param remote the remote to configure
+ * @param cred_acquire_cb The credentials acquisition callback to use (defaults
+ * to NULL)
+ */
+GIT_EXTERN(void) git_remote_set_cred_acquire_cb(
+	git_remote *remote,
+	git_cred_acquire_cb cred_acquire_cb,
+	void *payload);
+
+/**
+ * Sets a custom transport for the remote. The caller can use this function
+ * to bypass the automatic discovery of a transport by URL scheme (i.e.
+ * http://, https://, git://) and supply their own transport to be used
+ * instead. After providing the transport to a remote using this function,
+ * the transport object belongs exclusively to that remote, and the remote will
+ * free it when it is freed with git_remote_free.
+ *
+ * @param remote the remote to configure
+ * @param transport the transport object for the remote to use
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_remote_set_transport(
+	git_remote *remote,
+	git_transport *transport);
+
+/**
+ * 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;
+
+/**
+ * The callback settings structure
+ *
+ * Set the calbacks to be called by the remote.
+ */
+struct git_remote_callbacks {
+	unsigned int version;
+	void (*progress)(const char *str, int len, void *data);
+	int (*completion)(git_remote_completion_type type, void *data);
+	int (*update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data);
+	void *payload;
+};
+
+#define GIT_REMOTE_CALLBACKS_VERSION 1
+#define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION}
+
+/**
+ * Set the callbacks for a remote
+ *
+ * Note that the remote keeps its own copy of the data and you need to
+ * call this function again if you want to change the callbacks.
+ *
+ * @param remote the remote to configure
+ * @param callbacks a pointer to the user's callback settings
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_remote_set_callbacks(git_remote *remote, git_remote_callbacks *callbacks);
+
+/**
+ * Get the statistics structure that is filled in by the fetch operation.
+ */
+GIT_EXTERN(const git_transfer_progress *) git_remote_stats(git_remote *remote);
+
+typedef enum {
+	GIT_REMOTE_DOWNLOAD_TAGS_UNSET,
+	GIT_REMOTE_DOWNLOAD_TAGS_NONE,
+	GIT_REMOTE_DOWNLOAD_TAGS_AUTO,
+	GIT_REMOTE_DOWNLOAD_TAGS_ALL
+} git_remote_autotag_option_t;
+
+/**
+ * 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(git_remote *remote);
+
+/**
+ * Set the tag auto-follow setting
+ *
+ * @param remote the remote to configure
+ * @param value a GIT_REMOTE_DOWNLOAD_TAGS value
+ */
+GIT_EXTERN(void) git_remote_set_autotag(
+	git_remote *remote,
+	git_remote_autotag_option_t value);
+
+/**
+ * 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.
+ *
+ * A temporary in-memory remote cannot be given a name with this method.
+ *
+ * @param remote the remote to rename
+ * @param new_name the new name the remote should bear
+ * @param callback Optional callback to notify the consumer of fetch refspecs
+ * that haven't been automatically updated and need potential manual tweaking.
+ * @param payload Additional data to pass to the callback
+ * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
+ */
+GIT_EXTERN(int) git_remote_rename(
+	git_remote *remote,
+	const char *new_name,
+	git_remote_rename_problem_cb callback,
+	void *payload);
+
+/**
+ * Retrieve the update FETCH_HEAD setting.
+ *
+ * @param remote the remote to query
+ * @return the update FETCH_HEAD setting
+ */
+GIT_EXTERN(int) git_remote_update_fetchhead(git_remote *remote);
+
+/**
+ * Sets the update FETCH_HEAD setting.  By default, FETCH_HEAD will be
+ * updated on every fetch.  Set to 0 to disable.
+ *
+ * @param remote the remote to configure
+ * @param value 0 to disable updating FETCH_HEAD
+ */
+GIT_EXTERN(void) git_remote_set_update_fetchhead(git_remote *remote, int value);
+
+/**
+ * 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_add(git_remote **out, git_repository *repo, const char *name, const char *url);
+GIT_EXTERN(int) git_remote_is_valid_name(const char *remote_name);
 
 /** @} */
 GIT_END_DECL