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 190