2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
7 #ifndef INCLUDE_git_checkout_h__
8 #define INCLUDE_git_checkout_h__
15 * @file git2/checkout.h
16 * @brief Git checkout routines
17 * @defgroup git_checkout Git checkout routines
24 * Checkout behavior flags
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.
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.
34 * You give checkout one of three strategies for update:
36 * - `GIT_CHECKOUT_NONE` is a dry-run strategy that checks for conflicts,
37 * etc., but doesn't make any actual changes.
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).
43 * - `GIT_CHECKOUT_SAFE` is between these two options, it will only make
44 * modifications that will not lose changes.
46 * | target == baseline | target != baseline |
47 * ---------------------|-----------------------|----------------------|
48 * workdir == baseline | no action | create, update, or |
50 * ---------------------|-----------------------|----------------------|
51 * workdir exists and | no action | conflict (notify |
52 * is != baseline | notify dirty MODIFIED | and cancel checkout) |
53 * ---------------------|-----------------------|----------------------|
54 * workdir missing, | notify dirty DELETED | create file |
55 * baseline present | | |
56 * ---------------------|-----------------------|----------------------|
58 * To emulate `git checkout`, use `GIT_CHECKOUT_SAFE` with a checkout
59 * notification callback (see below) that displays information about dirty
60 * files. The default behavior will cancel checkout on conflicts.
62 * To emulate `git checkout-index`, use `GIT_CHECKOUT_SAFE` with a
63 * notification callback that cancels the operation if a dirty-but-existing
64 * file is found in the working directory. This core git command isn't
65 * quite "force" but is sensitive about some types of changes.
67 * To emulate `git checkout -f`, use `GIT_CHECKOUT_FORCE`.
70 * There are some additional flags to modify the behavior of checkout:
72 * - GIT_CHECKOUT_ALLOW_CONFLICTS makes SAFE mode apply safe file updates
73 * even if there are conflicts (instead of cancelling the checkout).
75 * - GIT_CHECKOUT_REMOVE_UNTRACKED means remove untracked files (i.e. not
76 * in target, baseline, or index, and not ignored) from the working dir.
78 * - GIT_CHECKOUT_REMOVE_IGNORED means remove ignored files (that are also
79 * untracked) from the working directory as well.
81 * - GIT_CHECKOUT_UPDATE_ONLY means to only update the content of files that
82 * already exist. Files will not be created nor deleted. This just skips
83 * applying adds, deletes, and typechanges.
85 * - GIT_CHECKOUT_DONT_UPDATE_INDEX prevents checkout from writing the
86 * updated files' information to the index.
88 * - Normally, checkout will reload the index and git attributes from disk
89 * before any operations. GIT_CHECKOUT_NO_REFRESH prevents this reload.
91 * - Unmerged index entries are conflicts. GIT_CHECKOUT_SKIP_UNMERGED skips
92 * files with unmerged index entries instead. GIT_CHECKOUT_USE_OURS and
93 * GIT_CHECKOUT_USE_THEIRS to proceed with the checkout using either the
94 * stage 2 ("ours") or stage 3 ("theirs") version of files in the index.
96 * - GIT_CHECKOUT_DONT_OVERWRITE_IGNORED prevents ignored files from being
97 * overwritten. Normally, files that are ignored in the working directory
98 * are not considered "precious" and may be overwritten if the checkout
99 * target contains that file.
101 * - GIT_CHECKOUT_DONT_REMOVE_EXISTING prevents checkout from removing
102 * files or folders that fold to the same name on case insensitive
103 * filesystems. This can cause files to retain their existing names
104 * and write through existing symbolic links.
107 GIT_CHECKOUT_NONE
= 0, /**< default is a dry run, no actual updates */
110 * Allow safe updates that cannot overwrite uncommitted data.
111 * If the uncommitted changes don't conflict with the checked out files,
112 * the checkout will still proceed, leaving the changes intact.
114 * Mutually exclusive with GIT_CHECKOUT_FORCE.
115 * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE.
117 GIT_CHECKOUT_SAFE
= (1u << 0),
120 * Allow all updates to force working directory to look like index.
122 * Mutually exclusive with GIT_CHECKOUT_SAFE.
123 * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE.
125 GIT_CHECKOUT_FORCE
= (1u << 1),
128 /** Allow checkout to recreate missing files */
129 GIT_CHECKOUT_RECREATE_MISSING
= (1u << 2),
131 /** Allow checkout to make safe updates even if conflicts are found */
132 GIT_CHECKOUT_ALLOW_CONFLICTS
= (1u << 4),
134 /** Remove untracked files not in index (that are not ignored) */
135 GIT_CHECKOUT_REMOVE_UNTRACKED
= (1u << 5),
137 /** Remove ignored files not in index */
138 GIT_CHECKOUT_REMOVE_IGNORED
= (1u << 6),
140 /** Only update existing files, don't create new ones */
141 GIT_CHECKOUT_UPDATE_ONLY
= (1u << 7),
144 * Normally checkout updates index entries as it goes; this stops that.
145 * Implies `GIT_CHECKOUT_DONT_WRITE_INDEX`.
147 GIT_CHECKOUT_DONT_UPDATE_INDEX
= (1u << 8),
149 /** Don't refresh index/config/etc before doing checkout */
150 GIT_CHECKOUT_NO_REFRESH
= (1u << 9),
152 /** Allow checkout to skip unmerged files */
153 GIT_CHECKOUT_SKIP_UNMERGED
= (1u << 10),
154 /** For unmerged files, checkout stage 2 from index */
155 GIT_CHECKOUT_USE_OURS
= (1u << 11),
156 /** For unmerged files, checkout stage 3 from index */
157 GIT_CHECKOUT_USE_THEIRS
= (1u << 12),
159 /** Treat pathspec as simple list of exact match file paths */
160 GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH
= (1u << 13),
162 /** Ignore directories in use, they will be left empty */
163 GIT_CHECKOUT_SKIP_LOCKED_DIRECTORIES
= (1u << 18),
165 /** Don't overwrite ignored files that exist in the checkout target */
166 GIT_CHECKOUT_DONT_OVERWRITE_IGNORED
= (1u << 19),
168 /** Write normal merge files for conflicts */
169 GIT_CHECKOUT_CONFLICT_STYLE_MERGE
= (1u << 20),
171 /** Include common ancestor data in diff3 format files for conflicts */
172 GIT_CHECKOUT_CONFLICT_STYLE_DIFF3
= (1u << 21),
174 /** Don't overwrite existing files or folders */
175 GIT_CHECKOUT_DONT_REMOVE_EXISTING
= (1u << 22),
177 /** Normally checkout writes the index upon completion; this prevents that. */
178 GIT_CHECKOUT_DONT_WRITE_INDEX
= (1u << 23),
181 * THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED
184 /** Recursively checkout submodules with same options (NOT IMPLEMENTED) */
185 GIT_CHECKOUT_UPDATE_SUBMODULES
= (1u << 16),
186 /** Recursively checkout submodules if HEAD moved in super repo (NOT IMPLEMENTED) */
187 GIT_CHECKOUT_UPDATE_SUBMODULES_IF_CHANGED
= (1u << 17),
189 } git_checkout_strategy_t
;
192 * Checkout notification flags
194 * Checkout will invoke an options notification callback (`notify_cb`) for
195 * certain cases - you pick which ones via `notify_flags`:
197 * - GIT_CHECKOUT_NOTIFY_CONFLICT invokes checkout on conflicting paths.
199 * - GIT_CHECKOUT_NOTIFY_DIRTY notifies about "dirty" files, i.e. those that
200 * do not need an update but no longer match the baseline. Core git
201 * displays these files when checkout runs, but won't stop the checkout.
203 * - GIT_CHECKOUT_NOTIFY_UPDATED sends notification for any file changed.
205 * - GIT_CHECKOUT_NOTIFY_UNTRACKED notifies about untracked files.
207 * - GIT_CHECKOUT_NOTIFY_IGNORED notifies about ignored files.
209 * Returning a non-zero value from this callback will cancel the checkout.
210 * The non-zero return value will be propagated back and returned by the
211 * git_checkout_... call.
213 * Notification callbacks are made prior to modifying any files on disk,
214 * so canceling on any notification will still happen prior to any files
218 GIT_CHECKOUT_NOTIFY_NONE
= 0,
219 GIT_CHECKOUT_NOTIFY_CONFLICT
= (1u << 0),
220 GIT_CHECKOUT_NOTIFY_DIRTY
= (1u << 1),
221 GIT_CHECKOUT_NOTIFY_UPDATED
= (1u << 2),
222 GIT_CHECKOUT_NOTIFY_UNTRACKED
= (1u << 3),
223 GIT_CHECKOUT_NOTIFY_IGNORED
= (1u << 4),
225 GIT_CHECKOUT_NOTIFY_ALL
= 0x0FFFFu
226 } git_checkout_notify_t
;
228 /** Checkout performance-reporting structure */
233 } git_checkout_perfdata
;
235 /** Checkout notification callback function */
236 typedef int GIT_CALLBACK(git_checkout_notify_cb
)(
237 git_checkout_notify_t why
,
239 const git_diff_file
*baseline
,
240 const git_diff_file
*target
,
241 const git_diff_file
*workdir
,
244 /** Checkout progress notification function */
245 typedef void GIT_CALLBACK(git_checkout_progress_cb
)(
247 size_t completed_steps
,
251 /** Checkout perfdata notification function */
252 typedef void GIT_CALLBACK(git_checkout_perfdata_cb
)(
253 const git_checkout_perfdata
*perfdata
,
257 * Checkout options structure
259 * Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can
260 * use `git_checkout_options_init`.
263 typedef struct git_checkout_options
{
264 unsigned int version
; /**< The version */
266 unsigned int checkout_strategy
; /**< default will be a safe checkout */
268 int disable_filters
; /**< don't apply filters like CRLF conversion */
269 unsigned int dir_mode
; /**< default is 0755 */
270 unsigned int file_mode
; /**< default is 0644 or 0755 as dictated by blob */
271 int file_open_flags
; /**< default is O_CREAT | O_TRUNC | O_WRONLY */
273 unsigned int notify_flags
; /**< see `git_checkout_notify_t` above */
276 * Optional callback to get notifications on specific file states.
277 * @see git_checkout_notify_t
279 git_checkout_notify_cb notify_cb
;
281 /** Payload passed to notify_cb */
282 void *notify_payload
;
284 /** Optional callback to notify the consumer of checkout progress. */
285 git_checkout_progress_cb progress_cb
;
287 /** Payload passed to progress_cb */
288 void *progress_payload
;
291 * A list of wildmatch patterns or paths.
293 * By default, all paths are processed. If you pass an array of wildmatch
294 * patterns, those will be used to filter which paths should be taken into
297 * Use GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as a simple list.
302 * The expected content of the working directory; defaults to HEAD.
304 * If the working directory does not match this baseline information,
305 * that will produce a checkout conflict.
310 * Like `baseline` above, though expressed as an index. This
311 * option overrides `baseline`.
313 git_index
*baseline_index
;
315 const char *target_directory
; /**< alternative checkout path to workdir */
317 const char *ancestor_label
; /**< the name of the common ancestor side of conflicts */
318 const char *our_label
; /**< the name of the "our" side of conflicts */
319 const char *their_label
; /**< the name of the "their" side of conflicts */
321 /** Optional callback to notify the consumer of performance data. */
322 git_checkout_perfdata_cb perfdata_cb
;
324 /** Payload passed to perfdata_cb */
325 void *perfdata_payload
;
326 } git_checkout_options
;
328 #define GIT_CHECKOUT_OPTIONS_VERSION 1
329 #define GIT_CHECKOUT_OPTIONS_INIT {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE}
332 * Initialize git_checkout_options structure
334 * Initializes a `git_checkout_options` with default values. Equivalent to creating
335 * an instance with GIT_CHECKOUT_OPTIONS_INIT.
337 * @param opts The `git_checkout_options` struct to initialize.
338 * @param version The struct version; pass `GIT_CHECKOUT_OPTIONS_VERSION`.
339 * @return Zero on success; -1 on failure.
341 GIT_EXTERN(int) git_checkout_options_init(
342 git_checkout_options
*opts
,
343 unsigned int version
);
346 * Updates files in the index and the working tree to match the content of
347 * the commit pointed at by HEAD.
349 * Note that this is _not_ the correct mechanism used to switch branches;
350 * do not change your `HEAD` and then call this method, that would leave
351 * you with checkout conflicts since your working directory would then
352 * appear to be dirty. Instead, checkout the target of the branch and
353 * then update `HEAD` using `git_repository_set_head` to point to the
354 * branch you checked out.
356 * @param repo repository to check out (must be non-bare)
357 * @param opts specifies checkout options (may be NULL)
358 * @return 0 on success, GIT_EUNBORNBRANCH if HEAD points to a non
359 * existing branch, non-zero value returned by `notify_cb`, or
360 * other error code < 0 (use git_error_last for error details)
362 GIT_EXTERN(int) git_checkout_head(
363 git_repository
*repo
,
364 const git_checkout_options
*opts
);
367 * Updates files in the working tree to match the content of the index.
369 * @param repo repository into which to check out (must be non-bare)
370 * @param index index to be checked out (or NULL to use repository index)
371 * @param opts specifies checkout options (may be NULL)
372 * @return 0 on success, non-zero return value from `notify_cb`, or error
373 * code < 0 (use git_error_last for error details)
375 GIT_EXTERN(int) git_checkout_index(
376 git_repository
*repo
,
378 const git_checkout_options
*opts
);
381 * Updates files in the index and working tree to match the content of the
382 * tree pointed at by the treeish.
384 * @param repo repository to check out (must be non-bare)
385 * @param treeish a commit, tag or tree which content will be used to update
386 * the working directory (or NULL to use HEAD)
387 * @param opts specifies checkout options (may be NULL)
388 * @return 0 on success, non-zero return value from `notify_cb`, or error
389 * code < 0 (use git_error_last for error details)
391 GIT_EXTERN(int) git_checkout_tree(
392 git_repository
*repo
,
393 const git_object
*treeish
,
394 const git_checkout_options
*opts
);