diff options
Diffstat (limited to 'include/git2/checkout.h')
| -rw-r--r-- | include/git2/checkout.h | 90 |
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 |