Document C-x v M D and C-x v M L in the manual

* doc/emacs/emacs.texi (Merge Bases):
* doc/emacs/vc1-xtra.texi (Merge Bases): New node.

3 files changed, 73 insertions, 1 deletions

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index b373dc092f8..4b625f99f52 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -868,6 +868,7 @@ Miscellaneous Commands and Features of VC
 * Change Logs and VC::    Generating a change log file from log entries.
 * VC Delete/Rename::      Deleting and renaming version-controlled files.
 * Revision Tags::         Symbolic names for revisions.
+* Merge Bases::           The most recent revision existing on both branches.
 * Other Working Trees::   Multiple sets of workfiles.
 * Version Headers::       Inserting version control headers into working files.
 * Editing VC Commands::   Editing the VC shell commands that Emacs will run.
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 3de00fe8684..5801604204c 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1815,7 +1815,7 @@ and so on, depending on the number of existing branches at that point.
 @kindex C-x v b c
 @findex vc-create-branch
   This procedure will not work for distributed version control systems
-like git or Mercurial.  For those systems you should use the command
+like Git or Mercurial.  For those systems you should use the command
 @code{vc-create-branch} (@w{@kbd{C-x v b c @var{branch-name} @key{RET}}})
 instead.
 
diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi
index 72e660a2def..8830b93c91a 100644
--- a/doc/emacs/vc1-xtra.texi
+++ b/doc/emacs/vc1-xtra.texi
@@ -14,6 +14,7 @@
 * Change Logs and VC::  Generating a change log file from log entries.
 * VC Delete/Rename::    Deleting and renaming version-controlled files.
 * Revision Tags::       Symbolic names for revisions.
+* Merge Bases::         The most recent revision existing on both branches.
 * Other Working Trees:: Multiple sets of workfiles.
 * Version Headers::     Inserting version control headers into working files.
 * Editing VC Commands:: Editing the VC shell commands that Emacs will run.
@@ -227,6 +228,76 @@ an old tag, the renamed file is retrieved under its new name, which is
 not the name that the makefile expects.  So the program won't really
 work as retrieved.
 
+@node Merge Bases
+@subsubsection Merge Bases
+@cindex merge bases
+
+@table @kbd
+@item C-x v M D
+Report diffs of changes on a branch since it diverged from another
+(@code{vc-diff-mergebase}).
+
+@item C-x v M L
+Display log messages for revisions on a branch since it diverged from
+another (@code{vc-log-mergebase}).
+@end table
+
+@c This definition is possibly dVCS-specific -- can revisions exist on
+@c more than one branch for older VCS?  This needs thinking through if
+@c any of our centalized VCS gain support for these commands.
+The @dfn{merge base} of two branches is the most recent revision that
+exists on both branches.  If neither of the branches were ever merged
+into the other (@pxref{Merging}), then the merge base is the revision
+that the older of the two branches was at when the newer branch was
+created from it (@pxref{Creating Branches}).  If one of the branches was
+ever merged into the other, then the merge base is the most recent merge
+point.
+
+With this understood, we can generalize the concept of a merge base from
+branches to any two revisions.  The merge base of two revisions is the
+most recent revision that can be found in the revision history of both
+of the two revisions.@footnote{In fact the concept generalizes to any
+number of revisions, but Emacs's commands for merge bases work with only
+two, so we limit ourselves to that.}
+
+The commands described in this section are currently implemented only
+for decentralized version control systems (@pxref{VCS Repositories}).
+
+@kindex C-x v M D
+@findex vc-diff-mergebase
+@kindex C-x v M L
+@findex vc-log-mergebase
+Merge bases are useful to make certain comparisons between branches, and
+Emacs provides two commands for doing so.  Each of @kbd{C-x v M D}
+(@code{vc-diff-mergebase}) and @kbd{C-x v M L} (@code{vc-log-mergebase})
+prompts for two branches, finds their merge base, and then compares that
+merge base with the second of the two branches.  The commands report
+diffs and display change history, respectively.
+
+The typical use case for these commands is when one of the branches was
+originally created from the other and you or a collaborator have made
+merges of one of the branches into the other at least once.  Then you
+can use these commands to see what changes on one branch have not yet
+been merged into the other.
+
+Call the branch which has the changes you are interested in the ``source
+branch'' and the branch into which these changes have not yet been
+merged the ``target branch''.  Specify the target branch when prompted
+for the ``older revision'' and the source branch when prompted for the
+``newer revision''.@footnote{The concept of merge bases generalizes from
+branches to any two revisions.  The merge base of two revisions is the
+most recent revision that can be found in the revision history of both
+of the two revisions.  @kbd{C-x v M D} and @kbd{C-x v M L} accept any
+two revisions, not just branches.  Comparing two branches is the same as
+comparing the revisions at the ends of the branches.
+
+(In fact the concept generalizes to any number of revisions, but Emacs's
+commands for merge bases work with only two, so we limit ourselves to
+that.)}  Then @kbd{C-x v M D} shows you a preview of what would change
+on the target branch if you were to merge the source branch into it, and
+@kbd{C-x v M L} shows you a log of the changes on the source branch not
+yet merged into the target branch.
+
 @node Other Working Trees
 @subsubsection Multiple Working Trees for One Repository