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