Update iterators for consistency across library

This updates all the `foreach()` type functions across the library
that take callbacks from the user to have a consistent behavior.
The rules are:

* A callback terminates the loop by returning any non-zero value
* Once the callback returns non-zero, it will not be called again
  (i.e. the loop stops all iteration regardless of state)
* If the callback returns non-zero, the parent fn returns GIT_EUSER
* Although the parent returns GIT_EUSER, no error will be set in
  the library and `giterr_last()` will return NULL if called.

This commit makes those changes across the library and adds tests
for most of the iteration APIs to make sure that they follow the
above rules.

10 files changed, 56 insertions, 29 deletions

diff --git a/include/git2/attr.h b/include/git2/attr.h
index fad7183da..73a625a7e 100644
--- a/include/git2/attr.h
+++ b/include/git2/attr.h
@@ -172,18 +172,17 @@ GIT_EXTERN(int) git_attr_get_many(
  *
  * @param repo The repository containing the path.
  * @param flags A combination of GIT_ATTR_CHECK... flags.
- * @param path The path inside the repo to check attributes.  This
- *             does not have to exist, but if it does not, then
- *             it will be treated as a plain file (i.e. not a directory).
- * @param callback The function that will be invoked on each attribute
- *             and attribute value.  The name parameter will be the name
- *             of the attribute and the value will be the value it is
- *             set to, including possibly NULL if the attribute is
- *             explicitly set to UNSPECIFIED using the ! sign.  This
- *             will be invoked only once per attribute name, even if
- *             there are multiple rules for a given file.  The highest
- *             priority rule will be used.
+ * @param path Path inside the repo to check attributes.  This does not have
+ *             to exist, but if it does not, then it will be treated as a
+ *             plain file (i.e. not a directory).
+ * @param callback Function to invoke on each attribute name and value.  The
+ *             value may be NULL is the attribute is explicitly set to
+ *             UNSPECIFIED using the '!' sign.  Callback will be invoked
+ *             only once per attribute name, even if there are multiple
+ *             rules for a given file.  The highest priority rule will be
+ *             used.  Return a non-zero value from this to stop looping.
  * @param payload Passed on as extra parameter to callback function.
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_attr_foreach(
 	git_repository *repo,
diff --git a/include/git2/branch.h b/include/git2/branch.h
index 8884df15a..c8f2d8f5f 100644
--- a/include/git2/branch.h
+++ b/include/git2/branch.h
@@ -74,6 +74,8 @@ GIT_EXTERN(int) git_branch_delete(
 /**
  * Loop over all the branches and issue a callback for each one.
  *
+ * If the callback returns a non-zero value, this will stop looping.
+ *
  * @param repo Repository where to find the branches.
  *
  * @param list_flags Filtering flags for the branch
@@ -84,7 +86,7 @@ GIT_EXTERN(int) git_branch_delete(
  *
  * @param payload Extra parameter to callback function.
  *
- * @return 0 or an error code.
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_branch_foreach(
 		git_repository *repo,
diff --git a/include/git2/config.h b/include/git2/config.h
index c46e7fc9d..8a36885c7 100644
--- a/include/git2/config.h
+++ b/include/git2/config.h
@@ -302,12 +302,12 @@ GIT_EXTERN(int) git_config_delete(git_config *cfg, const char *name);
  * The callback receives the normalized name and value of each variable
  * in the config backend, and the data pointer passed to this function.
  * As soon as one of the callback functions returns something other than 0,
- * this function returns that value.
+ * this function stops iterating and returns `GIT_EUSER`.
  *
  * @param cfg where to get the variables from
  * @param callback the function to call on each variable
  * @param payload the data to pass to the callback
- * @return 0 or the return value of the callback which didn't return 0
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_config_foreach(
 	git_config *cfg,
diff --git a/include/git2/diff.h b/include/git2/diff.h
index 85727d969..79ef7a49b 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -332,6 +332,9 @@ GIT_EXTERN(int) git_diff_merge(
  * callbacks will not be invoked for binary files on the diff list or for
  * files whose only changed is a file mode change.
  *
+ * Returning a non-zero value from any of the callbacks will terminate
+ * the iteration and cause this return `GIT_EUSER`.
+ *
  * @param diff A git_diff_list generated by one of the above functions.
  * @param cb_data Reference pointer that will be passed to your callbacks.
  * @param file_cb Callback function to make per file in the diff.
@@ -341,6 +344,7 @@ GIT_EXTERN(int) git_diff_merge(
  * @param line_cb Optional callback to make per line of diff text.  This
  *                same callback will be made for context lines, added, and
  *                removed lines, and even for a deleted trailing newline.
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_diff_foreach(
 	git_diff_list *diff,
@@ -351,6 +355,14 @@ GIT_EXTERN(int) git_diff_foreach(
 
 /**
  * Iterate over a diff generating text output like "git diff --name-status".
+ *
+ * Returning a non-zero value from the callbacks will terminate the
+ * iteration and cause this return `GIT_EUSER`.
+ *
+ * @param diff A git_diff_list generated by one of the above functions.
+ * @param cb_data Reference pointer that will be passed to your callback.
+ * @param print_cb Callback to make per line of diff text.
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_diff_print_compact(
 	git_diff_list *diff,
@@ -362,6 +374,9 @@ GIT_EXTERN(int) git_diff_print_compact(
  *
  * This is a super easy way to generate a patch from a diff.
  *
+ * Returning a non-zero value from the callbacks will terminate the
+ * iteration and cause this return `GIT_EUSER`.
+ *
  * @param diff A git_diff_list generated by one of the above functions.
  * @param cb_data Reference pointer that will be passed to your callbacks.
  * @param print_cb Callback function to output lines of the diff.  This
@@ -369,6 +384,7 @@ GIT_EXTERN(int) git_diff_print_compact(
  *                 headers, and diff lines.  Fortunately, you can probably
  *                 use various GIT_DIFF_LINE constants to determine what
  *                 text you are given.
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_diff_print_patch(
 	git_diff_list *diff,
@@ -393,6 +409,8 @@ GIT_EXTERN(int) git_diff_print_patch(
  * When at least one of the blobs being dealt with is binary, the
  * `git_diff_delta` binary attribute will be set to 1 and no call to the
  * hunk_cb nor line_cb will be made.
+ *
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_diff_blobs(
 	git_blob *old_blob,
diff --git a/include/git2/errors.h b/include/git2/errors.h
index ca7f0de6e..2ab1da403 100644
--- a/include/git2/errors.h
+++ b/include/git2/errors.h
@@ -25,6 +25,7 @@ enum {
 	GIT_EEXISTS = -4,
 	GIT_EAMBIGUOUS = -5,
 	GIT_EBUFS = -6,
+	GIT_EUSER = -7,
 
 	GIT_PASSTHROUGH = -30,
 	GIT_REVWALKOVER = -31,
diff --git a/include/git2/notes.h b/include/git2/notes.h
index 19073abd1..b4839bec3 100644
--- a/include/git2/notes.h
+++ b/include/git2/notes.h
@@ -119,19 +119,21 @@ typedef struct {
  *
  * @param repo Repository where to find the notes.
  *
- * @param notes_ref OID reference to read from (optional); defaults to "refs/notes/commits".
+ * @param notes_ref OID reference to read from (optional); defaults to
+ *        "refs/notes/commits".
  *
- * @param note_cb Callback to invoke per found annotation.
+ * @param note_cb Callback to invoke per found annotation.  Return non-zero
+ *        to stop looping.
  *
  * @param payload Extra parameter to callback function.
  *
- * @return 0 or an error code.
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_note_foreach(
-		git_repository *repo,
-		const char *notes_ref,
-		int (*note_cb)(git_note_data *note_data, void *payload),
-		void *payload
+	git_repository *repo,
+	const char *notes_ref,
+	int (*note_cb)(git_note_data *note_data, void *payload),
+	void *payload
 );
 
 /** @} */
diff --git a/include/git2/odb.h b/include/git2/odb.h
index dac9e06a9..1f25db463 100644
--- a/include/git2/odb.h
+++ b/include/git2/odb.h
@@ -176,13 +176,14 @@ GIT_EXTERN(int) git_odb_exists(git_odb *db, const git_oid *id);
  * List all objects available in the database
  *
  * The callback will be called for each object available in the
- * database. Note that the objects are likely to be returned in the
- * index order, which would make accessing the objects in that order
- * inefficient.
+ * database. Note that the objects are likely to be returned in the index
+ * order, which would make accessing the objects in that order inefficient.
+ * Return a non-zero value from the callback to stop looping.
  *
  * @param db database to use
  * @param cb the callback to call for each object
  * @param data data to pass to the callback
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_odb_foreach(git_odb *db, int (*cb)(git_oid *oid, void *data), void *data);
 
diff --git a/include/git2/refs.h b/include/git2/refs.h
index b119e90b1..dbd9b7151 100644
--- a/include/git2/refs.h
+++ b/include/git2/refs.h
@@ -268,14 +268,15 @@ GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo, un
  *
  * The `callback` function will be called for each of the references
  * in the repository, and will receive the name of the reference and
- * the `payload` value passed to this method.
+ * the `payload` value passed to this method.  Returning a non-zero
+ * value from the callback will terminate the iteration.
  *
  * @param repo Repository where to find the refs
  * @param list_flags Filtering flags for the reference
  *		listing.
  * @param callback Function which will be called for every listed ref
  * @param payload Additional data to pass to the callback
- * @return 0 or an error code
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload);
 
diff --git a/include/git2/remote.h b/include/git2/remote.h
index 5c01949d2..02b93e099 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -133,9 +133,12 @@ GIT_EXTERN(int) git_remote_connect(git_remote *remote, int direction);
  * The remote (or more exactly its transport) must be connected. The
  * memory belongs to the remote.
  *
+ * If you a return a non-zero value from the callback, this will stop
+ * looping over the refs.
+ *
  * @param refs where to store the refs
  * @param remote the remote
- * @return 0 or an error code
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_remote_ls(git_remote *remote, git_headlist_cb list_cb, void *payload);
 
diff --git a/include/git2/status.h b/include/git2/status.h
index 9e7b5de4a..cc94d7680 100644
--- a/include/git2/status.h
+++ b/include/git2/status.h
@@ -38,11 +38,11 @@ enum {
  *
  * The callback is passed the path of the file, the status and the data
  * pointer passed to this function. If the callback returns something other
- * than 0, this function will return that value.
+ * than 0, this function will stop looping and return GIT_EUSER.
  *
  * @param repo a repository object
  * @param callback the function to call on each file
- * @return 0 on success or the return value of the callback that was non-zero
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_status_foreach(
 	git_repository *repo,