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