[thirdparty/git.git] / Documentation / git-merge.txt

git-merge(1)
============

NAME
----
git-merge - Join two or more development histories together


SYNOPSIS
--------
[verse]
'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...
	[-m <msg>] <remote> <remote>...

DESCRIPTION
-----------
This is the top-level interface to the merge machinery
which drives multiple merge strategy scripts.


OPTIONS
-------
include::merge-options.txt[]

<msg>::
	The commit message to be used for the merge commit (in case
	it is created). The `git-fmt-merge-msg` script can be used
	to give a good default for automated `git-merge` invocations.

<head>::
	Our branch head commit.  This has to be `HEAD`, so new
	syntax does not require it

<remote>::
	Other branch head merged into our branch.  You need at
	least one <remote>.  Specifying more than one <remote>
	obviously means you are trying an Octopus.

include::merge-strategies.txt[]


If you tried a merge which resulted in a complex conflicts and
would want to start over, you can recover with
gitlink:git-reset[1].

CONFIGURATION
-------------

merge.summary::
	Whether to include summaries of merged commits in newly
	created merge commit. False by default.

merge.verbosity::
	Controls the amount of output shown by the recursive merge
	strategy.  Level 0 outputs nothing except a final error
	message if conflicts were detected. Level 1 outputs only
	conflicts, 2 outputs conflicts and file changes.  Level 5 and
	above outputs debugging information.  The default is level 2.
	Can be overriden by 'GIT_MERGE_VERBOSITY' environment variable.


HOW MERGE WORKS
---------------

A merge is always between the current `HEAD` and one or more
remote branch heads, and the index file must exactly match the
tree of `HEAD` commit (i.e. the contents of the last commit) when
it happens.  In other words, `git-diff --cached HEAD` must
report no changes.

[NOTE]
This is a bit of lie.  In certain special cases, your index are
allowed to be different from the tree of `HEAD` commit.  The most
notable case is when your `HEAD` commit is already ahead of what
is being merged, in which case your index can have arbitrary
difference from your `HEAD` commit.  Otherwise, your index entries
are allowed have differences from your `HEAD` commit that match
the result of trivial merge (e.g. you received the same patch
from external source to produce the same result as what you are
merging).  For example, if a path did not exist in the common
ancestor and your head commit but exists in the tree you are
merging into your repository, and if you already happen to have
that path exactly in your index, the merge does not have to
fail.

Otherwise, merge will refuse to do any harm to your repository
(that is, it may fetch the objects from remote, and it may even
update the local branch used to keep track of the remote branch
with `git pull remote rbranch:lbranch`, but your working tree,
`.git/HEAD` pointer and index file are left intact).

You may have local modifications in the working tree files.  In
other words, `git-diff` is allowed to report changes.
However, the merge uses your working tree as the working area,
and in order to prevent the merge operation from losing such
changes, it makes sure that they do not interfere with the
merge. Those complex tables in read-tree documentation define
what it means for a path to "interfere with the merge".  And if
your local modifications interfere with the merge, again, it
stops before touching anything.

So in the above two "failed merge" case, you do not have to
worry about loss of data --- you simply were not ready to do
a merge, so no merge happened at all.  You may want to finish
whatever you were in the middle of doing, and retry the same
pull after you are done and ready.

When things cleanly merge, these things happen:

1. the results are updated both in the index file and in your
   working tree,
2. index file is written out as a tree,
3. the tree gets committed, and
4. the `HEAD` pointer gets advanced.

Because of 2., we require that the original state of the index
file to match exactly the current `HEAD` commit; otherwise we
will write out your local changes already registered in your
index file along with the merge result, which is not good.
Because 1. involves only the paths different between your
branch and the remote branch you are pulling from during the
merge (which is typically a fraction of the whole tree), you can
have local modifications in your working tree as long as they do
not overlap with what the merge updates.

When there are conflicts, these things happen:

1. `HEAD` stays the same.

2. Cleanly merged paths are updated both in the index file and
   in your working tree.

3. For conflicting paths, the index file records up to three
   versions; stage1 stores the version from the common ancestor,
   stage2 from `HEAD`, and stage3 from the remote branch (you
   can inspect the stages with `git-ls-files -u`).  The working
   tree files have the result of "merge" program; i.e. 3-way
   merge result with familiar conflict markers `<<< === >>>`.

4. No other changes are done.  In particular, the local
   modifications you had before you started merge will stay the
   same and the index entries for them stay as they were,
   i.e. matching `HEAD`.

After seeing a conflict, you can do two things:

 * Decide not to merge.  The only clean-up you need are to reset
   the index file to the `HEAD` commit to reverse 2. and to clean
   up working tree changes made by 2. and 3.; `git-reset` can
   be used for this.

 * Resolve the conflicts.  `git-diff` would report only the
   conflicting paths because of the above 2. and 3..  Edit the
   working tree files into a desirable shape, `git-add` or `git-rm`
   them, to make the index file contain what the merge result
   should be, and run `git-commit` to commit the result.


SEE ALSO
--------
gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1]


Author
------
Written by Junio C Hamano <junkio@cox.net>


Documentation
--------------
Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.

GIT
---
Part of the gitlink:git[7] suite
Commit	Line	Data
0f69be53 JH	1	git-merge(1)
0f69be53 JH	2	============
0f69be53 JH	3
	4	NAME
	5	----
c3f0baac	6	git-merge - Join two or more development histories together
0f69be53 JH	7
	8
	9	SYNOPSIS
	10	--------
17bcdad3	11	[verse]
51e7ecf4	12	'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...
1e8b0d48	13	[-m <msg>] <remote> <remote>...
0f69be53 JH	14
	15	DESCRIPTION
	16	-----------
17bcdad3	17	This is the top-level interface to the merge machinery
0f69be53 JH	18	which drives multiple merge strategy scripts.
	19
	20
	21	OPTIONS
	22	-------
93d69d86	23	include::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
17bcdad3 JH	32	syntax does not require it
0f69be53 JH	33
0f69be53 JH	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	39	include::merge-strategies.txt[]
bb73d73c JL	40
0f69be53	41
3ae854c3 JH	42	If you tried a merge which resulted in a complex conflicts and
	43	would want to start over, you can recover with
	44	gitlink:git-reset[1].
	45
dbddb714 JN	46	CONFIGURATION
	47	-------------
	48
	49	merge.summary::
	50	Whether to include summaries of merged commits in newly
	51	created merge commit. False by default.
	52
	53	merge.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.
	59	Can be overriden by 'GIT_MERGE_VERBOSITY' environment variable.
	60
3ae854c3	61
ffb1a4be JH	62	HOW MERGE WORKS
	63	---------------
	64
	65	A merge is always between the current `HEAD` and one or more
	66	remote branch heads, and the index file must exactly match the
	67	tree of `HEAD` commit (i.e. the contents of the last commit) when
	68	it happens. In other words, `git-diff --cached HEAD` must
	69	report no changes.
	70
	71	[NOTE]
	72	This is a bit of lie. In certain special cases, your index are
	73	allowed to be different from the tree of `HEAD` commit. The most
	74	notable case is when your `HEAD` commit is already ahead of what
	75	is being merged, in which case your index can have arbitrary
	76	difference from your `HEAD` commit. Otherwise, your index entries
	77	are allowed have differences from your `HEAD` commit that match
	78	the result of trivial merge (e.g. you received the same patch
	79	from external source to produce the same result as what you are
	80	merging). For example, if a path did not exist in the common
	81	ancestor and your head commit but exists in the tree you are
	82	merging into your repository, and if you already happen to have
	83	that path exactly in your index, the merge does not have to
	84	fail.
	85
	86	Otherwise, merge will refuse to do any harm to your repository
	87	(that is, it may fetch the objects from remote, and it may even
	88	update the local branch used to keep track of the remote branch
	89	with `git pull remote rbranch:lbranch`, but your working tree,
	90	`.git/HEAD` pointer and index file are left intact).
	91
	92	You may have local modifications in the working tree files. In
	93	other words, `git-diff` is allowed to report changes.
	94	However, the merge uses your working tree as the working area,
	95	and in order to prevent the merge operation from losing such
	96	changes, it makes sure that they do not interfere with the
	97	merge. Those complex tables in read-tree documentation define
	98	what it means for a path to "interfere with the merge". And if
	99	your local modifications interfere with the merge, again, it
	100	stops before touching anything.
	101
	102	So in the above two "failed merge" case, you do not have to
addf88e4	103	worry about loss of data --- you simply were not ready to do
ffb1a4be JH	104	a merge, so no merge happened at all. You may want to finish
	105	whatever you were in the middle of doing, and retry the same
	106	pull after you are done and ready.
	107
	108	When things cleanly merge, these things happen:
	109
	110	1. the results are updated both in the index file and in your
	111	working tree,
	112	2. index file is written out as a tree,
a6080a0a	113	3. the tree gets committed, and
ffb1a4be JH	114	4. the `HEAD` pointer gets advanced.
	115
	116	Because of 2., we require that the original state of the index
	117	file to match exactly the current `HEAD` commit; otherwise we
	118	will write out your local changes already registered in your
	119	index file along with the merge result, which is not good.
	120	Because 1. involves only the paths different between your
	121	branch and the remote branch you are pulling from during the
	122	merge (which is typically a fraction of the whole tree), you can
	123	have local modifications in your working tree as long as they do
	124	not overlap with what the merge updates.
	125
	126	When there are conflicts, these things happen:
	127
	128	1. `HEAD` stays the same.
	129
	130	2. Cleanly merged paths are updated both in the index file and
	131	in your working tree.
	132
3ace1fe3 JH	133	3. 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
	140	4. 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
	145	After 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	159	SEE ALSO
3c64314c PB	160	--------
fdd08979	161	gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1]
3c64314c PB	162
3c64314c PB	163
0f69be53 JH	164	Author
	165	------
	166	Written by Junio C Hamano <junkio@cox.net>
	167
	168
	169	Documentation
	170	--------------
	171	Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
	172
	173	GIT
	174	---
a7154e91	175	Part of the gitlink:git[7] suite