include/git2/apply.h

   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_apply_h__
   8 #define INCLUDE_git_apply_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "oid.h"
  13 #include "diff.h"
  14
  15 /**
  16  * @file git2/apply.h
  17  * @brief Git patch application routines
  18  * @defgroup git_apply Git patch application routines
  19  * @ingroup Git
  20  * @{
  21  */
  22 GIT_BEGIN_DECL
  23
  24 /**
  25  * When applying a patch, callback that will be made per delta (file).
  26  *
  27  * When the callback:
  28  * - returns < 0, the apply process will be aborted.
  29  * - returns > 0, the delta will not be applied, but the apply process
  30  *      continues
  31  * - returns 0, the delta is applied, and the apply process continues.
  32  *
  33  * @param delta The delta to be applied
  34  * @param payload User-specified payload
  35  * @return 0 if the delta is applied, < 0 if the apply process will be aborted
  36  *      or > 0 if the delta will not be applied.
  37  */
  38 typedef int GIT_CALLBACK(git_apply_delta_cb)(
  39         const git_diff_delta *delta,
  40         void *payload);
  41
  42 /**
  43  * When applying a patch, callback that will be made per hunk.
  44  *
  45  * When the callback:
  46  * - returns < 0, the apply process will be aborted.
  47  * - returns > 0, the hunk will not be applied, but the apply process
  48  *      continues
  49  * - returns 0, the hunk is applied, and the apply process continues.
  50  *
  51  * @param hunk The hunk to be applied
  52  * @param payload User-specified payload
  53  * @return 0 if the hunk is applied, < 0 if the apply process will be aborted
  54  *      or > 0 if the hunk will not be applied.
  55  */
  56 typedef int GIT_CALLBACK(git_apply_hunk_cb)(
  57         const git_diff_hunk *hunk,
  58         void *payload);
  59
  60 /** Flags controlling the behavior of git_apply */
  61 typedef enum {
  62         /**
  63          * Don't actually make changes, just test that the patch applies.
  64          * This is the equivalent of `git apply --check`.
  65          */
  66         GIT_APPLY_CHECK = (1 << 0)
  67 } git_apply_flags_t;
  68
  69 /**
  70  * Apply options structure
  71  *
  72  * Initialize with `GIT_APPLY_OPTIONS_INIT`. Alternatively, you can
  73  * use `git_apply_options_init`.
  74  *
  75  * @see git_apply_to_tree, git_apply
  76  */
  77 typedef struct {
  78         unsigned int version; /**< The version */
  79
  80         /** When applying a patch, callback that will be made per delta (file). */
  81         git_apply_delta_cb delta_cb;
  82
  83         /** When applying a patch, callback that will be made per hunk. */
  84         git_apply_hunk_cb hunk_cb;
  85
  86         /** Payload passed to both delta_cb & hunk_cb. */
  87         void *payload;
  88
  89         /** Bitmask of git_apply_flags_t */
  90         unsigned int flags;
  91 } git_apply_options;
  92
  93 #define GIT_APPLY_OPTIONS_VERSION 1
  94 #define GIT_APPLY_OPTIONS_INIT {GIT_APPLY_OPTIONS_VERSION}
  95
  96 /**
  97  * Initialize git_apply_options structure
  98  *
  99  * Initialize a `git_apply_options` with default values. Equivalent to creating
 100  * an instance with GIT_APPLY_OPTIONS_INIT.
 101  *
 102  * @param opts The `git_apply_options` struct to initialize.
 103  * @param version The struct version; pass `GIT_APPLY_OPTIONS_VERSION`
 104  * @return 0 on success or -1 on failure.
 105  */
 106 GIT_EXTERN(int) git_apply_options_init(git_apply_options *opts, unsigned int version);
 107
 108 /**
 109  * Apply a `git_diff` to a `git_tree`, and return the resulting image
 110  * as an index.
 111  *
 112  * @param out the postimage of the application
 113  * @param repo the repository to apply
 114  * @param preimage the tree to apply the diff to
 115  * @param diff the diff to apply
 116  * @param options the options for the apply (or null for defaults)
 117  * @return 0 or an error code
 118  */
 119 GIT_EXTERN(int) git_apply_to_tree(
 120         git_index **out,
 121         git_repository *repo,
 122         git_tree *preimage,
 123         git_diff *diff,
 124         const git_apply_options *options);
 125
 126 /** Possible application locations for git_apply */
 127 typedef enum {
 128         /**
 129          * Apply the patch to the workdir, leaving the index untouched.
 130          * This is the equivalent of `git apply` with no location argument.
 131          */
 132         GIT_APPLY_LOCATION_WORKDIR = 0,
 133
 134         /**
 135          * Apply the patch to the index, leaving the working directory
 136          * untouched.  This is the equivalent of `git apply --cached`.
 137          */
 138         GIT_APPLY_LOCATION_INDEX = 1,
 139
 140         /**
 141          * Apply the patch to both the working directory and the index.
 142          * This is the equivalent of `git apply --index`.
 143          */
 144         GIT_APPLY_LOCATION_BOTH = 2
 145 } git_apply_location_t;
 146
 147 /**
 148  * Apply a `git_diff` to the given repository, making changes directly
 149  * in the working directory, the index, or both.
 150  *
 151  * @param repo the repository to apply to
 152  * @param diff the diff to apply
 153  * @param location the location to apply (workdir, index or both)
 154  * @param options the options for the apply (or null for defaults)
 155  * @return 0 or an error code
 156  */
 157 GIT_EXTERN(int) git_apply(
 158         git_repository *repo,
 159         git_diff *diff,
 160         git_apply_location_t location,
 161         const git_apply_options *options);
 162
 163 /** @} */
 164 GIT_END_DECL
 165 #endif