include/git2/merge.h

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