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] 13 [-s <strategy>] [-X <strategy-option>] 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 uncommitted changes is 60discouraged: while possible, it leaves 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-m <msg>:: 69 Set the commit message to be used for the merge commit (in 70 case one is created). 71+ 72If `--log` is specified, a shortlog of the commits being merged 73will be appended to the specified message. 74+ 75The 'git fmt-merge-msg' command can be 76used to give a good default for automated 'git merge' 77invocations. 78 79--rerere-autoupdate:: 80--no-rerere-autoupdate:: 81 Allow the rerere mechanism to update the index with the 82 result of auto-conflict resolution if possible. 83 84--abort:: 85 Abort the current conflict resolution process, and 86 try to reconstruct the pre-merge state. 87+ 88If there were uncommitted worktree changes present when the merge 89started, 'git merge --abort' will in some cases be unable to 90reconstruct these changes. It is therefore recommended to always 91commit or stash your changes before running 'git merge'. 92+ 93'git merge --abort' is equivalent to 'git reset --merge' when 94`MERGE_HEAD` is present. 95 96<commit>...:: 97 Commits, usually other branch heads, to merge into our branch. 98 You need at least one <commit>. Specifying more than one 99 <commit> obviously means you are trying an Octopus. 100 101 102PRE-MERGE CHECKS 103---------------- 104 105Before applying outside changes, you should get your own work in 106good shape and committed locally, so it will not be clobbered if 107there are conflicts. See also linkgit:git-stash[1]. 108'git pull' and 'git merge' will stop without doing anything when 109local uncommitted changes overlap with files that 'git pull'/'git 110merge' may need to update. 111 112To avoid recording unrelated changes in the merge commit, 113'git pull' and 'git merge' will also abort if there are any changes 114registered in the index relative to the `HEAD` commit. (One 115exception is when the changed index entries are in the state that 116would result from the merge already.) 117 118If all named commits are already ancestors of `HEAD`, 'git merge' 119will exit early with the message "Already up-to-date." 120 121FAST-FORWARD MERGE 122------------------ 123 124Often the current branch head is an ancestor of the named commit. 125This is the most common case especially when invoked from 'git 126pull': you are tracking an upstream repository, you have committed 127no local changes, and now you want to update to a newer upstream 128revision. In this case, a new commit is not needed to store the 129combined history; instead, the `HEAD` (along with the index) is 130updated to point at the named commit, without creating an extra 131merge commit. 132 133This behavior can be suppressed with the `--no-ff` option. 134 135TRUE MERGE 136---------- 137 138Except in a fast-forward merge (see above), the branches to be 139merged must be tied together by a merge commit that has both of them 140as its parents. 141 142A merged version reconciling the changes from all branches to be 143merged is committed, and your `HEAD`, index, and working tree are 144updated to it. It is possible to have modifications in the working 145tree as long as they do not overlap; the update will preserve them. 146 147When it is not obvious how to reconcile the changes, the following 148happens: 149 1501. The `HEAD` pointer stays the same. 1512. The `MERGE_HEAD` ref is set to point to the other branch head. 1523. Paths that merged cleanly are updated both in the index file and 153 in your working tree. 1544. For conflicting paths, the index file records up to three 155 versions: stage 1 stores the version from the common ancestor, 156 stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you 157 can inspect the stages with `git ls-files -u`). The working 158 tree files contain the result of the "merge" program; i.e. 3-way 159 merge results with familiar conflict markers `<<<` `===` `>>>`. 1605. No other changes are made. In particular, the local 161 modifications you had before you started merge will stay the 162 same and the index entries for them stay as they were, 163 i.e. matching `HEAD`. 164 165If you tried a merge which resulted in complex conflicts and 166want to start over, you can recover with `git merge --abort`. 167 168HOW CONFLICTS ARE PRESENTED 169--------------------------- 170 171During a merge, the working tree files are updated to reflect the result 172of the merge. Among the changes made to the common ancestor's version, 173non-overlapping ones (that is, you changed an area of the file while the 174other side left that area intact, or vice versa) are incorporated in the 175final result verbatim. When both sides made changes to the same area, 176however, git cannot randomly pick one side over the other, and asks you to 177resolve it by leaving what both sides did to that area. 178 179By default, git uses the same style as that is used by "merge" program 180from the RCS suite to present such a conflicted hunk, like this: 181 182------------ 183Here are lines that are either unchanged from the common 184ancestor, or cleanly resolved because only one side changed. 185<<<<<<< yours:sample.txt 186Conflict resolution is hard; 187let's go shopping. 188======= 189Git makes conflict resolution easy. 190>>>>>>> theirs:sample.txt 191And here is another line that is cleanly resolved or unmodified. 192------------ 193 194The area where a pair of conflicting changes happened is marked with markers 195`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======` 196is typically your side, and the part afterwards is typically their side. 197 198The default format does not show what the original said in the conflicting 199area. You cannot tell how many lines are deleted and replaced with 200Barbie's remark on your side. The only thing you can tell is that your 201side wants to say it is hard and you'd prefer to go shopping, while the 202other side wants to claim it is easy. 203 204An alternative style can be used by setting the "merge.conflictstyle" 205configuration variable to "diff3". In "diff3" style, the above conflict 206may look like this: 207 208------------ 209Here are lines that are either unchanged from the common 210ancestor, or cleanly resolved because only one side changed. 211<<<<<<< yours:sample.txt 212Conflict resolution is hard; 213let's go shopping. 214||||||| 215Conflict resolution is hard. 216======= 217Git makes conflict resolution easy. 218>>>>>>> theirs:sample.txt 219And here is another line that is cleanly resolved or unmodified. 220------------ 221 222In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses 223another `|||||||` marker that is followed by the original text. You can 224tell that the original just stated a fact, and your side simply gave in to 225that statement and gave up, while the other side tried to have a more 226positive attitude. You can sometimes come up with a better resolution by 227viewing the original. 228 229 230HOW TO RESOLVE CONFLICTS 231------------------------ 232 233After seeing a conflict, you can do two things: 234 235 * Decide not to merge. The only clean-ups you need are to reset 236 the index file to the `HEAD` commit to reverse 2. and to clean 237 up working tree changes made by 2. and 3.; `git merge --abort` 238 can be used for this. 239 240 * Resolve the conflicts. Git will mark the conflicts in 241 the working tree. Edit the files into shape and 242 'git add' them to the index. Use 'git commit' to seal the deal. 243 244You can work through the conflict with a number of tools: 245 246 * Use a mergetool. `git mergetool` to launch a graphical 247 mergetool which will work you through the merge. 248 249 * Look at the diffs. `git diff` will show a three-way diff, 250 highlighting changes from both the `HEAD` and `MERGE_HEAD` 251 versions. 252 253 * Look at the diffs from each branch. `git log --merge -p <path>` 254 will show diffs first for the `HEAD` version and then the 255 `MERGE_HEAD` version. 256 257 * Look at the originals. `git show :1:filename` shows the 258 common ancestor, `git show :2:filename` shows the `HEAD` 259 version, and `git show :3:filename` shows the `MERGE_HEAD` 260 version. 261 262 263EXAMPLES 264-------- 265 266* Merge branches `fixes` and `enhancements` on top of 267 the current branch, making an octopus merge: 268+ 269------------------------------------------------ 270$ git merge fixes enhancements 271------------------------------------------------ 272 273* Merge branch `obsolete` into the current branch, using `ours` 274 merge strategy: 275+ 276------------------------------------------------ 277$ git merge -s ours obsolete 278------------------------------------------------ 279 280* Merge branch `maint` into the current branch, but do not make 281 a new commit automatically: 282+ 283------------------------------------------------ 284$ git merge --no-commit maint 285------------------------------------------------ 286+ 287This can be used when you want to include further changes to the 288merge, or want to write your own merge commit message. 289+ 290You should refrain from abusing this option to sneak substantial 291changes into a merge commit. Small fixups like bumping 292release/version name would be acceptable. 293 294 295include::merge-strategies.txt[] 296 297CONFIGURATION 298------------- 299include::merge-config.txt[] 300 301branch.<name>.mergeoptions:: 302 Sets default options for merging into branch <name>. The syntax and 303 supported options are the same as those of 'git merge', but option 304 values containing whitespace characters are currently not supported. 305 306SEE ALSO 307-------- 308linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], 309linkgit:gitattributes[5], 310linkgit:git-reset[1], 311linkgit:git-diff[1], linkgit:git-ls-files[1], 312linkgit:git-add[1], linkgit:git-rm[1], 313linkgit:git-mergetool[1] 314 315GIT 316--- 317Part of the linkgit:git[1] suite