Back to home page

EIC code displayed by LXR

 
 

    


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