]>
Commit | Line | Data |
---|---|---|
14741d62 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
14741d62 BS |
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 | 85 | * - GIT_CHECKOUT_REMOVE_IGNORED means remove ignored files (that are also |
7eb222fc | 86 | * untracked) from the working directory as well. |
77cffa31 RB |
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 | |
7eb222fc | 100 | * GIT_CHECKOUT_USE_THEIRS to proceed with the checkout using either the |
77cffa31 | 101 | * stage 2 ("ours") or stage 3 ("theirs") version of files in the index. |
81a2012d ET |
102 | * |
103 | * - GIT_CHECKOUT_DONT_OVERWRITE_IGNORED prevents ignored files from being | |
104 | * overwritten. Normally, files that are ignored in the working directory | |
105 | * are not considered "precious" and may be overwritten if the checkout | |
106 | * target contains that file. | |
0d64bef9 RB |
107 | */ |
108 | typedef enum { | |
cf208031 | 109 | GIT_CHECKOUT_NONE = 0, /** default is a dry run, no actual updates */ |
ad9a921b | 110 | |
7eb222fc | 111 | /** Allow safe updates that cannot overwrite uncommitted data */ |
cf208031 | 112 | GIT_CHECKOUT_SAFE = (1u << 0), |
ad9a921b | 113 | |
cf208031 RB |
114 | /** Allow safe updates plus creation of missing files */ |
115 | GIT_CHECKOUT_SAFE_CREATE = (1u << 1), | |
fe67e404 | 116 | |
ad9a921b | 117 | /** Allow all updates to force working directory to look like index */ |
cf208031 RB |
118 | GIT_CHECKOUT_FORCE = (1u << 2), |
119 | ||
fe67e404 | 120 | |
cf208031 | 121 | /** Allow checkout to make safe updates even if conflicts are found */ |
ad9a921b RB |
122 | GIT_CHECKOUT_ALLOW_CONFLICTS = (1u << 4), |
123 | ||
124 | /** Remove untracked files not in index (that are not ignored) */ | |
125 | GIT_CHECKOUT_REMOVE_UNTRACKED = (1u << 5), | |
126 | ||
cf208031 RB |
127 | /** Remove ignored files not in index */ |
128 | GIT_CHECKOUT_REMOVE_IGNORED = (1u << 6), | |
129 | ||
ad9a921b | 130 | /** Only update existing files, don't create new ones */ |
cf208031 | 131 | GIT_CHECKOUT_UPDATE_ONLY = (1u << 7), |
ad9a921b | 132 | |
5cf9875a RB |
133 | /** Normally checkout updates index entries as it goes; this stops that */ |
134 | GIT_CHECKOUT_DONT_UPDATE_INDEX = (1u << 8), | |
135 | ||
7e5c8a5b | 136 | /** Don't refresh index/config/etc before doing checkout */ |
5cf9875a | 137 | GIT_CHECKOUT_NO_REFRESH = (1u << 9), |
7e5c8a5b | 138 | |
629b661c ET |
139 | /** Allow checkout to skip unmerged files */ |
140 | GIT_CHECKOUT_SKIP_UNMERGED = (1u << 10), | |
141 | /** For unmerged files, checkout stage 2 from index */ | |
142 | GIT_CHECKOUT_USE_OURS = (1u << 11), | |
143 | /** For unmerged files, checkout stage 3 from index */ | |
144 | GIT_CHECKOUT_USE_THEIRS = (1u << 12), | |
145 | ||
40342bd2 RB |
146 | /** Treat pathspec as simple list of exact match file paths */ |
147 | GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH = (1u << 13), | |
148 | ||
e09d18ee ET |
149 | /** Ignore directories in use, they will be left empty */ |
150 | GIT_CHECKOUT_SKIP_LOCKED_DIRECTORIES = (1u << 18), | |
151 | ||
81a2012d ET |
152 | /** Don't overwrite ignored files that exist in the checkout target */ |
153 | GIT_CHECKOUT_DONT_OVERWRITE_IGNORED = (1u << 19), | |
154 | ||
e651e8e2 ET |
155 | /** Write normal merge files for conflicts */ |
156 | GIT_CHECKOUT_CONFLICT_STYLE_MERGE = (1u << 20), | |
157 | ||
158 | /** Include common ancestor data in diff3 format files for conflicts */ | |
159 | GIT_CHECKOUT_CONFLICT_STYLE_DIFF3 = (1u << 21), | |
160 | ||
0f3def71 RB |
161 | /** |
162 | * THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED | |
163 | */ | |
164 | ||
0f3def71 | 165 | /** Recursively checkout submodules with same options (NOT IMPLEMENTED) */ |
ad9a921b | 166 | GIT_CHECKOUT_UPDATE_SUBMODULES = (1u << 16), |
0f3def71 | 167 | /** Recursively checkout submodules if HEAD moved in super repo (NOT IMPLEMENTED) */ |
ad9a921b | 168 | GIT_CHECKOUT_UPDATE_SUBMODULES_IF_CHANGED = (1u << 17), |
ef9905c9 | 169 | |
0d64bef9 | 170 | } git_checkout_strategy_t; |
ef9905c9 | 171 | |
cf208031 RB |
172 | /** |
173 | * Checkout notification flags | |
174 | * | |
77cffa31 RB |
175 | * Checkout will invoke an options notification callback (`notify_cb`) for |
176 | * certain cases - you pick which ones via `notify_flags`: | |
177 | * | |
178 | * - GIT_CHECKOUT_NOTIFY_CONFLICT invokes checkout on conflicting paths. | |
179 | * | |
180 | * - GIT_CHECKOUT_NOTIFY_DIRTY notifies about "dirty" files, i.e. those that | |
181 | * do not need an update but no longer match the baseline. Core git | |
182 | * displays these files when checkout runs, but won't stop the checkout. | |
183 | * | |
184 | * - GIT_CHECKOUT_NOTIFY_UPDATED sends notification for any file changed. | |
185 | * | |
186 | * - GIT_CHECKOUT_NOTIFY_UNTRACKED notifies about untracked files. | |
187 | * | |
188 | * - GIT_CHECKOUT_NOTIFY_IGNORED notifies about ignored files. | |
189 | * | |
190 | * Returning a non-zero value from this callback will cancel the checkout. | |
cbd04896 RB |
191 | * The non-zero return value will be propagated back and returned by the |
192 | * git_checkout_... call. | |
193 | * | |
194 | * Notification callbacks are made prior to modifying any files on disk, | |
195 | * so canceling on any notification will still happen prior to any files | |
196 | * being modified. | |
cf208031 RB |
197 | */ |
198 | typedef enum { | |
7e5c8a5b RB |
199 | GIT_CHECKOUT_NOTIFY_NONE = 0, |
200 | GIT_CHECKOUT_NOTIFY_CONFLICT = (1u << 0), | |
201 | GIT_CHECKOUT_NOTIFY_DIRTY = (1u << 1), | |
202 | GIT_CHECKOUT_NOTIFY_UPDATED = (1u << 2), | |
cf208031 | 203 | GIT_CHECKOUT_NOTIFY_UNTRACKED = (1u << 3), |
7e5c8a5b | 204 | GIT_CHECKOUT_NOTIFY_IGNORED = (1u << 4), |
36fd9e30 RB |
205 | |
206 | GIT_CHECKOUT_NOTIFY_ALL = 0x0FFFFu | |
cf208031 RB |
207 | } git_checkout_notify_t; |
208 | ||
77cffa31 RB |
209 | /** Checkout notification callback function */ |
210 | typedef int (*git_checkout_notify_cb)( | |
211 | git_checkout_notify_t why, | |
212 | const char *path, | |
213 | const git_diff_file *baseline, | |
214 | const git_diff_file *target, | |
215 | const git_diff_file *workdir, | |
216 | void *payload); | |
217 | ||
218 | /** Checkout progress notification function */ | |
219 | typedef void (*git_checkout_progress_cb)( | |
220 | const char *path, | |
221 | size_t completed_steps, | |
222 | size_t total_steps, | |
223 | void *payload); | |
224 | ||
fe67e404 RB |
225 | /** |
226 | * Checkout options structure | |
227 | * | |
77cffa31 RB |
228 | * Zero out for defaults. Initialize with `GIT_CHECKOUT_OPTS_INIT` macro to |
229 | * correctly set the `version` field. E.g. | |
cfbe4be3 VM |
230 | * |
231 | * git_checkout_opts opts = GIT_CHECKOUT_OPTS_INIT; | |
fe67e404 | 232 | */ |
ef9905c9 | 233 | typedef struct git_checkout_opts { |
cfbe4be3 | 234 | unsigned int version; |
cf208031 | 235 | |
ad9a921b RB |
236 | unsigned int checkout_strategy; /** default will be a dry run */ |
237 | ||
cf208031 RB |
238 | int disable_filters; /** don't apply filters like CRLF conversion */ |
239 | unsigned int dir_mode; /** default is 0755 */ | |
240 | unsigned int file_mode; /** default is 0644 or 0755 as dictated by blob */ | |
241 | int file_open_flags; /** default is O_CREAT | O_TRUNC | O_WRONLY */ | |
3aa443a9 | 242 | |
cf208031 | 243 | unsigned int notify_flags; /** see `git_checkout_notify_t` above */ |
77cffa31 | 244 | git_checkout_notify_cb notify_cb; |
cf208031 | 245 | void *notify_payload; |
9e592583 | 246 | |
2c8bbb27 | 247 | /* Optional callback to notify the consumer of checkout progress. */ |
77cffa31 | 248 | git_checkout_progress_cb progress_cb; |
2c8bbb27 BS |
249 | void *progress_payload; |
250 | ||
ad9a921b | 251 | /** When not zeroed out, array of fnmatch patterns specifying which |
40342bd2 RB |
252 | * paths should be taken into account, otherwise all files. Use |
253 | * GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as simple list. | |
3aa443a9 | 254 | */ |
ad9a921b | 255 | git_strarray paths; |
cf208031 RB |
256 | |
257 | git_tree *baseline; /** expected content of workdir, defaults to HEAD */ | |
9094ae5a RB |
258 | |
259 | const char *target_directory; /** alternative checkout path to workdir */ | |
629b661c | 260 | |
e651e8e2 | 261 | const char *ancestor_label; /** the name of the common ancestor side of conflicts */ |
629b661c ET |
262 | const char *our_label; /** the name of the "our" side of conflicts */ |
263 | const char *their_label; /** the name of the "their" side of conflicts */ | |
ef9905c9 BS |
264 | } git_checkout_opts; |
265 | ||
bde336ea | 266 | #define GIT_CHECKOUT_OPTS_VERSION 1 |
fac43c54 | 267 | #define GIT_CHECKOUT_OPTS_INIT {GIT_CHECKOUT_OPTS_VERSION} |
cfbe4be3 | 268 | |
ef9905c9 | 269 | /** |
cf208031 RB |
270 | * Updates files in the index and the working tree to match the content of |
271 | * the commit pointed at by HEAD. | |
ef9905c9 BS |
272 | * |
273 | * @param repo repository to check out (must be non-bare) | |
274 | * @param opts specifies checkout options (may be NULL) | |
cbd04896 RB |
275 | * @return 0 on success, GIT_EUNBORNBRANCH if HEAD points to a non |
276 | * existing branch, non-zero value returned by `notify_cb`, or | |
277 | * other error code < 0 (use giterr_last for error details) | |
ef9905c9 | 278 | */ |
746642a6 | 279 | GIT_EXTERN(int) git_checkout_head( |
280 | git_repository *repo, | |
eec1c1fe | 281 | const git_checkout_opts *opts); |
ef9905c9 | 282 | |
e93af304 | 283 | /** |
284 | * Updates files in the working tree to match the content of the index. | |
285 | * | |
bbe6dbec RB |
286 | * @param repo repository into which to check out (must be non-bare) |
287 | * @param index index to be checked out (or NULL to use repository index) | |
e93af304 | 288 | * @param opts specifies checkout options (may be NULL) |
cbd04896 RB |
289 | * @return 0 on success, non-zero return value from `notify_cb`, or error |
290 | * code < 0 (use giterr_last for error details) | |
e93af304 | 291 | */ |
292 | GIT_EXTERN(int) git_checkout_index( | |
293 | git_repository *repo, | |
bbe6dbec | 294 | git_index *index, |
10749f6c | 295 | const git_checkout_opts *opts); |
e93af304 | 296 | |
3aa443a9 | 297 | /** |
298 | * Updates files in the index and working tree to match the content of the | |
299 | * tree pointed at by the treeish. | |
300 | * | |
301 | * @param repo repository to check out (must be non-bare) | |
302 | * @param treeish a commit, tag or tree which content will be used to update | |
35221441 | 303 | * the working directory (or NULL to use HEAD) |
3aa443a9 | 304 | * @param opts specifies checkout options (may be NULL) |
cbd04896 RB |
305 | * @return 0 on success, non-zero return value from `notify_cb`, or error |
306 | * code < 0 (use giterr_last for error details) | |
3aa443a9 | 307 | */ |
308 | GIT_EXTERN(int) git_checkout_tree( | |
309 | git_repository *repo, | |
cfbe4be3 | 310 | const git_object *treeish, |
10749f6c | 311 | const git_checkout_opts *opts); |
14741d62 BS |
312 | |
313 | /** @} */ | |
314 | GIT_END_DECL | |
315 | #endif |