Improve language in git-merge.txt and related docs
[git/git.git] / Documentation / git-merge-base.txt
CommitLineData
2cf565c5
DG
1git-merge-base(1)
2=================
2cf565c5
DG
3
4NAME
5----
c3f0baac 6git-merge-base - Find as good common ancestors as possible for a merge
2cf565c5
DG
7
8
9SYNOPSIS
10--------
99f1c04b 11'git merge-base' [--all] <commit> <commit>...
2cf565c5
DG
12
13DESCRIPTION
14-----------
2aa83961 15
99f1c04b
JH
16'git-merge-base' finds best common ancestor(s) between two commits to use
17in a three-way merge. One common ancestor is 'better' than another common
18ancestor if the latter is an ancestor of the former. A common ancestor
29b802aa 19that does not have any better common ancestor is a 'best common
99f1c04b 20ancestor', i.e. a 'merge base'. Note that there can be more than one
29b802aa 21merge base for a pair of commits.
2aa83961 22
29b802aa 23Among the two commits to compute the merge base from, one is specified by
99f1c04b
JH
24the first commit argument on the command line; the other commit is a
25(possibly hypothetical) commit that is a merge across all the remaining
29b802aa
RW
26commits on the command line. As the most common special case, specifying only
27two commits on the command line means computing the merge base between
99f1c04b 28the given two commits.
2cf565c5 29
2aa83961
FK
30OPTIONS
31-------
32--all::
99f1c04b
JH
33 Output all merge bases for the commits, instead of just one.
34
35DISCUSSION
36----------
37
38Given two commits 'A' and 'B', `git merge-base A B` will output a commit
39which is reachable from both 'A' and 'B' through the parent relationship.
40
41For example, with this topology:
42
43 o---o---o---B
44 /
45 ---o---1---o---o---o---A
46
47the merge base between 'A' and 'B' is '1'.
48
49Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the
29b802aa 50merge base between 'A' and a hypothetical commit 'M', which is a merge
99f1c04b
JH
51between 'B' and 'C'. For example, with this topology:
52
53 o---o---o---o---C
54 /
55 / o---o---o---B
56 / /
57 ---2---1---o---o---o---A
58
59the result of `git merge-base A B C` is '1'. This is because the
60equivalent topology with a merge commit 'M' between 'B' and 'C' is:
61
62
63 o---o---o---o---o
64 / \
65 / o---o---o---o---M
66 / /
67 ---2---1---o---o---o---A
68
69and the result of `git merge-base A M` is '1'. Commit '2' is also a
70common ancestor between 'A' and 'M', but '1' is a better common ancestor,
71because '2' is an ancestor of '1'. Hence, '2' is not a merge base.
72
73When the history involves criss-cross merges, there can be more than one
29b802aa 74'best' common ancestor for two commits. For example, with this topology:
99f1c04b
JH
75
76 ---1---o---A
77 \ /
78 X
79 / \
80 ---2---o---o---B
81
29b802aa
RW
82both '1' and '2' are merge-bases of A and B. Neither one is better than
83the other (both are 'best' merge bases). When the `--all` option is not given,
99f1c04b 84it is unspecified which best one is output.
2cf565c5
DG
85
86Author
87------
88Written by Linus Torvalds <torvalds@osdl.org>
89
90Documentation
91--------------
92Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
93
94GIT
95---
9e1f0a85 96Part of the linkgit:git[1] suite