Merge branch 'sb/parse-options'

diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index 2f0c5259e01917e456954de5eb59597a2c829b0c..ce5b369985c254ec5d986aa3dd250828cf3cc4cb 100644 (file)
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -8,27 +8,32 @@ git-merge-base - Find as good common ancestors as possible for a merge
 
 SYNOPSIS
 --------
-'git merge-base' [--all] <commit> <commit>...
+'git merge-base' [-a|--all] <commit> <commit>...
 
 DESCRIPTION
 -----------
 
-'git-merge-base' finds best common ancestor(s) between two commits to use
+'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
+that does not have any better common ancestor is a 'best common
 ancestor', i.e. a 'merge base'.  Note that there can be more than one
-merge bases between two commits.
+merge base for a pair of commits.
 
-Among the two commits to compute their merge bases, one is specified by
+Among the two commits to compute the merge base from, 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
+commits on the command line.  As the most common special case, specifying only
+two commits on the command line means computing the merge base between
 the given two commits.
 
+As a consequence, the 'merge base' is not necessarily contained in each of the
+commit arguments if more than two commits are specified. This is different
+from linkgit:git-show-branch[1] when used with the `--merge-base` option.
+
 OPTIONS
 -------
+-a::
 --all::
        Output all merge bases for the commits, instead of just one.
 
@@ -47,7 +52,7 @@ For example, with this topology:
 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
+merge base between 'A' and a hypothetical commit 'M', which is a merge
 between 'B' and 'C'.  For example, with this topology:
 
               o---o---o---o---C
@@ -71,8 +76,7 @@ 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:
+'best' common ancestor for two commits.  For example, with this topology:
 
        ---1---o---A
           \ /
@@ -80,8 +84,8 @@ topology:
           / \
        ---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,
+both '1' and '2' are merge-bases of A and B.  Neither one is better than
+the other (both are 'best' merge bases).  When the `--all` option is not given,
 it is unspecified which best one is output.
 
 Author