Prevent send-pack from segfaulting (backport from 'master')
[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]
51e7ecf4 12'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...
1e8b0d48 13 [-m <msg>] <remote> <remote>...
0f69be53
JH
14
15DESCRIPTION
16-----------
17bcdad3 17This is the top-level interface to the merge machinery
0f69be53
JH
18which drives multiple merge strategy scripts.
19
20
21OPTIONS
22-------
93d69d86 23include::merge-options.txt[]
0f69be53 24
3c64314c
PB
25<msg>::
26 The commit message to be used for the merge commit (in case
27 it is created). The `git-fmt-merge-msg` script can be used
28 to give a good default for automated `git-merge` invocations.
29
0f69be53 30<head>::
17bcdad3
JH
31 Our branch head commit. This has to be `HEAD`, so new
32 syntax does not require it
0f69be53
JH
33
34<remote>::
17bcdad3 35 Other branch head merged into our branch. You need at
0f69be53
JH
36 least one <remote>. Specifying more than one <remote>
37 obviously means you are trying an Octopus.
38
bb73d73c
JL
39include::merge-strategies.txt[]
40
0f69be53 41
3ae854c3
JH
42If you tried a merge which resulted in a complex conflicts and
43would want to start over, you can recover with
44gitlink:git-reset[1].
45
dbddb714
JN
46CONFIGURATION
47-------------
48
49merge.summary::
50 Whether to include summaries of merged commits in newly
51 created merge commit. False by default.
52
53merge.verbosity::
54 Controls the amount of output shown by the recursive merge
55 strategy. Level 0 outputs nothing except a final error
56 message if conflicts were detected. Level 1 outputs only
57 conflicts, 2 outputs conflicts and file changes. Level 5 and
58 above outputs debugging information. The default is level 2.
b0674392 59 Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable.
dbddb714 60
3ae854c3 61
ffb1a4be
JH
62HOW MERGE WORKS
63---------------
64
65A merge is always between the current `HEAD` and one or more
66remote branch heads, and the index file must exactly match the
67tree of `HEAD` commit (i.e. the contents of the last commit) when
68it happens. In other words, `git-diff --cached HEAD` must
69report no changes.
70
71[NOTE]
72This is a bit of lie. In certain special cases, your index are
73allowed to be different from the tree of `HEAD` commit. The most
74notable case is when your `HEAD` commit is already ahead of what
75is being merged, in which case your index can have arbitrary
76difference from your `HEAD` commit. Otherwise, your index entries
77are allowed have differences from your `HEAD` commit that match
78the result of trivial merge (e.g. you received the same patch
79from external source to produce the same result as what you are
80merging). For example, if a path did not exist in the common
81ancestor and your head commit but exists in the tree you are
82merging into your repository, and if you already happen to have
83that path exactly in your index, the merge does not have to
84fail.
85
86Otherwise, merge will refuse to do any harm to your repository
87(that is, it may fetch the objects from remote, and it may even
88update the local branch used to keep track of the remote branch
89with `git pull remote rbranch:lbranch`, but your working tree,
90`.git/HEAD` pointer and index file are left intact).
91
92You may have local modifications in the working tree files. In
93other words, `git-diff` is allowed to report changes.
94However, the merge uses your working tree as the working area,
95and in order to prevent the merge operation from losing such
96changes, it makes sure that they do not interfere with the
97merge. Those complex tables in read-tree documentation define
98what it means for a path to "interfere with the merge". And if
99your local modifications interfere with the merge, again, it
100stops before touching anything.
101
102So in the above two "failed merge" case, you do not have to
addf88e4 103worry about loss of data --- you simply were not ready to do
ffb1a4be
JH
104a merge, so no merge happened at all. You may want to finish
105whatever you were in the middle of doing, and retry the same
106pull after you are done and ready.
107
108When things cleanly merge, these things happen:
109
434e6ef8
SH
1101. The results are updated both in the index file and in your
111 working tree;
1122. Index file is written out as a tree;
1133. The tree gets committed; and
1144. The `HEAD` pointer gets advanced.
ffb1a4be
JH
115
116Because of 2., we require that the original state of the index
117file to match exactly the current `HEAD` commit; otherwise we
118will write out your local changes already registered in your
119index file along with the merge result, which is not good.
120Because 1. involves only the paths different between your
121branch and the remote branch you are pulling from during the
122merge (which is typically a fraction of the whole tree), you can
123have local modifications in your working tree as long as they do
124not overlap with what the merge updates.
125
126When there are conflicts, these things happen:
127
1281. `HEAD` stays the same.
129
1302. Cleanly merged paths are updated both in the index file and
131 in your working tree.
132
3ace1fe3
JH
1333. For conflicting paths, the index file records up to three
134 versions; stage1 stores the version from the common ancestor,
135 stage2 from `HEAD`, and stage3 from the remote branch (you
136 can inspect the stages with `git-ls-files -u`). The working
137 tree files have the result of "merge" program; i.e. 3-way
138 merge result with familiar conflict markers `<<< === >>>`.
ffb1a4be
JH
139
1404. No other changes are done. In particular, the local
141 modifications you had before you started merge will stay the
142 same and the index entries for them stay as they were,
143 i.e. matching `HEAD`.
144
145After seeing a conflict, you can do two things:
146
147 * Decide not to merge. The only clean-up you need are to reset
148 the index file to the `HEAD` commit to reverse 2. and to clean
149 up working tree changes made by 2. and 3.; `git-reset` can
150 be used for this.
151
152 * Resolve the conflicts. `git-diff` would report only the
153 conflicting paths because of the above 2. and 3.. Edit the
d7f078b8 154 working tree files into a desirable shape, `git-add` or `git-rm`
ffb1a4be
JH
155 them, to make the index file contain what the merge result
156 should be, and run `git-commit` to commit the result.
157
158
3c64314c
PB
159SEE ALSO
160--------
fdd08979 161gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1]
3c64314c
PB
162
163
0f69be53
JH
164Author
165------
166Written by Junio C Hamano <junkio@cox.net>
167
168
169Documentation
170--------------
171Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
172
173GIT
174---
a7154e91 175Part of the gitlink:git[7] suite