include/git2/stash.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_stash_h__
   8 #define INCLUDE_git_stash_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "checkout.h"
  13
  14 /**
  15  * @file git2/stash.h
  16  * @brief Git stash management routines
  17  * @ingroup Git
  18  * @{
  19  */
  20 GIT_BEGIN_DECL
  21
  22 /**
  23  * Stash flags
  24  */
  25 typedef enum {
  26         /**
  27          * No option, default
  28          */
  29         GIT_STASH_DEFAULT = 0,
  30
  31         /**
  32          * All changes already added to the index are left intact in
  33          * the working directory
  34          */
  35         GIT_STASH_KEEP_INDEX = (1 << 0),
  36
  37         /**
  38          * All untracked files are also stashed and then cleaned up
  39          * from the working directory
  40          */
  41         GIT_STASH_INCLUDE_UNTRACKED = (1 << 1),
  42
  43         /**
  44          * All ignored files are also stashed and then cleaned up from
  45          * the working directory
  46          */
  47         GIT_STASH_INCLUDE_IGNORED = (1 << 2),
  48 } git_stash_flags;
  49
  50 /**
  51  * Save the local modifications to a new stash.
  52  *
  53  * @param out Object id of the commit containing the stashed state.
  54  * This commit is also the target of the direct reference refs/stash.
  55  *
  56  * @param repo The owning repository.
  57  *
  58  * @param stasher The identity of the person performing the stashing.
  59  *
  60  * @param message Optional description along with the stashed state.
  61  *
  62  * @param flags Flags to control the stashing process. (see GIT_STASH_* above)
  63  *
  64  * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash,
  65  * or error code.
  66  */
  67 GIT_EXTERN(int) git_stash_save(
  68         git_oid *out,
  69         git_repository *repo,
  70         const git_signature *stasher,
  71         const char *message,
  72         uint32_t flags);
  73
  74 /** Stash application flags. */
  75 typedef enum {
  76         GIT_STASH_APPLY_DEFAULT = 0,
  77
  78         /* Try to reinstate not only the working tree's changes,
  79          * but also the index's changes.
  80          */
  81         GIT_STASH_APPLY_REINSTATE_INDEX = (1 << 0),
  82 } git_stash_apply_flags;
  83
  84 /** Stash apply progression states */
  85 typedef enum {
  86         GIT_STASH_APPLY_PROGRESS_NONE = 0,
  87
  88         /** Loading the stashed data from the object database. */
  89         GIT_STASH_APPLY_PROGRESS_LOADING_STASH,
  90
  91         /** The stored index is being analyzed. */
  92         GIT_STASH_APPLY_PROGRESS_ANALYZE_INDEX,
  93
  94         /** The modified files are being analyzed. */
  95         GIT_STASH_APPLY_PROGRESS_ANALYZE_MODIFIED,
  96
  97         /** The untracked and ignored files are being analyzed. */
  98         GIT_STASH_APPLY_PROGRESS_ANALYZE_UNTRACKED,
  99
 100         /** The untracked files are being written to disk. */
 101         GIT_STASH_APPLY_PROGRESS_CHECKOUT_UNTRACKED,
 102
 103         /** The modified files are being written to disk. */
 104         GIT_STASH_APPLY_PROGRESS_CHECKOUT_MODIFIED,
 105
 106         /** The stash was applied successfully. */
 107         GIT_STASH_APPLY_PROGRESS_DONE,
 108 } git_stash_apply_progress_t;
 109
 110 /**
 111  * Stash application progress notification function.
 112  * Return 0 to continue processing, or a negative value to
 113  * abort the stash application.
 114  */
 115 typedef int GIT_CALLBACK(git_stash_apply_progress_cb)(
 116         git_stash_apply_progress_t progress,
 117         void *payload);
 118
 119 /**
 120  * Stash application options structure
 121  *
 122  * Initialize with `GIT_STASH_APPLY_OPTIONS_INIT`. Alternatively, you can
 123  * use `git_stash_apply_options_init`.
 124  *
 125  */
 126 typedef struct git_stash_apply_options {
 127         unsigned int version;
 128
 129         /** See `git_stash_apply_flags`, above. */
 130         uint32_t flags;
 131
 132         /** Options to use when writing files to the working directory. */
 133         git_checkout_options checkout_options;
 134
 135         /** Optional callback to notify the consumer of application progress. */
 136         git_stash_apply_progress_cb progress_cb;
 137         void *progress_payload;
 138 } git_stash_apply_options;
 139
 140 #define GIT_STASH_APPLY_OPTIONS_VERSION 1
 141 #define GIT_STASH_APPLY_OPTIONS_INIT { \
 142         GIT_STASH_APPLY_OPTIONS_VERSION, \
 143         GIT_STASH_APPLY_DEFAULT, \
 144         GIT_CHECKOUT_OPTIONS_INIT }
 145
 146 /**
 147  * Initialize git_stash_apply_options structure
 148  *
 149  * Initializes a `git_stash_apply_options` with default values. Equivalent to
 150  * creating an instance with `GIT_STASH_APPLY_OPTIONS_INIT`.
 151  *
 152  * @param opts The `git_stash_apply_options` struct to initialize.
 153  * @param version The struct version; pass `GIT_STASH_APPLY_OPTIONS_VERSION`.
 154  * @return Zero on success; -1 on failure.
 155  */
 156 GIT_EXTERN(int) git_stash_apply_options_init(
 157         git_stash_apply_options *opts, unsigned int version);
 158
 159 /**
 160  * Apply a single stashed state from the stash list.
 161  *
 162  * If local changes in the working directory conflict with changes in the
 163  * stash then GIT_EMERGECONFLICT will be returned.  In this case, the index
 164  * will always remain unmodified and all files in the working directory will
 165  * remain unmodified.  However, if you are restoring untracked files or
 166  * ignored files and there is a conflict when applying the modified files,
 167  * then those files will remain in the working directory.
 168  *
 169  * If passing the GIT_STASH_APPLY_REINSTATE_INDEX flag and there would be
 170  * conflicts when reinstating the index, the function will return
 171  * GIT_EMERGECONFLICT and both the working directory and index will be left
 172  * unmodified.
 173  *
 174  * Note that a minimum checkout strategy of `GIT_CHECKOUT_SAFE` is implied.
 175  *
 176  * @param repo The owning repository.
 177  * @param index The position within the stash list. 0 points to the
 178  *              most recent stashed state.
 179  * @param options Optional options to control how stashes are applied.
 180  *
 181  * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the
 182  *         given index, GIT_EMERGECONFLICT if changes exist in the working
 183  *         directory, or an error code
 184  */
 185 GIT_EXTERN(int) git_stash_apply(
 186         git_repository *repo,
 187         size_t index,
 188         const git_stash_apply_options *options);
 189
 190 /**
 191  * This is a callback function you can provide to iterate over all the
 192  * stashed states that will be invoked per entry.
 193  *
 194  * @param index The position within the stash list. 0 points to the
 195  *              most recent stashed state.
 196  * @param message The stash message.
 197  * @param stash_id The commit oid of the stashed state.
 198  * @param payload Extra parameter to callback function.
 199  * @return 0 to continue iterating or non-zero to stop.
 200  */
 201 typedef int GIT_CALLBACK(git_stash_cb)(
 202         size_t index,
 203         const char *message,
 204         const git_oid *stash_id,
 205         void *payload);
 206
 207 /**
 208  * Loop over all the stashed states and issue a callback for each one.
 209  *
 210  * If the callback returns a non-zero value, this will stop looping.
 211  *
 212  * @param repo Repository where to find the stash.
 213  *
 214  * @param callback Callback to invoke per found stashed state. The most
 215  *                 recent stash state will be enumerated first.
 216  *
 217  * @param payload Extra parameter to callback function.
 218  *
 219  * @return 0 on success, non-zero callback return value, or error code.
 220  */
 221 GIT_EXTERN(int) git_stash_foreach(
 222         git_repository *repo,
 223         git_stash_cb callback,
 224         void *payload);
 225
 226 /**
 227  * Remove a single stashed state from the stash list.
 228  *
 229  * @param repo The owning repository.
 230  *
 231  * @param index The position within the stash list. 0 points to the
 232  * most recent stashed state.
 233  *
 234  * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the given
 235  * index, or error code.
 236  */
 237 GIT_EXTERN(int) git_stash_drop(
 238         git_repository *repo,
 239         size_t index);
 240
 241 /**
 242  * Apply a single stashed state from the stash list and remove it from the list
 243  * if successful.
 244  *
 245  * @param repo The owning repository.
 246  * @param index The position within the stash list. 0 points to the
 247  *              most recent stashed state.
 248  * @param options Optional options to control how stashes are applied.
 249  *
 250  * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the given
 251  * index, or error code. (see git_stash_apply() above for details)
 252 */
 253 GIT_EXTERN(int) git_stash_pop(
 254         git_repository *repo,
 255         size_t index,
 256         const git_stash_apply_options *options);
 257
 258 /** @} */
 259 GIT_END_DECL
 260 #endif