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.blame; 8 9 10 private static import libgit2_d.oid; 11 private static import libgit2_d.types; 12 13 /** 14 * @file git2/blame.h 15 * @brief Git blame routines 16 * @defgroup git_blame Git blame routines 17 * @ingroup Git 18 * @{ 19 */ 20 extern (C): 21 nothrow @nogc: 22 public: 23 24 /** 25 * Flags for indicating option behavior for git_blame APIs. 26 */ 27 enum git_blame_flag_t 28 { 29 /** 30 * Normal blame, the default 31 */ 32 GIT_BLAME_NORMAL = 0, 33 34 /** 35 * Track lines that have moved within a file (like `git blame -M`). 36 * NOT IMPLEMENTED. 37 */ 38 GIT_BLAME_TRACK_COPIES_SAME_FILE = 1 << 0, 39 40 /** 41 * Track lines that have moved across files in the same commit (like `git 42 * blame -C`). NOT IMPLEMENTED. 43 */ 44 GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = 1 << 1, 45 46 /** 47 * Track lines that have been copied from another file that exists in the 48 * same commit (like `git blame -CC`). Implies SAME_FILE. 49 * NOT IMPLEMENTED. 50 */ 51 GIT_BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = 1 << 2, 52 53 /** 54 * Track lines that have been copied from another file that exists in *any* 55 * commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES. 56 * NOT IMPLEMENTED. 57 */ 58 GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = 1 << 3, 59 60 /** 61 * Restrict the search of commits to those reachable following only the 62 * first parents. 63 */ 64 GIT_BLAME_FIRST_PARENT = 1 << 4, 65 66 /** 67 * Use mailmap file to map author and committer names and email addresses 68 * to canonical real names and email addresses. The mailmap will be read 69 * from the working directory, or HEAD in a bare repository. 70 */ 71 GIT_BLAME_USE_MAILMAP = 1 << 5, 72 } 73 74 /** 75 * Blame options structure 76 * 77 * Initialize with `GIT_BLAME_OPTIONS_INIT`. Alternatively, you can 78 * use `git_blame_options_init`. 79 */ 80 struct git_blame_options 81 { 82 uint version_; 83 84 /** 85 * A combination of `git_blame_flag_t` 86 */ 87 uint flags; 88 89 /** 90 * The lower bound on the number of alphanumeric 91 * characters that must be detected as moving/copying within a file for it to 92 * associate those lines with the parent commit. The default value is 20. 93 * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*` 94 * flags are specified. 95 */ 96 ushort min_match_characters; 97 98 /** 99 * The id of the newest commit to consider. The default is HEAD. 100 */ 101 libgit2_d.oid.git_oid newest_commit; 102 103 /** 104 * The id of the oldest commit to consider. 105 * The default is the first commit encountered with a NULL parent. 106 */ 107 libgit2_d.oid.git_oid oldest_commit; 108 109 /** 110 * The first line in the file to blame. 111 * The default is 1 (line numbers start with 1). 112 */ 113 size_t min_line; 114 115 /** 116 * The last line in the file to blame. 117 * The default is the last line of the file. 118 */ 119 size_t max_line; 120 } 121 122 enum GIT_BLAME_OPTIONS_VERSION = 1; 123 124 pragma(inline, true) 125 pure nothrow @safe @nogc 126 .git_blame_options GIT_BLAME_OPTIONS_INIT() 127 128 do 129 { 130 .git_blame_options OUTPUT = 131 { 132 version_: .GIT_BLAME_OPTIONS_VERSION, 133 }; 134 135 return OUTPUT; 136 } 137 138 /** 139 * Initialize git_blame_options structure 140 * 141 * Initializes a `git_blame_options` with default values. Equivalent to creating 142 * an instance with GIT_BLAME_OPTIONS_INIT. 143 * 144 * @param opts The `git_blame_options` struct to initialize. 145 * @param version The struct version; pass `GIT_BLAME_OPTIONS_VERSION`. 146 * @return Zero on success; -1 on failure. 147 */ 148 //GIT_EXTERN 149 int git_blame_options_init(.git_blame_options* opts, uint version_); 150 151 /** 152 * Structure that represents a blame hunk. 153 * 154 * - `lines_in_hunk` is the number of lines in this hunk 155 * - `final_commit_id` is the OID of the commit where this line was last 156 * changed. 157 * - `final_start_line_number` is the 1-based line number where this hunk 158 * begins, in the final version of the file 159 * - `final_signature` is the author of `final_commit_id`. If 160 * `git_blame_flag_t.GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical 161 * real name and email address. 162 * - `orig_commit_id` is the OID of the commit where this hunk was found. This 163 * will usually be the same as `final_commit_id`, except when 164 * `git_blame_flag_t.GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified. 165 * - `orig_path` is the path to the file where this hunk originated, as of the 166 * commit specified by `orig_commit_id`. 167 * - `orig_start_line_number` is the 1-based line number where this hunk begins 168 * in the file named by `orig_path` in the commit specified by 169 * `orig_commit_id`. 170 * - `orig_signature` is the author of `orig_commit_id`. If 171 * `git_blame_flag_t.GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical 172 * real name and email address. 173 * - `boundary` is 1 iff the hunk has been tracked to a boundary commit (the 174 * root, or the commit specified in git_blame_options.oldest_commit) 175 */ 176 struct git_blame_hunk 177 { 178 size_t lines_in_hunk; 179 180 libgit2_d.oid.git_oid final_commit_id; 181 size_t final_start_line_number; 182 libgit2_d.types.git_signature* final_signature; 183 184 libgit2_d.oid.git_oid orig_commit_id; 185 const (char)* orig_path; 186 size_t orig_start_line_number; 187 libgit2_d.types.git_signature* orig_signature; 188 189 char boundary = '\0'; 190 } 191 192 /** 193 * Opaque structure to hold blame results 194 */ 195 struct git_blame; 196 197 /** 198 * Gets the number of hunks that exist in the blame structure. 199 */ 200 //GIT_EXTERN 201 uint git_blame_get_hunk_count(.git_blame* blame); 202 203 /** 204 * Gets the blame hunk at the given index. 205 * 206 * @param blame the blame structure to query 207 * @param index index of the hunk to retrieve 208 * @return the hunk at the given index, or null on error 209 */ 210 //GIT_EXTERN 211 const (.git_blame_hunk)* git_blame_get_hunk_byindex(.git_blame* blame, uint index); 212 213 /** 214 * Gets the hunk that relates to the given line number in the newest commit. 215 * 216 * @param blame the blame structure to query 217 * @param lineno the (1-based) line number to find a hunk for 218 * @return the hunk that contains the given line, or null on error 219 */ 220 //GIT_EXTERN 221 const (.git_blame_hunk)* git_blame_get_hunk_byline(.git_blame* blame, size_t lineno); 222 223 /** 224 * Get the blame for a single file. 225 * 226 * @param out_ pointer that will receive the blame object 227 * @param repo repository whose history is to be walked 228 * @param path path to file to consider 229 * @param options options for the blame operation. If null, this is treated as 230 * though GIT_BLAME_OPTIONS_INIT were passed. 231 * @return 0 on success, or an error code. (use git_error_last for information 232 * about the error.) 233 */ 234 //GIT_EXTERN 235 int git_blame_file(.git_blame** out_, libgit2_d.types.git_repository* repo, const (char)* path, .git_blame_options* options); 236 237 /** 238 * Get blame data for a file that has been modified in memory. The `reference` 239 * parameter is a pre-calculated blame for the in-odb history of the file. This 240 * means that once a file blame is completed (which can be expensive), updating 241 * the buffer blame is very fast. 242 * 243 * Lines that differ between the buffer and the committed version are marked as 244 * having a zero OID for their final_commit_id. 245 * 246 * @param out_ pointer that will receive the resulting blame data 247 * @param reference cached blame from the history of the file (usually the 248 * output from git_blame_file) 249 * @param buffer the (possibly) modified contents of the file 250 * @param buffer_len number of valid bytes in the buffer 251 * @return 0 on success, or an error code. (use git_error_last for information 252 * about the error) 253 */ 254 //GIT_EXTERN 255 int git_blame_buffer(.git_blame** out_, .git_blame* reference, const (char)* buffer, size_t buffer_len); 256 257 /** 258 * Free memory allocated by git_blame_file or git_blame_buffer. 259 * 260 * @param blame the blame structure to free 261 */ 262 //GIT_EXTERN 263 void git_blame_free(.git_blame* blame); 264 265 /** @} */