mirror of
https://github.com/git/git
synced 2024-08-27 11:39:22 +00:00
documentation: merge-base: explain "git merge-base" with more than 2 args
Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
parent
53eda89b2f
commit
99f1c04be0
|
@ -8,26 +8,81 @@ git-merge-base - Find as good common ancestors as possible for a merge
|
|||
|
||||
SYNOPSIS
|
||||
--------
|
||||
'git merge-base' [--all] <commit> <commit>
|
||||
'git merge-base' [--all] <commit> <commit>...
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
'git-merge-base' finds as good a common ancestor as possible between
|
||||
the two commits. That is, given two commits A and B, `git merge-base A
|
||||
B` will output a commit which is reachable from both A and B through
|
||||
the parent relationship.
|
||||
'git-merge-base' finds best common ancestor(s) between two commits to use
|
||||
in a three-way merge. One common ancestor is 'better' than another common
|
||||
ancestor if the latter is an ancestor of the former. A common ancestor
|
||||
that does not have any better common ancestor than it is a 'best common
|
||||
ancestor', i.e. a 'merge base'. Note that there can be more than one
|
||||
merge bases between two commits.
|
||||
|
||||
Given a selection of equally good common ancestors it should not be
|
||||
relied on to decide in any particular way.
|
||||
|
||||
The 'git-merge-base' algorithm is still in flux - use the source...
|
||||
Among the two commits to compute their merge bases, one is specified by
|
||||
the first commit argument on the command line; the other commit is a
|
||||
(possibly hypothetical) commit that is a merge across all the remaining
|
||||
commits on the command line. As the most common special case, giving only
|
||||
two commits from the command line means computing the merge base between
|
||||
the given two commits.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
--all::
|
||||
Output all common ancestors for the two commits instead of
|
||||
just one.
|
||||
Output all merge bases for the commits, instead of just one.
|
||||
|
||||
DISCUSSION
|
||||
----------
|
||||
|
||||
Given two commits 'A' and 'B', `git merge-base A B` will output a commit
|
||||
which is reachable from both 'A' and 'B' through the parent relationship.
|
||||
|
||||
For example, with this topology:
|
||||
|
||||
o---o---o---B
|
||||
/
|
||||
---o---1---o---o---o---A
|
||||
|
||||
the merge base between 'A' and 'B' is '1'.
|
||||
|
||||
Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the
|
||||
merge base between 'A' and an hypothetical commit 'M', which is a merge
|
||||
between 'B' and 'C'. For example, with this topology:
|
||||
|
||||
o---o---o---o---C
|
||||
/
|
||||
/ o---o---o---B
|
||||
/ /
|
||||
---2---1---o---o---o---A
|
||||
|
||||
the result of `git merge-base A B C` is '1'. This is because the
|
||||
equivalent topology with a merge commit 'M' between 'B' and 'C' is:
|
||||
|
||||
|
||||
o---o---o---o---o
|
||||
/ \
|
||||
/ o---o---o---o---M
|
||||
/ /
|
||||
---2---1---o---o---o---A
|
||||
|
||||
and the result of `git merge-base A M` is '1'. Commit '2' is also a
|
||||
common ancestor between 'A' and 'M', but '1' is a better common ancestor,
|
||||
because '2' is an ancestor of '1'. Hence, '2' is not a merge base.
|
||||
|
||||
When the history involves criss-cross merges, there can be more than one
|
||||
'best' common ancestors between two commits. For example, with this
|
||||
topology:
|
||||
|
||||
---1---o---A
|
||||
\ /
|
||||
X
|
||||
/ \
|
||||
---2---o---o---B
|
||||
|
||||
both '1' and '2' are merge-base of A and B. Neither one is better than
|
||||
the other (both are 'best' merge base). When `--all` option is not given,
|
||||
it is unspecified which best one is output.
|
||||
|
||||
Author
|
||||
------
|
||||
|
|
Loading…
Reference in a new issue