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>
Junio C Hamano committed
Jul 30, 2008 at 07:04 UTC
99f1c04be09d73a40ef0a37c6868969d40391196
1 file changed
+66
-11
Documentation/git-merge-base.txt
+66
-11
@@ -8,26 +8,81 @@ git-merge-base - Find as good common ancestors as possible for a merge
8
9
SYNOPSIS
10
--------
11
-'git merge-base' [--all] <commit> <commit>
11
+'git merge-base' [--all] <commit> <commit>...
12
13
DESCRIPTION
14
-----------
15
16
-'git-merge-base' finds as good a common ancestor as possible between
17
-the two commits. That is, given two commits A and B, `git merge-base A
18
-B` will output a commit which is reachable from both A and B through
19
-the parent relationship.
16
+'git-merge-base' finds best common ancestor(s) between two commits to use
17
+in a three-way merge. One common ancestor is 'better' than another common
18
+ancestor if the latter is an ancestor of the former. A common ancestor
19
+that does not have any better common ancestor than it is a 'best common
20
+ancestor', i.e. a 'merge base'. Note that there can be more than one
21
+merge bases between two commits.
22
21
-Given a selection of equally good common ancestors it should not be
22
-relied on to decide in any particular way.
23
-
24
-The 'git-merge-base' algorithm is still in flux - use the source...
23
+Among the two commits to compute their merge bases, one is specified by
24
+the first commit argument on the command line; the other commit is a
25
+(possibly hypothetical) commit that is a merge across all the remaining
26
+commits on the command line. As the most common special case, giving only
27
+two commits from the command line means computing the merge base between
28
+the given two commits.
29
30
OPTIONS
31
-------
32
--all::
29
- Output all common ancestors for the two commits instead of
30
- just one.
33
+ Output all merge bases for the commits, instead of just one.
34
+
35
+DISCUSSION
36
+----------
37
+
38
+Given two commits 'A' and 'B', `git merge-base A B` will output a commit
39
+which is reachable from both 'A' and 'B' through the parent relationship.
40
+
41
+For example, with this topology:
42
+
43
+ o---o---o---B
44
+ /
45
+ ---o---1---o---o---o---A
46
+
47
+the merge base between 'A' and 'B' is '1'.
48
+
49
+Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the
50
+merge base between 'A' and an hypothetical commit 'M', which is a merge
51
+between '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
+
59
+the result of `git merge-base A B C` is '1'. This is because the
60
+equivalent 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
+
69
+and the result of `git merge-base A M` is '1'. Commit '2' is also a
70
+common ancestor between 'A' and 'M', but '1' is a better common ancestor,
71
+because '2' is an ancestor of '1'. Hence, '2' is not a merge base.
72
+
73
+When the history involves criss-cross merges, there can be more than one
74
+'best' common ancestors between two commits. For example, with this
75
+topology:
76
+
77
+ ---1---o---A
78
+ \ /
79
+ X
80
+ / \
81
+ ---2---o---o---B
82
+
83
+both '1' and '2' are merge-base of A and B. Neither one is better than
84
+the other (both are 'best' merge base). When `--all` option is not given,
85
+it is unspecified which best one is output.
86
87
Author
88
------