1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 4 * This file is part of libgit2, distributed under the GNU GPL v2 with 5 * a Linking Exception. For full terms see the included COPYING file. 6 */ 7 #ifndef INCLUDE_git_merge_h__ 8 #define INCLUDE_git_merge_h__ 9 10 #include "common.h" 11 #include "types.h" 12 #include "oid.h" 13 #include "oidarray.h" 14 #include "checkout.h" 15 #include "index.h" 16 #include "annotated_commit.h" 17 18 /** 19 * @file git2/merge.h 20 * @brief Git merge routines 21 * @defgroup git_merge Git merge routines 22 * @ingroup Git 23 * @{ 24 */ 25 GIT_BEGIN_DECL 26 27 /** 28 * The file inputs to `git_merge_file`. Callers should populate the 29 * `git_merge_file_input` structure with descriptions of the files in 30 * each side of the conflict for use in producing the merge file. 31 */ 32 typedef struct { 33 unsigned int version; 34 35 /** Pointer to the contents of the file. */ 36 const char *ptr; 37 38 /** Size of the contents pointed to in `ptr`. */ 39 size_t size; 40 41 /** File name of the conflicted file, or `NULL` to not merge the path. */ 42 const char *path; 43 44 /** File mode of the conflicted file, or `0` to not merge the mode. */ 45 unsigned int mode; 46 } git_merge_file_input; 47 48 #define GIT_MERGE_FILE_INPUT_VERSION 1 49 #define GIT_MERGE_FILE_INPUT_INIT {GIT_MERGE_FILE_INPUT_VERSION} 50 51 /** 52 * Initializes a `git_merge_file_input` with default values. Equivalent to 53 * creating an instance with GIT_MERGE_FILE_INPUT_INIT. 54 * 55 * @param opts the `git_merge_file_input` instance to initialize. 56 * @param version the version of the struct; you should pass 57 * `GIT_MERGE_FILE_INPUT_VERSION` here. 58 * @return Zero on success; -1 on failure. 59 */ 60 GIT_EXTERN(int) git_merge_file_input_init( 61 git_merge_file_input *opts, 62 unsigned int version); 63 64 /** 65 * Flags for `git_merge` options. A combination of these flags can be 66 * passed in via the `flags` value in the `git_merge_options`. 67 */ 68 typedef enum { 69 /** 70 * Detect renames that occur between the common ancestor and the "ours" 71 * side or the common ancestor and the "theirs" side. This will enable 72 * the ability to merge between a modified and renamed file. 73 */ 74 GIT_MERGE_FIND_RENAMES = (1 << 0), 75 76 /** 77 * If a conflict occurs, exit immediately instead of attempting to 78 * continue resolving conflicts. The merge operation will fail with 79 * GIT_EMERGECONFLICT and no index will be returned. 80 */ 81 GIT_MERGE_FAIL_ON_CONFLICT = (1 << 1), 82 83 /** 84 * Do not write the REUC extension on the generated index 85 */ 86 GIT_MERGE_SKIP_REUC = (1 << 2), 87 88 /** 89 * If the commits being merged have multiple merge bases, do not build 90 * a recursive merge base (by merging the multiple merge bases), 91 * instead simply use the first base. This flag provides a similar 92 * merge base to `git-merge-resolve`. 93 */ 94 GIT_MERGE_NO_RECURSIVE = (1 << 3), 95 } git_merge_flag_t; 96 97 /** 98 * Merge file favor options for `git_merge_options` instruct the file-level 99 * merging functionality how to deal with conflicting regions of the files. 100 */ 101 typedef enum { 102 /** 103 * When a region of a file is changed in both branches, a conflict 104 * will be recorded in the index so that `git_checkout` can produce 105 * a merge file with conflict markers in the working directory. 106 * This is the default. 107 */ 108 GIT_MERGE_FILE_FAVOR_NORMAL = 0, 109 110 /** 111 * When a region of a file is changed in both branches, the file 112 * created in the index will contain the "ours" side of any conflicting 113 * region. The index will not record a conflict. 114 */ 115 GIT_MERGE_FILE_FAVOR_OURS = 1, 116 117 /** 118 * When a region of a file is changed in both branches, the file 119 * created in the index will contain the "theirs" side of any conflicting 120 * region. The index will not record a conflict. 121 */ 122 GIT_MERGE_FILE_FAVOR_THEIRS = 2, 123 124 /** 125 * When a region of a file is changed in both branches, the file 126 * created in the index will contain each unique line from each side, 127 * which has the result of combining both files. The index will not 128 * record a conflict. 129 */ 130 GIT_MERGE_FILE_FAVOR_UNION = 3, 131 } git_merge_file_favor_t; 132 133 /** 134 * File merging flags 135 */ 136 typedef enum { 137 /** Defaults */ 138 GIT_MERGE_FILE_DEFAULT = 0, 139 140 /** Create standard conflicted merge files */ 141 GIT_MERGE_FILE_STYLE_MERGE = (1 << 0), 142 143 /** Create diff3-style files */ 144 GIT_MERGE_FILE_STYLE_DIFF3 = (1 << 1), 145 146 /** Condense non-alphanumeric regions for simplified diff file */ 147 GIT_MERGE_FILE_SIMPLIFY_ALNUM = (1 << 2), 148 149 /** Ignore all whitespace */ 150 GIT_MERGE_FILE_IGNORE_WHITESPACE = (1 << 3), 151 152 /** Ignore changes in amount of whitespace */ 153 GIT_MERGE_FILE_IGNORE_WHITESPACE_CHANGE = (1 << 4), 154 155 /** Ignore whitespace at end of line */ 156 GIT_MERGE_FILE_IGNORE_WHITESPACE_EOL = (1 << 5), 157 158 /** Use the "patience diff" algorithm */ 159 GIT_MERGE_FILE_DIFF_PATIENCE = (1 << 6), 160 161 /** Take extra time to find minimal diff */ 162 GIT_MERGE_FILE_DIFF_MINIMAL = (1 << 7), 163 } git_merge_file_flag_t; 164 165 #define GIT_MERGE_CONFLICT_MARKER_SIZE 7 166 167 /** 168 * Options for merging a file 169 */ 170 typedef struct { 171 unsigned int version; 172 173 /** 174 * Label for the ancestor file side of the conflict which will be prepended 175 * to labels in diff3-format merge files. 176 */ 177 const char *ancestor_label; 178 179 /** 180 * Label for our file side of the conflict which will be prepended 181 * to labels in merge files. 182 */ 183 const char *our_label; 184 185 /** 186 * Label for their file side of the conflict which will be prepended 187 * to labels in merge files. 188 */ 189 const char *their_label; 190 191 /** The file to favor in region conflicts. */ 192 git_merge_file_favor_t favor; 193 194 /** see `git_merge_file_flag_t` above */ 195 uint32_t flags; 196 197 /** The size of conflict markers (eg, "<<<<<<<"). Default is 198 * GIT_MERGE_CONFLICT_MARKER_SIZE. */ 199 unsigned short marker_size; 200 } git_merge_file_options; 201 202 #define GIT_MERGE_FILE_OPTIONS_VERSION 1 203 #define GIT_MERGE_FILE_OPTIONS_INIT {GIT_MERGE_FILE_OPTIONS_VERSION} 204 205 /** 206 * Initialize git_merge_file_options structure 207 * 208 * Initializes a `git_merge_file_options` with default values. Equivalent to 209 * creating an instance with `GIT_MERGE_FILE_OPTIONS_INIT`. 210 * 211 * @param opts The `git_merge_file_options` struct to initialize. 212 * @param version The struct version; pass `GIT_MERGE_FILE_OPTIONS_VERSION`. 213 * @return Zero on success; -1 on failure. 214 */ 215 GIT_EXTERN(int) git_merge_file_options_init(git_merge_file_options *opts, unsigned int version); 216 217 /** 218 * Information about file-level merging 219 */ 220 typedef struct { 221 /** 222 * True if the output was automerged, false if the output contains 223 * conflict markers. 224 */ 225 unsigned int automergeable; 226 227 /** 228 * The path that the resultant merge file should use, or NULL if a 229 * filename conflict would occur. 230 */ 231 const char *path; 232 233 /** The mode that the resultant merge file should use. */ 234 unsigned int mode; 235 236 /** The contents of the merge. */ 237 const char *ptr; 238 239 /** The length of the merge contents. */ 240 size_t len; 241 } git_merge_file_result; 242 243 /** 244 * Merging options 245 */ 246 typedef struct { 247 unsigned int version; 248 249 /** See `git_merge_flag_t` above */ 250 uint32_t flags; 251 252 /** 253 * Similarity to consider a file renamed (default 50). If 254 * `GIT_MERGE_FIND_RENAMES` is enabled, added files will be compared 255 * with deleted files to determine their similarity. Files that are 256 * more similar than the rename threshold (percentage-wise) will be 257 * treated as a rename. 258 */ 259 unsigned int rename_threshold; 260 261 /** 262 * Maximum similarity sources to examine for renames (default 200). 263 * If the number of rename candidates (add / delete pairs) is greater 264 * than this value, inexact rename detection is aborted. 265 * 266 * This setting overrides the `merge.renameLimit` configuration value. 267 */ 268 unsigned int target_limit; 269 270 /** Pluggable similarity metric; pass NULL to use internal metric */ 271 git_diff_similarity_metric *metric; 272 273 /** 274 * Maximum number of times to merge common ancestors to build a 275 * virtual merge base when faced with criss-cross merges. When this 276 * limit is reached, the next ancestor will simply be used instead of 277 * attempting to merge it. The default is unlimited. 278 */ 279 unsigned int recursion_limit; 280 281 /** 282 * Default merge driver to be used when both sides of a merge have 283 * changed. The default is the `text` driver. 284 */ 285 const char *default_driver; 286 287 /** 288 * Flags for handling conflicting content, to be used with the standard 289 * (`text`) merge driver. 290 */ 291 git_merge_file_favor_t file_favor; 292 293 /** see `git_merge_file_flag_t` above */ 294 uint32_t file_flags; 295 } git_merge_options; 296 297 #define GIT_MERGE_OPTIONS_VERSION 1 298 #define GIT_MERGE_OPTIONS_INIT { \ 299 GIT_MERGE_OPTIONS_VERSION, GIT_MERGE_FIND_RENAMES } 300 301 /** 302 * Initialize git_merge_options structure 303 * 304 * Initializes a `git_merge_options` with default values. Equivalent to 305 * creating an instance with `GIT_MERGE_OPTIONS_INIT`. 306 * 307 * @param opts The `git_merge_options` struct to initialize. 308 * @param version The struct version; pass `GIT_MERGE_OPTIONS_VERSION`. 309 * @return Zero on success; -1 on failure. 310 */ 311 GIT_EXTERN(int) git_merge_options_init(git_merge_options *opts, unsigned int version); 312 313 /** 314 * The results of `git_merge_analysis` indicate the merge opportunities. 315 */ 316 typedef enum { 317 /** No merge is possible. (Unused.) */ 318 GIT_MERGE_ANALYSIS_NONE = 0, 319 320 /** 321 * A "normal" merge; both HEAD and the given merge input have diverged 322 * from their common ancestor. The divergent commits must be merged. 323 */ 324 GIT_MERGE_ANALYSIS_NORMAL = (1 << 0), 325 326 /** 327 * All given merge inputs are reachable from HEAD, meaning the 328 * repository is up-to-date and no merge needs to be performed. 329 */ 330 GIT_MERGE_ANALYSIS_UP_TO_DATE = (1 << 1), 331 332 /** 333 * The given merge input is a fast-forward from HEAD and no merge 334 * needs to be performed. Instead, the client can check out the 335 * given merge input. 336 */ 337 GIT_MERGE_ANALYSIS_FASTFORWARD = (1 << 2), 338 339 /** 340 * The HEAD of the current repository is "unborn" and does not point to 341 * a valid commit. No merge can be performed, but the caller may wish 342 * to simply set HEAD to the target commit(s). 343 */ 344 GIT_MERGE_ANALYSIS_UNBORN = (1 << 3), 345 } git_merge_analysis_t; 346 347 /** 348 * The user's stated preference for merges. 349 */ 350 typedef enum { 351 /** 352 * No configuration was found that suggests a preferred behavior for 353 * merge. 354 */ 355 GIT_MERGE_PREFERENCE_NONE = 0, 356 357 /** 358 * There is a `merge.ff=false` configuration setting, suggesting that 359 * the user does not want to allow a fast-forward merge. 360 */ 361 GIT_MERGE_PREFERENCE_NO_FASTFORWARD = (1 << 0), 362 363 /** 364 * There is a `merge.ff=only` configuration setting, suggesting that 365 * the user only wants fast-forward merges. 366 */ 367 GIT_MERGE_PREFERENCE_FASTFORWARD_ONLY = (1 << 1), 368 } git_merge_preference_t; 369 370 /** 371 * Analyzes the given branch(es) and determines the opportunities for 372 * merging them into the HEAD of the repository. 373 * 374 * @param analysis_out analysis enumeration that the result is written into 375 * @param repo the repository to merge 376 * @param their_heads the heads to merge into 377 * @param their_heads_len the number of heads to merge 378 * @return 0 on success or error code 379 */ 380 GIT_EXTERN(int) git_merge_analysis( 381 git_merge_analysis_t *analysis_out, 382 git_merge_preference_t *preference_out, 383 git_repository *repo, 384 const git_annotated_commit **their_heads, 385 size_t their_heads_len); 386 387 /** 388 * Analyzes the given branch(es) and determines the opportunities for 389 * merging them into a reference. 390 * 391 * @param analysis_out analysis enumeration that the result is written into 392 * @param repo the repository to merge 393 * @param our_ref the reference to perform the analysis from 394 * @param their_heads the heads to merge into 395 * @param their_heads_len the number of heads to merge 396 * @return 0 on success or error code 397 */ 398 GIT_EXTERN(int) git_merge_analysis_for_ref( 399 git_merge_analysis_t *analysis_out, 400 git_merge_preference_t *preference_out, 401 git_repository *repo, 402 git_reference *our_ref, 403 const git_annotated_commit **their_heads, 404 size_t their_heads_len); 405 406 /** 407 * Find a merge base between two commits 408 * 409 * @param out the OID of a merge base between 'one' and 'two' 410 * @param repo the repository where the commits exist 411 * @param one one of the commits 412 * @param two the other commit 413 * @return 0 on success, GIT_ENOTFOUND if not found or error code 414 */ 415 GIT_EXTERN(int) git_merge_base( 416 git_oid *out, 417 git_repository *repo, 418 const git_oid *one, 419 const git_oid *two); 420 421 /** 422 * Find merge bases between two commits 423 * 424 * @param out array in which to store the resulting ids 425 * @param repo the repository where the commits exist 426 * @param one one of the commits 427 * @param two the other commit 428 * @return 0 on success, GIT_ENOTFOUND if not found or error code 429 */ 430 GIT_EXTERN(int) git_merge_bases( 431 git_oidarray *out, 432 git_repository *repo, 433 const git_oid *one, 434 const git_oid *two); 435 436 /** 437 * Find a merge base given a list of commits 438 * 439 * @param out the OID of a merge base considering all the commits 440 * @param repo the repository where the commits exist 441 * @param length The number of commits in the provided `input_array` 442 * @param input_array oids of the commits 443 * @return Zero on success; GIT_ENOTFOUND or -1 on failure. 444 */ 445 GIT_EXTERN(int) git_merge_base_many( 446 git_oid *out, 447 git_repository *repo, 448 size_t length, 449 const git_oid input_array[]); 450 451 /** 452 * Find all merge bases given a list of commits 453 * 454 * @param out array in which to store the resulting ids 455 * @param repo the repository where the commits exist 456 * @param length The number of commits in the provided `input_array` 457 * @param input_array oids of the commits 458 * @return Zero on success; GIT_ENOTFOUND or -1 on failure. 459 */ 460 GIT_EXTERN(int) git_merge_bases_many( 461 git_oidarray *out, 462 git_repository *repo, 463 size_t length, 464 const git_oid input_array[]); 465 466 /** 467 * Find a merge base in preparation for an octopus merge 468 * 469 * @param out the OID of a merge base considering all the commits 470 * @param repo the repository where the commits exist 471 * @param length The number of commits in the provided `input_array` 472 * @param input_array oids of the commits 473 * @return Zero on success; GIT_ENOTFOUND or -1 on failure. 474 */ 475 GIT_EXTERN(int) git_merge_base_octopus( 476 git_oid *out, 477 git_repository *repo, 478 size_t length, 479 const git_oid input_array[]); 480 481 /** 482 * Merge two files as they exist in the in-memory data structures, using 483 * the given common ancestor as the baseline, producing a 484 * `git_merge_file_result` that reflects the merge result. The 485 * `git_merge_file_result` must be freed with `git_merge_file_result_free`. 486 * 487 * Note that this function does not reference a repository and any 488 * configuration must be passed as `git_merge_file_options`. 489 * 490 * @param out The git_merge_file_result to be filled in 491 * @param ancestor The contents of the ancestor file 492 * @param ours The contents of the file in "our" side 493 * @param theirs The contents of the file in "their" side 494 * @param opts The merge file options or `NULL` for defaults 495 * @return 0 on success or error code 496 */ 497 GIT_EXTERN(int) git_merge_file( 498 git_merge_file_result *out, 499 const git_merge_file_input *ancestor, 500 const git_merge_file_input *ours, 501 const git_merge_file_input *theirs, 502 const git_merge_file_options *opts); 503 504 /** 505 * Merge two files as they exist in the index, using the given common 506 * ancestor as the baseline, producing a `git_merge_file_result` that 507 * reflects the merge result. The `git_merge_file_result` must be freed with 508 * `git_merge_file_result_free`. 509 * 510 * @param out The git_merge_file_result to be filled in 511 * @param repo The repository 512 * @param ancestor The index entry for the ancestor file (stage level 1) 513 * @param ours The index entry for our file (stage level 2) 514 * @param theirs The index entry for their file (stage level 3) 515 * @param opts The merge file options or NULL 516 * @return 0 on success or error code 517 */ 518 GIT_EXTERN(int) git_merge_file_from_index( 519 git_merge_file_result *out, 520 git_repository *repo, 521 const git_index_entry *ancestor, 522 const git_index_entry *ours, 523 const git_index_entry *theirs, 524 const git_merge_file_options *opts); 525 526 /** 527 * Frees a `git_merge_file_result`. 528 * 529 * @param result The result to free or `NULL` 530 */ 531 GIT_EXTERN(void) git_merge_file_result_free(git_merge_file_result *result); 532 533 /** 534 * Merge two trees, producing a `git_index` that reflects the result of 535 * the merge. The index may be written as-is to the working directory 536 * or checked out. If the index is to be converted to a tree, the caller 537 * should resolve any conflicts that arose as part of the merge. 538 * 539 * The returned index must be freed explicitly with `git_index_free`. 540 * 541 * @param out pointer to store the index result in 542 * @param repo repository that contains the given trees 543 * @param ancestor_tree the common ancestor between the trees (or null if none) 544 * @param our_tree the tree that reflects the destination tree 545 * @param their_tree the tree to merge in to `our_tree` 546 * @param opts the merge tree options (or null for defaults) 547 * @return 0 on success or error code 548 */ 549 GIT_EXTERN(int) git_merge_trees( 550 git_index **out, 551 git_repository *repo, 552 const git_tree *ancestor_tree, 553 const git_tree *our_tree, 554 const git_tree *their_tree, 555 const git_merge_options *opts); 556 557 /** 558 * Merge two commits, producing a `git_index` that reflects the result of 559 * the merge. The index may be written as-is to the working directory 560 * or checked out. If the index is to be converted to a tree, the caller 561 * should resolve any conflicts that arose as part of the merge. 562 * 563 * The returned index must be freed explicitly with `git_index_free`. 564 * 565 * @param out pointer to store the index result in 566 * @param repo repository that contains the given trees 567 * @param our_commit the commit that reflects the destination tree 568 * @param their_commit the commit to merge in to `our_commit` 569 * @param opts the merge tree options (or null for defaults) 570 * @return 0 on success or error code 571 */ 572 GIT_EXTERN(int) git_merge_commits( 573 git_index **out, 574 git_repository *repo, 575 const git_commit *our_commit, 576 const git_commit *their_commit, 577 const git_merge_options *opts); 578 579 /** 580 * Merges the given commit(s) into HEAD, writing the results into the working 581 * directory. Any changes are staged for commit and any conflicts are written 582 * to the index. Callers should inspect the repository's index after this 583 * completes, resolve any conflicts and prepare a commit. 584 * 585 * For compatibility with git, the repository is put into a merging 586 * state. Once the commit is done (or if the uses wishes to abort), 587 * you should clear this state by calling 588 * `git_repository_state_cleanup()`. 589 * 590 * @param repo the repository to merge 591 * @param their_heads the heads to merge into 592 * @param their_heads_len the number of heads to merge 593 * @param merge_opts merge options 594 * @param checkout_opts checkout options 595 * @return 0 on success or error code 596 */ 597 GIT_EXTERN(int) git_merge( 598 git_repository *repo, 599 const git_annotated_commit **their_heads, 600 size_t their_heads_len, 601 const git_merge_options *merge_opts, 602 const git_checkout_options *checkout_opts); 603 604 /** @} */ 605 GIT_END_DECL 606 #endif 607