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 /** @} */