Documentation: be consistent about "git-" versus "git "
[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>]...
1e8b0d48 13 [-m <msg>] <remote> <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>::
3c64314c
PB
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.
34
0f69be53 35<remote>::
17bcdad3 36 Other branch head merged into our branch. You need at
0f69be53
JH
37 least one <remote>. Specifying more than one <remote>
38 obviously means you are trying an Octopus.
39
bb73d73c
JL
40include::merge-strategies.txt[]
41
0f69be53 42
3ae854c3
JH
43If you tried a merge which resulted in a complex conflicts and
44would want to start over, you can recover with
5162e697 45linkgit:git-reset[1].
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
53 supported options are equal to that of git-merge, but option values
54 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
MM
60commits (usually, branch head or tag), and the index file must
61exactly match the
ffb1a4be 62tree of `HEAD` commit (i.e. the contents of the last commit) when
b1889c36 63it happens. In other words, `git diff --cached HEAD` must
ffb1a4be
JH
64report no changes.
65
66[NOTE]
b98525e4
DP
67This is a bit of a lie. In certain special cases, your index is
68allowed to be different from the tree of the `HEAD` commit. The most
ffb1a4be
JH
69notable case is when your `HEAD` commit is already ahead of what
70is being merged, in which case your index can have arbitrary
b98525e4
DP
71differences from your `HEAD` commit. Also, your index entries
72may have differences from your `HEAD` commit that match
73the result of a trivial merge (e.g. you received the same patch
74from an external source to produce the same result as what you are
ffb1a4be
JH
75merging). For example, if a path did not exist in the common
76ancestor and your head commit but exists in the tree you are
77merging into your repository, and if you already happen to have
78that path exactly in your index, the merge does not have to
79fail.
80
81Otherwise, merge will refuse to do any harm to your repository
82(that is, it may fetch the objects from remote, and it may even
83update the local branch used to keep track of the remote branch
84with `git pull remote rbranch:lbranch`, but your working tree,
85`.git/HEAD` pointer and index file are left intact).
86
87You may have local modifications in the working tree files. In
88other words, `git-diff` is allowed to report changes.
89However, the merge uses your working tree as the working area,
90and in order to prevent the merge operation from losing such
91changes, it makes sure that they do not interfere with the
92merge. Those complex tables in read-tree documentation define
93what it means for a path to "interfere with the merge". And if
94your local modifications interfere with the merge, again, it
95stops before touching anything.
96
97So in the above two "failed merge" case, you do not have to
addf88e4 98worry about loss of data --- you simply were not ready to do
ffb1a4be
JH
99a merge, so no merge happened at all. You may want to finish
100whatever you were in the middle of doing, and retry the same
101pull after you are done and ready.
102
103When things cleanly merge, these things happen:
104
434e6ef8
SH
1051. The results are updated both in the index file and in your
106 working tree;
1072. Index file is written out as a tree;
1083. The tree gets committed; and
1094. The `HEAD` pointer gets advanced.
ffb1a4be
JH
110
111Because of 2., we require that the original state of the index
112file to match exactly the current `HEAD` commit; otherwise we
113will write out your local changes already registered in your
114index file along with the merge result, which is not good.
115Because 1. involves only the paths different between your
116branch and the remote branch you are pulling from during the
117merge (which is typically a fraction of the whole tree), you can
118have local modifications in your working tree as long as they do
119not overlap with what the merge updates.
120
121When there are conflicts, these things happen:
122
1231. `HEAD` stays the same.
124
1252. Cleanly merged paths are updated both in the index file and
126 in your working tree.
127
3ace1fe3
JH
1283. For conflicting paths, the index file records up to three
129 versions; stage1 stores the version from the common ancestor,
130 stage2 from `HEAD`, and stage3 from the remote branch (you
b1889c36 131 can inspect the stages with `git ls-files -u`). The working
3ace1fe3
JH
132 tree files have the result of "merge" program; i.e. 3-way
133 merge result with familiar conflict markers `<<< === >>>`.
ffb1a4be
JH
134
1354. No other changes are done. In particular, the local
136 modifications you had before you started merge will stay the
137 same and the index entries for them stay as they were,
138 i.e. matching `HEAD`.
139
140After seeing a conflict, you can do two things:
141
142 * Decide not to merge. The only clean-up you need are to reset
143 the index file to the `HEAD` commit to reverse 2. and to clean
144 up working tree changes made by 2. and 3.; `git-reset` can
145 be used for this.
146
b1889c36 147 * Resolve the conflicts. `git diff` would report only the
ffb1a4be 148 conflicting paths because of the above 2. and 3.. Edit the
d7f078b8 149 working tree files into a desirable shape, `git-add` or `git-rm`
ffb1a4be
JH
150 them, to make the index file contain what the merge result
151 should be, and run `git-commit` to commit the result.
152
153
3c64314c
PB
154SEE ALSO
155--------
5162e697
DM
156linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
157linkgit:gitattributes[5]
3c64314c
PB
158
159
0f69be53
JH
160Author
161------
162Written by Junio C Hamano <junkio@cox.net>
163
164
165Documentation
166--------------
167Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
168
169GIT
170---
9e1f0a85 171Part of the linkgit:git[1] suite