e3c611dd0e5a7564c087d8d09eea8943dc509d08
   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] [-s <strategy>]...
  13        [-m <msg>] <commit>...
  14'git merge' <msg> HEAD <commit>...
  15
  16DESCRIPTION
  17-----------
  18Incorporates changes from the named commits (since the time their
  19histories diverged from the current branch) into the current
  20branch.  This command is used by 'git pull' to incorporate changes
  21from another repository and can be used by hand to merge changes
  22from one branch into another.
  23
  24Assume the following history exists and the current branch is
  25"`master`":
  26
  27------------
  28          A---B---C topic
  29         /
  30    D---E---F---G master
  31------------
  32
  33Then "`git merge topic`" will replay the changes made on the
  34`topic` branch since it diverged from `master` (i.e., `E`) until
  35its current commit (`C`) on top of `master`, and record the result
  36in a new commit along with the names of the two parent commits and
  37a log message from the user describing the changes.
  38
  39------------
  40          A---B---C topic
  41         /         \
  42    D---E---F---G---H master
  43------------
  44
  45The second syntax (<msg> `HEAD` <commit>...) is supported for
  46historical reasons.  Do not use it from the command line or in
  47new scripts.  It is the same as `git merge -m <msg> <commit>...`.
  48
  49*Warning*: Running 'git merge' with uncommitted changes is
  50discouraged: while possible, it leaves you in a state that is hard to
  51back out of in the case of a conflict.
  52
  53
  54OPTIONS
  55-------
  56include::merge-options.txt[]
  57
  58-m <msg>::
  59        Set the commit message to be used for the merge commit (in
  60        case one is created). The 'git fmt-merge-msg' command can be
  61        used to give a good default for automated 'git merge'
  62        invocations.
  63
  64<commit>...::
  65        Commits, usually other branch heads, to merge into our branch.
  66        You need at least one <commit>.  Specifying more than one
  67        <commit> obviously means you are trying an Octopus.
  68
  69
  70HOW MERGE WORKS
  71---------------
  72
  73A merge is always between the current `HEAD` and one or more
  74commits (usually, branch head or tag), and the index file must
  75match the tree of `HEAD` commit (i.e. the contents of the last commit)
  76when it starts out.  In other words, `git diff --cached HEAD` must
  77report no changes.  (One exception is when the changed index
  78entries are already in the same state that would result from
  79the merge anyway.)
  80
  81Three kinds of merge can happen:
  82
  83* The merged commit is already contained in `HEAD`. This is the
  84  simplest case, called "Already up-to-date."
  85
  86* `HEAD` is already contained in the merged commit. This is the
  87  most common case especially when invoked from 'git pull':
  88  you are tracking an upstream repository, have committed no local
  89  changes and now you want to update to a newer upstream revision.
  90  Your `HEAD` (and the index) is updated to point at the merged
  91  commit, without creating an extra merge commit.  This is
  92  called "Fast-forward".
  93
  94* Both the merged commit and `HEAD` are independent and must be
  95  tied together by a merge commit that has both of them as its parents.
  96  The rest of this section describes this "True merge" case.
  97
  98The chosen merge strategy merges the two commits into a single
  99new source tree.
 100When things merge cleanly, this is what happens:
 101
 1021. The results are updated both in the index file and in your
 103   working tree;
 1042. Index file is written out as a tree;
 1053. The tree gets committed; and
 1064. The `HEAD` pointer gets advanced.
 107
 108Because of 2., we require that the original state of the index
 109file matches exactly the current `HEAD` commit; otherwise we
 110will write out your local changes already registered in your
 111index file along with the merge result, which is not good.
 112Because 1. involves only those paths differing between your
 113branch and the branch you are merging
 114(which is typically a fraction of the whole tree), you can
 115have local modifications in your working tree as long as they do
 116not overlap with what the merge updates.
 117
 118When there are conflicts, the following happens:
 119
 1201. `HEAD` stays the same.
 121
 1222. Cleanly merged paths are updated both in the index file and
 123   in your working tree.
 124
 1253. For conflicting paths, the index file records up to three
 126   versions; stage1 stores the version from the common ancestor,
 127   stage2 from `HEAD`, and stage3 from the other branch (you
 128   can inspect the stages with `git ls-files -u`).  The working
 129   tree files contain the result of the "merge" program; i.e. 3-way
 130   merge results with familiar conflict markers `<<< === >>>`.
 131
 1324. No other changes are done.  In particular, the local
 133   modifications you had before you started merge will stay the
 134   same and the index entries for them stay as they were,
 135   i.e. matching `HEAD`.
 136
 137If you tried a merge which resulted in complex conflicts and
 138want to start over, you can recover with `git reset --merge`.
 139
 140HOW CONFLICTS ARE PRESENTED
 141---------------------------
 142
 143During a merge, the working tree files are updated to reflect the result
 144of the merge.  Among the changes made to the common ancestor's version,
 145non-overlapping ones (that is, you changed an area of the file while the
 146other side left that area intact, or vice versa) are incorporated in the
 147final result verbatim.  When both sides made changes to the same area,
 148however, git cannot randomly pick one side over the other, and asks you to
 149resolve it by leaving what both sides did to that area.
 150
 151By default, git uses the same style as that is used by "merge" program
 152from the RCS suite to present such a conflicted hunk, like this:
 153
 154------------
 155Here are lines that are either unchanged from the common
 156ancestor, or cleanly resolved because only one side changed.
 157<<<<<<< yours:sample.txt
 158Conflict resolution is hard;
 159let's go shopping.
 160=======
 161Git makes conflict resolution easy.
 162>>>>>>> theirs:sample.txt
 163And here is another line that is cleanly resolved or unmodified.
 164------------
 165
 166The area where a pair of conflicting changes happened is marked with markers
 167`<<<<<<<`, `=======`, and `>>>>>>>`.  The part before the `=======`
 168is typically your side, and the part afterwards is typically their side.
 169
 170The default format does not show what the original said in the conflicting
 171area.  You cannot tell how many lines are deleted and replaced with
 172Barbie's remark on your side.  The only thing you can tell is that your
 173side wants to say it is hard and you'd prefer to go shopping, while the
 174other side wants to claim it is easy.
 175
 176An alternative style can be used by setting the "merge.conflictstyle"
 177configuration variable to "diff3".  In "diff3" style, the above conflict
 178may look like this:
 179
 180------------
 181Here are lines that are either unchanged from the common
 182ancestor, or cleanly resolved because only one side changed.
 183<<<<<<< yours:sample.txt
 184Conflict resolution is hard;
 185let's go shopping.
 186|||||||
 187Conflict resolution is hard.
 188=======
 189Git makes conflict resolution easy.
 190>>>>>>> theirs:sample.txt
 191And here is another line that is cleanly resolved or unmodified.
 192------------
 193
 194In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
 195another `|||||||` marker that is followed by the original text.  You can
 196tell that the original just stated a fact, and your side simply gave in to
 197that statement and gave up, while the other side tried to have a more
 198positive attitude.  You can sometimes come up with a better resolution by
 199viewing the original.
 200
 201
 202HOW TO RESOLVE CONFLICTS
 203------------------------
 204
 205After seeing a conflict, you can do two things:
 206
 207 * Decide not to merge.  The only clean-ups you need are to reset
 208   the index file to the `HEAD` commit to reverse 2. and to clean
 209   up working tree changes made by 2. and 3.; `git-reset --hard` can
 210   be used for this.
 211
 212 * Resolve the conflicts.  Git will mark the conflicts in
 213   the working tree.  Edit the files into shape and
 214   'git add' them to the index.  Use 'git commit' to seal the deal.
 215
 216You can work through the conflict with a number of tools:
 217
 218 * Use a mergetool.  `git mergetool` to launch a graphical
 219   mergetool which will work you through the merge.
 220
 221 * Look at the diffs.  `git diff` will show a three-way diff,
 222   highlighting changes from both the HEAD and their versions.
 223
 224 * Look at the diffs on their own. `git log --merge -p <path>`
 225   will show diffs first for the HEAD version and then
 226   their version.
 227
 228 * Look at the originals.  `git show :1:filename` shows the
 229   common ancestor, `git show :2:filename` shows the HEAD
 230   version and `git show :3:filename` shows their version.
 231
 232
 233EXAMPLES
 234--------
 235
 236* Merge branches `fixes` and `enhancements` on top of
 237  the current branch, making an octopus merge:
 238+
 239------------------------------------------------
 240$ git merge fixes enhancements
 241------------------------------------------------
 242
 243* Merge branch `obsolete` into the current branch, using `ours`
 244  merge strategy:
 245+
 246------------------------------------------------
 247$ git merge -s ours obsolete
 248------------------------------------------------
 249
 250* Merge branch `maint` into the current branch, but do not make
 251  a new commit automatically:
 252+
 253------------------------------------------------
 254$ git merge --no-commit maint
 255------------------------------------------------
 256+
 257This can be used when you want to include further changes to the
 258merge, or want to write your own merge commit message.
 259+
 260You should refrain from abusing this option to sneak substantial
 261changes into a merge commit.  Small fixups like bumping
 262release/version name would be acceptable.
 263
 264
 265include::merge-strategies.txt[]
 266
 267CONFIGURATION
 268-------------
 269include::merge-config.txt[]
 270
 271branch.<name>.mergeoptions::
 272        Sets default options for merging into branch <name>. The syntax and
 273        supported options are the same as those of 'git merge', but option
 274        values containing whitespace characters are currently not supported.
 275
 276SEE ALSO
 277--------
 278linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
 279linkgit:gitattributes[5],
 280linkgit:git-reset[1],
 281linkgit:git-diff[1], linkgit:git-ls-files[1],
 282linkgit:git-add[1], linkgit:git-rm[1],
 283linkgit:git-mergetool[1]
 284
 285Author
 286------
 287Written by Junio C Hamano <gitster@pobox.com>
 288
 289
 290Documentation
 291--------------
 292Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 293
 294GIT
 295---
 296Part of the linkgit:git[1] suite