diff options
Diffstat (limited to 'include/git2/revparse.h')
| -rw-r--r-- | include/git2/revparse.h | 43 |
1 files changed, 27 insertions, 16 deletions
diff --git a/include/git2/revparse.h b/include/git2/revparse.h index 786a9da57..d170e1621 100644 --- a/include/git2/revparse.h +++ b/include/git2/revparse.h @@ -10,7 +10,6 @@ #include "common.h" #include "types.h" - /** * @file git2/revparse.h * @brief Git revision parsing routines @@ -21,27 +20,37 @@ GIT_BEGIN_DECL /** - * Find a single object, as specified by a revision string. See `man gitrevisions`, - * or http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for + * Find a single object, as specified by a revision string. + * + * See `man gitrevisions`, or + * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for * information on the syntax accepted. * + * The returned object should be released with `git_object_free` when no + * longer needed. + * * @param out pointer to output object * @param repo the repository to search in * @param spec the textual specification for an object * @return 0 on success, GIT_ENOTFOUND, GIT_EAMBIGUOUS, GIT_EINVALIDSPEC or an error code */ -GIT_EXTERN(int) git_revparse_single(git_object **out, git_repository *repo, const char *spec); +GIT_EXTERN(int) git_revparse_single( + git_object **out, git_repository *repo, const char *spec); /** - * Find a single object, as specified by a revision string. - * See `man gitrevisions`, - * or http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for + * Find a single object and intermediate reference by a revision string. + * + * See `man gitrevisions`, or + * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for * information on the syntax accepted. * * In some cases (`@{<-n>}` or `<branchname>@{upstream}`), the expression may * point to an intermediate reference. When such expressions are being passed * in, `reference_out` will be valued as well. * + * The returned object should be released with `git_object_free` and the + * returned reference with `git_reference_free` when no longer needed. + * * @param object_out pointer to output object * @param reference_out pointer to output reference or NULL * @param repo the repository to search in @@ -76,25 +85,27 @@ typedef struct { git_object *from; /** The right element of the revspec; must be freed by the user */ git_object *to; - /** The intent of the revspec */ + /** The intent of the revspec (i.e. `git_revparse_mode_t` flags) */ unsigned int flags; } git_revspec; /** - * Parse a revision string for `from`, `to`, and intent. See `man gitrevisions` or - * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for information - * on the syntax accepted. + * Parse a revision string for `from`, `to`, and intent. + * + * See `man gitrevisions` or + * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for + * information on the syntax accepted. * - * @param revspec Pointer to an user-allocated git_revspec struct where the result - * of the rev-parse will be stored + * @param revspec Pointer to an user-allocated git_revspec struct where + * the result of the rev-parse will be stored * @param repo the repository to search in * @param spec the rev-parse spec to parse * @return 0 on success, GIT_INVALIDSPEC, GIT_ENOTFOUND, GIT_EAMBIGUOUS or an error code */ GIT_EXTERN(int) git_revparse( - git_revspec *revspec, - git_repository *repo, - const char *spec); + git_revspec *revspec, + git_repository *repo, + const char *spec); /** @} */ |