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