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` macro to correctly set 40 * the `version` field. E.g. 41 * 42 * git_describe_options opts = GIT_DESCRIBE_OPTIONS_INIT; 43 */ 44 typedef struct git_describe_options { 45 unsigned int version; 46 47 unsigned int max_candidates_tags; /**< default: 10 */ 48 unsigned int describe_strategy; /**< default: GIT_DESCRIBE_DEFAULT */ 49 const char *pattern; 50 /** 51 * When calculating the distance from the matching tag or 52 * reference, only walk down the first-parent ancestry. 53 */ 54 int only_follow_first_parent; 55 /** 56 * If no matching tag or reference is found, the describe 57 * operation would normally fail. If this option is set, it 58 * will instead fall back to showing the full id of the 59 * commit. 60 */ 61 int show_commit_oid_as_fallback; 62 } git_describe_options; 63 64 #define GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS 10 65 #define GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE 7 66 67 #define GIT_DESCRIBE_OPTIONS_VERSION 1 68 #define GIT_DESCRIBE_OPTIONS_INIT { \ 69 GIT_DESCRIBE_OPTIONS_VERSION, \ 70 GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \ 71 } 72 73 GIT_EXTERN(int) git_describe_init_options(git_describe_options *opts, unsigned int version); 74 75 /** 76 * Options for formatting the describe string 77 */ 78 typedef struct { 79 unsigned int version; 80 81 /** 82 * Size of the abbreviated commit id to use. This value is the 83 * lower bound for the length of the abbreviated string. The 84 * default is 7. 85 */ 86 unsigned int abbreviated_size; 87 88 /** 89 * Set to use the long format even when a shorter name could be used. 90 */ 91 int always_use_long_format; 92 93 /** 94 * If the workdir is dirty and this is set, this string will 95 * be appended to the description string. 96 */ 97 const char *dirty_suffix; 98 } git_describe_format_options; 99 100 #define GIT_DESCRIBE_FORMAT_OPTIONS_VERSION 1 101 #define GIT_DESCRIBE_FORMAT_OPTIONS_INIT { \ 102 GIT_DESCRIBE_FORMAT_OPTIONS_VERSION, \ 103 GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \ 104 } 105 106 GIT_EXTERN(int) git_describe_init_format_options(git_describe_format_options *opts, unsigned int version); 107 108 /** 109 * A struct that stores the result of a describe operation. 110 */ 111 typedef struct git_describe_result git_describe_result; 112 113 /** 114 * Describe a commit 115 * 116 * Perform the describe operation on the given committish object. 117 * 118 * @param result pointer to store the result. You must free this once 119 * you're done with it. 120 * @param committish a committish to describe 121 * @param opts the lookup options (or NULL for defaults) 122 */ 123 GIT_EXTERN(int) git_describe_commit( 124 git_describe_result **result, 125 git_object *committish, 126 git_describe_options *opts); 127 128 /** 129 * Describe a commit 130 * 131 * Perform the describe operation on the current commit and the 132 * worktree. After peforming describe on HEAD, a status is run and the 133 * description is considered to be dirty if there are. 134 * 135 * @param out pointer to store the result. You must free this once 136 * you're done with it. 137 * @param repo the repository in which to perform the describe 138 * @param opts the lookup options (or NULL for defaults) 139 */ 140 GIT_EXTERN(int) git_describe_workdir( 141 git_describe_result **out, 142 git_repository *repo, 143 git_describe_options *opts); 144 145 /** 146 * Print the describe result to a buffer 147 * 148 * @param out The buffer to store the result 149 * @param result the result from `git_describe_commit()` or 150 * `git_describe_workdir()`. 151 * @param opts the formatting options (or NULL for defaults) 152 */ 153 GIT_EXTERN(int) git_describe_format( 154 git_buf *out, 155 const git_describe_result *result, 156 const git_describe_format_options *opts); 157 158 /** 159 * Free the describe result. 160 */ 161 GIT_EXTERN(void) git_describe_result_free(git_describe_result *result); 162 163 /** @} */ 164 GIT_END_DECL 165 166 #endif 167