|
||||
File indexing completed on 2025-01-18 09:59:38
0001 /* 0002 * Copyright (C) the libgit2 contributors. All rights reserved. 0003 * 0004 * This file is part of libgit2, distributed under the GNU GPL v2 with 0005 * a Linking Exception. For full terms see the included COPYING file. 0006 */ 0007 #ifndef INCLUDE_git_patch_h__ 0008 #define INCLUDE_git_patch_h__ 0009 0010 #include "common.h" 0011 #include "types.h" 0012 #include "oid.h" 0013 #include "diff.h" 0014 0015 /** 0016 * @file git2/patch.h 0017 * @brief Patch handling routines. 0018 * @ingroup Git 0019 * @{ 0020 */ 0021 GIT_BEGIN_DECL 0022 0023 /** 0024 * The diff patch is used to store all the text diffs for a delta. 0025 * 0026 * You can easily loop over the content of patches and get information about 0027 * them. 0028 */ 0029 typedef struct git_patch git_patch; 0030 0031 /** 0032 * Get the repository associated with this patch. May be NULL. 0033 * 0034 * @param patch the patch 0035 * @return a pointer to the repository 0036 */ 0037 GIT_EXTERN(git_repository *) git_patch_owner(const git_patch *patch); 0038 0039 /** 0040 * Return a patch for an entry in the diff list. 0041 * 0042 * The `git_patch` is a newly created object contains the text diffs 0043 * for the delta. You have to call `git_patch_free()` when you are 0044 * done with it. You can use the patch object to loop over all the hunks 0045 * and lines in the diff of the one delta. 0046 * 0047 * For an unchanged file or a binary file, no `git_patch` will be 0048 * created, the output will be set to NULL, and the `binary` flag will be 0049 * set true in the `git_diff_delta` structure. 0050 * 0051 * It is okay to pass NULL for either of the output parameters; if you pass 0052 * NULL for the `git_patch`, then the text diff will not be calculated. 0053 * 0054 * @param out Output parameter for the delta patch object 0055 * @param diff Diff list object 0056 * @param idx Index into diff list 0057 * @return 0 on success, other value < 0 on error 0058 */ 0059 GIT_EXTERN(int) git_patch_from_diff( 0060 git_patch **out, git_diff *diff, size_t idx); 0061 0062 /** 0063 * Directly generate a patch from the difference between two blobs. 0064 * 0065 * This is just like `git_diff_blobs()` except it generates a patch object 0066 * for the difference instead of directly making callbacks. You can use the 0067 * standard `git_patch` accessor functions to read the patch data, and 0068 * you must call `git_patch_free()` on the patch when done. 0069 * 0070 * @param out The generated patch; NULL on error 0071 * @param old_blob Blob for old side of diff, or NULL for empty blob 0072 * @param old_as_path Treat old blob as if it had this filename; can be NULL 0073 * @param new_blob Blob for new side of diff, or NULL for empty blob 0074 * @param new_as_path Treat new blob as if it had this filename; can be NULL 0075 * @param opts Options for diff, or NULL for default options 0076 * @return 0 on success or error code < 0 0077 */ 0078 GIT_EXTERN(int) git_patch_from_blobs( 0079 git_patch **out, 0080 const git_blob *old_blob, 0081 const char *old_as_path, 0082 const git_blob *new_blob, 0083 const char *new_as_path, 0084 const git_diff_options *opts); 0085 0086 /** 0087 * Directly generate a patch from the difference between a blob and a buffer. 0088 * 0089 * This is just like `git_diff_blob_to_buffer()` except it generates a patch 0090 * object for the difference instead of directly making callbacks. You can 0091 * use the standard `git_patch` accessor functions to read the patch 0092 * data, and you must call `git_patch_free()` on the patch when done. 0093 * 0094 * @param out The generated patch; NULL on error 0095 * @param old_blob Blob for old side of diff, or NULL for empty blob 0096 * @param old_as_path Treat old blob as if it had this filename; can be NULL 0097 * @param buffer Raw data for new side of diff, or NULL for empty 0098 * @param buffer_len Length of raw data for new side of diff 0099 * @param buffer_as_path Treat buffer as if it had this filename; can be NULL 0100 * @param opts Options for diff, or NULL for default options 0101 * @return 0 on success or error code < 0 0102 */ 0103 GIT_EXTERN(int) git_patch_from_blob_and_buffer( 0104 git_patch **out, 0105 const git_blob *old_blob, 0106 const char *old_as_path, 0107 const void *buffer, 0108 size_t buffer_len, 0109 const char *buffer_as_path, 0110 const git_diff_options *opts); 0111 0112 /** 0113 * Directly generate a patch from the difference between two buffers. 0114 * 0115 * This is just like `git_diff_buffers()` except it generates a patch 0116 * object for the difference instead of directly making callbacks. You can 0117 * use the standard `git_patch` accessor functions to read the patch 0118 * data, and you must call `git_patch_free()` on the patch when done. 0119 * 0120 * @param out The generated patch; NULL on error 0121 * @param old_buffer Raw data for old side of diff, or NULL for empty 0122 * @param old_len Length of the raw data for old side of the diff 0123 * @param old_as_path Treat old buffer as if it had this filename; can be NULL 0124 * @param new_buffer Raw data for new side of diff, or NULL for empty 0125 * @param new_len Length of raw data for new side of diff 0126 * @param new_as_path Treat buffer as if it had this filename; can be NULL 0127 * @param opts Options for diff, or NULL for default options 0128 * @return 0 on success or error code < 0 0129 */ 0130 GIT_EXTERN(int) git_patch_from_buffers( 0131 git_patch **out, 0132 const void *old_buffer, 0133 size_t old_len, 0134 const char *old_as_path, 0135 const void *new_buffer, 0136 size_t new_len, 0137 const char *new_as_path, 0138 const git_diff_options *opts); 0139 0140 /** 0141 * Free a git_patch object. 0142 * 0143 * @param patch The patch to free. 0144 */ 0145 GIT_EXTERN(void) git_patch_free(git_patch *patch); 0146 0147 /** 0148 * Get the delta associated with a patch. This delta points to internal 0149 * data and you do not have to release it when you are done with it. 0150 * 0151 * @param patch The patch in which to get the delta. 0152 * @return The delta associated with the patch. 0153 */ 0154 GIT_EXTERN(const git_diff_delta *) git_patch_get_delta(const git_patch *patch); 0155 0156 /** 0157 * Get the number of hunks in a patch 0158 * 0159 * @param patch The patch in which to get the number of hunks. 0160 * @return The number of hunks of the patch. 0161 */ 0162 GIT_EXTERN(size_t) git_patch_num_hunks(const git_patch *patch); 0163 0164 /** 0165 * Get line counts of each type in a patch. 0166 * 0167 * This helps imitate a diff --numstat type of output. For that purpose, 0168 * you only need the `total_additions` and `total_deletions` values, but we 0169 * include the `total_context` line count in case you want the total number 0170 * of lines of diff output that will be generated. 0171 * 0172 * All outputs are optional. Pass NULL if you don't need a particular count. 0173 * 0174 * @param total_context Count of context lines in output, can be NULL. 0175 * @param total_additions Count of addition lines in output, can be NULL. 0176 * @param total_deletions Count of deletion lines in output, can be NULL. 0177 * @param patch The git_patch object 0178 * @return 0 on success, <0 on error 0179 */ 0180 GIT_EXTERN(int) git_patch_line_stats( 0181 size_t *total_context, 0182 size_t *total_additions, 0183 size_t *total_deletions, 0184 const git_patch *patch); 0185 0186 /** 0187 * Get the information about a hunk in a patch 0188 * 0189 * Given a patch and a hunk index into the patch, this returns detailed 0190 * information about that hunk. Any of the output pointers can be passed 0191 * as NULL if you don't care about that particular piece of information. 0192 * 0193 * @param out Output pointer to git_diff_hunk of hunk 0194 * @param lines_in_hunk Output count of total lines in this hunk 0195 * @param patch Input pointer to patch object 0196 * @param hunk_idx Input index of hunk to get information about 0197 * @return 0 on success, GIT_ENOTFOUND if hunk_idx out of range, <0 on error 0198 */ 0199 GIT_EXTERN(int) git_patch_get_hunk( 0200 const git_diff_hunk **out, 0201 size_t *lines_in_hunk, 0202 git_patch *patch, 0203 size_t hunk_idx); 0204 0205 /** 0206 * Get the number of lines in a hunk. 0207 * 0208 * @param patch The git_patch object 0209 * @param hunk_idx Index of the hunk 0210 * @return Number of lines in hunk or GIT_ENOTFOUND if invalid hunk index 0211 */ 0212 GIT_EXTERN(int) git_patch_num_lines_in_hunk( 0213 const git_patch *patch, 0214 size_t hunk_idx); 0215 0216 /** 0217 * Get data about a line in a hunk of a patch. 0218 * 0219 * Given a patch, a hunk index, and a line index in the hunk, this 0220 * will return a lot of details about that line. If you pass a hunk 0221 * index larger than the number of hunks or a line index larger than 0222 * the number of lines in the hunk, this will return -1. 0223 * 0224 * @param out The git_diff_line data for this line 0225 * @param patch The patch to look in 0226 * @param hunk_idx The index of the hunk 0227 * @param line_of_hunk The index of the line in the hunk 0228 * @return 0 on success, <0 on failure 0229 */ 0230 GIT_EXTERN(int) git_patch_get_line_in_hunk( 0231 const git_diff_line **out, 0232 git_patch *patch, 0233 size_t hunk_idx, 0234 size_t line_of_hunk); 0235 0236 /** 0237 * Look up size of patch diff data in bytes 0238 * 0239 * This returns the raw size of the patch data. This only includes the 0240 * actual data from the lines of the diff, not the file or hunk headers. 0241 * 0242 * If you pass `include_context` as true (non-zero), this will be the size 0243 * of all of the diff output; if you pass it as false (zero), this will 0244 * only include the actual changed lines (as if `context_lines` was 0). 0245 * 0246 * @param patch A git_patch representing changes to one file 0247 * @param include_context Include context lines in size if non-zero 0248 * @param include_hunk_headers Include hunk header lines if non-zero 0249 * @param include_file_headers Include file header lines if non-zero 0250 * @return The number of bytes of data 0251 */ 0252 GIT_EXTERN(size_t) git_patch_size( 0253 git_patch *patch, 0254 int include_context, 0255 int include_hunk_headers, 0256 int include_file_headers); 0257 0258 /** 0259 * Serialize the patch to text via callback. 0260 * 0261 * Returning a non-zero value from the callback will terminate the iteration 0262 * and return that value to the caller. 0263 * 0264 * @param patch A git_patch representing changes to one file 0265 * @param print_cb Callback function to output lines of the patch. Will be 0266 * called for file headers, hunk headers, and diff lines. 0267 * @param payload Reference pointer that will be passed to your callbacks. 0268 * @return 0 on success, non-zero callback return value, or error code 0269 */ 0270 GIT_EXTERN(int) git_patch_print( 0271 git_patch *patch, 0272 git_diff_line_cb print_cb, 0273 void *payload); 0274 0275 /** 0276 * Get the content of a patch as a single diff text. 0277 * 0278 * @param out The git_buf to be filled in 0279 * @param patch A git_patch representing changes to one file 0280 * @return 0 on success, <0 on failure. 0281 */ 0282 GIT_EXTERN(int) git_patch_to_buf( 0283 git_buf *out, 0284 git_patch *patch); 0285 0286 GIT_END_DECL 0287 0288 /**@}*/ 0289 0290 #endif
[ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |