Merge pull request #4773 from RandomSort/giterr

Document giterr_last() use only after error. #4772

docs/error-handling.md

@@ -117,6 +117,11 @@ The public error API
   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.
+  Do not use this function unless the prior call to a libgit2 API
+  returned an error, as it can otherwise give misleading results.
+  libgit2's error strings are not cleared aggressively, 
+  and this function may return an error string that reflects a prior error,
+  possibly even reflecting internal state.
 
   The last error is stored in thread-local storage when libgit2 is
   compiled with thread support, so you do not have to worry about another

include/git2/errors.h

@@ -109,7 +109,12 @@ typedef enum {
 
 /**
  * Return the last `git_error` object that was generated for the
- * current thread or NULL if no error has occurred.
+ * current thread.
+ *
+ * The default behaviour of this function is to return NULL if no previous error has occurred.
+ * However, libgit2's error strings are not cleared aggressively, so a prior
+ * (unrelated) error may be returned. This can be avoided by only calling
+ * this function if the prior call to a libgit2 API returned an error.
  *
  * @return A git_error object.
  */