]>
Commit | Line | Data |
---|---|---|
3ff1d123 RB |
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_patch_h__ | |
8 | #define INCLUDE_git_patch_h__ | |
9 | ||
10 | #include "common.h" | |
11 | #include "types.h" | |
12 | #include "oid.h" | |
13 | #include "diff.h" | |
14 | ||
15 | /** | |
16 | * @file git2/patch.h | |
17 | * @brief Patch handling routines. | |
18 | * @ingroup Git | |
19 | * @{ | |
20 | */ | |
21 | GIT_BEGIN_DECL | |
22 | ||
23 | /** | |
24 | * The diff patch is used to store all the text diffs for a delta. | |
25 | * | |
26 | * You can easily loop over the content of patches and get information about | |
27 | * them. | |
28 | */ | |
29 | typedef struct git_patch git_patch; | |
30 | ||
c25aa7cd PP |
31 | /** |
32 | * Get the repository associated with this patch. May be NULL. | |
33 | * | |
34 | * @param patch the patch | |
35 | * @return a pointer to the repository | |
36 | */ | |
37 | GIT_EXTERN(git_repository *) git_patch_owner(const git_patch *patch); | |
38 | ||
3ff1d123 | 39 | /** |
3538f8f1 | 40 | * Return a patch for an entry in the diff list. |
3ff1d123 RB |
41 | * |
42 | * The `git_patch` is a newly created object contains the text diffs | |
43 | * for the delta. You have to call `git_patch_free()` when you are | |
44 | * done with it. You can use the patch object to loop over all the hunks | |
45 | * and lines in the diff of the one delta. | |
46 | * | |
47 | * For an unchanged file or a binary file, no `git_patch` will be | |
48 | * created, the output will be set to NULL, and the `binary` flag will be | |
49 | * set true in the `git_diff_delta` structure. | |
50 | * | |
3ff1d123 RB |
51 | * It is okay to pass NULL for either of the output parameters; if you pass |
52 | * NULL for the `git_patch`, then the text diff will not be calculated. | |
53 | * | |
10672e3e | 54 | * @param out Output parameter for the delta patch object |
3ff1d123 RB |
55 | * @param diff Diff list object |
56 | * @param idx Index into diff list | |
57 | * @return 0 on success, other value < 0 on error | |
58 | */ | |
59 | GIT_EXTERN(int) git_patch_from_diff( | |
10672e3e | 60 | git_patch **out, git_diff *diff, size_t idx); |
3ff1d123 RB |
61 | |
62 | /** | |
63 | * Directly generate a patch from the difference between two blobs. | |
64 | * | |
65 | * This is just like `git_diff_blobs()` except it generates a patch object | |
66 | * for the difference instead of directly making callbacks. You can use the | |
67 | * standard `git_patch` accessor functions to read the patch data, and | |
68 | * you must call `git_patch_free()` on the patch when done. | |
69 | * | |
70 | * @param out The generated patch; NULL on error | |
71 | * @param old_blob Blob for old side of diff, or NULL for empty blob | |
72 | * @param old_as_path Treat old blob as if it had this filename; can be NULL | |
73 | * @param new_blob Blob for new side of diff, or NULL for empty blob | |
74 | * @param new_as_path Treat new blob as if it had this filename; can be NULL | |
75 | * @param opts Options for diff, or NULL for default options | |
76 | * @return 0 on success or error code < 0 | |
77 | */ | |
78 | GIT_EXTERN(int) git_patch_from_blobs( | |
79 | git_patch **out, | |
80 | const git_blob *old_blob, | |
81 | const char *old_as_path, | |
82 | const git_blob *new_blob, | |
83 | const char *new_as_path, | |
84 | const git_diff_options *opts); | |
85 | ||
86 | /** | |
87 | * Directly generate a patch from the difference between a blob and a buffer. | |
88 | * | |
89 | * This is just like `git_diff_blob_to_buffer()` except it generates a patch | |
90 | * object for the difference instead of directly making callbacks. You can | |
91 | * use the standard `git_patch` accessor functions to read the patch | |
92 | * data, and you must call `git_patch_free()` on the patch when done. | |
93 | * | |
94 | * @param out The generated patch; NULL on error | |
95 | * @param old_blob Blob for old side of diff, or NULL for empty blob | |
96 | * @param old_as_path Treat old blob as if it had this filename; can be NULL | |
97 | * @param buffer Raw data for new side of diff, or NULL for empty | |
98 | * @param buffer_len Length of raw data for new side of diff | |
99 | * @param buffer_as_path Treat buffer as if it had this filename; can be NULL | |
100 | * @param opts Options for diff, or NULL for default options | |
101 | * @return 0 on success or error code < 0 | |
102 | */ | |
103 | GIT_EXTERN(int) git_patch_from_blob_and_buffer( | |
104 | git_patch **out, | |
105 | const git_blob *old_blob, | |
106 | const char *old_as_path, | |
eae0bfdc | 107 | const void *buffer, |
3ff1d123 RB |
108 | size_t buffer_len, |
109 | const char *buffer_as_path, | |
110 | const git_diff_options *opts); | |
111 | ||
6789b7a7 RB |
112 | /** |
113 | * Directly generate a patch from the difference between two buffers. | |
114 | * | |
115 | * This is just like `git_diff_buffers()` except it generates a patch | |
116 | * object for the difference instead of directly making callbacks. You can | |
117 | * use the standard `git_patch` accessor functions to read the patch | |
118 | * data, and you must call `git_patch_free()` on the patch when done. | |
119 | * | |
120 | * @param out The generated patch; NULL on error | |
121 | * @param old_buffer Raw data for old side of diff, or NULL for empty | |
122 | * @param old_len Length of the raw data for old side of the diff | |
123 | * @param old_as_path Treat old buffer as if it had this filename; can be NULL | |
124 | * @param new_buffer Raw data for new side of diff, or NULL for empty | |
125 | * @param new_len Length of raw data for new side of diff | |
126 | * @param new_as_path Treat buffer as if it had this filename; can be NULL | |
127 | * @param opts Options for diff, or NULL for default options | |
128 | * @return 0 on success or error code < 0 | |
129 | */ | |
130 | GIT_EXTERN(int) git_patch_from_buffers( | |
131 | git_patch **out, | |
132 | const void *old_buffer, | |
133 | size_t old_len, | |
134 | const char *old_as_path, | |
eae0bfdc | 135 | const void *new_buffer, |
6789b7a7 RB |
136 | size_t new_len, |
137 | const char *new_as_path, | |
138 | const git_diff_options *opts); | |
139 | ||
3ff1d123 RB |
140 | /** |
141 | * Free a git_patch object. | |
e579e0f7 MB |
142 | * |
143 | * @param patch The patch to free. | |
3ff1d123 | 144 | */ |
10672e3e | 145 | GIT_EXTERN(void) git_patch_free(git_patch *patch); |
3ff1d123 RB |
146 | |
147 | /** | |
3538f8f1 ET |
148 | * Get the delta associated with a patch. This delta points to internal |
149 | * data and you do not have to release it when you are done with it. | |
e579e0f7 MB |
150 | * |
151 | * @param patch The patch in which to get the delta. | |
152 | * @return The delta associated with the patch. | |
3ff1d123 | 153 | */ |
7a28f268 | 154 | GIT_EXTERN(const git_diff_delta *) git_patch_get_delta(const git_patch *patch); |
3ff1d123 RB |
155 | |
156 | /** | |
157 | * Get the number of hunks in a patch | |
e579e0f7 MB |
158 | * |
159 | * @param patch The patch in which to get the number of hunks. | |
160 | * @return The number of hunks of the patch. | |
3ff1d123 | 161 | */ |
7a28f268 | 162 | GIT_EXTERN(size_t) git_patch_num_hunks(const git_patch *patch); |
3ff1d123 RB |
163 | |
164 | /** | |
165 | * Get line counts of each type in a patch. | |
166 | * | |
167 | * This helps imitate a diff --numstat type of output. For that purpose, | |
168 | * you only need the `total_additions` and `total_deletions` values, but we | |
169 | * include the `total_context` line count in case you want the total number | |
170 | * of lines of diff output that will be generated. | |
171 | * | |
172 | * All outputs are optional. Pass NULL if you don't need a particular count. | |
173 | * | |
174 | * @param total_context Count of context lines in output, can be NULL. | |
175 | * @param total_additions Count of addition lines in output, can be NULL. | |
176 | * @param total_deletions Count of deletion lines in output, can be NULL. | |
177 | * @param patch The git_patch object | |
178 | * @return 0 on success, <0 on error | |
179 | */ | |
180 | GIT_EXTERN(int) git_patch_line_stats( | |
181 | size_t *total_context, | |
182 | size_t *total_additions, | |
183 | size_t *total_deletions, | |
184 | const git_patch *patch); | |
185 | ||
186 | /** | |
187 | * Get the information about a hunk in a patch | |
188 | * | |
189 | * Given a patch and a hunk index into the patch, this returns detailed | |
190 | * information about that hunk. Any of the output pointers can be passed | |
191 | * as NULL if you don't care about that particular piece of information. | |
192 | * | |
193 | * @param out Output pointer to git_diff_hunk of hunk | |
3ff1d123 RB |
194 | * @param lines_in_hunk Output count of total lines in this hunk |
195 | * @param patch Input pointer to patch object | |
196 | * @param hunk_idx Input index of hunk to get information about | |
197 | * @return 0 on success, GIT_ENOTFOUND if hunk_idx out of range, <0 on error | |
198 | */ | |
199 | GIT_EXTERN(int) git_patch_get_hunk( | |
200 | const git_diff_hunk **out, | |
3ff1d123 RB |
201 | size_t *lines_in_hunk, |
202 | git_patch *patch, | |
203 | size_t hunk_idx); | |
204 | ||
205 | /** | |
206 | * Get the number of lines in a hunk. | |
207 | * | |
208 | * @param patch The git_patch object | |
209 | * @param hunk_idx Index of the hunk | |
6d8ecf08 | 210 | * @return Number of lines in hunk or GIT_ENOTFOUND if invalid hunk index |
3ff1d123 RB |
211 | */ |
212 | GIT_EXTERN(int) git_patch_num_lines_in_hunk( | |
7a28f268 | 213 | const git_patch *patch, |
3ff1d123 RB |
214 | size_t hunk_idx); |
215 | ||
216 | /** | |
217 | * Get data about a line in a hunk of a patch. | |
218 | * | |
219 | * Given a patch, a hunk index, and a line index in the hunk, this | |
220 | * will return a lot of details about that line. If you pass a hunk | |
221 | * index larger than the number of hunks or a line index larger than | |
222 | * the number of lines in the hunk, this will return -1. | |
223 | * | |
3b5f7954 | 224 | * @param out The git_diff_line data for this line |
3ff1d123 RB |
225 | * @param patch The patch to look in |
226 | * @param hunk_idx The index of the hunk | |
227 | * @param line_of_hunk The index of the line in the hunk | |
228 | * @return 0 on success, <0 on failure | |
229 | */ | |
230 | GIT_EXTERN(int) git_patch_get_line_in_hunk( | |
3b5f7954 | 231 | const git_diff_line **out, |
3ff1d123 RB |
232 | git_patch *patch, |
233 | size_t hunk_idx, | |
234 | size_t line_of_hunk); | |
235 | ||
236 | /** | |
237 | * Look up size of patch diff data in bytes | |
238 | * | |
239 | * This returns the raw size of the patch data. This only includes the | |
240 | * actual data from the lines of the diff, not the file or hunk headers. | |
241 | * | |
242 | * If you pass `include_context` as true (non-zero), this will be the size | |
243 | * of all of the diff output; if you pass it as false (zero), this will | |
244 | * only include the actual changed lines (as if `context_lines` was 0). | |
245 | * | |
246 | * @param patch A git_patch representing changes to one file | |
247 | * @param include_context Include context lines in size if non-zero | |
248 | * @param include_hunk_headers Include hunk header lines if non-zero | |
249 | * @param include_file_headers Include file header lines if non-zero | |
250 | * @return The number of bytes of data | |
251 | */ | |
252 | GIT_EXTERN(size_t) git_patch_size( | |
253 | git_patch *patch, | |
254 | int include_context, | |
255 | int include_hunk_headers, | |
256 | int include_file_headers); | |
257 | ||
258 | /** | |
259 | * Serialize the patch to text via callback. | |
260 | * | |
261 | * Returning a non-zero value from the callback will terminate the iteration | |
373cf6a9 | 262 | * and return that value to the caller. |
3ff1d123 RB |
263 | * |
264 | * @param patch A git_patch representing changes to one file | |
265 | * @param print_cb Callback function to output lines of the patch. Will be | |
266 | * called for file headers, hunk headers, and diff lines. | |
267 | * @param payload Reference pointer that will be passed to your callbacks. | |
373cf6a9 | 268 | * @return 0 on success, non-zero callback return value, or error code |
3ff1d123 RB |
269 | */ |
270 | GIT_EXTERN(int) git_patch_print( | |
271 | git_patch *patch, | |
272 | git_diff_line_cb print_cb, | |
273 | void *payload); | |
274 | ||
450e8e9e NH |
275 | /** |
276 | * Get the content of a patch as a single diff text. | |
277 | * | |
278 | * @param out The git_buf to be filled in | |
279 | * @param patch A git_patch representing changes to one file | |
280 | * @return 0 on success, <0 on failure. | |
281 | */ | |
282 | GIT_EXTERN(int) git_patch_to_buf( | |
283 | git_buf *out, | |
284 | git_patch *patch); | |
3ff1d123 RB |
285 | |
286 | GIT_END_DECL | |
287 | ||
288 | /**@}*/ | |
289 | ||
290 | #endif |