Merge branch 'master' into pr/3938

9 files changed, 72 insertions, 12 deletions

diff --git a/include/git2/common.h b/include/git2/common.h
index a8d698fa4..99c99812b 100644
--- a/include/git2/common.h
+++ b/include/git2/common.h
@@ -109,9 +109,27 @@ GIT_EXTERN(void) git_libgit2_version(int *major, int *minor, int *rev);
  * was compiled
  */
 typedef enum {
+  /**
+   * If set, libgit2 was built thread-aware and can be safely used from multiple
+   * threads.
+   */
 	GIT_FEATURE_THREADS	= (1 << 0),
+  /**
+   * If set, libgit2 was built with and linked against a TLS implementation.
+   * Custom TLS streams may still be added by the user to support HTTPS
+   * regardless of this.
+   */
 	GIT_FEATURE_HTTPS	= (1 << 1),
+  /**
+   * If set, libgit2 was built with and linked against libssh2. A custom
+   * transport may still be added by the user to support libssh2 regardless of
+   * this.
+   */
 	GIT_FEATURE_SSH		= (1 << 2),
+  /**
+   * If set, libgit2 was built with support for sub-second resolution in file
+   * modification times.
+   */
 	GIT_FEATURE_NSEC	= (1 << 3),
 } git_feature_t;
 
diff --git a/include/git2/describe.h b/include/git2/describe.h
index 3044d9165..971eb350c 100644
--- a/include/git2/describe.h
+++ b/include/git2/describe.h
@@ -44,8 +44,8 @@ typedef enum {
 typedef struct git_describe_options {
 	unsigned int version;
 
-	unsigned int max_candidates_tags; /** default: 10 */
-	unsigned int describe_strategy; /** default: GIT_DESCRIBE_DEFAULT */
+	unsigned int max_candidates_tags; /**< default: 10 */
+	unsigned int describe_strategy; /**< default: GIT_DESCRIBE_DEFAULT */
 	const char *pattern;
 	/**
 	 * When calculating the distance from the matching tag or
@@ -105,6 +105,9 @@ typedef struct {
 
 GIT_EXTERN(int) git_describe_init_format_options(git_describe_format_options *opts, unsigned int version);
 
+/**
+ * A struct that stores the result of a describe operation.
+ */
 typedef struct git_describe_result git_describe_result;
 
 /**
diff --git a/include/git2/merge.h b/include/git2/merge.h
index c6f6cba6c..94ac8b5c5 100644
--- a/include/git2/merge.h
+++ b/include/git2/merge.h
@@ -290,7 +290,8 @@ typedef struct {
 } git_merge_options;
 
 #define GIT_MERGE_OPTIONS_VERSION 1
-#define GIT_MERGE_OPTIONS_INIT {GIT_MERGE_OPTIONS_VERSION}
+#define GIT_MERGE_OPTIONS_INIT { \
+	GIT_MERGE_OPTIONS_VERSION, GIT_MERGE_FIND_RENAMES }
 
 /**
  * Initializes a `git_merge_options` with default values. Equivalent to
diff --git a/include/git2/patch.h b/include/git2/patch.h
index 790cb74fc..4eb9f0263 100644
--- a/include/git2/patch.h
+++ b/include/git2/patch.h
@@ -191,7 +191,7 @@ GIT_EXTERN(int) git_patch_get_hunk(
  *
  * @param patch The git_patch object
  * @param hunk_idx Index of the hunk
- * @return Number of lines in hunk or -1 if invalid hunk index
+ * @return Number of lines in hunk or GIT_ENOTFOUND if invalid hunk index
  */
 GIT_EXTERN(int) git_patch_num_lines_in_hunk(
 	const git_patch *patch,
diff --git a/include/git2/proxy.h b/include/git2/proxy.h
index dcd615633..194cbb651 100644
--- a/include/git2/proxy.h
+++ b/include/git2/proxy.h
@@ -19,7 +19,7 @@ typedef enum {
 	/**
 	 * Do not attempt to connect through a proxy
 	 *
-	 * If built against lbicurl, it itself may attempt to connect
+	 * If built against libcurl, it itself may attempt to connect
 	 * to a proxy if the environment variables specify it.
 	 */
 	GIT_PROXY_NONE,
diff --git a/include/git2/remote.h b/include/git2/remote.h
index c459f42cc..691114172 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -26,8 +26,6 @@
  */
 GIT_BEGIN_DECL
 
-typedef int (*git_remote_rename_problem_cb)(const char *problematic_refspec, void *payload);
-
 /**
  * Add a remote with the default fetch refspec to the repository's configuration.
  *
@@ -360,6 +358,8 @@ typedef struct {
 } 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`
@@ -403,7 +403,7 @@ struct git_remote_callbacks {
 	 * 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;
+	git_transport_certificate_check_cb certificate_check;
 
 	/**
 	 * During the download of new data, this will be regularly
@@ -569,7 +569,7 @@ typedef struct {
  * Initializes a `git_fetch_options` with default values. Equivalent to
  * creating an instance with GIT_FETCH_OPTIONS_INIT.
  *
- * @param opts the `git_push_options` instance to initialize.
+ * @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.
diff --git a/include/git2/sys/repository.h b/include/git2/sys/repository.h
index 800396c86..0c9142143 100644
--- a/include/git2/sys/repository.h
+++ b/include/git2/sys/repository.h
@@ -135,6 +135,35 @@ GIT_EXTERN(void) git_repository_set_index(git_repository *repo, git_index *index
  */
 GIT_EXTERN(int) git_repository_set_bare(git_repository *repo);
 
+/**
+ * Load and cache all submodules.
+ *
+ * Because the `.gitmodules` file is unstructured, loading submodules is an
+ * O(N) operation.  Any operation (such as `git_rebase_init`) that requires
+ * accessing all submodules is O(N^2) in the number of submodules, if it
+ * has to look each one up individually.  This function loads all submodules
+ * and caches them so that subsequent calls to `git_submodule_lookup` are O(1).
+ *
+ * @param repo the repository whose submodules will be cached.
+ */
+GIT_EXTERN(int) git_repository_submodule_cache_all(
+	git_repository *repo);
+
+/**
+ * Clear the submodule cache.
+ *
+ * Clear the submodule cache populated by `git_repository_submodule_cache_all`.
+ * If there is no cache, do nothing.
+ *
+ * The cache incorporates data from the repository's configuration, as well
+ * as the state of the working tree, the index, and HEAD.  So any time any
+ * of these has changed, the cache might become invalid.
+ *
+ * @param repo the repository whose submodule cache will be cleared
+ */
+GIT_EXTERN(int) git_repository_submodule_cache_clear(
+	git_repository *repo);
+
 /** @} */
 GIT_END_DECL
 #endif
diff --git a/include/git2/transaction.h b/include/git2/transaction.h
index 64abb0c69..00ca13993 100644
--- a/include/git2/transaction.h
+++ b/include/git2/transaction.h
@@ -8,6 +8,14 @@
 #define INCLUDE_git_transaction_h__
 
 #include "common.h"
+
+/**
+ * @file git2/transaction.h
+ * @brief Git transactional reference routines
+ * @defgroup git_transaction Git transactional reference routines
+ * @ingroup Git
+ * @{
+ */
 GIT_BEGIN_DECL
 
 /**
@@ -107,5 +115,6 @@ GIT_EXTERN(int) git_transaction_commit(git_transaction *tx);
  */
 GIT_EXTERN(void) git_transaction_free(git_transaction *tx);
 
+/** @} */
 GIT_END_DECL
 #endif
diff --git a/include/git2/version.h b/include/git2/version.h
index 66a6623cd..0df191f4f 100644
--- a/include/git2/version.h
+++ b/include/git2/version.h
@@ -7,12 +7,12 @@
 #ifndef INCLUDE_git_version_h__
 #define INCLUDE_git_version_h__
 
-#define LIBGIT2_VERSION "0.24.0"
+#define LIBGIT2_VERSION "0.25.0"
 #define LIBGIT2_VER_MAJOR 0
-#define LIBGIT2_VER_MINOR 24
+#define LIBGIT2_VER_MINOR 25
 #define LIBGIT2_VER_REVISION 0
 #define LIBGIT2_VER_PATCH 0
 
-#define LIBGIT2_SOVERSION 24
+#define LIBGIT2_SOVERSION 25
 
 #endif