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