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