Describe second batch for 1.7.0 in draft release notes
[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>]...
22f1fb66 13 [-m <msg>] <remote>...
b1889c36 14'git merge' <msg> HEAD <remote>...
0f69be53
JH
15
16DESCRIPTION
17-----------
17bcdad3 18This is the top-level interface to the merge machinery
0f69be53
JH
19which drives multiple merge strategy scripts.
20
dee48c3c
JH
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
0f69be53
JH
25
26OPTIONS
27-------
93d69d86 28include::merge-options.txt[]
0f69be53 29
dee48c3c 30-m <msg>::
0f8a02c6
JN
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.
3c64314c 35
f448e24e
AMS
36<remote>...::
37 Other branch heads to merge into our branch. You need at
0f69be53
JH
38 least one <remote>. Specifying more than one <remote>
39 obviously means you are trying an Octopus.
40
bb73d73c
JL
41include::merge-strategies.txt[]
42
0f69be53 43
9fe00538 44If you tried a merge which resulted in complex conflicts and
4fa535a1 45want to start over, you can recover with 'git-reset'.
3ae854c3 46
dbddb714
JN
47CONFIGURATION
48-------------
f5a84c37 49include::merge-config.txt[]
dbddb714 50
aec7b362
LH
51branch.<name>.mergeoptions::
52 Sets default options for merging into branch <name>. The syntax and
25dcc0d6
JN
53 supported options are the same as those of 'git merge', but option
54 values containing whitespace characters are currently not supported.
3ae854c3 55
ffb1a4be
JH
56HOW MERGE WORKS
57---------------
58
59A merge is always between the current `HEAD` and one or more
81646ad2 60commits (usually, branch head or tag), and the index file must
c0be8aa0
PB
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
29b802aa
RW
73 most common case especially when invoked from 'git pull':
74 you are tracking an upstream repository, have committed no local
c0be8aa0 75 changes and now you want to update to a newer upstream revision.
29b802aa 76 Your `HEAD` (and the index) is updated to point at the merged
c0be8aa0
PB
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
29b802aa 81 tied together by a merge commit that has both of them as its parents.
c0be8aa0
PB
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.
29b802aa 86When things merge cleanly, this is what happens:
ffb1a4be 87
434e6ef8
SH
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.
ffb1a4be
JH
93
94Because of 2., we require that the original state of the index
29b802aa 95file matches exactly the current `HEAD` commit; otherwise we
ffb1a4be
JH
96will write out your local changes already registered in your
97index file along with the merge result, which is not good.
29b802aa 98Because 1. involves only those paths differing between your
ffb1a4be
JH
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
29b802aa 104When there are conflicts, the following happens:
ffb1a4be
JH
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
3ace1fe3
JH
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
b1889c36 114 can inspect the stages with `git ls-files -u`). The working
29b802aa
RW
115 tree files contain the result of the "merge" program; i.e. 3-way
116 merge results with familiar conflict markers `<<< === >>>`.
ffb1a4be
JH
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
70a3f897
JH
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
29b802aa 149The area where a pair of conflicting changes happened is marked with markers
dcb11263 150`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======`
29b802aa 151is typically your side, and the part afterwards is typically their side.
70a3f897 152
29b802aa
RW
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
70a3f897
JH
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
dcb11263
CJ
177In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
178another `|||||||` marker that is followed by the original text. You can
70a3f897
JH
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
ffb1a4be
JH
188After seeing a conflict, you can do two things:
189
29b802aa 190 * Decide not to merge. The only clean-ups you need are to reset
ffb1a4be 191 the index file to the `HEAD` commit to reverse 2. and to clean
c0be8aa0 192 up working tree changes made by 2. and 3.; 'git-reset --hard' can
ffb1a4be
JH
193 be used for this.
194
34ad1afa
DH
195 * Resolve the conflicts. Git will mark the conflicts in
196 the working tree. Edit the files into shape and
29b802aa 197 'git-add' them to the index. Use 'git-commit' to seal the deal.
ffb1a4be 198
34ad1afa
DH
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.
ffb1a4be 214
d504f697
CB
215
216EXAMPLES
217--------
218
219* Merge branches `fixes` and `enhancements` on top of
220 the current branch, making an octopus merge:
221+
222------------------------------------------------
223$ git merge fixes enhancements
224------------------------------------------------
225
226* Merge branch `obsolete` into the current branch, using `ours`
227 merge strategy:
228+
229------------------------------------------------
230$ git merge -s ours obsolete
231------------------------------------------------
232
233* Merge branch `maint` into the current branch, but do not make
234 a new commit automatically:
235+
236------------------------------------------------
237$ git merge --no-commit maint
238------------------------------------------------
239+
240This can be used when you want to include further changes to the
241merge, or want to write your own merge commit message.
242+
243You should refrain from abusing this option to sneak substantial
244changes into a merge commit. Small fixups like bumping
245release/version name would be acceptable.
246
247
3c64314c
PB
248SEE ALSO
249--------
5162e697 250linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
483bc4f0
JN
251linkgit:gitattributes[5],
252linkgit:git-reset[1],
253linkgit:git-diff[1], linkgit:git-ls-files[1],
254linkgit:git-add[1], linkgit:git-rm[1],
255linkgit:git-mergetool[1]
3c64314c 256
0f69be53
JH
257Author
258------
59eb68aa 259Written by Junio C Hamano <gitster@pobox.com>
0f69be53
JH
260
261
262Documentation
263--------------
264Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
265
266GIT
267---
9e1f0a85 268Part of the linkgit:git[1] suite