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