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