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