diff options
Diffstat (limited to 'include/git2')
| -rw-r--r-- | include/git2/attr.h | 21 | ||||
| -rw-r--r-- | include/git2/branch.h | 4 | ||||
| -rw-r--r-- | include/git2/config.h | 4 | ||||
| -rw-r--r-- | include/git2/diff.h | 18 | ||||
| -rw-r--r-- | include/git2/errors.h | 1 | ||||
| -rw-r--r-- | include/git2/notes.h | 16 | ||||
| -rw-r--r-- | include/git2/odb.h | 7 | ||||
| -rw-r--r-- | include/git2/refs.h | 5 | ||||
| -rw-r--r-- | include/git2/remote.h | 5 | ||||
| -rw-r--r-- | include/git2/status.h | 4 |
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, |