summaryrefslogtreecommitdiff
path: root/include/git2/stash.h
blob: dcfc013dc4ea0772fb6317e30209b819d7fa9bc5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
/*
 * Copyright (C) the libgit2 contributors. All rights reserved.
 *
 * This file is part of libgit2, distributed under the GNU GPL v2 with
 * a Linking Exception. For full terms see the included COPYING file.
 */
#ifndef INCLUDE_git_stash_h__
#define INCLUDE_git_stash_h__

#include "common.h"
#include "types.h"
#include "checkout.h"

/**
 * @file git2/stash.h
 * @brief Git stash management routines
 * @ingroup Git
 * @{
 */
GIT_BEGIN_DECL

/**
 * Stash flags
 */
typedef enum {
	/**
	 * No option, default
	 */
	GIT_STASH_DEFAULT = 0,

	/**
	 * All changes already added to the index are left intact in
	 * the working directory
	 */
	GIT_STASH_KEEP_INDEX = (1 << 0),

	/**
	 * All untracked files are also stashed and then cleaned up
	 * from the working directory
	 */
	GIT_STASH_INCLUDE_UNTRACKED = (1 << 1),

	/**
	 * All ignored files are also stashed and then cleaned up from
	 * the working directory
	 */
	GIT_STASH_INCLUDE_IGNORED = (1 << 2),

	/**
	 * All changes in the index and working directory are left intact
	 */
	GIT_STASH_KEEP_ALL = (1 << 3)
} git_stash_flags;

/**
 * Save the local modifications to a new stash.
 *
 * @param out Object id of the commit containing the stashed state.
 * This commit is also the target of the direct reference refs/stash.
 * @param repo The owning repository.
 * @param stasher The identity of the person performing the stashing.
 * @param message Optional description along with the stashed state.
 * @param flags Flags to control the stashing process. (see GIT_STASH_* above)
 * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash,
 * or error code.
 */
GIT_EXTERN(int) git_stash_save(
	git_oid *out,
	git_repository *repo,
	const git_signature *stasher,
	const char *message,
	uint32_t flags);

/**
 * Stash save options structure
 *
 * Initialize with `GIT_STASH_SAVE_OPTIONS_INIT`. Alternatively, you can
 * use `git_stash_save_options_init`.
 *
 */
typedef struct git_stash_save_options {
	unsigned int version;

	/** Flags to control the stashing process. (see GIT_STASH_* above) */
	uint32_t flags;

	/** The identity of the person performing the stashing. */
	const git_signature *stasher;

	/** Optional description along with the stashed state. */
	const char *message;

	/** Optional paths that control which files are stashed. */
	git_strarray paths;
} git_stash_save_options;

#define GIT_STASH_SAVE_OPTIONS_VERSION 1
#define GIT_STASH_SAVE_OPTIONS_INIT { GIT_STASH_SAVE_OPTIONS_VERSION }

/**
 * Initialize git_stash_save_options structure
 *
 * Initializes a `git_stash_save_options` with default values. Equivalent to
 * creating an instance with `GIT_STASH_SAVE_OPTIONS_INIT`.
 *
 * @param opts The `git_stash_save_options` struct to initialize.
 * @param version The struct version; pass `GIT_STASH_SAVE_OPTIONS_VERSION`.
 * @return Zero on success; -1 on failure.
 */
GIT_EXTERN(int) git_stash_save_options_init(
	git_stash_save_options *opts, unsigned int version);

/**
 * Save the local modifications to a new stash, with options.
 *
 * @param out Object id of the commit containing the stashed state.
 * This commit is also the target of the direct reference refs/stash.
 * @param repo The owning repository.
 * @param opts The stash options.
 * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash,
 * or error code.
 */
GIT_EXTERN(int) git_stash_save_with_opts(
	git_oid *out,
	git_repository *repo,
	const git_stash_save_options *opts);

/** Stash application flags. */
typedef enum {
	GIT_STASH_APPLY_DEFAULT = 0,

	/* Try to reinstate not only the working tree's changes,
	 * but also the index's changes.
	 */
	GIT_STASH_APPLY_REINSTATE_INDEX = (1 << 0)
} git_stash_apply_flags;

/** Stash apply progression states */
typedef enum {
	GIT_STASH_APPLY_PROGRESS_NONE = 0,

	/** Loading the stashed data from the object database. */
	GIT_STASH_APPLY_PROGRESS_LOADING_STASH,

	/** The stored index is being analyzed. */
	GIT_STASH_APPLY_PROGRESS_ANALYZE_INDEX,

	/** The modified files are being analyzed. */
	GIT_STASH_APPLY_PROGRESS_ANALYZE_MODIFIED,

	/** The untracked and ignored files are being analyzed. */
	GIT_STASH_APPLY_PROGRESS_ANALYZE_UNTRACKED,

	/** The untracked files are being written to disk. */
	GIT_STASH_APPLY_PROGRESS_CHECKOUT_UNTRACKED,

	/** The modified files are being written to disk. */
	GIT_STASH_APPLY_PROGRESS_CHECKOUT_MODIFIED,

	/** The stash was applied successfully. */
	GIT_STASH_APPLY_PROGRESS_DONE
} git_stash_apply_progress_t;

/**
 * Stash application progress notification function.
 * Return 0 to continue processing, or a negative value to
 * abort the stash application.
 */
typedef int GIT_CALLBACK(git_stash_apply_progress_cb)(
	git_stash_apply_progress_t progress,
	void *payload);

/**
 * Stash application options structure
 *
 * Initialize with `GIT_STASH_APPLY_OPTIONS_INIT`. Alternatively, you can
 * use `git_stash_apply_options_init`.
 *
 */
typedef struct git_stash_apply_options {
	unsigned int version;

	/** See `git_stash_apply_flags`, above. */
	uint32_t flags;

	/** Options to use when writing files to the working directory. */
	git_checkout_options checkout_options;

	/** Optional callback to notify the consumer of application progress. */
	git_stash_apply_progress_cb progress_cb;
	void *progress_payload;
} git_stash_apply_options;

#define GIT_STASH_APPLY_OPTIONS_VERSION 1
#define GIT_STASH_APPLY_OPTIONS_INIT { \
	GIT_STASH_APPLY_OPTIONS_VERSION, \
	GIT_STASH_APPLY_DEFAULT, \
	GIT_CHECKOUT_OPTIONS_INIT }

/**
 * Initialize git_stash_apply_options structure
 *
 * Initializes a `git_stash_apply_options` with default values. Equivalent to
 * creating an instance with `GIT_STASH_APPLY_OPTIONS_INIT`.
 *
 * @param opts The `git_stash_apply_options` struct to initialize.
 * @param version The struct version; pass `GIT_STASH_APPLY_OPTIONS_VERSION`.
 * @return Zero on success; -1 on failure.
 */
GIT_EXTERN(int) git_stash_apply_options_init(
	git_stash_apply_options *opts, unsigned int version);

/**
 * Apply a single stashed state from the stash list.
 *
 * If local changes in the working directory conflict with changes in the
 * stash then GIT_EMERGECONFLICT will be returned.  In this case, the index
 * will always remain unmodified and all files in the working directory will
 * remain unmodified.  However, if you are restoring untracked files or
 * ignored files and there is a conflict when applying the modified files,
 * then those files will remain in the working directory.
 *
 * If passing the GIT_STASH_APPLY_REINSTATE_INDEX flag and there would be
 * conflicts when reinstating the index, the function will return
 * GIT_EMERGECONFLICT and both the working directory and index will be left
 * unmodified.
 *
 * Note that a minimum checkout strategy of `GIT_CHECKOUT_SAFE` is implied.
 *
 * @param repo The owning repository.
 * @param index The position within the stash list. 0 points to the
 *              most recent stashed state.
 * @param options Optional options to control how stashes are applied.
 *
 * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the
 *         given index, GIT_EMERGECONFLICT if changes exist in the working
 *         directory, or an error code
 */
GIT_EXTERN(int) git_stash_apply(
	git_repository *repo,
	size_t index,
	const git_stash_apply_options *options);

/**
 * This is a callback function you can provide to iterate over all the
 * stashed states that will be invoked per entry.
 *
 * @param index The position within the stash list. 0 points to the
 *              most recent stashed state.
 * @param message The stash message.
 * @param stash_id The commit oid of the stashed state.
 * @param payload Extra parameter to callback function.
 * @return 0 to continue iterating or non-zero to stop.
 */
typedef int GIT_CALLBACK(git_stash_cb)(
	size_t index,
	const char *message,
	const git_oid *stash_id,
	void *payload);

/**
 * Loop over all the stashed states and issue a callback for each one.
 *
 * If the callback returns a non-zero value, this will stop looping.
 *
 * @param repo Repository where to find the stash.
 *
 * @param callback Callback to invoke per found stashed state. The most
 *                 recent stash state will be enumerated first.
 *
 * @param payload Extra parameter to callback function.
 *
 * @return 0 on success, non-zero callback return value, or error code.
 */
GIT_EXTERN(int) git_stash_foreach(
	git_repository *repo,
	git_stash_cb callback,
	void *payload);

/**
 * Remove a single stashed state from the stash list.
 *
 * @param repo The owning repository.
 *
 * @param index The position within the stash list. 0 points to the
 * most recent stashed state.
 *
 * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the given
 * index, or error code.
 */
GIT_EXTERN(int) git_stash_drop(
	git_repository *repo,
	size_t index);

/**
 * Apply a single stashed state from the stash list and remove it from the list
 * if successful.
 *
 * @param repo The owning repository.
 * @param index The position within the stash list. 0 points to the
 *              most recent stashed state.
 * @param options Optional options to control how stashes are applied.
 *
 * @return 0 on success, GIT_ENOTFOUND if there's no stashed state for the given
 * index, or error code. (see git_stash_apply() above for details)
*/
GIT_EXTERN(int) git_stash_pop(
	git_repository *repo,
	size_t index,
	const git_stash_apply_options *options);

/** @} */
GIT_END_DECL
#endif