Merge pull request libgit2#4917 from libgit2/ethomson/giterr

Move `giterr` to `git_error`

Author: ethomson

docs/conventions.md

@@ -136,11 +136,11 @@ Check
 [`include/git2/errors.h`](https://github.com/libgit2/libgit2/blob/development/include/git2/errors.h)
 for the return codes already defined.
 
-In your implementation, use `giterr_set()` to provide extended error
+In your implementation, use `git_error_set()` to provide extended error
 information to callers.
 
 If a `libgit2` function internally invokes another function that reports an
-error, but the error is not propagated up, use `giterr_clear()` to prevent
+error, but the error is not propagated up, use `git_error_clear()` to prevent
 callers from getting the wrong error message later on.
 
 

docs/error-handling.md

@@ -9,7 +9,7 @@ and a generic error code (-1) for all critical or non-specific failures
 (e.g. running out of memory or system corruption).
 
 When a negative value is returned, an error message is also set.  The
-message can be accessed via the `giterr_last` function which will return a
+message can be accessed via the `git_error_last` function which will return a
 pointer to a `git_error` structure containing the error message text and
 the class of error (i.e. what part of the library generated the error).
 
@@ -51,7 +51,7 @@ look at the error message that was generated.
 	int error = git_repository_open(&repo, "path/to/repo");
 
 	if (error < 0) {
-		fprintf(stderr, "Could not open repository: %s\n", giterr_last()->message);
+		fprintf(stderr, "Could not open repository: %s\n", git_error_last()->message);
 		exit(1);
 	}
 
@@ -75,7 +75,7 @@ at the specific error values to decide what to do.
 			fprintf(stderr, "Could not find repository at path '%s'\n", path);
 		else
 			fprintf(stderr, "Unable to open repository: %s\n",
-				giterr_last()->message);
+				git_error_last()->message);
 		exit(1);
 	}
 
@@ -86,7 +86,7 @@ at the specific error values to decide what to do.
 Some of the higher-level language bindings may use a range of information
 from libgit2 to convert error return codes into exceptions, including the
 specific error return codes and even the class of error and the error
-message returned by `giterr_last`, but the full range of that logic is
+message returned by `git_error_last`, but the full range of that logic is
 beyond the scope of this document.
 
 Example internal implementation
@@ -102,7 +102,7 @@ int git_repository_open(git_repository **repository, const char *path)
 {
 	/* perform some logic to open the repository */
 	if (p_exists(path) < 0) {
-		giterr_set(GITERR_REPOSITORY, "The path '%s' doesn't exist", path);
+		git_error_set(GIT_ERROR_REPOSITORY, "The path '%s' doesn't exist", path);
 		return GIT_ENOTFOUND;
 	}
 
@@ -113,7 +113,7 @@ int git_repository_open(git_repository **repository, const char *path)
 The public error API
 --------------------
 
-- `const git_error *giterr_last(void)`: The main function used to look up
+- `const git_error *git_error_last(void)`: The main function used to look up
   the last error.  This may return NULL if no error has occurred.
   Otherwise this should return a `git_error` object indicating the class
   of error and the error message that was generated by the library.
@@ -133,22 +133,22 @@ The public error API
   bugs, but in the meantime, please code defensively and check for NULL
   when calling this function.
 
-- `void giterr_clear(void)`: This function clears the last error.  The
+- `void git_error_clear(void)`: This function clears the last error.  The
   library will call this when an error is generated by low level function
   and the higher level function handles the error.
 
   _Note_ There are some known bugs in the library where a low level
   function's error message is not cleared by higher level code that
   handles the error and returns zero.  Please report these as bugs, but in
   the meantime, a zero return value from a libgit2 API does not guarantee
-  that `giterr_last()` will return NULL.
+  that `git_error_last()` will return NULL.
 
-- `void giterr_set_str(int error_class, const char *message)`: This
+- `void git_error_set(int error_class, const char *message)`: This
   function can be used when writing a custom backend module to set the
   libgit2 error message.  See the documentation on this function for its
   use.  Normal usage of libgit2 will probably never need to call this API.
 
-- `void giterr_set_oom(void)`: This is a standard function for reporting
+- `void git_error_set_oom(void)`: This is a standard function for reporting
   an out-of-memory error.  It is written in a manner that it doesn't have
   to allocate any extra memory in order to record the error, so this is
   the best way to report that scenario.
@@ -182,18 +182,18 @@ There are some known bugs in the library where some functions may return a
 negative value but not set an error message and some other functions may
 return zero (no error) and yet leave an error message set.  Please report
 these cases as issues and they will be fixed.  In the meanwhile, please
-code defensively, checking that the return value of `giterr_last` is not
-NULL before using it, and not relying on `giterr_last` to return NULL when
+code defensively, checking that the return value of `git_error_last` is not
+NULL before using it, and not relying on `git_error_last` to return NULL when
 a function returns 0 for success.
 
 The internal error API
 ----------------------
 
-- `void giterr_set(int error_class, const char *fmt, ...)`: This is the
+- `void git_error_set(int error_class, const char *fmt, ...)`: This is the
   main internal function for setting an error.  It works like `printf` to
-  format the error message.  See the notes of `giterr_set_str` for a
+  format the error message.  See the notes of `git_error_set_str` for a
   general description of how error messages are stored (and also about
-  special handling for `error_class` of `GITERR_OS`).
+  special handling for `error_class` of `GIT_ERROR_OS`).
 
 Writing error messages
 ----------------------
@@ -248,7 +248,7 @@ General guidelines for error reporting
 		...
 
 		if (git_commit_lookup(parent, repo, parent_id) < 0) {
-			giterr_set(GITERR_COMMIT, "Overwrite lookup error message");
+			git_error_set(GIT_ERROR_COMMIT, "Overwrite lookup error message");
 			return -1; /* mask error code */
 		}
 

docs/threading.md

@@ -22,7 +22,7 @@ snapshots.
 Error messages
 --------------
 
-The error message is thread-local. The `giterr_last()` call must
+The error message is thread-local. The `git_error_last()` call must
 happen on the same thread as the error in order to get the
 message. Often this will be the case regardless, but if you use
 something like the [GCD](http://en.wikipedia.org/wiki/Grand_Central_Dispatch)

examples/checkout.c

@@ -132,20 +132,20 @@ static int perform_checkout_ref(git_repository *repo, git_annotated_commit *targ
 	/** Grab the commit we're interested to move to */
 	err = git_commit_lookup(&target_commit, repo, git_annotated_commit_id(target));
 	if (err != 0) {
-		fprintf(stderr, "failed to lookup commit: %s\n", giterr_last()->message);
+		fprintf(stderr, "failed to lookup commit: %s\n", git_error_last()->message);
 		goto cleanup;
 	}
 
 	/**
 	 * Perform the checkout so the workdir corresponds to what target_commit
 	 * contains.
 	 *
-	 * Note that it's okay to pass a git_commit here, because it will be 
+	 * Note that it's okay to pass a git_commit here, because it will be
 	 * peeled to a tree.
 	 */
 	err = git_checkout_tree(repo, (const git_object *)target_commit, &checkout_opts);
 	if (err != 0) {
-		fprintf(stderr, "failed to checkout tree: %s\n", giterr_last()->message);
+		fprintf(stderr, "failed to checkout tree: %s\n", git_error_last()->message);
 		goto cleanup;
 	}
 
@@ -161,7 +161,7 @@ static int perform_checkout_ref(git_repository *repo, git_annotated_commit *targ
 		err = git_repository_set_head_detached_from_annotated(repo, target);
 	}
 	if (err != 0) {
-		fprintf(stderr, "failed to update HEAD reference: %s\n", giterr_last()->message);
+		fprintf(stderr, "failed to update HEAD reference: %s\n", git_error_last()->message);
 		goto cleanup;
 	}
 
@@ -219,7 +219,7 @@ int main(int argc, char **argv)
 		 */
 		err = resolve_refish(&checkout_target, repo, args.argv[args.pos]);
 		if (err != 0) {
-			fprintf(stderr, "failed to resolve %s: %s\n", args.argv[args.pos], giterr_last()->message);
+			fprintf(stderr, "failed to resolve %s: %s\n", args.argv[args.pos], git_error_last()->message);
 			goto cleanup;
 		}
 		err = perform_checkout_ref(repo, checkout_target, &opts);

examples/common.c

@@ -24,7 +24,7 @@ void check_lg2(int error, const char *message, const char *extra)
 	if (!error)
 		return;
 
-	if ((lg2err = giterr_last()) != NULL && lg2err->message != NULL) {
+	if ((lg2err = git_error_last()) != NULL && lg2err->message != NULL) {
 		lg2msg = lg2err->message;
 		lg2spacer = " - ";
 	}

examples/general.c

@@ -66,7 +66,7 @@ static void config_files(const char *repo_path, git_repository *repo);
  */
 static void check_error(int error_code, const char *action)
 {
-	const git_error *error = giterr_last();
+	const git_error *error = git_error_last();
 	if (!error_code)
 		return;
 

examples/merge.c

@@ -96,7 +96,7 @@ static int resolve_heads(git_repository *repo, merge_options *opts)
 	for (i = 0; i < opts->heads_count; i++) {
 		err = resolve_refish(&annotated[annotated_count++], repo, opts->heads[i]);
 		if (err != 0) {
-			fprintf(stderr, "failed to resolve refish %s: %s\n", opts->heads[i], giterr_last()->message);
+			fprintf(stderr, "failed to resolve refish %s: %s\n", opts->heads[i], git_error_last()->message);
 			annotated_count--;
 			continue;
 		}
@@ -229,7 +229,7 @@ static int create_merge_commit(git_repository *repo, git_index *index, merge_opt
 
 	/* Maybe that's a ref, so DWIM it */
 	err = git_reference_dwim(&merge_ref, repo, opts->heads[0]);
-	check_lg2(err, "failed to DWIM reference", giterr_last()->message);
+	check_lg2(err, "failed to DWIM reference", git_error_last()->message);
 
 	/* Grab a signature */
 	check_lg2(git_signature_now(&sign, "Me", "me@example.com"), "failed to create signature", NULL);

examples/network/clone.c

@@ -104,7 +104,7 @@ int do_clone(git_repository *repo, int argc, char **argv)
 	error = git_clone(&cloned_repo, url, path, &clone_opts);
 	printf("\n");
 	if (error != 0) {
-		const git_error *err = giterr_last();
+		const git_error *err = git_error_last();
 		if (err) printf("ERROR %d: %s\n", err->klass, err->message);
 		else printf("ERROR %d: no detailed info\n", error);
 	}

examples/network/git2.c

@@ -26,10 +26,10 @@ static int run_command(git_cb fn, git_repository *repo, struct args_info args)
 	/* Run the command. If something goes wrong, print the error message to stderr */
 	error = fn(repo, args.argc - args.pos, &args.argv[args.pos]);
 	if (error < 0) {
-		if (giterr_last() == NULL)
+		if (git_error_last() == NULL)
 			fprintf(stderr, "Error without message");
 		else
-			fprintf(stderr, "Bad news:\n %s\n", giterr_last()->message);
+			fprintf(stderr, "Bad news:\n %s\n", git_error_last()->message);
 	}
 
 	return !!error;

fuzzers/download_refs_fuzzer.c

@@ -158,7 +158,7 @@ int fuzzer_transport_cb(git_transport **out, git_remote *owner, void *param)
 
 void fuzzer_git_abort(const char *op)
 {
-	const git_error *err = giterr_last();
+	const git_error *err = git_error_last();
 	fprintf(stderr, "unexpected libgit error: %s: %s\n",
 		op, err ? err->message : "<none>");
 	abort();