Documentation / git-merge.txton commit wt-status.h: drop stdio.h include (7a06fb0)
   1git-merge(1)
   2============
   3
   4NAME
   5----
   6git-merge - Join two or more development histories together
   7
   8
   9SYNOPSIS
  10--------
  11[verse]
  12'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
  13        [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
  14        [--[no-]allow-unrelated-histories]
  15        [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>...]
  16'git merge' --abort
  17'git merge' --continue
  18
  19DESCRIPTION
  20-----------
  21Incorporates changes from the named commits (since the time their
  22histories diverged from the current branch) into the current
  23branch.  This command is used by 'git pull' to incorporate changes
  24from another repository and can be used by hand to merge changes
  25from one branch into another.
  26
  27Assume the following history exists and the current branch is
  28"`master`":
  29
  30------------
  31          A---B---C topic
  32         /
  33    D---E---F---G master
  34------------
  35
  36Then "`git merge topic`" will replay the changes made on the
  37`topic` branch since it diverged from `master` (i.e., `E`) until
  38its current commit (`C`) on top of `master`, and record the result
  39in a new commit along with the names of the two parent commits and
  40a log message from the user describing the changes.
  41
  42------------
  43          A---B---C topic
  44         /         \
  45    D---E---F---G---H master
  46------------
  47
  48The second syntax ("`git merge --abort`") can only be run after the
  49merge has resulted in conflicts. 'git merge --abort' will abort the
  50merge process and try to reconstruct the pre-merge state. However,
  51if there were uncommitted changes when the merge started (and
  52especially if those changes were further modified after the merge
  53was started), 'git merge --abort' will in some cases be unable to
  54reconstruct the original (pre-merge) changes. Therefore:
  55
  56*Warning*: Running 'git merge' with non-trivial uncommitted changes is
  57discouraged: while possible, it may leave you in a state that is hard to
  58back out of in the case of a conflict.
  59
  60The third syntax ("`git merge --continue`") can only be run after the
  61merge has resulted in conflicts.
  62
  63OPTIONS
  64-------
  65include::merge-options.txt[]
  66
  67-m <msg>::
  68        Set the commit message to be used for the merge commit (in
  69        case one is created).
  70+
  71If `--log` is specified, a shortlog of the commits being merged
  72will be appended to the specified message.
  73+
  74The 'git fmt-merge-msg' command can be
  75used to give a good default for automated 'git merge'
  76invocations. The automated message can include the branch description.
  77
  78-F <file>::
  79--file=<file>::
  80        Read the commit message to be used for the merge commit (in
  81        case one is created).
  82+
  83If `--log` is specified, a shortlog of the commits being merged
  84will be appended to the specified message.
  85
  86--rerere-autoupdate::
  87--no-rerere-autoupdate::
  88        Allow the rerere mechanism to update the index with the
  89        result of auto-conflict resolution if possible.
  90
  91--abort::
  92        Abort the current conflict resolution process, and
  93        try to reconstruct the pre-merge state.
  94+
  95If there were uncommitted worktree changes present when the merge
  96started, 'git merge --abort' will in some cases be unable to
  97reconstruct these changes. It is therefore recommended to always
  98commit or stash your changes before running 'git merge'.
  99+
 100'git merge --abort' is equivalent to 'git reset --merge' when
 101`MERGE_HEAD` is present.
 102
 103--continue::
 104        After a 'git merge' stops due to conflicts you can conclude the
 105        merge by running 'git merge --continue' (see "HOW TO RESOLVE
 106        CONFLICTS" section below).
 107
 108<commit>...::
 109        Commits, usually other branch heads, to merge into our branch.
 110        Specifying more than one commit will create a merge with
 111        more than two parents (affectionately called an Octopus merge).
 112+
 113If no commit is given from the command line, merge the remote-tracking
 114branches that the current branch is configured to use as its upstream.
 115See also the configuration section of this manual page.
 116+
 117When `FETCH_HEAD` (and no other commit) is specified, the branches
 118recorded in the `.git/FETCH_HEAD` file by the previous invocation
 119of `git fetch` for merging are merged to the current branch.
 120
 121
 122PRE-MERGE CHECKS
 123----------------
 124
 125Before applying outside changes, you should get your own work in
 126good shape and committed locally, so it will not be clobbered if
 127there are conflicts.  See also linkgit:git-stash[1].
 128'git pull' and 'git merge' will stop without doing anything when
 129local uncommitted changes overlap with files that 'git pull'/'git
 130merge' may need to update.
 131
 132To avoid recording unrelated changes in the merge commit,
 133'git pull' and 'git merge' will also abort if there are any changes
 134registered in the index relative to the `HEAD` commit.  (Special
 135narrow exceptions to this rule may exist depending on which merge
 136strategy is in use, but generally, the index must match HEAD.)
 137
 138If all named commits are already ancestors of `HEAD`, 'git merge'
 139will exit early with the message "Already up to date."
 140
 141FAST-FORWARD MERGE
 142------------------
 143
 144Often the current branch head is an ancestor of the named commit.
 145This is the most common case especially when invoked from 'git
 146pull': you are tracking an upstream repository, you have committed
 147no local changes, and now you want to update to a newer upstream
 148revision.  In this case, a new commit is not needed to store the
 149combined history; instead, the `HEAD` (along with the index) is
 150updated to point at the named commit, without creating an extra
 151merge commit.
 152
 153This behavior can be suppressed with the `--no-ff` option.
 154
 155TRUE MERGE
 156----------
 157
 158Except in a fast-forward merge (see above), the branches to be
 159merged must be tied together by a merge commit that has both of them
 160as its parents.
 161
 162A merged version reconciling the changes from all branches to be
 163merged is committed, and your `HEAD`, index, and working tree are
 164updated to it.  It is possible to have modifications in the working
 165tree as long as they do not overlap; the update will preserve them.
 166
 167When it is not obvious how to reconcile the changes, the following
 168happens:
 169
 1701. The `HEAD` pointer stays the same.
 1712. The `MERGE_HEAD` ref is set to point to the other branch head.
 1723. Paths that merged cleanly are updated both in the index file and
 173   in your working tree.
 1744. For conflicting paths, the index file records up to three
 175   versions: stage 1 stores the version from the common ancestor,
 176   stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
 177   can inspect the stages with `git ls-files -u`).  The working
 178   tree files contain the result of the "merge" program; i.e. 3-way
 179   merge results with familiar conflict markers `<<<` `===` `>>>`.
 1805. No other changes are made.  In particular, the local
 181   modifications you had before you started merge will stay the
 182   same and the index entries for them stay as they were,
 183   i.e. matching `HEAD`.
 184
 185If you tried a merge which resulted in complex conflicts and
 186want to start over, you can recover with `git merge --abort`.
 187
 188MERGING TAG
 189-----------
 190
 191When merging an annotated (and possibly signed) tag, Git always
 192creates a merge commit even if a fast-forward merge is possible, and
 193the commit message template is prepared with the tag message.
 194Additionally, if the tag is signed, the signature check is reported
 195as a comment in the message template. See also linkgit:git-tag[1].
 196
 197When you want to just integrate with the work leading to the commit
 198that happens to be tagged, e.g. synchronizing with an upstream
 199release point, you may not want to make an unnecessary merge commit.
 200
 201In such a case, you can "unwrap" the tag yourself before feeding it
 202to `git merge`, or pass `--ff-only` when you do not have any work on
 203your own. e.g.
 204
 205----
 206git fetch origin
 207git merge v1.2.3^0
 208git merge --ff-only v1.2.3
 209----
 210
 211
 212HOW CONFLICTS ARE PRESENTED
 213---------------------------
 214
 215During a merge, the working tree files are updated to reflect the result
 216of the merge.  Among the changes made to the common ancestor's version,
 217non-overlapping ones (that is, you changed an area of the file while the
 218other side left that area intact, or vice versa) are incorporated in the
 219final result verbatim.  When both sides made changes to the same area,
 220however, Git cannot randomly pick one side over the other, and asks you to
 221resolve it by leaving what both sides did to that area.
 222
 223By default, Git uses the same style as the one used by the "merge" program
 224from the RCS suite to present such a conflicted hunk, like this:
 225
 226------------
 227Here are lines that are either unchanged from the common
 228ancestor, or cleanly resolved because only one side changed.
 229<<<<<<< yours:sample.txt
 230Conflict resolution is hard;
 231let's go shopping.
 232=======
 233Git makes conflict resolution easy.
 234>>>>>>> theirs:sample.txt
 235And here is another line that is cleanly resolved or unmodified.
 236------------
 237
 238The area where a pair of conflicting changes happened is marked with markers
 239`<<<<<<<`, `=======`, and `>>>>>>>`.  The part before the `=======`
 240is typically your side, and the part afterwards is typically their side.
 241
 242The default format does not show what the original said in the conflicting
 243area.  You cannot tell how many lines are deleted and replaced with
 244Barbie's remark on your side.  The only thing you can tell is that your
 245side wants to say it is hard and you'd prefer to go shopping, while the
 246other side wants to claim it is easy.
 247
 248An alternative style can be used by setting the "merge.conflictStyle"
 249configuration variable to "diff3".  In "diff3" style, the above conflict
 250may look like this:
 251
 252------------
 253Here are lines that are either unchanged from the common
 254ancestor, or cleanly resolved because only one side changed.
 255<<<<<<< yours:sample.txt
 256Conflict resolution is hard;
 257let's go shopping.
 258|||||||
 259Conflict resolution is hard.
 260=======
 261Git makes conflict resolution easy.
 262>>>>>>> theirs:sample.txt
 263And here is another line that is cleanly resolved or unmodified.
 264------------
 265
 266In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
 267another `|||||||` marker that is followed by the original text.  You can
 268tell that the original just stated a fact, and your side simply gave in to
 269that statement and gave up, while the other side tried to have a more
 270positive attitude.  You can sometimes come up with a better resolution by
 271viewing the original.
 272
 273
 274HOW TO RESOLVE CONFLICTS
 275------------------------
 276
 277After seeing a conflict, you can do two things:
 278
 279 * Decide not to merge.  The only clean-ups you need are to reset
 280   the index file to the `HEAD` commit to reverse 2. and to clean
 281   up working tree changes made by 2. and 3.; `git merge --abort`
 282   can be used for this.
 283
 284 * Resolve the conflicts.  Git will mark the conflicts in
 285   the working tree.  Edit the files into shape and
 286   'git add' them to the index.  Use 'git commit' or
 287   'git merge --continue' to seal the deal. The latter command
 288   checks whether there is a (interrupted) merge in progress
 289   before calling 'git commit'.
 290
 291You can work through the conflict with a number of tools:
 292
 293 * Use a mergetool.  `git mergetool` to launch a graphical
 294   mergetool which will work you through the merge.
 295
 296 * Look at the diffs.  `git diff` will show a three-way diff,
 297   highlighting changes from both the `HEAD` and `MERGE_HEAD`
 298   versions.
 299
 300 * Look at the diffs from each branch. `git log --merge -p <path>`
 301   will show diffs first for the `HEAD` version and then the
 302   `MERGE_HEAD` version.
 303
 304 * Look at the originals.  `git show :1:filename` shows the
 305   common ancestor, `git show :2:filename` shows the `HEAD`
 306   version, and `git show :3:filename` shows the `MERGE_HEAD`
 307   version.
 308
 309
 310EXAMPLES
 311--------
 312
 313* Merge branches `fixes` and `enhancements` on top of
 314  the current branch, making an octopus merge:
 315+
 316------------------------------------------------
 317$ git merge fixes enhancements
 318------------------------------------------------
 319
 320* Merge branch `obsolete` into the current branch, using `ours`
 321  merge strategy:
 322+
 323------------------------------------------------
 324$ git merge -s ours obsolete
 325------------------------------------------------
 326
 327* Merge branch `maint` into the current branch, but do not make
 328  a new commit automatically:
 329+
 330------------------------------------------------
 331$ git merge --no-commit maint
 332------------------------------------------------
 333+
 334This can be used when you want to include further changes to the
 335merge, or want to write your own merge commit message.
 336+
 337You should refrain from abusing this option to sneak substantial
 338changes into a merge commit.  Small fixups like bumping
 339release/version name would be acceptable.
 340
 341
 342include::merge-strategies.txt[]
 343
 344CONFIGURATION
 345-------------
 346include::config/merge.txt[]
 347
 348branch.<name>.mergeOptions::
 349        Sets default options for merging into branch <name>. The syntax and
 350        supported options are the same as those of 'git merge', but option
 351        values containing whitespace characters are currently not supported.
 352
 353SEE ALSO
 354--------
 355linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
 356linkgit:gitattributes[5],
 357linkgit:git-reset[1],
 358linkgit:git-diff[1], linkgit:git-ls-files[1],
 359linkgit:git-add[1], linkgit:git-rm[1],
 360linkgit:git-mergetool[1]
 361
 362GIT
 363---
 364Part of the linkgit:git[1] suite