6 git-merge - Join two or more development histories together
12 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
13 [-m <msg>] <remote> <remote>...
14 'git merge' <msg> HEAD <remote>...
18 This is the top-level interface to the merge machinery
19 which drives multiple merge strategy scripts.
21 The second syntax (<msg> `HEAD` <remote>) is supported for
22 historical reasons. Do not use it from the command line or in
23 new scripts. It is the same as `git merge -m <msg> <remote>`.
28 include::merge-options.txt[]
31 The commit message to be used for the merge commit (in case
32 it is created). The 'git-fmt-merge-msg' script can be used
33 to give a good default for automated 'git-merge' invocations.
36 Other branch head merged into our branch. You need at
37 least one <remote>. Specifying more than one <remote>
38 obviously means you are trying an Octopus.
40 include::merge-strategies.txt[]
43 If you tried a merge which resulted in a complex conflicts and
44 would want to start over, you can recover with 'git-reset'.
48 include::merge-config.txt[]
50 branch.<name>.mergeoptions::
51 Sets default options for merging into branch <name>. The syntax and
52 supported options are equal to that of 'git-merge', but option values
53 containing whitespace characters are currently not supported.
58 A merge is always between the current `HEAD` and one or more
59 commits (usually, branch head or tag), and the index file must
61 tree of `HEAD` commit (i.e. the contents of the last commit) when
62 it happens. In other words, `git diff --cached HEAD` must
66 This is a bit of a lie. In certain special cases, your index is
67 allowed to be different from the tree of the `HEAD` commit. The most
68 notable case is when your `HEAD` commit is already ahead of what
69 is being merged, in which case your index can have arbitrary
70 differences from your `HEAD` commit. Also, your index entries
71 may have differences from your `HEAD` commit that match
72 the result of a trivial merge (e.g. you received the same patch
73 from an external source to produce the same result as what you are
74 merging). For example, if a path did not exist in the common
75 ancestor and your head commit but exists in the tree you are
76 merging into your repository, and if you already happen to have
77 that path exactly in your index, the merge does not have to
80 Otherwise, merge will refuse to do any harm to your repository
81 (that is, it may fetch the objects from remote, and it may even
82 update the local branch used to keep track of the remote branch
83 with `git pull remote rbranch:lbranch`, but your working tree,
84 `.git/HEAD` pointer and index file are left intact). In addition,
85 merge always sets `.git/ORIG_HEAD` to the original state of HEAD so
86 a problematic merge can be removed by using `git reset ORIG_HEAD`.
88 You may have local modifications in the working tree files. In
89 other words, 'git-diff' is allowed to report changes.
90 However, the merge uses your working tree as the working area,
91 and in order to prevent the merge operation from losing such
92 changes, it makes sure that they do not interfere with the
93 merge. Those complex tables in read-tree documentation define
94 what it means for a path to "interfere with the merge". And if
95 your local modifications interfere with the merge, again, it
96 stops before touching anything.
98 So in the above two "failed merge" case, you do not have to
99 worry about loss of data --- you simply were not ready to do
100 a merge, so no merge happened at all. You may want to finish
101 whatever you were in the middle of doing, and retry the same
102 pull after you are done and ready.
104 When things cleanly merge, these things happen:
106 1. The results are updated both in the index file and in your
108 2. Index file is written out as a tree;
109 3. The tree gets committed; and
110 4. The `HEAD` pointer gets advanced.
112 Because of 2., we require that the original state of the index
113 file to match exactly the current `HEAD` commit; otherwise we
114 will write out your local changes already registered in your
115 index file along with the merge result, which is not good.
116 Because 1. involves only the paths different between your
117 branch and the remote branch you are pulling from during the
118 merge (which is typically a fraction of the whole tree), you can
119 have local modifications in your working tree as long as they do
120 not overlap with what the merge updates.
122 When there are conflicts, these things happen:
124 1. `HEAD` stays the same.
126 2. Cleanly merged paths are updated both in the index file and
127 in your working tree.
129 3. For conflicting paths, the index file records up to three
130 versions; stage1 stores the version from the common ancestor,
131 stage2 from `HEAD`, and stage3 from the remote branch (you
132 can inspect the stages with `git ls-files -u`). The working
133 tree files have the result of "merge" program; i.e. 3-way
134 merge result with familiar conflict markers `<<< === >>>`.
136 4. No other changes are done. In particular, the local
137 modifications you had before you started merge will stay the
138 same and the index entries for them stay as they were,
139 i.e. matching `HEAD`.
141 After seeing a conflict, you can do two things:
143 * Decide not to merge. The only clean-up you need are to reset
144 the index file to the `HEAD` commit to reverse 2. and to clean
145 up working tree changes made by 2. and 3.; 'git-reset' can
148 * Resolve the conflicts. `git diff` would report only the
149 conflicting paths because of the above 2. and 3. Edit the
150 working tree files into a desirable shape, 'git-add' or 'git-rm'
151 them, to make the index file contain what the merge result
152 should be, and run 'git-commit' to commit the result.
157 linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
158 linkgit:gitattributes[5],
159 linkgit:git-reset[1],
160 linkgit:git-diff[1], linkgit:git-ls-files[1],
161 linkgit:git-add[1], linkgit:git-rm[1],
162 linkgit:git-mergetool[1]
166 Written by Junio C Hamano <junkio@cox.net>
171 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
175 Part of the linkgit:git[1] suite