blob: 0c9ad7f2bbdf4872882d127804e7c474729c0818 [file] [log] [blame]
Junio C Hamano1a4e8412005-12-27 08:17:231git-merge(1)
2============
3
4NAME
5----
Junio C Hamano7c73c662007-01-19 00:37:506git-merge - Join two or more development histories together
Junio C Hamano1a4e8412005-12-27 08:17:237
8
9SYNOPSIS
10--------
Junio C Hamanoee6d9612006-11-27 20:03:2211[verse]
Junio C Hamano591dc6a2007-05-29 09:18:1912'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...
Junio C Hamano5dad0832007-02-13 05:16:2313[-m <msg>] <remote> <remote>...
Junio C Hamano1974bf22007-10-31 05:57:2014'git-merge' <msg> HEAD <remote>...
Junio C Hamano1a4e8412005-12-27 08:17:2315
16DESCRIPTION
17-----------
Junio C Hamanoee6d9612006-11-27 20:03:2218This is the top-level interface to the merge machinery
Junio C Hamano1a4e8412005-12-27 08:17:2319which drives multiple merge strategy scripts.
20
Junio C Hamano1974bf22007-10-31 05:57:2021The 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
Junio C Hamano1a4e8412005-12-27 08:17:2325
26OPTIONS
27-------
28include::merge-options.txt[]
29
Junio C Hamano1974bf22007-10-31 05:57:2030-m <msg>::
Junio C Hamano1a4e8412005-12-27 08:17:2331The commit message to be used for the merge commit (in case
32it is created). The `git-fmt-merge-msg` script can be used
33to give a good default for automated `git-merge` invocations.
34
Junio C Hamano1a4e8412005-12-27 08:17:2335<remote>::
Junio C Hamanoee6d9612006-11-27 20:03:2236Other branch head merged into our branch. You need at
Junio C Hamano1a4e8412005-12-27 08:17:2337least one <remote>. Specifying more than one <remote>
38obviously means you are trying an Octopus.
39
40include::merge-strategies.txt[]
41
42
43If you tried a merge which resulted in a complex conflicts and
44would want to start over, you can recover with
Junio C Hamano35738e82008-01-07 07:55:4645linkgit:git-reset[1].
Junio C Hamano1a4e8412005-12-27 08:17:2346
Junio C Hamano1e6e0062007-07-13 05:33:2547CONFIGURATION
48-------------
49
50merge.summary::
51Whether to include summaries of merged commits in newly
52created merge commit. False by default.
53
54merge.verbosity::
55Controls the amount of output shown by the recursive merge
56strategy. Level 0 outputs nothing except a final error
57message if conflicts were detected. Level 1 outputs only
58conflicts, 2 outputs conflicts and file changes. Level 5 and
59above outputs debugging information. The default is level 2.
Junio C Hamano4fd58d42007-09-30 00:51:1460Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable.
Junio C Hamano1e6e0062007-07-13 05:33:2561
Junio C Hamano1b50ce92007-10-03 12:05:5362branch.<name>.mergeoptions::
63Sets default options for merging into branch <name>. The syntax and
64supported options are equal to that of git-merge, but option values
65containing whitespace characters are currently not supported.
Junio C Hamano1a4e8412005-12-27 08:17:2366
67HOW MERGE WORKS
68---------------
69
70A merge is always between the current `HEAD` and one or more
71remote branch heads, and the index file must exactly match the
72tree of `HEAD` commit (i.e. the contents of the last commit) when
73it happens. In other words, `git-diff --cached HEAD` must
74report no changes.
75
76[NOTE]
Junio C Hamano5bd1d592008-01-17 02:43:1077This is a bit of a lie. In certain special cases, your index is
78allowed to be different from the tree of the `HEAD` commit. The most
Junio C Hamano1a4e8412005-12-27 08:17:2379notable case is when your `HEAD` commit is already ahead of what
80is being merged, in which case your index can have arbitrary
Junio C Hamano5bd1d592008-01-17 02:43:1081differences from your `HEAD` commit. Also, your index entries
82may have differences from your `HEAD` commit that match
83the result of a trivial merge (e.g. you received the same patch
84from an external source to produce the same result as what you are
Junio C Hamano1a4e8412005-12-27 08:17:2385merging). For example, if a path did not exist in the common
86ancestor and your head commit but exists in the tree you are
87merging into your repository, and if you already happen to have
88that path exactly in your index, the merge does not have to
89fail.
90
91Otherwise, merge will refuse to do any harm to your repository
92(that is, it may fetch the objects from remote, and it may even
93update the local branch used to keep track of the remote branch
94with `git pull remote rbranch:lbranch`, but your working tree,
95`.git/HEAD` pointer and index file are left intact).
96
97You may have local modifications in the working tree files. In
98other words, `git-diff` is allowed to report changes.
99However, the merge uses your working tree as the working area,
100and in order to prevent the merge operation from losing such
101changes, it makes sure that they do not interfere with the
102merge. Those complex tables in read-tree documentation define
103what it means for a path to "interfere with the merge". And if
104your local modifications interfere with the merge, again, it
105stops before touching anything.
106
107So in the above two "failed merge" case, you do not have to
Junio C Hamano51c2ab02006-07-09 20:38:54108worry about loss of data --- you simply were not ready to do
Junio C Hamano1a4e8412005-12-27 08:17:23109a merge, so no merge happened at all. You may want to finish
110whatever you were in the middle of doing, and retry the same
111pull after you are done and ready.
112
113When things cleanly merge, these things happen:
114
Junio C Hamano092f5f02007-08-02 07:23:381151. The results are updated both in the index file and in your
116 working tree;
1172. Index file is written out as a tree;
1183. The tree gets committed; and
1194. The `HEAD` pointer gets advanced.
Junio C Hamano1a4e8412005-12-27 08:17:23120
121Because of 2., we require that the original state of the index
122file to match exactly the current `HEAD` commit; otherwise we
123will write out your local changes already registered in your
124index file along with the merge result, which is not good.
125Because 1. involves only the paths different between your
126branch and the remote branch you are pulling from during the
127merge (which is typically a fraction of the whole tree), you can
128have local modifications in your working tree as long as they do
129not overlap with what the merge updates.
130
131When there are conflicts, these things happen:
132
1331. `HEAD` stays the same.
134
1352. Cleanly merged paths are updated both in the index file and
136 in your working tree.
137
1383. For conflicting paths, the index file records up to three
139 versions; stage1 stores the version from the common ancestor,
140 stage2 from `HEAD`, and stage3 from the remote branch (you
141 can inspect the stages with `git-ls-files -u`). The working
142 tree files have the result of "merge" program; i.e. 3-way
143 merge result with familiar conflict markers `<<< === >>>`.
144
1454. No other changes are done. In particular, the local
146 modifications you had before you started merge will stay the
147 same and the index entries for them stay as they were,
148 i.e. matching `HEAD`.
149
150After seeing a conflict, you can do two things:
151
152 * Decide not to merge. The only clean-up you need are to reset
153 the index file to the `HEAD` commit to reverse 2. and to clean
154 up working tree changes made by 2. and 3.; `git-reset` can
155 be used for this.
156
157 * Resolve the conflicts. `git-diff` would report only the
158 conflicting paths because of the above 2. and 3.. Edit the
Junio C Hamano89d4e0f2007-02-18 00:34:59159 working tree files into a desirable shape, `git-add` or `git-rm`
Junio C Hamano1a4e8412005-12-27 08:17:23160 them, to make the index file contain what the merge result
161 should be, and run `git-commit` to commit the result.
162
163
164SEE ALSO
165--------
Junio C Hamano35738e82008-01-07 07:55:46166linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
167linkgit:gitattributes[5]
Junio C Hamano1a4e8412005-12-27 08:17:23168
169
170Author
171------
172Written by Junio C Hamano <junkio@cox.net>
173
174
175Documentation
176--------------
177Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
178
179GIT
180---
Junio C Hamano35738e82008-01-07 07:55:46181Part of the linkgit:git[7] suite