/*
* Copyright (C) 2012 the libgit2 contributors
*
* This file is part of libgit2, distributed under the GNU GPL v2 with
* a Linking Exception. For full terms see the included COPYING file.
*/
#ifndef INCLUDE_git_checkout_h__
#define INCLUDE_git_checkout_h__
#include "common.h"
#include "types.h"
#include "indexer.h"
#include "strarray.h"
/**
* @file git2/checkout.h
* @brief Git checkout routines
* @defgroup git_checkout Git checkout routines
* @ingroup Git
* @{
*/
GIT_BEGIN_DECL
/**
* Checkout behavior flags
*
* These flags control what checkout does with files. Pass in a
* combination of these values OR'ed together. If you just pass zero
* (i.e. no flags), then you are effectively doing a "dry run" where no
* files will be modified.
*
* Checkout groups the working directory content into 3 classes of files:
* (1) files that don't need a change, and files that do need a change
* that either (2) we are allowed to modifed or (3) we are not. The flags
* you pass in will decide which files we are allowed to modify.
*
* By default, checkout is not allowed to modify any files. Anything
* needing a change would be considered a conflict.
*
* GIT_CHECKOUT_UPDATE_UNMODIFIED means that checkout is allowed to update
* any file where the working directory content matches the HEAD
* (e.g. either the files match or the file is absent in both places).
*
* GIT_CHECKOUT_UPDATE_MISSING means checkout can create a missing file
* that exists in the index and does not exist in the working directory.
* This is usually desirable for initial checkout, etc. Technically, the
* missing file differs from the HEAD, which is why this is separate.
*
* GIT_CHECKOUT_UPDATE_MODIFIED means checkout is allowed to update files
* where the working directory does not match the HEAD so long as the file
* actually exists in the HEAD. This option implies UPDATE_UNMODIFIED.
*
* GIT_CHECKOUT_UPDATE_UNTRACKED means checkout is allowed to update files
* even if there is a working directory version that does not exist in the
* HEAD (i.e. the file was independently created in the workdir). This
* implies UPDATE_UNMODIFIED | UPDATE_MISSING (but *not* UPDATE_MODIFIED).
*
*
* On top of these three basic strategies, there are some modifiers
* options that can be applied:
*
* If any files need update but are disallowed by the strategy, normally
* checkout calls the conflict callback (if given) and then aborts.
* GIT_CHECKOUT_ALLOW_CONFLICTS means it is okay to update the files that
* are allowed by the strategy even if there are conflicts. The conflict
* callbacks are still made, but non-conflicting files will be updated.
*
* Any unmerged entries in the index are automatically considered conflicts.
* If you want to proceed anyhow and just skip unmerged entries, you can use
* GIT_CHECKOUT_SKIP_UNMERGED which is less dangerous than just allowing all
* conflicts. Alternatively, use GIT_CHECKOUT_USE_OURS to proceed and
* checkout the stage 2 ("ours") version. GIT_CHECKOUT_USE_THEIRS means to
* proceed and use the stage 3 ("theirs") version.
*
* GIT_CHECKOUT_UPDATE_ONLY means that update is not allowed to create new
* files or delete old ones, only update existing content. With this
* flag, files that needs to be created or deleted are not conflicts -
* they are just skipped. This also skips typechanges to existing files
* (because the old would have to be removed).
*
* GIT_CHECKOUT_REMOVE_UNTRACKED means that files in the working directory
* that are untracked (and not ignored) will be removed altogether. These
* untracked files (that do not shadow index entries) are not considered
* conflicts and would normally be ignored.
*
*
* Checkout is "semi-atomic" as in it will go through the work to be done
* before making any changes and if may decide to abort if there are
* conflicts, or you can use the conflict callback to explicitly abort the
* action before any updates are made. Despite this, if a second process
* is modifying the filesystem while checkout is running, it can't
* guarantee that the choices is makes while initially examining the
* filesystem are still going to be correct as it applies them.
*/
typedef enum {
GIT_CHECKOUT_DEFAULT = 0, /** default is a dry run, no actual updates */
/** Allow update of entries where working dir matches HEAD. */
GIT_CHECKOUT_UPDATE_UNMODIFIED = (1u << 0),
/** Allow update of entries where working dir does not have file. */
GIT_CHECKOUT_UPDATE_MISSING = (1u << 1),
/** Allow safe updates that cannot overwrite uncommited data */
GIT_CHECKOUT_SAFE =
(GIT_CHECKOUT_UPDATE_UNMODIFIED | GIT_CHECKOUT_UPDATE_MISSING),
/** Allow update of entries in working dir that are modified from HEAD. */
GIT_CHECKOUT_UPDATE_MODIFIED = (1u << 2),
/** Update existing untracked files that are now present in the index. */
GIT_CHECKOUT_UPDATE_UNTRACKED = (1u << 3),
/** Allow all updates to force working directory to look like index */
GIT_CHECKOUT_FORCE =
(GIT_CHECKOUT_SAFE | GIT_CHECKOUT_UPDATE_MODIFIED | GIT_CHECKOUT_UPDATE_UNTRACKED),
/** Allow checkout to make updates even if conflicts are found */
GIT_CHECKOUT_ALLOW_CONFLICTS = (1u << 4),
/** Remove untracked files not in index (that are not ignored) */
GIT_CHECKOUT_REMOVE_UNTRACKED = (1u << 5),
/** Only update existing files, don't create new ones */
GIT_CHECKOUT_UPDATE_ONLY = (1u << 6),
/**
* THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED
*/
/** Allow checkout to skip unmerged files (NOT IMPLEMENTED) */
GIT_CHECKOUT_SKIP_UNMERGED = (1u << 10),
/** For unmerged files, checkout stage 2 from index (NOT IMPLEMENTED) */
GIT_CHECKOUT_USE_OURS = (1u << 11),
/** For unmerged files, checkout stage 3 from index (NOT IMPLEMENTED) */
GIT_CHECKOUT_USE_THEIRS = (1u << 12),
/** Recursively checkout submodules with same options (NOT IMPLEMENTED) */
GIT_CHECKOUT_UPDATE_SUBMODULES = (1u << 16),
/** Recursively checkout submodules if HEAD moved in super repo (NOT IMPLEMENTED) */
GIT_CHECKOUT_UPDATE_SUBMODULES_IF_CHANGED = (1u << 17),
} git_checkout_strategy_t;
/**
* Checkout options structure
*
* Use zeros to indicate default settings.
* This needs to be initialized with the `GIT_CHECKOUT_OPTS_INIT` macro:
*
* git_checkout_opts opts = GIT_CHECKOUT_OPTS_INIT;
*/
typedef struct git_checkout_opts {
unsigned int version;
unsigned int checkout_strategy; /** default will be a dry run */
int disable_filters; /** don't apply filters like CRLF conversion */
int dir_mode; /** default is 0755 */
int file_mode; /** default is 0644 or 0755 as dictated by blob */
int file_open_flags; /** default is O_CREAT | O_TRUNC | O_WRONLY */
/** Optional callback made on files where the index differs from the
* working directory but the rules do not allow update. Return a
* non-zero value to abort the checkout. All such callbacks will be
* made before any changes are made to the working directory.
*/
int (*conflict_cb)(
const char *conflicting_path,
const git_oid *index_oid,
unsigned int index_mode,
unsigned int wd_mode,
void *payload);
void *conflict_payload;
/* Optional callback to notify the consumer of checkout progress. */
void (*progress_cb)(
const char *path,
size_t completed_steps,
size_t total_steps,
void *payload);
void *progress_payload;
/** When not zeroed out, array of fnmatch patterns specifying which
* paths should be taken into account, otherwise all files.
*/
git_strarray paths;
} git_checkout_opts;
#define GIT_CHECKOUT_OPTS_VERSION 1
#define GIT_CHECKOUT_OPTS_INIT {GIT_CHECKOUT_OPTS_VERSION}
/**
* Updates files in the index and the working tree to match the content of the
* commit pointed at by HEAD.
*
* @param repo repository to check out (must be non-bare)
* @param opts specifies checkout options (may be NULL)
* @return 0 on success, GIT_EORPHANEDHEAD when HEAD points to a non existing
* branch, GIT_ERROR otherwise (use giterr_last for information
* about the error)
*/
GIT_EXTERN(int) git_checkout_head(
git_repository *repo,
git_checkout_opts *opts);
/**
* Updates files in the working tree to match the content of the index.
*
* @param repo repository into which to check out (must be non-bare)
* @param index index to be checked out (or NULL to use repository index)
* @param opts specifies checkout options (may be NULL)
* @return 0 on success, GIT_ERROR otherwise (use giterr_last for information
* about the error)
*/
GIT_EXTERN(int) git_checkout_index(
git_repository *repo,
git_index *index,
git_checkout_opts *opts);
/**
* Updates files in the index and working tree to match the content of the
* tree pointed at by the treeish.
*
* @param repo repository to check out (must be non-bare)
* @param treeish a commit, tag or tree which content will be used to update
* the working directory
* @param opts specifies checkout options (may be NULL)
* @return 0 on success, GIT_ERROR otherwise (use giterr_last for information
* about the error)
*/
GIT_EXTERN(int) git_checkout_tree(
git_repository *repo,
const git_object *treeish,
git_checkout_opts *opts);
/** @} */
GIT_END_DECL
#endif
