include/git2/apply.h

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_apply_h__
0008 #define INCLUDE_git_apply_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012 #include "oid.h"
0013 #include "diff.h"
0014
0015 /**
0016  * @file git2/apply.h
0017  * @brief Git patch application routines
0018  * @defgroup git_apply Git patch application routines
0019  * @ingroup Git
0020  * @{
0021  */
0022 GIT_BEGIN_DECL
0023
0024 /**
0025  * When applying a patch, callback that will be made per delta (file).
0026  *
0027  * When the callback:
0028  * - returns < 0, the apply process will be aborted.
0029  * - returns > 0, the delta will not be applied, but the apply process
0030  *      continues
0031  * - returns 0, the delta is applied, and the apply process continues.
0032  *
0033  * @param delta The delta to be applied
0034  * @param payload User-specified payload
0035  * @return 0 if the delta is applied, < 0 if the apply process will be aborted
0036  *  or > 0 if the delta will not be applied.
0037  */
0038 typedef int GIT_CALLBACK(git_apply_delta_cb)(
0039     const git_diff_delta *delta,
0040     void *payload);
0041
0042 /**
0043  * When applying a patch, callback that will be made per hunk.
0044  *
0045  * When the callback:
0046  * - returns < 0, the apply process will be aborted.
0047  * - returns > 0, the hunk will not be applied, but the apply process
0048  *      continues
0049  * - returns 0, the hunk is applied, and the apply process continues.
0050  *
0051  * @param hunk The hunk to be applied
0052  * @param payload User-specified payload
0053  * @return 0 if the hunk is applied, < 0 if the apply process will be aborted
0054  *  or > 0 if the hunk will not be applied.
0055  */
0056 typedef int GIT_CALLBACK(git_apply_hunk_cb)(
0057     const git_diff_hunk *hunk,
0058     void *payload);
0059
0060 /** Flags controlling the behavior of git_apply */
0061 typedef enum {
0062     /**
0063      * Don't actually make changes, just test that the patch applies.
0064      * This is the equivalent of `git apply --check`.
0065      */
0066     GIT_APPLY_CHECK = (1 << 0)
0067 } git_apply_flags_t;
0068
0069 /**
0070  * Apply options structure
0071  *
0072  * Initialize with `GIT_APPLY_OPTIONS_INIT`. Alternatively, you can
0073  * use `git_apply_options_init`.
0074  *
0075  * @see git_apply_to_tree, git_apply
0076  */
0077 typedef struct {
0078     unsigned int version; /**< The version */
0079
0080     /** When applying a patch, callback that will be made per delta (file). */
0081     git_apply_delta_cb delta_cb;
0082
0083     /** When applying a patch, callback that will be made per hunk. */
0084     git_apply_hunk_cb hunk_cb;
0085
0086     /** Payload passed to both delta_cb & hunk_cb. */
0087     void *payload;
0088
0089     /** Bitmask of git_apply_flags_t */
0090     unsigned int flags;
0091 } git_apply_options;
0092
0093 #define GIT_APPLY_OPTIONS_VERSION 1
0094 #define GIT_APPLY_OPTIONS_INIT {GIT_APPLY_OPTIONS_VERSION}
0095
0096 /**
0097  * Initialize git_apply_options structure
0098  *
0099  * Initialize a `git_apply_options` with default values. Equivalent to creating
0100  * an instance with GIT_APPLY_OPTIONS_INIT.
0101  *
0102  * @param opts The `git_apply_options` struct to initialize.
0103  * @param version The struct version; pass `GIT_APPLY_OPTIONS_VERSION`
0104  * @return 0 on success or -1 on failure.
0105  */
0106 GIT_EXTERN(int) git_apply_options_init(git_apply_options *opts, unsigned int version);
0107
0108 /**
0109  * Apply a `git_diff` to a `git_tree`, and return the resulting image
0110  * as an index.
0111  *
0112  * @param out the postimage of the application
0113  * @param repo the repository to apply
0114  * @param preimage the tree to apply the diff to
0115  * @param diff the diff to apply
0116  * @param options the options for the apply (or null for defaults)
0117  * @return 0 or an error code
0118  */
0119 GIT_EXTERN(int) git_apply_to_tree(
0120     git_index **out,
0121     git_repository *repo,
0122     git_tree *preimage,
0123     git_diff *diff,
0124     const git_apply_options *options);
0125
0126 /** Possible application locations for git_apply */
0127 typedef enum {
0128     /**
0129      * Apply the patch to the workdir, leaving the index untouched.
0130      * This is the equivalent of `git apply` with no location argument.
0131      */
0132     GIT_APPLY_LOCATION_WORKDIR = 0,
0133
0134     /**
0135      * Apply the patch to the index, leaving the working directory
0136      * untouched.  This is the equivalent of `git apply --cached`.
0137      */
0138     GIT_APPLY_LOCATION_INDEX = 1,
0139
0140     /**
0141      * Apply the patch to both the working directory and the index.
0142      * This is the equivalent of `git apply --index`.
0143      */
0144     GIT_APPLY_LOCATION_BOTH = 2
0145 } git_apply_location_t;
0146
0147 /**
0148  * Apply a `git_diff` to the given repository, making changes directly
0149  * in the working directory, the index, or both.
0150  *
0151  * @param repo the repository to apply to
0152  * @param diff the diff to apply
0153  * @param location the location to apply (workdir, index or both)
0154  * @param options the options for the apply (or null for defaults)
0155  * @return 0 or an error code
0156  */
0157 GIT_EXTERN(int) git_apply(
0158     git_repository *repo,
0159     git_diff *diff,
0160     git_apply_location_t location,
0161     const git_apply_options *options);
0162
0163 /** @} */
0164 GIT_END_DECL
0165 #endif