1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 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" 12 #include "diff.h" 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 23 /** 24 * Checkout behavior flags 25 * 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. 29 * 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. 33 * 34 * You give checkout one of three strategies for update: 35 * 36 * - `GIT_CHECKOUT_NONE` is a dry-run strategy that checks for conflicts, 37 * etc., but doesn't make any actual changes. 38 * 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). 42 * 43 * - `GIT_CHECKOUT_SAFE` is between these two options, it will only make 44 * modifications that will not lose changes. 45 * 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, | notify dirty DELETED | create file | 55 * baseline present | | | 56 * ---------------------|-----------------------|----------------------| 57 * 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. 61 * 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. 66 * 67 * To emulate `git checkout -f`, use `GIT_CHECKOUT_FORCE`. 68 * 69 * 70 * There are some additional flags to modify the behavior of checkout: 71 * 72 * - GIT_CHECKOUT_ALLOW_CONFLICTS makes SAFE mode apply safe file updates 73 * even if there are conflicts (instead of cancelling the checkout). 74 * 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. 77 * 78 * - GIT_CHECKOUT_REMOVE_IGNORED means remove ignored files (that are also 79 * untracked) from the working directory as well. 80 * 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. 84 * 85 * - GIT_CHECKOUT_DONT_UPDATE_INDEX prevents checkout from writing the 86 * updated files' information to the index. 87 * 88 * - Normally, checkout will reload the index and git attributes from disk 89 * before any operations. GIT_CHECKOUT_NO_REFRESH prevents this reload. 90 * 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. 95 * 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. 100 * 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. 105 */ 106 typedef enum { 107 GIT_CHECKOUT_NONE = 0, /**< default is a dry run, no actual updates */ 108 109 /** 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. 113 * 114 * Mutually exclusive with GIT_CHECKOUT_FORCE. 115 * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE. 116 */ 117 GIT_CHECKOUT_SAFE = (1u << 0), 118 119 /** 120 * Allow all updates to force working directory to look like index. 121 * 122 * Mutually exclusive with GIT_CHECKOUT_SAFE. 123 * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE. 124 */ 125 GIT_CHECKOUT_FORCE = (1u << 1), 126 127 128 /** Allow checkout to recreate missing files */ 129 GIT_CHECKOUT_RECREATE_MISSING = (1u << 2), 130 131 /** Allow checkout to make safe updates even if conflicts are found */ 132 GIT_CHECKOUT_ALLOW_CONFLICTS = (1u << 4), 133 134 /** Remove untracked files not in index (that are not ignored) */ 135 GIT_CHECKOUT_REMOVE_UNTRACKED = (1u << 5), 136 137 /** Remove ignored files not in index */ 138 GIT_CHECKOUT_REMOVE_IGNORED = (1u << 6), 139 140 /** Only update existing files, don't create new ones */ 141 GIT_CHECKOUT_UPDATE_ONLY = (1u << 7), 142 143 /** 144 * Normally checkout updates index entries as it goes; this stops that. 145 * Implies `GIT_CHECKOUT_DONT_WRITE_INDEX`. 146 */ 147 GIT_CHECKOUT_DONT_UPDATE_INDEX = (1u << 8), 148 149 /** Don't refresh index/config/etc before doing checkout */ 150 GIT_CHECKOUT_NO_REFRESH = (1u << 9), 151 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), 158 159 /** Treat pathspec as simple list of exact match file paths */ 160 GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH = (1u << 13), 161 162 /** Ignore directories in use, they will be left empty */ 163 GIT_CHECKOUT_SKIP_LOCKED_DIRECTORIES = (1u << 18), 164 165 /** Don't overwrite ignored files that exist in the checkout target */ 166 GIT_CHECKOUT_DONT_OVERWRITE_IGNORED = (1u << 19), 167 168 /** Write normal merge files for conflicts */ 169 GIT_CHECKOUT_CONFLICT_STYLE_MERGE = (1u << 20), 170 171 /** Include common ancestor data in diff3 format files for conflicts */ 172 GIT_CHECKOUT_CONFLICT_STYLE_DIFF3 = (1u << 21), 173 174 /** Don't overwrite existing files or folders */ 175 GIT_CHECKOUT_DONT_REMOVE_EXISTING = (1u << 22), 176 177 /** Normally checkout writes the index upon completion; this prevents that. */ 178 GIT_CHECKOUT_DONT_WRITE_INDEX = (1u << 23), 179 180 /** 181 * THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED 182 */ 183 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), 188 189 } git_checkout_strategy_t; 190 191 /** 192 * Checkout notification flags 193 * 194 * Checkout will invoke an options notification callback (`notify_cb`) for 195 * certain cases - you pick which ones via `notify_flags`: 196 * 197 * - GIT_CHECKOUT_NOTIFY_CONFLICT invokes checkout on conflicting paths. 198 * 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. 202 * 203 * - GIT_CHECKOUT_NOTIFY_UPDATED sends notification for any file changed. 204 * 205 * - GIT_CHECKOUT_NOTIFY_UNTRACKED notifies about untracked files. 206 * 207 * - GIT_CHECKOUT_NOTIFY_IGNORED notifies about ignored files. 208 * 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. 212 * 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 215 * being modified. 216 */ 217 typedef enum { 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), 224 225 GIT_CHECKOUT_NOTIFY_ALL = 0x0FFFFu 226 } git_checkout_notify_t; 227 228 /** Checkout performance-reporting structure */ 229 typedef struct { 230 size_t mkdir_calls; 231 size_t stat_calls; 232 size_t chmod_calls; 233 } git_checkout_perfdata; 234 235 /** Checkout notification callback function */ 236 typedef int GIT_CALLBACK(git_checkout_notify_cb)( 237 git_checkout_notify_t why, 238 const char *path, 239 const git_diff_file *baseline, 240 const git_diff_file *target, 241 const git_diff_file *workdir, 242 void *payload); 243 244 /** Checkout progress notification function */ 245 typedef void GIT_CALLBACK(git_checkout_progress_cb)( 246 const char *path, 247 size_t completed_steps, 248 size_t total_steps, 249 void *payload); 250 251 /** Checkout perfdata notification function */ 252 typedef void GIT_CALLBACK(git_checkout_perfdata_cb)( 253 const git_checkout_perfdata *perfdata, 254 void *payload); 255 256 /** 257 * Checkout options structure 258 * 259 * Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can 260 * use `git_checkout_options_init`. 261 * 262 */ 263 typedef struct git_checkout_options { 264 unsigned int version; /**< The version */ 265 266 unsigned int checkout_strategy; /**< default will be a safe checkout */ 267 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 */ 272 273 unsigned int notify_flags; /**< see `git_checkout_notify_t` above */ 274 275 /** 276 * Optional callback to get notifications on specific file states. 277 * @see git_checkout_notify_t 278 */ 279 git_checkout_notify_cb notify_cb; 280 281 /** Payload passed to notify_cb */ 282 void *notify_payload; 283 284 /** Optional callback to notify the consumer of checkout progress. */ 285 git_checkout_progress_cb progress_cb; 286 287 /** Payload passed to progress_cb */ 288 void *progress_payload; 289 290 /** 291 * A list of wildmatch patterns or paths. 292 * 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 295 * account. 296 * 297 * Use GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as a simple list. 298 */ 299 git_strarray paths; 300 301 /** 302 * The expected content of the working directory; defaults to HEAD. 303 * 304 * If the working directory does not match this baseline information, 305 * that will produce a checkout conflict. 306 */ 307 git_tree *baseline; 308 309 /** 310 * Like `baseline` above, though expressed as an index. This 311 * option overrides `baseline`. 312 */ 313 git_index *baseline_index; 314 315 const char *target_directory; /**< alternative checkout path to workdir */ 316 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 */ 320 321 /** Optional callback to notify the consumer of performance data. */ 322 git_checkout_perfdata_cb perfdata_cb; 323 324 /** Payload passed to perfdata_cb */ 325 void *perfdata_payload; 326 } git_checkout_options; 327 328 #define GIT_CHECKOUT_OPTIONS_VERSION 1 329 #define GIT_CHECKOUT_OPTIONS_INIT {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE} 330 331 /** 332 * Initialize git_checkout_options structure 333 * 334 * Initializes a `git_checkout_options` with default values. Equivalent to creating 335 * an instance with GIT_CHECKOUT_OPTIONS_INIT. 336 * 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. 340 */ 341 GIT_EXTERN(int) git_checkout_options_init( 342 git_checkout_options *opts, 343 unsigned int version); 344 345 /** 346 * Updates files in the index and the working tree to match the content of 347 * the commit pointed at by HEAD. 348 * 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. 355 * 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) 361 */ 362 GIT_EXTERN(int) git_checkout_head( 363 git_repository *repo, 364 const git_checkout_options *opts); 365 366 /** 367 * Updates files in the working tree to match the content of the index. 368 * 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) 374 */ 375 GIT_EXTERN(int) git_checkout_index( 376 git_repository *repo, 377 git_index *index, 378 const git_checkout_options *opts); 379 380 /** 381 * Updates files in the index and working tree to match the content of the 382 * tree pointed at by the treeish. 383 * 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) 390 */ 391 GIT_EXTERN(int) git_checkout_tree( 392 git_repository *repo, 393 const git_object *treeish, 394 const git_checkout_options *opts); 395 396 /** @} */ 397 GIT_END_DECL 398 #endif 399