[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] [--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].


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