Documentation/git-merge.txt

   1 git-merge(1)
   2 ============
   3
   4 NAME
   5 ----
   6 git-merge - Join two or more development histories together
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
  13         [-m <msg>] <commit>...
  14 'git merge' <msg> HEAD <commit>...
  15
  16 DESCRIPTION
  17 -----------
  18 Incorporates changes from the named commits (since the time their
  19 histories diverged from the current branch) into the current
  20 branch.  This command is used by 'git pull' to incorporate changes
  21 from another repository and can be used by hand to merge changes
  22 from one branch into another.
  23
  24 Assume 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
  33 Then "`git merge topic`" will replay the changes made on the
  34 `topic` branch since it diverged from `master` (i.e., `E`) until
  35 its current commit (`C`) on top of `master`, and record the result
  36 in a new commit along with the names of the two parent commits and
  37 a 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
  45 The second syntax (<msg> `HEAD` <commit>...) is supported for
  46 historical reasons.  Do not use it from the command line or in
  47 new scripts.  It is the same as `git merge -m <msg> <commit>...`.
  48
  49 *Warning*: Running 'git merge' with uncommitted changes is
  50 discouraged: while possible, it leaves you in a state that is hard to
  51 back out of in the case of a conflict.
  52
  53
  54 OPTIONS
  55 -------
  56 include::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
  70 HOW MERGE WORKS
  71 ---------------
  72
  73 A merge is always between the current `HEAD` and one or more
  74 commits (usually, branch head or tag), and the index file must
  75 match the tree of `HEAD` commit (i.e. the contents of the last commit)
  76 when it starts out.  In other words, `git diff --cached HEAD` must
  77 report no changes.  (One exception is when the changed index
  78 entries are already in the same state that would result from
  79 the merge anyway.)
  80
  81 Three 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
  98 The chosen merge strategy merges the two commits into a single
  99 new source tree.
 100 When things merge cleanly, this is what happens:
 101
 102 1. The results are updated both in the index file and in your
 103    working tree;
 104 2. Index file is written out as a tree;
 105 3. The tree gets committed; and
 106 4. The `HEAD` pointer gets advanced.
 107
 108 Because of 2., we require that the original state of the index
 109 file matches exactly the current `HEAD` commit; otherwise we
 110 will write out your local changes already registered in your
 111 index file along with the merge result, which is not good.
 112 Because 1. involves only those paths differing between your
 113 branch and the branch you are merging
 114 (which is typically a fraction of the whole tree), you can
 115 have local modifications in your working tree as long as they do
 116 not overlap with what the merge updates.
 117
 118 When there are conflicts, the following happens:
 119
 120 1. `HEAD` stays the same.
 121
 122 2. Cleanly merged paths are updated both in the index file and
 123    in your working tree.
 124
 125 3. 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
 132 4. 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
 137 If you tried a merge which resulted in complex conflicts and
 138 want to start over, you can recover with `git reset --merge`.
 139
 140 HOW CONFLICTS ARE PRESENTED
 141 ---------------------------
 142
 143 During a merge, the working tree files are updated to reflect the result
 144 of the merge.  Among the changes made to the common ancestor's version,
 145 non-overlapping ones (that is, you changed an area of the file while the
 146 other side left that area intact, or vice versa) are incorporated in the
 147 final result verbatim.  When both sides made changes to the same area,
 148 however, git cannot randomly pick one side over the other, and asks you to
 149 resolve it by leaving what both sides did to that area.
 150
 151 By default, git uses the same style as that is used by "merge" program
 152 from the RCS suite to present such a conflicted hunk, like this:
 153
 154 ------------
 155 Here are lines that are either unchanged from the common
 156 ancestor, or cleanly resolved because only one side changed.
 157 <<<<<<< yours:sample.txt
 158 Conflict resolution is hard;
 159 let's go shopping.
 160 =======
 161 Git makes conflict resolution easy.
 162 >>>>>>> theirs:sample.txt
 163 And here is another line that is cleanly resolved or unmodified.
 164 ------------
 165
 166 The area where a pair of conflicting changes happened is marked with markers
 167 `<<<<<<<`, `=======`, and `>>>>>>>`.  The part before the `=======`
 168 is typically your side, and the part afterwards is typically their side.
 169
 170 The default format does not show what the original said in the conflicting
 171 area.  You cannot tell how many lines are deleted and replaced with
 172 Barbie's remark on your side.  The only thing you can tell is that your
 173 side wants to say it is hard and you'd prefer to go shopping, while the
 174 other side wants to claim it is easy.
 175
 176 An alternative style can be used by setting the "merge.conflictstyle"
 177 configuration variable to "diff3".  In "diff3" style, the above conflict
 178 may look like this:
 179
 180 ------------
 181 Here are lines that are either unchanged from the common
 182 ancestor, or cleanly resolved because only one side changed.
 183 <<<<<<< yours:sample.txt
 184 Conflict resolution is hard;
 185 let's go shopping.
 186 |||||||
 187 Conflict resolution is hard.
 188 =======
 189 Git makes conflict resolution easy.
 190 >>>>>>> theirs:sample.txt
 191 And here is another line that is cleanly resolved or unmodified.
 192 ------------
 193
 194 In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
 195 another `|||||||` marker that is followed by the original text.  You can
 196 tell that the original just stated a fact, and your side simply gave in to
 197 that statement and gave up, while the other side tried to have a more
 198 positive attitude.  You can sometimes come up with a better resolution by
 199 viewing the original.
 200
 201
 202 HOW TO RESOLVE CONFLICTS
 203 ------------------------
 204
 205 After 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
 216 You 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
 233 EXAMPLES
 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 +
 257 This can be used when you want to include further changes to the
 258 merge, or want to write your own merge commit message.
 259 +
 260 You should refrain from abusing this option to sneak substantial
 261 changes into a merge commit.  Small fixups like bumping
 262 release/version name would be acceptable.
 263
 264
 265 include::merge-strategies.txt[]
 266
 267 CONFIGURATION
 268 -------------
 269 include::merge-config.txt[]
 270
 271 branch.<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
 276 SEE ALSO
 277 --------
 278 linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
 279 linkgit:gitattributes[5],
 280 linkgit:git-reset[1],
 281 linkgit:git-diff[1], linkgit:git-ls-files[1],
 282 linkgit:git-add[1], linkgit:git-rm[1],
 283 linkgit:git-mergetool[1]
 284
 285 Author
 286 ------
 287 Written by Junio C Hamano <gitster@pobox.com>
 288
 289
 290 Documentation
 291 --------------
 292 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 293
 294 GIT
 295 ---
 296 Part of the linkgit:git[1] suite