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