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