include/git2/checkout.h

   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 four 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  * In between those are `GIT_CHECKOUT_SAFE` and `GIT_CHECKOUT_SAFE_CREATE`
  44  * both of which only make 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,   | create if SAFE_CREATE |     create file      |
  55  *   baseline present   | notify dirty DELETED  |                      |
  56  * ---------------------|-----------------------|----------------------|
  57  *
  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.
  61  *
  62  *
  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.
  66  *
  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.
  71  *
  72  * To emulate `git checkout -f`, use `GIT_CHECKOUT_FORCE`.
  73  *
  74  * To emulate `git clone` use `GIT_CHECKOUT_SAFE_CREATE` in the options.
  75  *
  76  *
  77  * There are some additional flags to modified the behavior of checkout:
  78  *
  79  * - GIT_CHECKOUT_ALLOW_CONFLICTS makes SAFE mode apply safe file updates
  80  *   even if there are conflicts (instead of cancelling the checkout).
  81  *
  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.
  84  *
  85  * - GIT_CHECKOUT_REMOVE_IGNORED means remove ignored files (that are also
  86  *   untracked) 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.
  91  *
  92  * - GIT_CHECKOUT_DONT_UPDATE_INDEX prevents checkout from writing the
  93  *   updated files' information to the index.
  94  *
  95  * - Normally, checkout will reload the index and git attributes from disk
  96  *   before any operations.  GIT_CHECKOUT_NO_REFRESH prevents this reload.
  97  *
  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 proceed with the checkout using either the
 101  *   stage 2 ("ours") or stage 3 ("theirs") version of files in the index.
 102  */
 103 typedef enum {
 104         GIT_CHECKOUT_NONE = 0, /** default is a dry run, no actual updates */
 105
 106         /** Allow safe updates that cannot overwrite uncommitted data */
 107         GIT_CHECKOUT_SAFE = (1u << 0),
 108
 109         /** Allow safe updates plus creation of missing files */
 110         GIT_CHECKOUT_SAFE_CREATE = (1u << 1),
 111
 112         /** Allow all updates to force working directory to look like index */
 113         GIT_CHECKOUT_FORCE = (1u << 2),
 114
 115
 116         /** Allow checkout to make safe updates even if conflicts are found */
 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
 122         /** Remove ignored files not in index */
 123         GIT_CHECKOUT_REMOVE_IGNORED = (1u << 6),
 124
 125         /** Only update existing files, don't create new ones */
 126         GIT_CHECKOUT_UPDATE_ONLY = (1u << 7),
 127
 128         /** Normally checkout updates index entries as it goes; this stops that */
 129         GIT_CHECKOUT_DONT_UPDATE_INDEX = (1u << 8),
 130
 131         /** Don't refresh index/config/etc before doing checkout */
 132         GIT_CHECKOUT_NO_REFRESH = (1u << 9),
 133
 134         /** Treat pathspec as simple list of exact match file paths */
 135         GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH = (1u << 13),
 136
 137         /** Ignore directories in use, they will be left empty */
 138         GIT_CHECKOUT_SKIP_LOCKED_DIRECTORIES = (1u << 18),
 139
 140         /**
 141          * THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED
 142          */
 143
 144         /** Allow checkout to skip unmerged files (NOT IMPLEMENTED) */
 145         GIT_CHECKOUT_SKIP_UNMERGED = (1u << 10),
 146         /** For unmerged files, checkout stage 2 from index (NOT IMPLEMENTED) */
 147         GIT_CHECKOUT_USE_OURS = (1u << 11),
 148         /** For unmerged files, checkout stage 3 from index (NOT IMPLEMENTED) */
 149         GIT_CHECKOUT_USE_THEIRS = (1u << 12),
 150
 151         /** Recursively checkout submodules with same options (NOT IMPLEMENTED) */
 152         GIT_CHECKOUT_UPDATE_SUBMODULES = (1u << 16),
 153         /** Recursively checkout submodules if HEAD moved in super repo (NOT IMPLEMENTED) */
 154         GIT_CHECKOUT_UPDATE_SUBMODULES_IF_CHANGED = (1u << 17),
 155
 156 } git_checkout_strategy_t;
 157
 158 /**
 159  * Checkout notification flags
 160  *
 161  * Checkout will invoke an options notification callback (`notify_cb`) for
 162  * certain cases - you pick which ones via `notify_flags`:
 163  *
 164  * - GIT_CHECKOUT_NOTIFY_CONFLICT invokes checkout on conflicting paths.
 165  *
 166  * - GIT_CHECKOUT_NOTIFY_DIRTY notifies about "dirty" files, i.e. those that
 167  *   do not need an update but no longer match the baseline.  Core git
 168  *   displays these files when checkout runs, but won't stop the checkout.
 169  *
 170  * - GIT_CHECKOUT_NOTIFY_UPDATED sends notification for any file changed.
 171  *
 172  * - GIT_CHECKOUT_NOTIFY_UNTRACKED notifies about untracked files.
 173  *
 174  * - GIT_CHECKOUT_NOTIFY_IGNORED notifies about ignored files.
 175  *
 176  * Returning a non-zero value from this callback will cancel the checkout.
 177  * Notification callbacks are made prior to modifying any files on disk.
 178  */
 179 typedef enum {
 180         GIT_CHECKOUT_NOTIFY_NONE      = 0,
 181         GIT_CHECKOUT_NOTIFY_CONFLICT  = (1u << 0),
 182         GIT_CHECKOUT_NOTIFY_DIRTY     = (1u << 1),
 183         GIT_CHECKOUT_NOTIFY_UPDATED   = (1u << 2),
 184         GIT_CHECKOUT_NOTIFY_UNTRACKED = (1u << 3),
 185         GIT_CHECKOUT_NOTIFY_IGNORED   = (1u << 4),
 186
 187         GIT_CHECKOUT_NOTIFY_ALL       = 0x0FFFFu
 188 } git_checkout_notify_t;
 189
 190 /** Checkout notification callback function */
 191 typedef int (*git_checkout_notify_cb)(
 192         git_checkout_notify_t why,
 193         const char *path,
 194         const git_diff_file *baseline,
 195         const git_diff_file *target,
 196         const git_diff_file *workdir,
 197         void *payload);
 198
 199 /** Checkout progress notification function */
 200 typedef void (*git_checkout_progress_cb)(
 201         const char *path,
 202         size_t completed_steps,
 203         size_t total_steps,
 204         void *payload);
 205
 206 /**
 207  * Checkout options structure
 208  *
 209  * Zero out for defaults.  Initialize with `GIT_CHECKOUT_OPTS_INIT` macro to
 210  * correctly set the `version` field.  E.g.
 211  *
 212  *              git_checkout_opts opts = GIT_CHECKOUT_OPTS_INIT;
 213  */
 214 typedef struct git_checkout_opts {
 215         unsigned int version;
 216
 217         unsigned int checkout_strategy; /** default will be a dry run */
 218
 219         int disable_filters;    /** don't apply filters like CRLF conversion */
 220         unsigned int dir_mode;  /** default is 0755 */
 221         unsigned int file_mode; /** default is 0644 or 0755 as dictated by blob */
 222         int file_open_flags;    /** default is O_CREAT | O_TRUNC | O_WRONLY */
 223
 224         unsigned int notify_flags; /** see `git_checkout_notify_t` above */
 225         git_checkout_notify_cb notify_cb;
 226         void *notify_payload;
 227
 228         /* Optional callback to notify the consumer of checkout progress. */
 229         git_checkout_progress_cb progress_cb;
 230         void *progress_payload;
 231
 232         /** When not zeroed out, array of fnmatch patterns specifying which
 233          *  paths should be taken into account, otherwise all files.  Use
 234          *  GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as simple list.
 235          */
 236         git_strarray paths;
 237
 238         git_tree *baseline; /** expected content of workdir, defaults to HEAD */
 239
 240         const char *target_directory; /** alternative checkout path to workdir */
 241 } git_checkout_opts;
 242
 243 #define GIT_CHECKOUT_OPTS_VERSION 1
 244 #define GIT_CHECKOUT_OPTS_INIT {GIT_CHECKOUT_OPTS_VERSION}
 245
 246 /**
 247  * Updates files in the index and the working tree to match the content of
 248  * the commit pointed at by HEAD.
 249  *
 250  * @param repo repository to check out (must be non-bare)
 251  * @param opts specifies checkout options (may be NULL)
 252  * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
 253  * branch, GIT_ERROR otherwise (use giterr_last for information
 254  * about the error)
 255  */
 256 GIT_EXTERN(int) git_checkout_head(
 257         git_repository *repo,
 258         git_checkout_opts *opts);
 259
 260 /**
 261  * Updates files in the working tree to match the content of the index.
 262  *
 263  * @param repo repository into which to check out (must be non-bare)
 264  * @param index index to be checked out (or NULL to use repository index)
 265  * @param opts specifies checkout options (may be NULL)
 266  * @return 0 on success, GIT_ERROR otherwise (use giterr_last for information
 267  * about the error)
 268  */
 269 GIT_EXTERN(int) git_checkout_index(
 270         git_repository *repo,
 271         git_index *index,
 272         git_checkout_opts *opts);
 273
 274 /**
 275  * Updates files in the index and working tree to match the content of the
 276  * tree pointed at by the treeish.
 277  *
 278  * @param repo repository to check out (must be non-bare)
 279  * @param treeish a commit, tag or tree which content will be used to update
 280  * the working directory
 281  * @param opts specifies checkout options (may be NULL)
 282  * @return 0 on success, GIT_ERROR otherwise (use giterr_last for information
 283  * about the error)
 284  */
 285 GIT_EXTERN(int) git_checkout_tree(
 286         git_repository *repo,
 287         const git_object *treeish,
 288         git_checkout_opts *opts);
 289
 290 /** @} */
 291 GIT_END_DECL
 292 #endif