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