/*
 * Copyright (C) the libgit2 contributors. All rights reserved.
 *
 * This file is part of libgit2, distributed under the GNU GPL v2 with
 * a Linking Exception. For full terms see the included COPYING file.
 */
module libgit2_d.checkout;


private static import libgit2_d.diff;
private static import libgit2_d.strarray;
private static import libgit2_d.types;

/**
 * @file git2/checkout.h
 * @brief Git checkout routines
 * @defgroup git_checkout Git checkout routines
 * @ingroup Git
 * @{
 */
extern (C):
nothrow @nogc:
public:

/**
 * Checkout behavior flags
 *
 * In libgit2, checkout is used to update the working directory and index
 * to match a target tree.  Unlike git checkout, it does not move the HEAD
 * commit for you - use `git_repository_set_head` or the like to do that.
 *
 * Checkout looks at (up to) four things: the "target" tree you want to
 * check out, the "baseline" tree of what was checked out previously, the
 * working directory for actual files, and the index for staged changes.
 *
 * You give checkout one of three strategies for update:
 *
 * - `GIT_CHECKOUT_NONE` is a dry-run strategy that checks for conflicts,
 *   etc., but doesn't make any actual changes.
 *
 * - `GIT_CHECKOUT_FORCE` is at the opposite extreme, taking any action to
 *   make the working directory match the target (including potentially
 *   discarding modified files).
 *
 * - `GIT_CHECKOUT_SAFE` is between these two options, it will only make
 *   modifications that will not lose changes.
 *
 *                         |  target == baseline   |  target != baseline  |
 *    ---------------------|-----------------------|----------------------|
 *     workdir == baseline |       no action       |  create, update, or  |
 *                         |                       |     delete file      |
 *    ---------------------|-----------------------|----------------------|
 *     workdir exists and  |       no action       |   conflict (notify   |
 *       is != baseline    | notify dirty MODIFIED | and cancel checkout) |
 *    ---------------------|-----------------------|----------------------|
 *      workdir missing,   | notify dirty DELETED  |     create file      |
 *      baseline present   |                       |                      |
 *    ---------------------|-----------------------|----------------------|
 *
 * To emulate `git checkout`, use `GIT_CHECKOUT_SAFE` with a checkout
 * notification callback (see below) that displays information about dirty
 * files.  The default behavior will cancel checkout on conflicts.
 *
 * To emulate `git checkout-index`, use `GIT_CHECKOUT_SAFE` with a
 * notification callback that cancels the operation if a dirty-but-existing
 * file is found in the working directory.  This core git command isn't
 * quite "force" but is sensitive about some types of changes.
 *
 * To emulate `git checkout -f`, use `GIT_CHECKOUT_FORCE`.
 *
 *
 * There are some additional flags to modify the behavior of checkout:
 *
 * - GIT_CHECKOUT_ALLOW_CONFLICTS makes SAFE mode apply safe file updates
 *   even if there are conflicts (instead of cancelling the checkout).
 *
 * - GIT_CHECKOUT_REMOVE_UNTRACKED means remove untracked files (i.e. not
 *   in target, baseline, or index, and not ignored) from the working dir.
 *
 * - GIT_CHECKOUT_REMOVE_IGNORED means remove ignored files (that are also
 *   untracked) from the working directory as well.
 *
 * - GIT_CHECKOUT_UPDATE_ONLY means to only update the content of files that
 *   already exist.  Files will not be created nor deleted.  This just skips
 *   applying adds, deletes, and typechanges.
 *
 * - GIT_CHECKOUT_DONT_UPDATE_INDEX prevents checkout from writing the
 *   updated files' information to the index.
 *
 * - Normally, checkout will reload the index and git attributes from disk
 *   before any operations.  GIT_CHECKOUT_NO_REFRESH prevents this reload.
 *
 * - Unmerged index entries are conflicts.  GIT_CHECKOUT_SKIP_UNMERGED skips
 *   files with unmerged index entries instead.  GIT_CHECKOUT_USE_OURS and
 *   GIT_CHECKOUT_USE_THEIRS to proceed with the checkout using either the
 *   stage 2 ("ours") or stage 3 ("theirs") version of files in the index.
 *
 * - GIT_CHECKOUT_DONT_OVERWRITE_IGNORED prevents ignored files from being
 *   overwritten.  Normally, files that are ignored in the working directory
 *   are not considered "precious" and may be overwritten if the checkout
 *   target contains that file.
 *
 * - GIT_CHECKOUT_DONT_REMOVE_EXISTING prevents checkout from removing
 *   files or folders that fold to the same name on case insensitive
 *   filesystems.  This can cause files to retain their existing names
 *   and write through existing symbolic links.
 */
enum git_checkout_strategy_t
{
	/**
	 * default is a dry run, no actual updates
	 */
	GIT_CHECKOUT_NONE = 0,

	/**
	 * Allow safe updates that cannot overwrite uncommitted data.
	 * If the uncommitted changes don't conflict with the checked out files,
	 * the checkout will still proceed, leaving the changes intact.
	 *
	 * Mutually exclusive with GIT_CHECKOUT_FORCE.
	 * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE.
	 */
	GIT_CHECKOUT_SAFE = 1u << 0,

	/**
	 * Allow all updates to force working directory to look like index.
	 *
	 * Mutually exclusive with GIT_CHECKOUT_SAFE.
	 * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE.
	 */
	GIT_CHECKOUT_FORCE = 1u << 1,

	/**
	 * Allow checkout to recreate missing files
	 */
	GIT_CHECKOUT_RECREATE_MISSING = 1u << 2,

	/**
	 * Allow checkout to make safe 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,

	/**
	 * Remove ignored files not in index
	 */
	GIT_CHECKOUT_REMOVE_IGNORED = 1u << 6,

	/**
	 * Only update existing files, don't create new ones
	 */
	GIT_CHECKOUT_UPDATE_ONLY = 1u << 7,

	/**
	 * Normally checkout updates index entries as it goes; this stops that.
	 * Implies `GIT_CHECKOUT_DONT_WRITE_INDEX`.
	 */
	GIT_CHECKOUT_DONT_UPDATE_INDEX = 1u << 8,

	/**
	 * Don't refresh index/config/etc before doing checkout
	 */
	GIT_CHECKOUT_NO_REFRESH = 1u << 9,

	/**
	 * Allow checkout to skip unmerged files
	 */
	GIT_CHECKOUT_SKIP_UNMERGED = 1u << 10,

	/**
	 * For unmerged files, checkout stage 2 from index
	 */
	GIT_CHECKOUT_USE_OURS = 1u << 11,

	/**
	 * For unmerged files, checkout stage 3 from index
	 */
	GIT_CHECKOUT_USE_THEIRS = 1u << 12,

	/**
	 * Treat pathspec as simple list of exact match file paths
	 */
	GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH = 1u << 13,

	/**
	 * Ignore directories in use, they will be left empty
	 */
	GIT_CHECKOUT_SKIP_LOCKED_DIRECTORIES = 1u << 18,

	/**
	 * Don't overwrite ignored files that exist in the checkout target
	 */
	GIT_CHECKOUT_DONT_OVERWRITE_IGNORED = 1u << 19,

	/**
	 * Write normal merge files for conflicts
	 */
	GIT_CHECKOUT_CONFLICT_STYLE_MERGE = 1u << 20,

	/**
	 * Include common ancestor data in diff3 format files for conflicts
	 */
	GIT_CHECKOUT_CONFLICT_STYLE_DIFF3 = 1u << 21,

	/**
	 * Don't overwrite existing files or folders
	 */
	GIT_CHECKOUT_DONT_REMOVE_EXISTING = 1u << 22,

	/**
	 * Normally checkout writes the index upon completion; this prevents that.
	 */
	GIT_CHECKOUT_DONT_WRITE_INDEX = 1u << 23,

	/**
	 * THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED
	 */

	/**
	 * 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,
}

/**
 * Checkout notification flags
 *
 * Checkout will invoke an options notification callback (`notify_cb`) for
 * certain cases - you pick which ones via `notify_flags`:
 *
 * - GIT_CHECKOUT_NOTIFY_CONFLICT invokes checkout on conflicting paths.
 *
 * - GIT_CHECKOUT_NOTIFY_DIRTY notifies about "dirty" files, i.e. those that
 *   do not need an update but no longer match the baseline.  Core git
 *   displays these files when checkout runs, but won't stop the checkout.
 *
 * - GIT_CHECKOUT_NOTIFY_UPDATED sends notification for any file changed.
 *
 * - GIT_CHECKOUT_NOTIFY_UNTRACKED notifies about untracked files.
 *
 * - GIT_CHECKOUT_NOTIFY_IGNORED notifies about ignored files.
 *
 * Returning a non-zero value from this callback will cancel the checkout.
 * The non-zero return value will be propagated back and returned by the
 * git_checkout_... call.
 *
 * Notification callbacks are made prior to modifying any files on disk,
 * so canceling on any notification will still happen prior to any files
 * being modified.
 */
enum git_checkout_notify_t
{
	GIT_CHECKOUT_NOTIFY_NONE = 0,
	GIT_CHECKOUT_NOTIFY_CONFLICT = 1u << 0,
	GIT_CHECKOUT_NOTIFY_DIRTY = 1u << 1,
	GIT_CHECKOUT_NOTIFY_UPDATED = 1u << 2,
	GIT_CHECKOUT_NOTIFY_UNTRACKED = 1u << 3,
	GIT_CHECKOUT_NOTIFY_IGNORED = 1u << 4,

	GIT_CHECKOUT_NOTIFY_ALL = 0x0FFFFu,
}

/**
 * Checkout performance-reporting structure
 */
struct git_checkout_perfdata
{
	size_t mkdir_calls;
	size_t stat_calls;
	size_t chmod_calls;
}

/**
 * Checkout notification callback function
 */
alias git_checkout_notify_cb = int function(.git_checkout_notify_t why, const (char)* path, const (libgit2_d.diff.git_diff_file)* baseline, const (libgit2_d.diff.git_diff_file)* target, const (libgit2_d.diff.git_diff_file)* workdir, void* payload);

/**
 * Checkout progress notification function
 */
alias git_checkout_progress_cb = void function(const (char)* path, size_t completed_steps, size_t total_steps, void* payload);

/**
 * Checkout perfdata notification function
 */
alias git_checkout_perfdata_cb = void function(const (.git_checkout_perfdata)* perfdata, void* payload);

/**
 * Checkout options structure
 *
 * Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can
 * use `git_checkout_options_init`.
 */
struct git_checkout_options
{
	/**
	 * The version
	 */
	uint version_;

	/**
	 * default will be a safe checkout
	 */
	uint checkout_strategy;

	/**
	 * don't apply filters like CRLF conversion
	 */
	int disable_filters;

	/**
	 * default is 0755
	 */
	uint dir_mode;

	/**
	 * default is 0644 or 0755 as dictated by blob
	 */
	uint file_mode;

	/**
	 * default is O_CREAT | O_TRUNC | O_WRONLY
	 */
	int file_open_flags;

	/**
	 * see `git_checkout_notify_t` above
	 */
	uint notify_flags;

	/**
	 * Optional callback to get notifications on specific file states.
	 * @see git_checkout_notify_t
	 */
	.git_checkout_notify_cb notify_cb;

	/**
	 * Payload passed to notify_cb
	 */
	void* notify_payload;

	/**
	 * Optional callback to notify the consumer of checkout progress.
	 */
	.git_checkout_progress_cb progress_cb;

	/**
	 * Payload passed to progress_cb
	 */
	void* progress_payload;

	/**
	 * A list of wildmatch patterns or paths.
	 *
	 * By default, all paths are processed. If you pass an array of wildmatch
	 * patterns, those will be used to filter which paths should be taken into
	 * account.
	 *
	 * Use git_checkout_strategy_t.GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as a simple list.
	 */
	libgit2_d.strarray.git_strarray paths;

	/**
	 * The expected content of the working directory; defaults to HEAD.
	 *
	 * If the working directory does not match this baseline information,
	 * that will produce a checkout conflict.
	 */
	libgit2_d.types.git_tree* baseline;

	/**
	 * Like `baseline` above, though expressed as an index.  This
	 * option overrides `baseline`.
	 */
	libgit2_d.types.git_index* baseline_index; 

	/**
	 * alternative checkout path to workdir
	 */
	const (char)* target_directory;

	/**
	 * the name of the common ancestor side of conflicts
	 */
	const (char)* ancestor_label;

	/**
	 * the name of the "our" side of conflicts
	 */
	const (char)* our_label;

	/**
	 * the name of the "their" side of conflicts
	 */
	const (char)* their_label;

	/**
	 * Optional callback to notify the consumer of performance data.
	 */
	.git_checkout_perfdata_cb perfdata_cb;

	/**
	 * Payload passed to perfdata_cb
	 */
	void* perfdata_payload;
}

enum GIT_CHECKOUT_OPTIONS_VERSION = 1;

pragma(inline, true)
pure nothrow @safe @nogc
.git_checkout_options GIT_CHECKOUT_OPTIONS_INIT()

	do
	{
		.git_checkout_options OUTPUT =
		{
			version_: .GIT_CHECKOUT_OPTIONS_VERSION,
			checkout_strategy: .git_checkout_strategy_t.GIT_CHECKOUT_SAFE,
		};

		return OUTPUT;
	}

/**
 * Initialize git_checkout_options structure
 *
 * Initializes a `git_checkout_options` with default values. Equivalent to creating
 * an instance with GIT_CHECKOUT_OPTIONS_INIT.
 *
 * Params:
 *      opts = The `git_checkout_options` struct to initialize.
 *      version = The struct version; pass `GIT_CHECKOUT_OPTIONS_VERSION`.
 *
 * Returns: Zero on success; -1 on failure.
 */
//GIT_EXTERN
int git_checkout_options_init(.git_checkout_options* opts, uint version_);

/**
 * Updates files in the index and the working tree to match the content of
 * the commit pointed at by HEAD.
 *
 * Note that this is _not_ the correct mechanism used to switch branches;
 * do not change your `HEAD` and then call this method, that would leave
 * you with checkout conflicts since your working directory would then
 * appear to be dirty.  Instead, checkout the target of the branch and
 * then update `HEAD` using `git_repository_set_head` to point to the
 * branch you checked out.
 *
 * Params:
 *      repo = repository to check out (must be non-bare)
 *      opts = specifies checkout options (may be null)
 *
 * Returns: 0 on success, git_error_code.GIT_EUNBORNBRANCH if HEAD points to a non existing branch, non-zero value returned by `notify_cb`, or other error code < 0 (use git_error_last for error details)
 */
//GIT_EXTERN
int git_checkout_head(libgit2_d.types.git_repository* repo, const (.git_checkout_options)* opts);

/**
 * Updates files in the working tree to match the content of the index.
 *
 * Params:
 *      repo = repository into which to check out (must be non-bare)
 *      index = index to be checked out (or null to use repository index)
 *      opts = specifies checkout options (may be null)
 *
 * Returns: 0 on success, non-zero return value from `notify_cb`, or error code < 0 (use git_error_last for error details)
 */
//GIT_EXTERN
int git_checkout_index(libgit2_d.types.git_repository* repo, libgit2_d.types.git_index* index, const (.git_checkout_options)* opts);

/**
 * Updates files in the index and working tree to match the content of the
 * tree pointed at by the treeish.
 *
 * Params:
 *      repo = repository to check out (must be non-bare)
 *      treeish = a commit, tag or tree which content will be used to update the working directory (or null to use HEAD)
 *      opts = specifies checkout options (may be null)
 *
 * Returns: 0 on success, non-zero return value from `notify_cb`, or error code < 0 (use git_error_last for error details)
 */
//GIT_EXTERN
int git_checkout_tree(libgit2_d.types.git_repository* repo, const (libgit2_d.types.git_object)* treeish, const (.git_checkout_options)* opts);

/** @} */