1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 4 * This file is part of libgit2, distributed under the GNU GPL v2 with 5 * a Linking Exception. For full terms see the included COPYING file. 6 */ 7 #ifndef INCLUDE_git_revparse_h__ 8 #define INCLUDE_git_revparse_h__ 9 10 #include "common.h" 11 #include "types.h" 12 13 /** 14 * @file git2/revparse.h 15 * @brief Git revision parsing routines 16 * @defgroup git_revparse Git revision parsing routines 17 * @ingroup Git 18 * @{ 19 */ 20 GIT_BEGIN_DECL 21 22 /** 23 * Find a single object, as specified by a revision string. 24 * 25 * See `man gitrevisions`, or 26 * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for 27 * information on the syntax accepted. 28 * 29 * The returned object should be released with `git_object_free` when no 30 * longer needed. 31 * 32 * @param out pointer to output object 33 * @param repo the repository to search in 34 * @param spec the textual specification for an object 35 * @return 0 on success, GIT_ENOTFOUND, GIT_EAMBIGUOUS, GIT_EINVALIDSPEC or an error code 36 */ 37 GIT_EXTERN(int) git_revparse_single( 38 git_object **out, git_repository *repo, const char *spec); 39 40 /** 41 * Find a single object and intermediate reference by a revision string. 42 * 43 * See `man gitrevisions`, or 44 * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for 45 * information on the syntax accepted. 46 * 47 * In some cases (`@{<-n>}` or `<branchname>@{upstream}`), the expression may 48 * point to an intermediate reference. When such expressions are being passed 49 * in, `reference_out` will be valued as well. 50 * 51 * The returned object should be released with `git_object_free` and the 52 * returned reference with `git_reference_free` when no longer needed. 53 * 54 * @param object_out pointer to output object 55 * @param reference_out pointer to output reference or NULL 56 * @param repo the repository to search in 57 * @param spec the textual specification for an object 58 * @return 0 on success, GIT_ENOTFOUND, GIT_EAMBIGUOUS, GIT_EINVALIDSPEC 59 * or an error code 60 */ 61 GIT_EXTERN(int) git_revparse_ext( 62 git_object **object_out, 63 git_reference **reference_out, 64 git_repository *repo, 65 const char *spec); 66 67 /** 68 * Revparse flags. These indicate the intended behavior of the spec passed to 69 * git_revparse. 70 */ 71 typedef enum { 72 /** The spec targeted a single object. */ 73 GIT_REVSPEC_SINGLE = 1 << 0, 74 /** The spec targeted a range of commits. */ 75 GIT_REVSPEC_RANGE = 1 << 1, 76 /** The spec used the '...' operator, which invokes special semantics. */ 77 GIT_REVSPEC_MERGE_BASE = 1 << 2, 78 } git_revspec_t; 79 80 /** 81 * Git Revision Spec: output of a `git_revparse` operation 82 */ 83 typedef struct { 84 /** The left element of the revspec; must be freed by the user */ 85 git_object *from; 86 /** The right element of the revspec; must be freed by the user */ 87 git_object *to; 88 /** The intent of the revspec (i.e. `git_revspec_mode_t` flags) */ 89 unsigned int flags; 90 } git_revspec; 91 92 /** 93 * Parse a revision string for `from`, `to`, and intent. 94 * 95 * See `man gitrevisions` or 96 * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for 97 * information on the syntax accepted. 98 * 99 * @param revspec Pointer to an user-allocated git_revspec struct where 100 * the result of the rev-parse will be stored 101 * @param repo the repository to search in 102 * @param spec the rev-parse spec to parse 103 * @return 0 on success, GIT_INVALIDSPEC, GIT_ENOTFOUND, GIT_EAMBIGUOUS or an error code 104 */ 105 GIT_EXTERN(int) git_revparse( 106 git_revspec *revspec, 107 git_repository *repo, 108 const char *spec); 109 110 111 /** @} */ 112 GIT_END_DECL 113 #endif 114