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