Add giterr_detach API to get and clear error

There are a number of cases where it is convenient to be able to
fetch and "claim" the current error string, clearing the error.
This is helpful when you need to call some code that may alter
the error and you want to restore it later on and/or report it via
some other mechanism.

1 files changed, 17 insertions, 0 deletions

diff --git a/include/git2/errors.h b/include/git2/errors.h
index a454ac956..5f5d0ab1f 100644
--- a/include/git2/errors.h
+++ b/include/git2/errors.h
@@ -8,6 +8,7 @@
 #define INCLUDE_git_errors_h__
 
 #include "common.h"
+#include "buffer.h"
 
 /**
  * @file git2/errors.h
@@ -45,6 +46,7 @@ typedef struct {
 
 /** Error classes */
 typedef enum {
+	GITERR_NONE = 0,
 	GITERR_NOMEMORY,
 	GITERR_OS,
 	GITERR_INVALID,
@@ -85,6 +87,21 @@ GIT_EXTERN(const git_error *) giterr_last(void);
 GIT_EXTERN(void) giterr_clear(void);
 
 /**
+ * Get the last error data and clear it.
+ *
+ * This copies the last error message into the given `git_buf` and returns
+ * the associated `git_error_t`, leaving the error cleared as if
+ * `giterr_clear` had been called.  You must call `git_buf_free` on the
+ * message to release the memory.
+ *
+ * Note: it is possible that this will return `GITERR_NONE` and set the
+ * buffer to NULL, so be prepared for that condition.  Also, if the last
+ * error was an out-of-memory error, this will return `GITERR_NOMEMORY`
+ * but also leave the buffer set to NULL (to avoid allocation).
+ */
+GIT_EXTERN(git_error_t) giterr_detach(git_buf *message);
+
+/**
  * Set the error message string for this thread.
  *
  * This function is public so that custom ODB backends and the like can