]>
Commit | Line | Data |
---|---|---|
ac250c56 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
ac250c56 BS |
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 | ||
bfc13e79 BS |
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 | */ | |
ac250c56 BS |
20 | GIT_BEGIN_DECL |
21 | ||
4291ad07 | 22 | /** |
b2d3efcb RB |
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 | |
4291ad07 BS |
27 | * information on the syntax accepted. |
28 | * | |
b2d3efcb RB |
29 | * The returned object should be released with `git_object_free` when no |
30 | * longer needed. | |
31 | * | |
4291ad07 BS |
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 | */ | |
b2d3efcb RB |
37 | GIT_EXTERN(int) git_revparse_single( |
38 | git_object **out, git_repository *repo, const char *spec); | |
4291ad07 | 39 | |
e841c533 | 40 | /** |
b2d3efcb RB |
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 | |
e841c533 | 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 | * | |
b2d3efcb RB |
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 | * | |
e841c533 | 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); | |
4d13d07a BS |
66 | |
67 | /** | |
68 | * Revparse flags. These indicate the intended behavior of the spec passed to | |
69 | * git_revparse. | |
70 | */ | |
71 | typedef enum { | |
8480eef7 | 72 | /** The spec targeted a single object. */ |
c25aa7cd | 73 | GIT_REVSPEC_SINGLE = 1 << 0, |
8480eef7 | 74 | /** The spec targeted a range of commits. */ |
c25aa7cd | 75 | GIT_REVSPEC_RANGE = 1 << 1, |
8480eef7 | 76 | /** The spec used the '...' operator, which invokes special semantics. */ |
c25aa7cd PP |
77 | GIT_REVSPEC_MERGE_BASE = 1 << 2, |
78 | } git_revspec_t; | |
4d13d07a | 79 | |
36c2dfed | 80 | /** |
e13a0647 | 81 | * Git Revision Spec: output of a `git_revparse` operation |
36c2dfed VM |
82 | */ |
83 | typedef struct { | |
e13a0647 | 84 | /** The left element of the revspec; must be freed by the user */ |
36c2dfed | 85 | git_object *from; |
e13a0647 | 86 | /** The right element of the revspec; must be freed by the user */ |
36c2dfed | 87 | git_object *to; |
c25aa7cd | 88 | /** The intent of the revspec (i.e. `git_revspec_mode_t` flags) */ |
36c2dfed | 89 | unsigned int flags; |
cbda09d0 | 90 | } git_revspec; |
4d13d07a BS |
91 | |
92 | /** | |
b2d3efcb RB |
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. | |
4d13d07a | 98 | * |
b2d3efcb RB |
99 | * @param revspec Pointer to an user-allocated git_revspec struct where |
100 | * the result of the rev-parse will be stored | |
4d13d07a BS |
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( | |
b2d3efcb RB |
106 | git_revspec *revspec, |
107 | git_repository *repo, | |
108 | const char *spec); | |
4d13d07a BS |
109 | |
110 | ||
bfc13e79 | 111 | /** @} */ |
ac250c56 | 112 | GIT_END_DECL |
ac250c56 | 113 | #endif |