diff options
Diffstat (limited to 'include/git2/merge.h')
| -rw-r--r-- | include/git2/merge.h | 449 |
1 files changed, 376 insertions, 73 deletions
diff --git a/include/git2/merge.h b/include/git2/merge.h index 3354fbeab..9eb14ccb1 100644 --- a/include/git2/merge.h +++ b/include/git2/merge.h @@ -23,70 +23,287 @@ GIT_BEGIN_DECL /** + * The file inputs to `git_merge_file`. Callers should populate the + * `git_merge_file_input` structure with descriptions of the files in + * each side of the conflict for use in producing the merge file. + */ +typedef struct { + unsigned int version; + + /** Pointer to the contents of the file. */ + const char *ptr; + + /** Size of the contents pointed to in `ptr`. */ + size_t size; + + /** File name of the conflicted file, or `NULL` to not merge the path. */ + const char *path; + + /** File mode of the conflicted file, or `0` to not merge the mode. */ + unsigned int mode; +} git_merge_file_input; + +#define GIT_MERGE_FILE_INPUT_VERSION 1 +#define GIT_MERGE_FILE_INPUT_INIT {GIT_MERGE_FILE_INPUT_VERSION} + +/** + * Initializes a `git_merge_file_input` with default values. Equivalent to + * creating an instance with GIT_MERGE_FILE_INPUT_INIT. + * + * @param opts the `git_merge_file_input` instance to initialize. + * @param version the version of the struct; you should pass + * `GIT_MERGE_FILE_INPUT_VERSION` here. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_merge_file_init_input( + git_merge_file_input *opts, + unsigned int version); + +/** * Flags for `git_merge_tree` options. A combination of these flags can be - * passed in via the `flags` value in the `git_merge_tree_opts`. + * passed in via the `flags` value in the `git_merge_options`. */ typedef enum { - /** Detect renames */ + /** + * Detect renames that occur between the common ancestor and the "ours" + * side or the common ancestor and the "theirs" side. This will enable + * the ability to merge between a modified and renamed file. + */ GIT_MERGE_TREE_FIND_RENAMES = (1 << 0), } git_merge_tree_flag_t; /** - * Automerge options for `git_merge_trees_opts`. + * Merge file favor options for `git_merge_options` instruct the file-level + * merging functionality how to deal with conflicting regions of the files. */ typedef enum { - GIT_MERGE_AUTOMERGE_NORMAL = 0, - GIT_MERGE_AUTOMERGE_NONE = 1, - GIT_MERGE_AUTOMERGE_FAVOR_OURS = 2, - GIT_MERGE_AUTOMERGE_FAVOR_THEIRS = 3, -} git_merge_automerge_flags; + /** + * When a region of a file is changed in both branches, a conflict + * will be recorded in the index so that `git_checkout` can produce + * a merge file with conflict markers in the working directory. + * This is the default. + */ + GIT_MERGE_FILE_FAVOR_NORMAL = 0, + /** + * When a region of a file is changed in both branches, the file + * created in the index will contain the "ours" side of any conflicting + * region. The index will not record a conflict. + */ + GIT_MERGE_FILE_FAVOR_OURS = 1, + + /** + * When a region of a file is changed in both branches, the file + * created in the index will contain the "theirs" side of any conflicting + * region. The index will not record a conflict. + */ + GIT_MERGE_FILE_FAVOR_THEIRS = 2, + + /** + * When a region of a file is changed in both branches, the file + * created in the index will contain each unique line from each side, + * which has the result of combining both files. The index will not + * record a conflict. + */ + GIT_MERGE_FILE_FAVOR_UNION = 3, +} git_merge_file_favor_t; + +typedef enum { + /* Defaults */ + GIT_MERGE_FILE_DEFAULT = 0, + + /* Create standard conflicted merge files */ + GIT_MERGE_FILE_STYLE_MERGE = (1 << 0), + + /* Create diff3-style files */ + GIT_MERGE_FILE_STYLE_DIFF3 = (1 << 1), + + /* Condense non-alphanumeric regions for simplified diff file */ + GIT_MERGE_FILE_SIMPLIFY_ALNUM = (1 << 2), +} git_merge_file_flags_t; + +typedef struct { + unsigned int version; + + /** + * Label for the ancestor file side of the conflict which will be prepended + * to labels in diff3-format merge files. + */ + const char *ancestor_label; + + /** + * Label for our file side of the conflict which will be prepended + * to labels in merge files. + */ + const char *our_label; + + /** + * Label for their file side of the conflict which will be prepended + * to labels in merge files. + */ + const char *their_label; + + /** The file to favor in region conflicts. */ + git_merge_file_favor_t favor; + + /** Merge file flags. */ + git_merge_file_flags_t flags; +} git_merge_file_options; + +#define GIT_MERGE_FILE_OPTIONS_VERSION 1 +#define GIT_MERGE_FILE_OPTIONS_INIT {GIT_MERGE_FILE_OPTIONS_VERSION} + +/** + * Initializes a `git_merge_file_options` with default values. Equivalent to + * creating an instance with GIT_MERGE_FILE_OPTIONS_INIT. + * + * @param opts the `git_merge_file_options` instance to initialize. + * @param version the version of the struct; you should pass + * `GIT_MERGE_FILE_OPTIONS_VERSION` here. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_merge_file_init_options( + git_merge_file_options *opts, + unsigned int version); + +typedef struct { + /** + * True if the output was automerged, false if the output contains + * conflict markers. + */ + unsigned int automergeable; + + /** + * The path that the resultant merge file should use, or NULL if a + * filename conflict would occur. + */ + const char *path; + + /** The mode that the resultant merge file should use. */ + unsigned int mode; + + /** The contents of the merge. */ + const char *ptr; + + /** The length of the merge contents. */ + size_t len; +} git_merge_file_result; typedef struct { unsigned int version; git_merge_tree_flag_t flags; - /** Similarity to consider a file renamed (default 50) */ + /** + * Similarity to consider a file renamed (default 50). If + * `GIT_MERGE_TREE_FIND_RENAMES` is enabled, added files will be compared + * with deleted files to determine their similarity. Files that are + * more similar than the rename threshold (percentage-wise) will be + * treated as a rename. + */ unsigned int rename_threshold; - /** Maximum similarity sources to examine (overrides the - * `merge.renameLimit` config) (default 200) + /** + * Maximum similarity sources to examine for renames (default 200). + * If the number of rename candidates (add / delete pairs) is greater + * than this value, inexact rename detection is aborted. + * + * This setting overrides the `merge.renameLimit` configuration value. */ unsigned int target_limit; /** Pluggable similarity metric; pass NULL to use internal metric */ git_diff_similarity_metric *metric; - /** Flags for automerging content. */ - git_merge_automerge_flags automerge_flags; -} git_merge_tree_opts; - -#define GIT_MERGE_TREE_OPTS_VERSION 1 -#define GIT_MERGE_TREE_OPTS_INIT {GIT_MERGE_TREE_OPTS_VERSION} + /** Flags for handling conflicting content. */ + git_merge_file_favor_t file_favor; +} git_merge_options; +#define GIT_MERGE_OPTIONS_VERSION 1 +#define GIT_MERGE_OPTIONS_INIT {GIT_MERGE_OPTIONS_VERSION} /** - * Option flags for `git_merge`. + * Initializes a `git_merge_options` with default values. Equivalent to + * creating an instance with GIT_MERGE_OPTIONS_INIT. * - * GIT_MERGE_NO_FASTFORWARD - Do not fast-forward. + * @param opts the `git_merge_options` instance to initialize. + * @param version the version of the struct; you should pass + * `GIT_MERGE_OPTIONS_VERSION` here. + * @return Zero on success; -1 on failure. + */ +GIT_EXTERN(int) git_merge_init_options( + git_merge_options *opts, + unsigned int version); + +/** + * The results of `git_merge_analysis` indicate the merge opportunities. */ typedef enum { - GIT_MERGE_NO_FASTFORWARD = 1, - GIT_MERGE_FASTFORWARD_ONLY = 2, -} git_merge_flags_t; + /** No merge is possible. (Unused.) */ + GIT_MERGE_ANALYSIS_NONE = 0, -typedef struct { - unsigned int version; + /** + * A "normal" merge; both HEAD and the given merge input have diverged + * from their common ancestor. The divergent commits must be merged. + */ + GIT_MERGE_ANALYSIS_NORMAL = (1 << 0), + + /** + * All given merge inputs are reachable from HEAD, meaning the + * repository is up-to-date and no merge needs to be performed. + */ + GIT_MERGE_ANALYSIS_UP_TO_DATE = (1 << 1), + + /** + * The given merge input is a fast-forward from HEAD and no merge + * needs to be performed. Instead, the client can check out the + * given merge input. + */ + GIT_MERGE_ANALYSIS_FASTFORWARD = (1 << 2), + + /** + * The HEAD of the current repository is "unborn" and does not point to + * a valid commit. No merge can be performed, but the caller may wish + * to simply set HEAD to the target commit(s). + */ + GIT_MERGE_ANALYSIS_UNBORN = (1 << 3), +} git_merge_analysis_t; - git_merge_flags_t merge_flags; - git_merge_tree_opts merge_tree_opts; +typedef enum { + /* + * No configuration was found that suggests a preferred behavior for + * merge. + */ + GIT_MERGE_PREFERENCE_NONE = 0, - git_checkout_opts checkout_opts; -} git_merge_opts; + /** + * There is a `merge.ff=false` configuration setting, suggesting that + * the user does not want to allow a fast-forward merge. + */ + GIT_MERGE_PREFERENCE_NO_FASTFORWARD = (1 << 0), -#define GIT_MERGE_OPTS_VERSION 1 -#define GIT_MERGE_OPTS_INIT {GIT_MERGE_OPTS_VERSION, 0, GIT_MERGE_TREE_OPTS_INIT, GIT_CHECKOUT_OPTS_INIT} + /** + * There is a `merge.ff=only` configuration setting, suggesting that + * the user only wants fast-forward merges. + */ + GIT_MERGE_PREFERENCE_FASTFORWARD_ONLY = (1 << 1), +} git_merge_preference_t; +/** + * Analyzes the given branch(es) and determines the opportunities for + * merging them into the HEAD of the repository. + * + * @param analysis_out analysis enumeration that the result is written into + * @param repo the repository to merge + * @param their_heads the heads to merge into + * @param their_heads_len the number of heads to merge + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_merge_analysis( + git_merge_analysis_t *analysis_out, + git_merge_preference_t *preference_out, + git_repository *repo, + const git_merge_head **their_heads, + size_t their_heads_len); /** * Find a merge base between two commits @@ -95,7 +312,7 @@ typedef struct { * @param repo the repository where the commits exist * @param one one of the commits * @param two the other commit - * @return Zero on success; GIT_ENOTFOUND or -1 on failure. + * @return 0 on success, GIT_ENOTFOUND if not found or error code */ GIT_EXTERN(int) git_merge_base( git_oid *out, @@ -119,27 +336,44 @@ GIT_EXTERN(int) git_merge_base_many( const git_oid input_array[]); /** - * Creates a `git_merge_head` from the given reference + * Find a merge base in preparation for an octopus merge + * + * @param out the OID of a merge base considering all the commits + * @param repo the repository where the commits exist + * @param length The number of commits in the provided `input_array` + * @param input_array oids of the commits + * @return Zero on success; GIT_ENOTFOUND or -1 on failure. + */ +GIT_EXTERN(int) git_merge_base_octopus( + git_oid *out, + git_repository *repo, + size_t length, + const git_oid input_array[]); + +/** + * Creates a `git_merge_head` from the given reference. The resulting + * git_merge_head must be freed with `git_merge_head_free`. * * @param out pointer to store the git_merge_head result in * @param repo repository that contains the given reference * @param ref reference to use as a merge input - * @return zero on success, -1 on failure. + * @return 0 on success or error code */ GIT_EXTERN(int) git_merge_head_from_ref( git_merge_head **out, git_repository *repo, - git_reference *ref); + const git_reference *ref); /** - * Creates a `git_merge_head` from the given fetch head data + * Creates a `git_merge_head` from the given fetch head data. The resulting + * git_merge_head must be freed with `git_merge_head_free`. * * @param out pointer to store the git_merge_head result in * @param repo repository that contains the given commit * @param branch_name name of the (remote) branch * @param remote_url url of the remote * @param oid the commit object id to use as a merge input - * @return zero on success, -1 on failure. + * @return 0 on success or error code */ GIT_EXTERN(int) git_merge_head_from_fetchhead( git_merge_head **out, @@ -149,20 +383,30 @@ GIT_EXTERN(int) git_merge_head_from_fetchhead( const git_oid *oid); /** - * Creates a `git_merge_head` from the given commit id + * Creates a `git_merge_head` from the given commit id. The resulting + * git_merge_head must be freed with `git_merge_head_free`. * * @param out pointer to store the git_merge_head result in * @param repo repository that contains the given commit - * @param oid the commit object id to use as a merge input - * @return zero on success, -1 on failure. + * @param id the commit object id to use as a merge input + * @return 0 on success or error code */ -GIT_EXTERN(int) git_merge_head_from_oid( +GIT_EXTERN(int) git_merge_head_from_id( git_merge_head **out, git_repository *repo, - const git_oid *oid); + const git_oid *id); /** - * Frees a `git_merge_head` + * Gets the commit ID that the given `git_merge_head` refers to. + * + * @param head the given merge head + * @return commit id + */ +GIT_EXTERN(const git_oid *) git_merge_head_id( + const git_merge_head *head); + +/** + * Frees a `git_merge_head`. * * @param head merge head to free */ @@ -170,8 +414,62 @@ GIT_EXTERN(void) git_merge_head_free( git_merge_head *head); /** + * Merge two files as they exist in the in-memory data structures, using + * the given common ancestor as the baseline, producing a + * `git_merge_file_result` that reflects the merge result. The + * `git_merge_file_result` must be freed with `git_merge_file_result_free`. + * + * Note that this function does not reference a repository and any + * configuration must be passed as `git_merge_file_options`. + * + * @param out The git_merge_file_result to be filled in + * @param ancestor The contents of the ancestor file + * @param ours The contents of the file in "our" side + * @param theirs The contents of the file in "their" side + * @param opts The merge file options or `NULL` for defaults + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_merge_file( + git_merge_file_result *out, + const git_merge_file_input *ancestor, + const git_merge_file_input *ours, + const git_merge_file_input *theirs, + const git_merge_file_options *opts); + +/** + * Merge two files as they exist in the index, using the given common + * ancestor as the baseline, producing a `git_merge_file_result` that + * reflects the merge result. The `git_merge_file_result` must be freed with + * `git_merge_file_result_free`. + * + * @param out The git_merge_file_result to be filled in + * @param repo The repository + * @param ancestor The index entry for the ancestor file (stage level 1) + * @param ours The index entry for our file (stage level 2) + * @param theirs The index entry for their file (stage level 3) + * @param opts The merge file options or NULL + * @return 0 on success or error code + */ +GIT_EXTERN(int) git_merge_file_from_index( + git_merge_file_result *out, + git_repository *repo, + const git_index_entry *ancestor, + const git_index_entry *ours, + const git_index_entry *theirs, + const git_merge_file_options *opts); + +/** + * Frees a `git_merge_file_result`. + * + * @param result The result to free or `NULL` + */ +GIT_EXTERN(void) git_merge_file_result_free(git_merge_file_result *result); + +/** * Merge two trees, producing a `git_index` that reflects the result of - * the merge. + * the merge. The index may be written as-is to the working directory + * or checked out. If the index is to be converted to a tree, the caller + * should resolve any conflicts that arose as part of the merge. * * The returned index must be freed explicitly with `git_index_free`. * @@ -181,7 +479,7 @@ GIT_EXTERN(void) git_merge_head_free( * @param our_tree the tree that reflects the destination tree * @param their_tree the tree to merge in to `our_tree` * @param opts the merge tree options (or null for defaults) - * @return zero on success, -1 on failure. + * @return 0 on success or error code */ GIT_EXTERN(int) git_merge_trees( git_index **out, @@ -189,44 +487,49 @@ GIT_EXTERN(int) git_merge_trees( const git_tree *ancestor_tree, const git_tree *our_tree, const git_tree *their_tree, - const git_merge_tree_opts *opts); + const git_merge_options *opts); /** - * Merges the given commits into HEAD, producing a new commit. + * Merge two commits, producing a `git_index` that reflects the result of + * the merge. The index may be written as-is to the working directory + * or checked out. If the index is to be converted to a tree, the caller + * should resolve any conflicts that arose as part of the merge. * - * @param out the results of the merge - * @param repo the repository to merge - * @param merge_heads the heads to merge into - * @param merge_heads_len the number of heads to merge - * @param flags merge flags + * The returned index must be freed explicitly with `git_index_free`. + * + * @param out pointer to store the index result in + * @param repo repository that contains the given trees + * @param our_commit the commit that reflects the destination tree + * @param their_commit the commit to merge in to `our_commit` + * @param opts the merge tree options (or null for defaults) + * @return 0 on success or error code */ -GIT_EXTERN(int) git_merge( - git_merge_result **out, +GIT_EXTERN(int) git_merge_commits( + git_index **out, git_repository *repo, - const git_merge_head **their_heads, - size_t their_heads_len, - const git_merge_opts *opts); - -/** - * Returns true if a merge is up-to-date (we were asked to merge the target - * into itself.) - */ -GIT_EXTERN(int) git_merge_result_is_uptodate(git_merge_result *merge_result); - -/** - * Returns true if a merge is eligible for fastforward - */ -GIT_EXTERN(int) git_merge_result_is_fastforward(git_merge_result *merge_result); + const git_commit *our_commit, + const git_commit *their_commit, + const git_merge_options *opts); /** - * Gets the fast-forward OID if the merge was a fastforward. + * Merges the given commit(s) into HEAD, writing the results into the working + * directory. Any changes are staged for commit and any conflicts are written + * to the index. Callers should inspect the repository's index after this + * completes, resolve any conflicts and prepare a commit. * - * @param out the OID of the fast-forward - * @param merge_result the results of the merge + * @param repo the repository to merge + * @param their_heads the heads to merge into + * @param their_heads_len the number of heads to merge + * @param merge_opts merge options + * @param checkout_opts checkout options + * @return 0 on success or error code */ -GIT_EXTERN(int) git_merge_result_fastforward_oid(git_oid *out, git_merge_result *merge_result); - -GIT_EXTERN(void) git_merge_result_free(git_merge_result *merge_result); +GIT_EXTERN(int) git_merge( + git_repository *repo, + const git_merge_head **their_heads, + size_t their_heads_len, + const git_merge_options *merge_opts, + const git_checkout_options *checkout_opts); /** @} */ GIT_END_DECL |