Merge pull request #4917 from libgit2/ethomson/giterr

Move `giterr` to `git_error`

7 files changed, 142 insertions, 54 deletions

diff --git a/include/git2/blame.h b/include/git2/blame.h
index cc9131718..eef863f9c 100644
--- a/include/git2/blame.h
+++ b/include/git2/blame.h
@@ -183,7 +183,7 @@ GIT_EXTERN(const git_blame_hunk*) git_blame_get_hunk_byline(
  * @param path path to file to consider
  * @param options options for the blame operation.  If NULL, this is treated as
  *                though GIT_BLAME_OPTIONS_INIT were passed.
- * @return 0 on success, or an error code. (use giterr_last for information
+ * @return 0 on success, or an error code. (use git_error_last for information
  *         about the error.)
  */
 GIT_EXTERN(int) git_blame_file(
@@ -207,7 +207,7 @@ GIT_EXTERN(int) git_blame_file(
  *                  from git_blame_file)
  * @param buffer the (possibly) modified contents of the file
  * @param buffer_len number of valid bytes in the buffer
- * @return 0 on success, or an error code. (use giterr_last for information
+ * @return 0 on success, or an error code. (use git_error_last for information
  *         about the error)
  */
 GIT_EXTERN(int) git_blame_buffer(
diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index 295363727..3fb3fc127 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -325,7 +325,7 @@ GIT_EXTERN(int) git_checkout_init_options(
  * @param opts specifies checkout options (may be NULL)
  * @return 0 on success, GIT_EUNBORNBRANCH if HEAD points to a non
  *         existing branch, non-zero value returned by `notify_cb`, or
- *         other error code < 0 (use giterr_last for error details)
+ *         other error code < 0 (use git_error_last for error details)
  */
 GIT_EXTERN(int) git_checkout_head(
 	git_repository *repo,
@@ -338,7 +338,7 @@ GIT_EXTERN(int) git_checkout_head(
  * @param index index to be checked out (or NULL to use repository index)
  * @param opts specifies checkout options (may be NULL)
  * @return 0 on success, non-zero return value from `notify_cb`, or error
- *         code < 0 (use giterr_last for error details)
+ *         code < 0 (use git_error_last for error details)
  */
 GIT_EXTERN(int) git_checkout_index(
 	git_repository *repo,
@@ -354,7 +354,7 @@ GIT_EXTERN(int) git_checkout_index(
  * the working directory (or NULL to use HEAD)
  * @param opts specifies checkout options (may be NULL)
  * @return 0 on success, non-zero return value from `notify_cb`, or error
- *         code < 0 (use giterr_last for error details)
+ *         code < 0 (use git_error_last for error details)
  */
 GIT_EXTERN(int) git_checkout_tree(
 	git_repository *repo,
diff --git a/include/git2/clone.h b/include/git2/clone.h
index 4a64aacd3..790a82832 100644
--- a/include/git2/clone.h
+++ b/include/git2/clone.h
@@ -196,7 +196,7 @@ GIT_EXTERN(int) git_clone_init_options(
  *        function works as though GIT_OPTIONS_INIT were passed.
  * @return 0 on success, any non-zero return value from a callback
  *         function, or a negative value to indicate an error (use
- *         `giterr_last` for a detailed error message)
+ *         `git_error_last` for a detailed error message)
  */
 GIT_EXTERN(int) git_clone(
 	git_repository **out,
diff --git a/include/git2/commit.h b/include/git2/commit.h
index 50f2fc963..7e0409cc7 100644
--- a/include/git2/commit.h
+++ b/include/git2/commit.h
@@ -296,8 +296,8 @@ GIT_EXTERN(int) git_commit_header_field(git_buf *out, const git_commit *commit,
  * Extract the signature from a commit
  *
  * If the id is not for a commit, the error class will be
- * `GITERR_INVALID`. If the commit does not have a signature, the
- * error class will be `GITERR_OBJECT`.
+ * `GIT_ERROR_INVALID`. If the commit does not have a signature, the
+ * error class will be `GIT_ERROR_OBJECT`.
  *
  * @param signature the signature block; existing content will be
  * overwritten
diff --git a/include/git2/errors.h b/include/git2/errors.h
index 2c0ac1c71..f00385b8c 100644
--- a/include/git2/errors.h
+++ b/include/git2/errors.h
@@ -73,42 +73,48 @@ typedef struct {
 
 /** Error classes */
 typedef enum {
-	GITERR_NONE = 0,
-	GITERR_NOMEMORY,
-	GITERR_OS,
-	GITERR_INVALID,
-	GITERR_REFERENCE,
-	GITERR_ZLIB,
-	GITERR_REPOSITORY,
-	GITERR_CONFIG,
-	GITERR_REGEX,
-	GITERR_ODB,
-	GITERR_INDEX,
-	GITERR_OBJECT,
-	GITERR_NET,
-	GITERR_TAG,
-	GITERR_TREE,
-	GITERR_INDEXER,
-	GITERR_SSL,
-	GITERR_SUBMODULE,
-	GITERR_THREAD,
-	GITERR_STASH,
-	GITERR_CHECKOUT,
-	GITERR_FETCHHEAD,
-	GITERR_MERGE,
-	GITERR_SSH,
-	GITERR_FILTER,
-	GITERR_REVERT,
-	GITERR_CALLBACK,
-	GITERR_CHERRYPICK,
-	GITERR_DESCRIBE,
-	GITERR_REBASE,
-	GITERR_FILESYSTEM,
-	GITERR_PATCH,
-	GITERR_WORKTREE,
-	GITERR_SHA1
+	GIT_ERROR_NONE = 0,
+	GIT_ERROR_NOMEMORY,
+	GIT_ERROR_OS,
+	GIT_ERROR_INVALID,
+	GIT_ERROR_REFERENCE,
+	GIT_ERROR_ZLIB,
+	GIT_ERROR_REPOSITORY,
+	GIT_ERROR_CONFIG,
+	GIT_ERROR_REGEX,
+	GIT_ERROR_ODB,
+	GIT_ERROR_INDEX,
+	GIT_ERROR_OBJECT,
+	GIT_ERROR_NET,
+	GIT_ERROR_TAG,
+	GIT_ERROR_TREE,
+	GIT_ERROR_INDEXER,
+	GIT_ERROR_SSL,
+	GIT_ERROR_SUBMODULE,
+	GIT_ERROR_THREAD,
+	GIT_ERROR_STASH,
+	GIT_ERROR_CHECKOUT,
+	GIT_ERROR_FETCHHEAD,
+	GIT_ERROR_MERGE,
+	GIT_ERROR_SSH,
+	GIT_ERROR_FILTER,
+	GIT_ERROR_REVERT,
+	GIT_ERROR_CALLBACK,
+	GIT_ERROR_CHERRYPICK,
+	GIT_ERROR_DESCRIBE,
+	GIT_ERROR_REBASE,
+	GIT_ERROR_FILESYSTEM,
+	GIT_ERROR_PATCH,
+	GIT_ERROR_WORKTREE,
+	GIT_ERROR_SHA1
 } git_error_t;
 
+/** @name Error Functions
+ *
+ * These functions report or set error information.
+ */
+/**@{*/
+
 /**
  * Return the last `git_error` object that was generated for the
  * current thread.
@@ -120,12 +126,12 @@ typedef enum {
  *
  * @return A git_error object.
  */
-GIT_EXTERN(const git_error *) giterr_last(void);
+GIT_EXTERN(const git_error *) git_error_last(void);
 
 /**
  * Clear the last library error that occurred for this thread.
  */
-GIT_EXTERN(void) giterr_clear(void);
+GIT_EXTERN(void) git_error_clear(void);
 
 /**
  * Set the error message string for this thread.
@@ -143,18 +149,100 @@ GIT_EXTERN(void) giterr_clear(void);
  *                    general subsystem that is responsible for the error.
  * @param string The formatted error message to keep
  */
-GIT_EXTERN(void) giterr_set_str(int error_class, const char *string);
+GIT_EXTERN(void) git_error_set_str(int error_class, const char *string);
 
 /**
  * Set the error message to a special value for memory allocation failure.
  *
- * The normal `giterr_set_str()` function attempts to `strdup()` the string
- * that is passed in.  This is not a good idea when the error in question
- * is a memory allocation failure.  That circumstance has a special setter
- * function that sets the error string to a known and statically allocated
- * internal value.
+ * The normal `git_error_set_str()` function attempts to `strdup()` the
+ * string that is passed in.  This is not a good idea when the error in
+ * question is a memory allocation failure.  That circumstance has a
+ * special setter function that sets the error string to a known and
+ * statically allocated internal value.
+ */
+GIT_EXTERN(void) git_error_set_oom(void);
+
+/**@}*/
+
+/** @name Deprecated Error Functions
+ *
+ * These functions and enumeration values are retained for backward
+ * compatibility.  The newer versions of these functions should be
+ * preferred in all new code.
+ */
+/**@{*/
+
+GIT_DEPRECATED(static const int) GITERR_NONE = GIT_ERROR_NONE;
+GIT_DEPRECATED(static const int) GITERR_NOMEMORY = GIT_ERROR_NOMEMORY;
+GIT_DEPRECATED(static const int) GITERR_OS = GIT_ERROR_OS;
+GIT_DEPRECATED(static const int) GITERR_INVALID = GIT_ERROR_INVALID;
+GIT_DEPRECATED(static const int) GITERR_REFERENCE = GIT_ERROR_REFERENCE;
+GIT_DEPRECATED(static const int) GITERR_ZLIB = GIT_ERROR_ZLIB;
+GIT_DEPRECATED(static const int) GITERR_REPOSITORY = GIT_ERROR_REPOSITORY;
+GIT_DEPRECATED(static const int) GITERR_CONFIG = GIT_ERROR_CONFIG;
+GIT_DEPRECATED(static const int) GITERR_REGEX = GIT_ERROR_REGEX;
+GIT_DEPRECATED(static const int) GITERR_ODB = GIT_ERROR_ODB;
+GIT_DEPRECATED(static const int) GITERR_INDEX = GIT_ERROR_INDEX;
+GIT_DEPRECATED(static const int) GITERR_OBJECT = GIT_ERROR_OBJECT;
+GIT_DEPRECATED(static const int) GITERR_NET = GIT_ERROR_NET;
+GIT_DEPRECATED(static const int) GITERR_TAG = GIT_ERROR_TAG;
+GIT_DEPRECATED(static const int) GITERR_TREE = GIT_ERROR_TREE;
+GIT_DEPRECATED(static const int) GITERR_INDEXER = GIT_ERROR_INDEXER;
+GIT_DEPRECATED(static const int) GITERR_SSL = GIT_ERROR_SSL;
+GIT_DEPRECATED(static const int) GITERR_SUBMODULE = GIT_ERROR_SUBMODULE;
+GIT_DEPRECATED(static const int) GITERR_THREAD = GIT_ERROR_THREAD;
+GIT_DEPRECATED(static const int) GITERR_STASH = GIT_ERROR_STASH;
+GIT_DEPRECATED(static const int) GITERR_CHECKOUT = GIT_ERROR_CHECKOUT;
+GIT_DEPRECATED(static const int) GITERR_FETCHHEAD = GIT_ERROR_FETCHHEAD;
+GIT_DEPRECATED(static const int) GITERR_MERGE = GIT_ERROR_MERGE;
+GIT_DEPRECATED(static const int) GITERR_SSH = GIT_ERROR_SSH;
+GIT_DEPRECATED(static const int) GITERR_FILTER = GIT_ERROR_FILTER;
+GIT_DEPRECATED(static const int) GITERR_REVERT = GIT_ERROR_REVERT;
+GIT_DEPRECATED(static const int) GITERR_CALLBACK = GIT_ERROR_CALLBACK;
+GIT_DEPRECATED(static const int) GITERR_CHERRYPICK = GIT_ERROR_CHERRYPICK;
+GIT_DEPRECATED(static const int) GITERR_DESCRIBE = GIT_ERROR_DESCRIBE;
+GIT_DEPRECATED(static const int) GITERR_REBASE = GIT_ERROR_REBASE;
+GIT_DEPRECATED(static const int) GITERR_FILESYSTEM = GIT_ERROR_FILESYSTEM;
+GIT_DEPRECATED(static const int) GITERR_PATCH = GIT_ERROR_PATCH;
+GIT_DEPRECATED(static const int) GITERR_WORKTREE = GIT_ERROR_WORKTREE;
+GIT_DEPRECATED(static const int) GITERR_SHA1 = GIT_ERROR_SHA1;
+
+/**
+ * Return the last `git_error` object that was generated for the
+ * current thread.  This function is deprecated and will be removed
+ * in a future release; `git_error_last` should be used instead.
+ *
+ * @see git_error_last
  */
-GIT_EXTERN(void) giterr_set_oom(void);
+GIT_DEPRECATED(GIT_EXTERN(const git_error *)) giterr_last(void);
+
+/**
+ * Clear the last error.  This function is deprecated and will be
+ * removed in a future release; `giterr_clear` should be used instead.
+ *
+ * @see git_error_last
+ */
+GIT_DEPRECATED(GIT_EXTERN(void)) giterr_clear(void);
+
+/**
+ * Sets the error message to the given string.  This function is
+ * deprecated and will be removed in a future release; `giterr_clear`
+ * should be used instead.
+ *
+ * @see git_error_set_str
+ */
+GIT_DEPRECATED(GIT_EXTERN(void)) giterr_set_str(int error_class, const char *string);
+
+/**
+ * Indicates that an out-of-memory situation occured.  This function
+ * is deprecated and will be removed in a future release; `giterr_clear`
+ * should be used instead.
+ *
+ * @see git_error_set_oom
+ */
+GIT_DEPRECATED(GIT_EXTERN(void)) giterr_set_oom(void);
+
+/**@}*/
 
 /** @} */
 GIT_END_DECL
diff --git a/include/git2/oid.h b/include/git2/oid.h
index aaa678cc0..7e071bac7 100644
--- a/include/git2/oid.h
+++ b/include/git2/oid.h
@@ -246,7 +246,7 @@ GIT_EXTERN(git_oid_shorten *) git_oid_shorten_new(size_t min_length);
  * memory-efficient.
  *
  * Attempting to add more than those OIDs will result in a
- * GITERR_INVALID error
+ * GIT_ERROR_INVALID error
  *
  * @param os a `git_oid_shorten` instance
  * @param text_id an OID in text form
diff --git a/include/git2/submodule.h b/include/git2/submodule.h
index ac6344ec6..efb3b75d6 100644
--- a/include/git2/submodule.h
+++ b/include/git2/submodule.h
@@ -133,7 +133,7 @@ typedef struct git_submodule_update_options {
 	 * checkout, set the `checkout_strategy` to
 	 * `GIT_CHECKOUT_NONE`. Generally you will want the use
 	 * GIT_CHECKOUT_SAFE to update files in the working
-	 * directory. 
+	 * directory.
 	 */
 	git_checkout_options checkout_opts;
 
@@ -187,7 +187,7 @@ GIT_EXTERN(int) git_submodule_update_init_options(
  *        function works as though GIT_SUBMODULE_UPDATE_OPTIONS_INIT was passed.
  * @return 0 on success, any non-zero return value from a callback
  *         function, or a negative value to indicate an error (use
- *         `giterr_last` for a detailed error message).
+ *         `git_error_last` for a detailed error message).
  */
 GIT_EXTERN(int) git_submodule_update(git_submodule *submodule, int init, git_submodule_update_options *options);