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