include/git2/describe.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_describe_h__
   8 #define INCLUDE_git_describe_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "buffer.h"
  13
  14 /**
  15  * @file git2/describe.h
  16  * @brief Git describing routines
  17  * @defgroup git_describe Git describing routines
  18  * @ingroup Git
  19  * @{
  20  */
  21 GIT_BEGIN_DECL
  22
  23 /**
  24  * Reference lookup strategy
  25  *
  26  * These behave like the --tags and --all options to git-describe,
  27  * namely they say to look for any reference in either refs/tags/ or
  28  * refs/ respectively.
  29  */
  30 typedef enum {
  31         GIT_DESCRIBE_DEFAULT,
  32         GIT_DESCRIBE_TAGS,
  33         GIT_DESCRIBE_ALL,
  34 } git_describe_strategy_t;
  35
  36 /**
  37  * Describe options structure
  38  *
  39  * Initialize with `GIT_DESCRIBE_OPTIONS_INIT`. Alternatively, you can
  40  * use `git_describe_options_init`.
  41  *
  42  */
  43 typedef struct git_describe_options {
  44         unsigned int version;
  45
  46         unsigned int max_candidates_tags; /**< default: 10 */
  47         unsigned int describe_strategy; /**< default: GIT_DESCRIBE_DEFAULT */
  48         const char *pattern;
  49         /**
  50          * When calculating the distance from the matching tag or
  51          * reference, only walk down the first-parent ancestry.
  52          */
  53         int only_follow_first_parent;
  54         /**
  55          * If no matching tag or reference is found, the describe
  56          * operation would normally fail. If this option is set, it
  57          * will instead fall back to showing the full id of the
  58          * commit.
  59          */
  60         int show_commit_oid_as_fallback;
  61 } git_describe_options;
  62
  63 #define GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS 10
  64 #define GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE 7
  65
  66 #define GIT_DESCRIBE_OPTIONS_VERSION 1
  67 #define GIT_DESCRIBE_OPTIONS_INIT { \
  68         GIT_DESCRIBE_OPTIONS_VERSION, \
  69         GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \
  70 }
  71
  72 /**
  73  * Initialize git_describe_options structure
  74  *
  75  * Initializes a `git_describe_options` with default values. Equivalent to creating
  76  * an instance with GIT_DESCRIBE_OPTIONS_INIT.
  77  *
  78  * @param opts The `git_describe_options` struct to initialize.
  79  * @param version The struct version; pass `GIT_DESCRIBE_OPTIONS_VERSION`.
  80  * @return Zero on success; -1 on failure.
  81  */
  82 GIT_EXTERN(int) git_describe_options_init(git_describe_options *opts, unsigned int version);
  83
  84 /**
  85  * Describe format options structure
  86  *
  87  * Initialize with `GIT_DESCRIBE_FORMAT_OPTIONS_INIT`. Alternatively, you can
  88  * use `git_describe_format_options_init`.
  89  *
  90  */
  91 typedef struct {
  92         unsigned int version;
  93
  94         /**
  95          * Size of the abbreviated commit id to use. This value is the
  96          * lower bound for the length of the abbreviated string. The
  97          * default is 7.
  98          */
  99         unsigned int abbreviated_size;
 100
 101         /**
 102          * Set to use the long format even when a shorter name could be used.
 103          */
 104         int always_use_long_format;
 105
 106         /**
 107          * If the workdir is dirty and this is set, this string will
 108          * be appended to the description string.
 109          */
 110         const char *dirty_suffix;
 111 } git_describe_format_options;
 112
 113 #define GIT_DESCRIBE_FORMAT_OPTIONS_VERSION 1
 114 #define GIT_DESCRIBE_FORMAT_OPTIONS_INIT { \
 115                 GIT_DESCRIBE_FORMAT_OPTIONS_VERSION,   \
 116                 GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \
 117  }
 118
 119 /**
 120  * Initialize git_describe_format_options structure
 121  *
 122  * Initializes a `git_describe_format_options` with default values. Equivalent to creating
 123  * an instance with GIT_DESCRIBE_FORMAT_OPTIONS_INIT.
 124  *
 125  * @param opts The `git_describe_format_options` struct to initialize.
 126  * @param version The struct version; pass `GIT_DESCRIBE_FORMAT_OPTIONS_VERSION`.
 127  * @return Zero on success; -1 on failure.
 128  */
 129 GIT_EXTERN(int) git_describe_format_options_init(git_describe_format_options *opts, unsigned int version);
 130
 131 /**
 132  * A struct that stores the result of a describe operation.
 133  */
 134 typedef struct git_describe_result git_describe_result;
 135
 136 /**
 137  * Describe a commit
 138  *
 139  * Perform the describe operation on the given committish object.
 140  *
 141  * @param result pointer to store the result. You must free this once
 142  * you're done with it.
 143  * @param committish a committish to describe
 144  * @param opts the lookup options (or NULL for defaults)
 145  */
 146 GIT_EXTERN(int) git_describe_commit(
 147         git_describe_result **result,
 148         git_object *committish,
 149         git_describe_options *opts);
 150
 151 /**
 152  * Describe a commit
 153  *
 154  * Perform the describe operation on the current commit and the
 155  * worktree. After peforming describe on HEAD, a status is run and the
 156  * description is considered to be dirty if there are.
 157  *
 158  * @param out pointer to store the result. You must free this once
 159  * you're done with it.
 160  * @param repo the repository in which to perform the describe
 161  * @param opts the lookup options (or NULL for defaults)
 162  */
 163 GIT_EXTERN(int) git_describe_workdir(
 164         git_describe_result **out,
 165         git_repository *repo,
 166         git_describe_options *opts);
 167
 168 /**
 169  * Print the describe result to a buffer
 170  *
 171  * @param out The buffer to store the result
 172  * @param result the result from `git_describe_commit()` or
 173  * `git_describe_workdir()`.
 174  * @param opts the formatting options (or NULL for defaults)
 175  */
 176 GIT_EXTERN(int) git_describe_format(
 177         git_buf *out,
 178         const git_describe_result *result,
 179         const git_describe_format_options *opts);
 180
 181 /**
 182  * Free the describe result.
 183  */
 184 GIT_EXTERN(void) git_describe_result_free(git_describe_result *result);
 185
 186 /** @} */
 187 GIT_END_DECL
 188
 189 #endif