git_error: use full class name in public error API

Move to the `git_error` name in error-related functions, deprecating the
`giterr` functions.  This means, for example, that `giterr_last` is now
`git_error_last`.  The old names are retained for compatibility.

This only updates the public API; internal API and function usage
remains unchanged.

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(

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,

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,

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

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.
+ */
+/**@{*/
+
+#define GITERR_NONE GIT_ERROR_NONE
+#define GITERR_NOMEMORY GIT_ERROR_NOMEMORY
+#define GITERR_OS GIT_ERROR_OS
+#define GITERR_INVALID GIT_ERROR_INVALID
+#define GITERR_REFERENCE GIT_ERROR_REFERENCE
+#define GITERR_ZLIB GIT_ERROR_ZLIB
+#define GITERR_REPOSITORY GIT_ERROR_REPOSITORY
+#define GITERR_CONFIG GIT_ERROR_CONFIG
+#define GITERR_REGEX GIT_ERROR_REGEX
+#define GITERR_ODB GIT_ERROR_ODB
+#define GITERR_INDEX GIT_ERROR_INDEX
+#define GITERR_OBJECT GIT_ERROR_OBJECT
+#define GITERR_NET GIT_ERROR_NET
+#define GITERR_TAG GIT_ERROR_TAG
+#define GITERR_TREE GIT_ERROR_TREE
+#define GITERR_INDEXER GIT_ERROR_INDEXER
+#define GITERR_SSL GIT_ERROR_SSL
+#define GITERR_SUBMODULE GIT_ERROR_SUBMODULE
+#define GITERR_THREAD GIT_ERROR_THREAD
+#define GITERR_STASH GIT_ERROR_STASH
+#define GITERR_CHECKOUT GIT_ERROR_CHECKOUT
+#define GITERR_FETCHHEAD GIT_ERROR_FETCHHEAD
+#define GITERR_MERGE GIT_ERROR_MERGE
+#define GITERR_SSH GIT_ERROR_SSH
+#define GITERR_FILTER GIT_ERROR_FILTER
+#define GITERR_REVERT GIT_ERROR_REVERT
+#define GITERR_CALLBACK GIT_ERROR_CALLBACK
+#define GITERR_CHERRYPICK GIT_ERROR_CHERRYPICK
+#define GITERR_DESCRIBE GIT_ERROR_DESCRIBE
+#define GITERR_REBASE GIT_ERROR_REBASE
+#define GITERR_FILESYSTEM GIT_ERROR_FILESYSTEM
+#define GITERR_PATCH GIT_ERROR_PATCH
+#define GITERR_WORKTREE GIT_ERROR_WORKTREE
+#define 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

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

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

src/errors.c

@@ -44,7 +44,7 @@ static void set_error(int error_class, char *string)
 	set_error_from_buffer(error_class);
 }
 
-void giterr_set_oom(void)
+void git_error_set_oom(void)
 {
 	GIT_GLOBAL->last_error = &g_git_oom_error;
 }
@@ -90,7 +90,7 @@ void giterr_set(int error_class, const char *string, ...)
 		set_error_from_buffer(error_class);
 }
 
-void giterr_set_str(int error_class, const char *string)
+void git_error_set_str(int error_class, const char *string)
 {
 	git_buf *buf = &GIT_GLOBAL->error_buf;
 
@@ -120,7 +120,7 @@ int giterr_set_regex(const regex_t *regex, int error_code)
 	return GIT_EINVALIDSPEC;
 }
 
-void giterr_clear(void)
+void git_error_clear(void)
 {
 	if (GIT_GLOBAL->last_error != NULL) {
 		set_error(0, NULL);
@@ -133,7 +133,7 @@ void giterr_clear(void)
 #endif
 }
 
-const git_error *giterr_last(void)
+const git_error *git_error_last(void)
 {
 	return GIT_GLOBAL->last_error;
 }
@@ -211,3 +211,25 @@ void giterr_system_set(int code)
 	errno = code;
 #endif
 }
+
+/* Deprecated functions */
+
+const git_error *giterr_last(void)
+{
+	return git_error_last();
+}
+
+void giterr_clear(void)
+{
+	git_error_clear();
+}
+
+void giterr_set_str(int error_class, const char *string)
+{
+	return git_error_set_str(error_class, string);
+}
+
+void giterr_set_oom(void)
+{
+	git_error_set_oom();
+}