git merge documentation: -m is optional
[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
JH
11[verse]
12'git-merge' [-n] [--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
46
ffb1a4be
JH
47HOW MERGE WORKS
48---------------
49
50A merge is always between the current `HEAD` and one or more
51remote branch heads, and the index file must exactly match the
52tree of `HEAD` commit (i.e. the contents of the last commit) when
53it happens. In other words, `git-diff --cached HEAD` must
54report no changes.
55
56[NOTE]
57This is a bit of lie. In certain special cases, your index are
58allowed to be different from the tree of `HEAD` commit. The most
59notable case is when your `HEAD` commit is already ahead of what
60is being merged, in which case your index can have arbitrary
61difference from your `HEAD` commit. Otherwise, your index entries
62are allowed have differences from your `HEAD` commit that match
63the result of trivial merge (e.g. you received the same patch
64from external source to produce the same result as what you are
65merging). For example, if a path did not exist in the common
66ancestor and your head commit but exists in the tree you are
67merging into your repository, and if you already happen to have
68that path exactly in your index, the merge does not have to
69fail.
70
71Otherwise, merge will refuse to do any harm to your repository
72(that is, it may fetch the objects from remote, and it may even
73update the local branch used to keep track of the remote branch
74with `git pull remote rbranch:lbranch`, but your working tree,
75`.git/HEAD` pointer and index file are left intact).
76
77You may have local modifications in the working tree files. In
78other words, `git-diff` is allowed to report changes.
79However, the merge uses your working tree as the working area,
80and in order to prevent the merge operation from losing such
81changes, it makes sure that they do not interfere with the
82merge. Those complex tables in read-tree documentation define
83what it means for a path to "interfere with the merge". And if
84your local modifications interfere with the merge, again, it
85stops before touching anything.
86
87So in the above two "failed merge" case, you do not have to
addf88e4 88worry about loss of data --- you simply were not ready to do
ffb1a4be
JH
89a merge, so no merge happened at all. You may want to finish
90whatever you were in the middle of doing, and retry the same
91pull after you are done and ready.
92
93When things cleanly merge, these things happen:
94
951. the results are updated both in the index file and in your
96 working tree,
972. index file is written out as a tree,
983. the tree gets committed, and
994. the `HEAD` pointer gets advanced.
100
101Because of 2., we require that the original state of the index
102file to match exactly the current `HEAD` commit; otherwise we
103will write out your local changes already registered in your
104index file along with the merge result, which is not good.
105Because 1. involves only the paths different between your
106branch and the remote branch you are pulling from during the
107merge (which is typically a fraction of the whole tree), you can
108have local modifications in your working tree as long as they do
109not overlap with what the merge updates.
110
111When there are conflicts, these things happen:
112
1131. `HEAD` stays the same.
114
1152. Cleanly merged paths are updated both in the index file and
116 in your working tree.
117
3ace1fe3
JH
1183. For conflicting paths, the index file records up to three
119 versions; stage1 stores the version from the common ancestor,
120 stage2 from `HEAD`, and stage3 from the remote branch (you
121 can inspect the stages with `git-ls-files -u`). The working
122 tree files have the result of "merge" program; i.e. 3-way
123 merge result with familiar conflict markers `<<< === >>>`.
ffb1a4be
JH
124
1254. No other changes are done. In particular, the local
126 modifications you had before you started merge will stay the
127 same and the index entries for them stay as they were,
128 i.e. matching `HEAD`.
129
130After seeing a conflict, you can do two things:
131
132 * Decide not to merge. The only clean-up you need are to reset
133 the index file to the `HEAD` commit to reverse 2. and to clean
134 up working tree changes made by 2. and 3.; `git-reset` can
135 be used for this.
136
137 * Resolve the conflicts. `git-diff` would report only the
138 conflicting paths because of the above 2. and 3.. Edit the
139 working tree files into a desirable shape, `git-update-index`
140 them, to make the index file contain what the merge result
141 should be, and run `git-commit` to commit the result.
142
143
3c64314c
PB
144SEE ALSO
145--------
fdd08979 146gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1]
3c64314c
PB
147
148
0f69be53
JH
149Author
150------
151Written by Junio C Hamano <junkio@cox.net>
152
153
154Documentation
155--------------
156Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
157
158GIT
159---
a7154e91 160Part of the gitlink:git[7] suite