libgit2 v0.21.0v0.21.0

1 files changed, 61 insertions, 29 deletions

diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index efafdc3e4..ad44173e6 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -43,17 +43,17 @@ GIT_BEGIN_DECL
  * In between those are `GIT_CHECKOUT_SAFE` and `GIT_CHECKOUT_SAFE_CREATE`
  * both of which 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,   | create if SAFE_CREATE |     create file      |
- *   baseline present   | notify dirty DELETED  |                      |
- * ---------------------|-----------------------|----------------------|
+ *                         |  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,   | create if SAFE_CREATE |     create file      |
+ *      baseline present   | notify dirty DELETED  |                      |
+ *    ---------------------|-----------------------|----------------------|
  *
  * The only difference between SAFE and SAFE_CREATE is that SAFE_CREATE
  * will cause a file to be checked out if it is missing from the working
@@ -99,9 +99,14 @@ GIT_BEGIN_DECL
  *   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.
  */
 typedef enum {
-	GIT_CHECKOUT_NONE = 0, /** default is a dry run, no actual updates */
+	GIT_CHECKOUT_NONE = 0, /**< default is a dry run, no actual updates */
 
 	/** Allow safe updates that cannot overwrite uncommitted data */
 	GIT_CHECKOUT_SAFE = (1u << 0),
@@ -144,6 +149,15 @@ typedef enum {
 	/** 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),
+
 	/**
 	 * THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED
 	 */
@@ -174,7 +188,12 @@ typedef enum {
  * - GIT_CHECKOUT_NOTIFY_IGNORED notifies about ignored files.
  *
  * Returning a non-zero value from this callback will cancel the checkout.
- * Notification callbacks are made prior to modifying any files on disk.
+ * 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,
@@ -206,12 +225,12 @@ typedef void (*git_checkout_progress_cb)(
 /**
  * Checkout options structure
  *
- * Zero out for defaults.  Initialize with `GIT_CHECKOUT_OPTS_INIT` macro to
+ * Zero out for defaults.  Initialize with `GIT_CHECKOUT_OPTIONS_INIT` macro to
  * correctly set the `version` field.  E.g.
  *
- *		git_checkout_opts opts = GIT_CHECKOUT_OPTS_INIT;
+ *		git_checkout_options opts = GIT_CHECKOUT_OPTIONS_INIT;
  */
-typedef struct git_checkout_opts {
+typedef struct git_checkout_options {
 	unsigned int version;
 
 	unsigned int checkout_strategy; /** default will be a dry run */
@@ -239,12 +258,25 @@ typedef struct git_checkout_opts {
 
 	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 */
-} git_checkout_opts;
+} git_checkout_options;
+
+#define GIT_CHECKOUT_OPTIONS_VERSION 1
+#define GIT_CHECKOUT_OPTIONS_INIT {GIT_CHECKOUT_OPTIONS_VERSION}
 
-#define GIT_CHECKOUT_OPTS_VERSION 1
-#define GIT_CHECKOUT_OPTS_INIT {GIT_CHECKOUT_OPTS_VERSION}
+/**
+* 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 Version of struct; pass `GIT_CHECKOUT_OPTIONS_VERSION`
+* @return Zero on success; -1 on failure.
+*/
+GIT_EXTERN(int) git_checkout_init_options(
+	git_checkout_options *opts,
+	unsigned int version);
 
 /**
  * Updates files in the index and the working tree to match the content of
@@ -252,13 +284,13 @@ typedef struct git_checkout_opts {
  *
  * @param repo repository to check out (must be non-bare)
  * @param opts specifies checkout options (may be NULL)
- * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
- * branch, GIT_ERROR otherwise (use giterr_last for information
- * about the error)
+ * @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 giterr_last for error details)
  */
 GIT_EXTERN(int) git_checkout_head(
 	git_repository *repo,
-	const git_checkout_opts *opts);
+	const git_checkout_options *opts);
 
 /**
  * Updates files in the working tree to match the content of the index.
@@ -266,13 +298,13 @@ GIT_EXTERN(int) git_checkout_head(
  * @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)
+ * @return 0 on success, non-zero return value from `notify_cb`, or error
+ *         code < 0 (use giterr_last for error details)
  */
 GIT_EXTERN(int) git_checkout_index(
 	git_repository *repo,
 	git_index *index,
-	const git_checkout_opts *opts);
+	const git_checkout_options *opts);
 
 /**
  * Updates files in the index and working tree to match the content of the
@@ -282,13 +314,13 @@ GIT_EXTERN(int) git_checkout_index(
  * @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, GIT_ERROR otherwise (use giterr_last for information
- * about the error)
+ * @return 0 on success, non-zero return value from `notify_cb`, or error
+ *         code < 0 (use giterr_last for error details)
  */
 GIT_EXTERN(int) git_checkout_tree(
 	git_repository *repo,
 	const git_object *treeish,
-	const git_checkout_opts *opts);
+	const git_checkout_options *opts);
 
 /** @} */
 GIT_END_DECL