include/git2/revparse.h

   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_REVPARSE_SINGLE         = 1 << 0,
  74         /** The spec targeted a range of commits. */
  75         GIT_REVPARSE_RANGE          = 1 << 1,
  76         /** The spec used the '...' operator, which invokes special semantics. */
  77         GIT_REVPARSE_MERGE_BASE     = 1 << 2,
  78 } git_revparse_mode_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_revparse_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