Adding upstream version 1.7.2+ds.upstream/1.7.2+ds

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 417 insertions, 0 deletions

diff --git a/include/git2/checkout.h b/include/git2/checkout.h
new file mode 100644
index 0000000..9f83411
--- /dev/null
+++ b/include/git2/checkout.h
@@ -0,0 +1,417 @@
+/*
+ * 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.
+ */
+#ifndef INCLUDE_git_checkout_h__
+#define INCLUDE_git_checkout_h__
+
+#include "common.h"
+#include "types.h"
+#include "diff.h"
+
+/**
+ * @file git2/checkout.h
+ * @brief Git checkout routines
+ * @defgroup git_checkout Git checkout routines
+ * @ingroup Git
+ * @{
+ */
+GIT_BEGIN_DECL
+
+/**
+ * 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.
+ */
+typedef enum {
+	GIT_CHECKOUT_NONE = 0, /**< default is a dry run, no actual updates */
+
+	/**
+	 * 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),
+
+	/**
+	 * Show what would be done by a checkout.  Stop after sending
+	 * notifications; don't update the working directory or index.
+	 */
+	GIT_CHECKOUT_DRY_RUN = (1u << 24),
+
+	/** Include common ancestor data in zdiff3 format for conflicts */
+	GIT_CHECKOUT_CONFLICT_STYLE_ZDIFF3 = (1u << 25),
+
+	/**
+	 * 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)
+
+} git_checkout_strategy_t;
+
+/**
+ * Checkout notification flags
+ *
+ * Checkout will invoke an options notification callback (`notify_cb`) for
+ * certain cases - you pick which ones via `notify_flags`:
+ *
+ * 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.
+ */
+typedef enum {
+	GIT_CHECKOUT_NOTIFY_NONE      = 0,
+
+	/**
+	 * Invokes checkout on conflicting paths.
+	 */
+	GIT_CHECKOUT_NOTIFY_CONFLICT  = (1u << 0),
+
+	/**
+	 * 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_DIRTY     = (1u << 1),
+
+	/**
+	 * Sends notification for any file changed.
+	 */
+	GIT_CHECKOUT_NOTIFY_UPDATED   = (1u << 2),
+
+	/**
+	 * Notifies about untracked files.
+	 */
+	GIT_CHECKOUT_NOTIFY_UNTRACKED = (1u << 3),
+
+	/**
+	 * Notifies about ignored files.
+	 */
+	GIT_CHECKOUT_NOTIFY_IGNORED   = (1u << 4),
+
+	GIT_CHECKOUT_NOTIFY_ALL       = 0x0FFFFu
+} git_checkout_notify_t;
+
+/** Checkout performance-reporting structure */
+typedef struct {
+	size_t mkdir_calls;
+	size_t stat_calls;
+	size_t chmod_calls;
+} git_checkout_perfdata;
+
+/** Checkout notification callback function */
+typedef int GIT_CALLBACK(git_checkout_notify_cb)(
+	git_checkout_notify_t why,
+	const char *path,
+	const git_diff_file *baseline,
+	const git_diff_file *target,
+	const git_diff_file *workdir,
+	void *payload);
+
+/** Checkout progress notification function */
+typedef void GIT_CALLBACK(git_checkout_progress_cb)(
+	const char *path,
+	size_t completed_steps,
+	size_t total_steps,
+	void *payload);
+
+/** Checkout perfdata notification function */
+typedef void GIT_CALLBACK(git_checkout_perfdata_cb)(
+	const git_checkout_perfdata *perfdata,
+	void *payload);
+
+/**
+ * Checkout options structure
+ *
+ * Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can
+ * use `git_checkout_options_init`.
+ *
+ */
+typedef struct git_checkout_options {
+	unsigned int version; /**< The version */
+
+	unsigned int checkout_strategy; /**< default will be a safe checkout */
+
+	int disable_filters;    /**< don't apply filters like CRLF conversion */
+	unsigned int dir_mode;  /**< default is 0755 */
+	unsigned int file_mode; /**< default is 0644 or 0755 as dictated by blob */
+	int file_open_flags;    /**< default is O_CREAT | O_TRUNC | O_WRONLY */
+
+	unsigned int notify_flags; /**< see `git_checkout_notify_t` above */
+
+	/**
+	 * 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_DISABLE_PATHSPEC_MATCH to treat as a simple list.
+	 */
+	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.
+	 */
+	git_tree *baseline;
+
+	/**
+	 * Like `baseline` above, though expressed as an index.  This
+	 * option overrides `baseline`.
+	 */
+	git_index *baseline_index;
+
+	const char *target_directory; /**< alternative checkout path to workdir */
+
+	const char *ancestor_label; /**< the name of the common ancestor side of conflicts */
+	const char *our_label; /**< the name of the "our" side of conflicts */
+	const char *their_label; /**< the name of the "their" side of conflicts */
+
+	/** Optional callback to notify the consumer of performance data. */
+	git_checkout_perfdata_cb perfdata_cb;
+
+	/** Payload passed to perfdata_cb */
+	void *perfdata_payload;
+} git_checkout_options;
+
+#define GIT_CHECKOUT_OPTIONS_VERSION 1
+#define GIT_CHECKOUT_OPTIONS_INIT {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE}
+
+/**
+ * Initialize git_checkout_options structure
+ *
+ * Initializes a `git_checkout_options` with default values. Equivalent to creating
+ * an instance with GIT_CHECKOUT_OPTIONS_INIT.
+ *
+ * @param opts The `git_checkout_options` struct to initialize.
+ * @param version The struct version; pass `GIT_CHECKOUT_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
+ */
+GIT_EXTERN(int) git_checkout_options_init(
+	git_checkout_options *opts,
+	unsigned int 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.
+ *
+ * @param repo repository to check out (must be non-bare)
+ * @param opts specifies checkout options (may be NULL)
+ * @return 0 on success, 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(
+	git_repository *repo,
+	const git_checkout_options *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, non-zero return value from `notify_cb`, or error
+ *         code < 0 (use git_error_last for error details)
+ */
+GIT_EXTERN(int) git_checkout_index(
+	git_repository *repo,
+	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.
+ *
+ * @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 (or NULL to use HEAD)
+ * @param opts specifies checkout options (may be NULL)
+ * @return 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(
+	git_repository *repo,
+	const git_object *treeish,
+	const git_checkout_options *opts);
+
+/** @} */
+GIT_END_DECL
+#endif