include/git2/stash.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_stash_h__
0008 #define INCLUDE_git_stash_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012 #include "checkout.h"
0013
0014 /**
0015  * @file git2/stash.h
0016  * @brief Git stash management routines
0017  * @ingroup Git
0018  * @{
0019  */
0020 GIT_BEGIN_DECL
0021
0022 /**
0023  * Stash flags
0024  */
0025 typedef enum {
0026     /**
0027      * No option, default
0028      */
0029     GIT_STASH_DEFAULT = 0,
0030
0031     /**
0032      * All changes already added to the index are left intact in
0033      * the working directory
0034      */
0035     GIT_STASH_KEEP_INDEX = (1 << 0),
0036
0037     /**
0038      * All untracked files are also stashed and then cleaned up
0039      * from the working directory
0040      */
0041     GIT_STASH_INCLUDE_UNTRACKED = (1 << 1),
0042
0043     /**
0044      * All ignored files are also stashed and then cleaned up from
0045      * the working directory
0046      */
0047     GIT_STASH_INCLUDE_IGNORED = (1 << 2),
0048
0049     /**
0050      * All changes in the index and working directory are left intact
0051      */
0052     GIT_STASH_KEEP_ALL = (1 << 3)
0053 } git_stash_flags;
0054
0055 /**
0056  * Save the local modifications to a new stash.
0057  *
0058  * @param out Object id of the commit containing the stashed state.
0059  * This commit is also the target of the direct reference refs/stash.
0060  * @param repo The owning repository.
0061  * @param stasher The identity of the person performing the stashing.
0062  * @param message Optional description along with the stashed state.
0063  * @param flags Flags to control the stashing process. (see GIT_STASH_* above)
0064  * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash,
0065  * or error code.
0066  */
0067 GIT_EXTERN(int) git_stash_save(
0068     git_oid *out,
0069     git_repository *repo,
0070     const git_signature *stasher,
0071     const char *message,
0072     uint32_t flags);
0073
0074 /**
0075  * Stash save options structure
0076  *
0077  * Initialize with `GIT_STASH_SAVE_OPTIONS_INIT`. Alternatively, you can
0078  * use `git_stash_save_options_init`.
0079  *
0080  */
0081 typedef struct git_stash_save_options {
0082     unsigned int version;
0083
0084     /** Flags to control the stashing process. (see GIT_STASH_* above) */
0085     uint32_t flags;
0086
0087     /** The identity of the person performing the stashing. */
0088     const git_signature *stasher;
0089
0090     /** Optional description along with the stashed state. */
0091     const char *message;
0092
0093     /** Optional paths that control which files are stashed. */
0094     git_strarray paths;
0095 } git_stash_save_options;
0096
0097 #define GIT_STASH_SAVE_OPTIONS_VERSION 1
0098 #define GIT_STASH_SAVE_OPTIONS_INIT { GIT_STASH_SAVE_OPTIONS_VERSION }
0099
0100 /**
0101  * Initialize git_stash_save_options structure
0102  *
0103  * Initializes a `git_stash_save_options` with default values. Equivalent to
0104  * creating an instance with `GIT_STASH_SAVE_OPTIONS_INIT`.
0105  *
0106  * @param opts The `git_stash_save_options` struct to initialize.
0107  * @param version The struct version; pass `GIT_STASH_SAVE_OPTIONS_VERSION`.
0108  * @return Zero on success; -1 on failure.
0109  */
0110 GIT_EXTERN(int) git_stash_save_options_init(
0111     git_stash_save_options *opts, unsigned int version);
0112
0113 /**
0114  * Save the local modifications to a new stash, with options.
0115  *
0116  * @param out Object id of the commit containing the stashed state.
0117  * This commit is also the target of the direct reference refs/stash.
0118  * @param repo The owning repository.
0119  * @param opts The stash options.
0120  * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash,
0121  * or error code.
0122  */
0123 GIT_EXTERN(int) git_stash_save_with_opts(
0124     git_oid *out,
0125     git_repository *repo,
0126     const git_stash_save_options *opts);
0127
0128 /** Stash application flags. */
0129 typedef enum {
0130     GIT_STASH_APPLY_DEFAULT = 0,
0131
0132     /* Try to reinstate not only the working tree's changes,
0133      * but also the index's changes.
0134      */
0135     GIT_STASH_APPLY_REINSTATE_INDEX = (1 << 0)
0136 } git_stash_apply_flags;
0137
0138 /** Stash apply progression states */
0139 typedef enum {
0140     GIT_STASH_APPLY_PROGRESS_NONE = 0,
0141
0142     /** Loading the stashed data from the object database. */
0143     GIT_STASH_APPLY_PROGRESS_LOADING_STASH,
0144
0145     /** The stored index is being analyzed. */
0146     GIT_STASH_APPLY_PROGRESS_ANALYZE_INDEX,
0147
0148     /** The modified files are being analyzed. */
0149     GIT_STASH_APPLY_PROGRESS_ANALYZE_MODIFIED,
0150
0151     /** The untracked and ignored files are being analyzed. */
0152     GIT_STASH_APPLY_PROGRESS_ANALYZE_UNTRACKED,
0153
0154     /** The untracked files are being written to disk. */
0155     GIT_STASH_APPLY_PROGRESS_CHECKOUT_UNTRACKED,
0156
0157     /** The modified files are being written to disk. */
0158     GIT_STASH_APPLY_PROGRESS_CHECKOUT_MODIFIED,
0159
0160     /** The stash was applied successfully. */
0161     GIT_STASH_APPLY_PROGRESS_DONE
0162 } git_stash_apply_progress_t;
0163
0164 /**
0165  * Stash application progress notification function.
0166  * Return 0 to continue processing, or a negative value to
0167  * abort the stash application.
0168  */
0169 typedef int GIT_CALLBACK(git_stash_apply_progress_cb)(
0170     git_stash_apply_progress_t progress,
0171     void *payload);
0172
0173 /**
0174  * Stash application options structure
0175  *
0176  * Initialize with `GIT_STASH_APPLY_OPTIONS_INIT`. Alternatively, you can
0177  * use `git_stash_apply_options_init`.
0178  *
0179  */
0180 typedef struct git_stash_apply_options {
0181     unsigned int version;
0182
0183     /** See `git_stash_apply_flags`, above. */
0184     uint32_t flags;
0185
0186     /** Options to use when writing files to the working directory. */
0187     git_checkout_options checkout_options;
0188
0189     /** Optional callback to notify the consumer of application progress. */
0190     git_stash_apply_progress_cb progress_cb;
0191     void *progress_payload;
0192 } git_stash_apply_options;
0193
0194 #define GIT_STASH_APPLY_OPTIONS_VERSION 1
0195 #define GIT_STASH_APPLY_OPTIONS_INIT { \
0196     GIT_STASH_APPLY_OPTIONS_VERSION, \
0197     GIT_STASH_APPLY_DEFAULT, \
0198     GIT_CHECKOUT_OPTIONS_INIT }
0199
0200 /**
0201  * Initialize git_stash_apply_options structure
0202  *
0203  * Initializes a `git_stash_apply_options` with default values. Equivalent to
0204  * creating an instance with `GIT_STASH_APPLY_OPTIONS_INIT`.
0205  *
0206  * @param opts The `git_stash_apply_options` struct to initialize.
0207  * @param version The struct version; pass `GIT_STASH_APPLY_OPTIONS_VERSION`.
0208  * @return Zero on success; -1 on failure.
0209  */
0210 GIT_EXTERN(int) git_stash_apply_options_init(
0211     git_stash_apply_options *opts, unsigned int version);
0212
0213 /**
0214  * Apply a single stashed state from the stash list.
0215  *
0216  * If local changes in the working directory conflict with changes in the
0217  * stash then GIT_EMERGECONFLICT will be returned.  In this case, the index
0218  * will always remain unmodified and all files in the working directory will
0219  * remain unmodified.  However, if you are restoring untracked files or
0220  * ignored files and there is a conflict when applying the modified files,
0221  * then those files will remain in the working directory.
0222  *
0223  * If passing the GIT_STASH_APPLY_REINSTATE_INDEX flag and there would be
0224  * conflicts when reinstating the index, the function will return
0225  * GIT_EMERGECONFLICT and both the working directory and index will be left
0226  * unmodified.
0227  *
0228  * Note that a minimum checkout strategy of `GIT_CHECKOUT_SAFE` is implied.
0229  *
0230  * @param repo The owning repository.
0231  * @param index The position within the stash list. 0 points to the
0232  *              most recent stashed state.
0233  * @param options Optional options to control how stashes are applied.
0234  *
0235  * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the
0236  *         given index, GIT_EMERGECONFLICT if changes exist in the working
0237  *         directory, or an error code
0238  */
0239 GIT_EXTERN(int) git_stash_apply(
0240     git_repository *repo,
0241     size_t index,
0242     const git_stash_apply_options *options);
0243
0244 /**
0245  * This is a callback function you can provide to iterate over all the
0246  * stashed states that will be invoked per entry.
0247  *
0248  * @param index The position within the stash list. 0 points to the
0249  *              most recent stashed state.
0250  * @param message The stash message.
0251  * @param stash_id The commit oid of the stashed state.
0252  * @param payload Extra parameter to callback function.
0253  * @return 0 to continue iterating or non-zero to stop.
0254  */
0255 typedef int GIT_CALLBACK(git_stash_cb)(
0256     size_t index,
0257     const char *message,
0258     const git_oid *stash_id,
0259     void *payload);
0260
0261 /**
0262  * Loop over all the stashed states and issue a callback for each one.
0263  *
0264  * If the callback returns a non-zero value, this will stop looping.
0265  *
0266  * @param repo Repository where to find the stash.
0267  *
0268  * @param callback Callback to invoke per found stashed state. The most
0269  *                 recent stash state will be enumerated first.
0270  *
0271  * @param payload Extra parameter to callback function.
0272  *
0273  * @return 0 on success, non-zero callback return value, or error code.
0274  */
0275 GIT_EXTERN(int) git_stash_foreach(
0276     git_repository *repo,
0277     git_stash_cb callback,
0278     void *payload);
0279
0280 /**
0281  * Remove a single stashed state from the stash list.
0282  *
0283  * @param repo The owning repository.
0284  *
0285  * @param index The position within the stash list. 0 points to the
0286  * most recent stashed state.
0287  *
0288  * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the given
0289  * index, or error code.
0290  */
0291 GIT_EXTERN(int) git_stash_drop(
0292     git_repository *repo,
0293     size_t index);
0294
0295 /**
0296  * Apply a single stashed state from the stash list and remove it from the list
0297  * if successful.
0298  *
0299  * @param repo The owning repository.
0300  * @param index The position within the stash list. 0 points to the
0301  *              most recent stashed state.
0302  * @param options Optional options to control how stashes are applied.
0303  *
0304  * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the given
0305  * index, or error code. (see git_stash_apply() above for details)
0306 */
0307 GIT_EXTERN(int) git_stash_pop(
0308     git_repository *repo,
0309     size_t index,
0310     const git_stash_apply_options *options);
0311
0312 /** @} */
0313 GIT_END_DECL
0314 #endif