]>
Commit | Line | Data |
---|---|---|
14741d62 BS |
1 | /* |
2 | * Copyright (C) 2012 the libgit2 contributors | |
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_checkout_h__ | |
8 | #define INCLUDE_git_checkout_h__ | |
9 | ||
10 | #include "common.h" | |
11 | #include "types.h" | |
7e5c8a5b | 12 | #include "diff.h" |
14741d62 BS |
13 | |
14 | /** | |
15 | * @file git2/checkout.h | |
16 | * @brief Git checkout routines | |
17 | * @defgroup git_checkout Git checkout routines | |
18 | * @ingroup Git | |
19 | * @{ | |
20 | */ | |
21 | GIT_BEGIN_DECL | |
22 | ||
0d64bef9 RB |
23 | /** |
24 | * Checkout behavior flags | |
25 | * | |
77cffa31 RB |
26 | * In libgit2, checkout is used to update the working directory and index |
27 | * to match a target tree. Unlike git checkout, it does not move the HEAD | |
28 | * commit for you - use `git_repository_set_head` or the like to do that. | |
cf208031 | 29 | * |
77cffa31 RB |
30 | * Checkout looks at (up to) four things: the "target" tree you want to |
31 | * check out, the "baseline" tree of what was checked out previously, the | |
32 | * working directory for actual files, and the index for staged changes. | |
cf208031 | 33 | * |
77cffa31 | 34 | * You give checkout one of four strategies for update: |
cf208031 | 35 | * |
77cffa31 RB |
36 | * - `GIT_CHECKOUT_NONE` is a dry-run strategy that checks for conflicts, |
37 | * etc., but doesn't make any actual changes. | |
cf208031 | 38 | * |
77cffa31 RB |
39 | * - `GIT_CHECKOUT_FORCE` is at the opposite extreme, taking any action to |
40 | * make the working directory match the target (including potentially | |
41 | * discarding modified files). | |
cf208031 | 42 | * |
77cffa31 RB |
43 | * In between those are `GIT_CHECKOUT_SAFE` and `GIT_CHECKOUT_SAFE_CREATE` |
44 | * both of which only make modifications that will not lose changes. | |
cf208031 | 45 | * |
77cffa31 RB |
46 | * | target == baseline | target != baseline | |
47 | * ---------------------|-----------------------|----------------------| | |
48 | * workdir == baseline | no action | create, update, or | | |
49 | * | | delete file | | |
50 | * ---------------------|-----------------------|----------------------| | |
51 | * workdir exists and | no action | conflict (notify | | |
52 | * is != baseline | notify dirty MODIFIED | and cancel checkout) | | |
53 | * ---------------------|-----------------------|----------------------| | |
54 | * workdir missing, | create if SAFE_CREATE | create file | | |
55 | * baseline present | notify dirty DELETED | | | |
56 | * ---------------------|-----------------------|----------------------| | |
cf208031 | 57 | * |
77cffa31 RB |
58 | * The only difference between SAFE and SAFE_CREATE is that SAFE_CREATE |
59 | * will cause a file to be checked out if it is missing from the working | |
60 | * directory even if it is not modified between the target and baseline. | |
cf208031 | 61 | * |
cf208031 | 62 | * |
77cffa31 RB |
63 | * To emulate `git checkout`, use `GIT_CHECKOUT_SAFE` with a checkout |
64 | * notification callback (see below) that displays information about dirty | |
65 | * files. The default behavior will cancel checkout on conflicts. | |
cf208031 | 66 | * |
77cffa31 RB |
67 | * To emulate `git checkout-index`, use `GIT_CHECKOUT_SAFE_CREATE` with a |
68 | * notification callback that cancels the operation if a dirty-but-existing | |
69 | * file is found in the working directory. This core git command isn't | |
70 | * quite "force" but is sensitive about some types of changes. | |
cf208031 | 71 | * |
77cffa31 | 72 | * To emulate `git checkout -f`, use `GIT_CHECKOUT_FORCE`. |
cf208031 | 73 | * |
77cffa31 | 74 | * To emulate `git clone` use `GIT_CHECKOUT_SAFE_CREATE` in the options. |
cf208031 | 75 | * |
cf208031 | 76 | * |
77cffa31 | 77 | * There are some additional flags to modified the behavior of checkout: |
cf208031 | 78 | * |
77cffa31 RB |
79 | * - GIT_CHECKOUT_ALLOW_CONFLICTS makes SAFE mode apply safe file updates |
80 | * even if there are conflicts (instead of cancelling the checkout). | |
cf208031 | 81 | * |
77cffa31 RB |
82 | * - GIT_CHECKOUT_REMOVE_UNTRACKED means remove untracked files (i.e. not |
83 | * in target, baseline, or index, and not ignored) from the working dir. | |
cf208031 | 84 | * |
77cffa31 RB |
85 | * - GIT_CHECKOUT_REMOVE_IGNORED means remove ignored files (that are also |
86 | * unrtacked) from the working directory as well. | |
87 | * | |
88 | * - GIT_CHECKOUT_UPDATE_ONLY means to only update the content of files that | |
89 | * already exist. Files will not be created nor deleted. This just skips | |
90 | * applying adds, deletes, and typechanges. | |
cf208031 | 91 | * |
77cffa31 RB |
92 | * - GIT_CHECKOUT_DONT_UPDATE_INDEX prevents checkout from writing the |
93 | * updated files' information to the index. | |
ad9a921b | 94 | * |
77cffa31 RB |
95 | * - Normally, checkout will reload the index and git attributes from disk |
96 | * before any operations. GIT_CHECKOUT_NO_REFRESH prevents this reload. | |
ad9a921b | 97 | * |
77cffa31 RB |
98 | * - Unmerged index entries are conflicts. GIT_CHECKOUT_SKIP_UNMERGED skips |
99 | * files with unmerged index entries instead. GIT_CHECKOUT_USE_OURS and | |
100 | * GIT_CHECKOUT_USE_THEIRS to proceeed with the checkout using either the | |
101 | * stage 2 ("ours") or stage 3 ("theirs") version of files in the index. | |
0d64bef9 RB |
102 | */ |
103 | typedef enum { | |
cf208031 | 104 | GIT_CHECKOUT_NONE = 0, /** default is a dry run, no actual updates */ |
ad9a921b RB |
105 | |
106 | /** Allow safe updates that cannot overwrite uncommited data */ | |
cf208031 | 107 | GIT_CHECKOUT_SAFE = (1u << 0), |
ad9a921b | 108 | |
cf208031 RB |
109 | /** Allow safe updates plus creation of missing files */ |
110 | GIT_CHECKOUT_SAFE_CREATE = (1u << 1), | |
fe67e404 | 111 | |
ad9a921b | 112 | /** Allow all updates to force working directory to look like index */ |
cf208031 RB |
113 | GIT_CHECKOUT_FORCE = (1u << 2), |
114 | ||
fe67e404 | 115 | |
cf208031 | 116 | /** Allow checkout to make safe updates even if conflicts are found */ |
ad9a921b RB |
117 | GIT_CHECKOUT_ALLOW_CONFLICTS = (1u << 4), |
118 | ||
119 | /** Remove untracked files not in index (that are not ignored) */ | |
120 | GIT_CHECKOUT_REMOVE_UNTRACKED = (1u << 5), | |
121 | ||
cf208031 RB |
122 | /** Remove ignored files not in index */ |
123 | GIT_CHECKOUT_REMOVE_IGNORED = (1u << 6), | |
124 | ||
ad9a921b | 125 | /** Only update existing files, don't create new ones */ |
cf208031 | 126 | GIT_CHECKOUT_UPDATE_ONLY = (1u << 7), |
ad9a921b | 127 | |
5cf9875a RB |
128 | /** Normally checkout updates index entries as it goes; this stops that */ |
129 | GIT_CHECKOUT_DONT_UPDATE_INDEX = (1u << 8), | |
130 | ||
7e5c8a5b | 131 | /** Don't refresh index/config/etc before doing checkout */ |
5cf9875a | 132 | GIT_CHECKOUT_NO_REFRESH = (1u << 9), |
7e5c8a5b | 133 | |
0f3def71 RB |
134 | /** |
135 | * THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED | |
136 | */ | |
137 | ||
138 | /** Allow checkout to skip unmerged files (NOT IMPLEMENTED) */ | |
ad9a921b | 139 | GIT_CHECKOUT_SKIP_UNMERGED = (1u << 10), |
0f3def71 | 140 | /** For unmerged files, checkout stage 2 from index (NOT IMPLEMENTED) */ |
ad9a921b | 141 | GIT_CHECKOUT_USE_OURS = (1u << 11), |
0f3def71 | 142 | /** For unmerged files, checkout stage 3 from index (NOT IMPLEMENTED) */ |
ad9a921b RB |
143 | GIT_CHECKOUT_USE_THEIRS = (1u << 12), |
144 | ||
0f3def71 | 145 | /** Recursively checkout submodules with same options (NOT IMPLEMENTED) */ |
ad9a921b | 146 | GIT_CHECKOUT_UPDATE_SUBMODULES = (1u << 16), |
0f3def71 | 147 | /** Recursively checkout submodules if HEAD moved in super repo (NOT IMPLEMENTED) */ |
ad9a921b | 148 | GIT_CHECKOUT_UPDATE_SUBMODULES_IF_CHANGED = (1u << 17), |
ef9905c9 | 149 | |
0d64bef9 | 150 | } git_checkout_strategy_t; |
ef9905c9 | 151 | |
cf208031 RB |
152 | /** |
153 | * Checkout notification flags | |
154 | * | |
77cffa31 RB |
155 | * Checkout will invoke an options notification callback (`notify_cb`) for |
156 | * certain cases - you pick which ones via `notify_flags`: | |
157 | * | |
158 | * - GIT_CHECKOUT_NOTIFY_CONFLICT invokes checkout on conflicting paths. | |
159 | * | |
160 | * - GIT_CHECKOUT_NOTIFY_DIRTY notifies about "dirty" files, i.e. those that | |
161 | * do not need an update but no longer match the baseline. Core git | |
162 | * displays these files when checkout runs, but won't stop the checkout. | |
163 | * | |
164 | * - GIT_CHECKOUT_NOTIFY_UPDATED sends notification for any file changed. | |
165 | * | |
166 | * - GIT_CHECKOUT_NOTIFY_UNTRACKED notifies about untracked files. | |
167 | * | |
168 | * - GIT_CHECKOUT_NOTIFY_IGNORED notifies about ignored files. | |
169 | * | |
170 | * Returning a non-zero value from this callback will cancel the checkout. | |
171 | * Notification callbacks are made prior to modifying any files on disk. | |
cf208031 RB |
172 | */ |
173 | typedef enum { | |
7e5c8a5b RB |
174 | GIT_CHECKOUT_NOTIFY_NONE = 0, |
175 | GIT_CHECKOUT_NOTIFY_CONFLICT = (1u << 0), | |
176 | GIT_CHECKOUT_NOTIFY_DIRTY = (1u << 1), | |
177 | GIT_CHECKOUT_NOTIFY_UPDATED = (1u << 2), | |
cf208031 | 178 | GIT_CHECKOUT_NOTIFY_UNTRACKED = (1u << 3), |
7e5c8a5b | 179 | GIT_CHECKOUT_NOTIFY_IGNORED = (1u << 4), |
cf208031 RB |
180 | } git_checkout_notify_t; |
181 | ||
77cffa31 RB |
182 | /** Checkout notification callback function */ |
183 | typedef int (*git_checkout_notify_cb)( | |
184 | git_checkout_notify_t why, | |
185 | const char *path, | |
186 | const git_diff_file *baseline, | |
187 | const git_diff_file *target, | |
188 | const git_diff_file *workdir, | |
189 | void *payload); | |
190 | ||
191 | /** Checkout progress notification function */ | |
192 | typedef void (*git_checkout_progress_cb)( | |
193 | const char *path, | |
194 | size_t completed_steps, | |
195 | size_t total_steps, | |
196 | void *payload); | |
197 | ||
fe67e404 RB |
198 | /** |
199 | * Checkout options structure | |
200 | * | |
77cffa31 RB |
201 | * Zero out for defaults. Initialize with `GIT_CHECKOUT_OPTS_INIT` macro to |
202 | * correctly set the `version` field. E.g. | |
cfbe4be3 VM |
203 | * |
204 | * git_checkout_opts opts = GIT_CHECKOUT_OPTS_INIT; | |
fe67e404 | 205 | */ |
ef9905c9 | 206 | typedef struct git_checkout_opts { |
cfbe4be3 | 207 | unsigned int version; |
cf208031 | 208 | |
ad9a921b RB |
209 | unsigned int checkout_strategy; /** default will be a dry run */ |
210 | ||
cf208031 RB |
211 | int disable_filters; /** don't apply filters like CRLF conversion */ |
212 | unsigned int dir_mode; /** default is 0755 */ | |
213 | unsigned int file_mode; /** default is 0644 or 0755 as dictated by blob */ | |
214 | int file_open_flags; /** default is O_CREAT | O_TRUNC | O_WRONLY */ | |
3aa443a9 | 215 | |
cf208031 | 216 | unsigned int notify_flags; /** see `git_checkout_notify_t` above */ |
77cffa31 | 217 | git_checkout_notify_cb notify_cb; |
cf208031 | 218 | void *notify_payload; |
9e592583 | 219 | |
2c8bbb27 | 220 | /* Optional callback to notify the consumer of checkout progress. */ |
77cffa31 | 221 | git_checkout_progress_cb progress_cb; |
2c8bbb27 BS |
222 | void *progress_payload; |
223 | ||
ad9a921b RB |
224 | /** When not zeroed out, array of fnmatch patterns specifying which |
225 | * paths should be taken into account, otherwise all files. | |
3aa443a9 | 226 | */ |
ad9a921b | 227 | git_strarray paths; |
cf208031 RB |
228 | |
229 | git_tree *baseline; /** expected content of workdir, defaults to HEAD */ | |
ef9905c9 BS |
230 | } git_checkout_opts; |
231 | ||
bde336ea | 232 | #define GIT_CHECKOUT_OPTS_VERSION 1 |
fac43c54 | 233 | #define GIT_CHECKOUT_OPTS_INIT {GIT_CHECKOUT_OPTS_VERSION} |
cfbe4be3 | 234 | |
ef9905c9 | 235 | /** |
cf208031 RB |
236 | * Updates files in the index and the working tree to match the content of |
237 | * the commit pointed at by HEAD. | |
ef9905c9 BS |
238 | * |
239 | * @param repo repository to check out (must be non-bare) | |
240 | * @param opts specifies checkout options (may be NULL) | |
8b05bea8 | 241 | * @return 0 on success, GIT_EORPHANEDHEAD when HEAD points to a non existing |
242 | * branch, GIT_ERROR otherwise (use giterr_last for information | |
746642a6 | 243 | * about the error) |
ef9905c9 | 244 | */ |
746642a6 | 245 | GIT_EXTERN(int) git_checkout_head( |
246 | git_repository *repo, | |
80642656 | 247 | git_checkout_opts *opts); |
ef9905c9 | 248 | |
e93af304 | 249 | /** |
250 | * Updates files in the working tree to match the content of the index. | |
251 | * | |
bbe6dbec RB |
252 | * @param repo repository into which to check out (must be non-bare) |
253 | * @param index index to be checked out (or NULL to use repository index) | |
e93af304 | 254 | * @param opts specifies checkout options (may be NULL) |
e93af304 | 255 | * @return 0 on success, GIT_ERROR otherwise (use giterr_last for information |
256 | * about the error) | |
257 | */ | |
258 | GIT_EXTERN(int) git_checkout_index( | |
259 | git_repository *repo, | |
bbe6dbec | 260 | git_index *index, |
2c8bbb27 | 261 | git_checkout_opts *opts); |
e93af304 | 262 | |
3aa443a9 | 263 | /** |
264 | * Updates files in the index and working tree to match the content of the | |
265 | * tree pointed at by the treeish. | |
266 | * | |
267 | * @param repo repository to check out (must be non-bare) | |
268 | * @param treeish a commit, tag or tree which content will be used to update | |
269 | * the working directory | |
270 | * @param opts specifies checkout options (may be NULL) | |
3aa443a9 | 271 | * @return 0 on success, GIT_ERROR otherwise (use giterr_last for information |
272 | * about the error) | |
273 | */ | |
274 | GIT_EXTERN(int) git_checkout_tree( | |
275 | git_repository *repo, | |
cfbe4be3 | 276 | const git_object *treeish, |
80642656 | 277 | git_checkout_opts *opts); |
14741d62 BS |
278 | |
279 | /** @} */ | |
280 | GIT_END_DECL | |
281 | #endif |