VC: New commands for cherry-picking (bug#79408)

* lisp/vc/diff-mode.el (diff-buffer-file-names): New function.
* lisp/vc/log-view.el (vc--pick-or-revert)
(vc--prompt-other-working-tree): Autoload.
(vc-parent-buffer-name, vc-log-short-style)
(vc-print-log-internal): Declare.
(log-view--pick-or-revert): New function.
(log-view-revision-cherry-pick, log-view-revision-revert): New
commands.
(log-view-mode-map, log-view-mode-menu): Bind them.
* lisp/vc/vc-dispatcher.el (vc-start-logentry): If
get-file-buffer returns nil, use the current buffer as the
parent buffer.
* lisp/vc/vc.el (diff-buffer-file-names, diff-reverse-direction):
Declare.
(vc--pick-or-revert): New function.
(vc-revision-cherry-pick, vc-revision-revert): New commands.
* lisp/vc/vc-hooks.el (vc-menu-map): Bind them.
* doc/emacs/maintaining.texi (VC Change Log, VC Undo)
(Copying Between Branches):
* etc/NEWS: Document the new commands.

2 files changed, 82 insertions, 8 deletions

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index b32c704bd12..7a5107ee359 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -857,10 +857,11 @@ VC Directory Mode
 
 Version Control Branches
 
-* Switching Branches::    How to get to another existing branch.
-* Pulling / Pushing::     Receiving/sending changes from/to elsewhere.
-* Merging::               Transferring changes between branches.
-* Creating Branches::     How to start a new branch.
+* Switching Branches::       How to get to another existing branch.
+* Pulling / Pushing::        Receiving/sending changes from/to elsewhere.
+* Merging::                  Transferring changes between branches.
+* Creating Branches::        How to start a new branch.
+* Copying Between Branches:: Copying the changes made by revisions.
 
 @ifnottex
 Miscellaneous Commands and Features of VC
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index e7a05a3556b..9d768cc1a77 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1264,6 +1264,15 @@ Unmark the entry at point (@code{log-view-unmark-entry}).
 
 @item U
 Unmark all marked entries (@code{log-view-unmark-all-entries}).
+
+@item C
+Copy changes to a currently checked out branch; either the changes from
+the revision at point, or the changes from all marked revisions
+(@code{log-view-revision-cherry-pick}).
+
+@item R
+Undo the effects of old revisions; either the revision at point, or all
+marked revisions (@code{log-view-revision-revert}).
 @end table
 
 @vindex vc-log-show-limit
@@ -1307,6 +1316,9 @@ also prompt for a specific VCS shell command to run for this purpose.
 @item C-x v u
 Revert the work file(s) in the current VC fileset to the last revision
 (@code{vc-revert}).
+
+@item M-x vc-revision-revert
+Undo the effects of an older commit.
 @end table
 
 @kindex C-x v u
@@ -1330,6 +1342,21 @@ unlocked; you must lock again to resume editing.  You can also use
 @kbd{C-x v u} to unlock a file if you lock it and then decide not to
 change it.
 
+@findex vc-revision-revert
+@cindex reverting commits
+  To discard changes that have already been committed, by yourself or
+someone else, you can use @w{@kbd{M-x vc-revision-revert}}.  This is
+called @dfn{reverting} a commit.  The command prompts for a revision to
+revert, and then the VC backend reverts it.  Most backends implement
+this by making a new commit which undoes the changes made by the
+revision.
+
+  An alternative way to access this functionality is to the
+@code{log-view-revision-revert} command, bound to @kbd{R} in Log View
+mode buffers (@pxref{VC Change Log}).  Compared to using @w{@kbd{M-x
+vc-revision revert}} directly, this can make it easier to be sure you
+are reverting the revision you intend.
+
 @node VC Ignore
 @subsection Ignore Version Control Files
 
@@ -1642,10 +1669,11 @@ supports checking out different branches and committing into new or
 different branches.
 
 @menu
-* Switching Branches::    How to get to another existing branch.
-* Pulling / Pushing::     Receiving/sending changes from/to elsewhere.
-* Merging::               Transferring changes between branches.
-* Creating Branches::     How to start a new branch.
+* Switching Branches::       How to get to another existing branch.
+* Pulling / Pushing::        Receiving/sending changes from/to elsewhere.
+* Merging::                  Transferring changes between branches.
+* Creating Branches::        How to start a new branch.
+* Copying Between Branches:: Copying the changes made by revisions.
 @end menu
 
 @node Switching Branches
@@ -1857,6 +1885,51 @@ revision.
 on that branch.  To leave the branch, you must explicitly select a
 different revision with @kbd{C-u C-x v v}.
 
+@node Copying Between Branches
+@subsubsection Copying Changes Made By Revisions Between Branches
+
+@table @kbd
+@item M-x vc-revision-cherry-pick
+Copy a single revision to branch checked out in this working tree.
+@end table
+
+@cindex cherry-pick
+@cindex revision, cherry-picks of
+  Sometimes it is useful to copy a revision from one branch to another.
+This means creating a new revision with the same changes, log message
+and authorship information as an existing revision that can be found on
+another branch.  This is often called @dfn{cherry-picking} the revision
+from one branch to another.
+
+@cindex revisions, backporting
+  The most common case is copying a revision from a branch that won't be
+merged (@pxref{Merging}) into your current branch.  For example, your
+project might have a feature-frozen branch that accepts only bug fixes.
+Someone (possibly you) fixes a bug on the main development branch.  You
+can then cherry-pick that revision onto the feature-frozen branch in
+order to fix the bug there, too.  This is called @dfn{backporting} the
+revision, or backporting the fix.
+
+@findex vc-revision-cherry-pick
+  You can use the command @kbd{M-x vc-revision-cherry-pick} to
+cherry-pick revisions.  It prompts for a revision to cherry-pick.  It
+then pops up a buffer for you to edit the log message for the new
+revision.  Normally the VC backend generates a log message including a
+reference to the revision you want to copy, so that the copy can be
+traced.  If you wish, you can delete this reference before typing
+@kbd{C-c C-c} to conclude the cherry-pick.
+
+  Alternatively you can invoke the command with a prefix argument,
+i.e. @w{@kbd{C-u M-x vc-revision-cherry-pick}}.  In this case the log
+message from the source revision is used unmodified, and the cherry-pick
+happens immediately, without popping up a buffer for log message edits.
+
+  An alternative way to access this functionality is the
+@code{log-view-revision-cherry-pick} command, bound to @kbd{C} in Log
+View mode buffers (@pxref{VC Change Log}).  Compared to using
+@w{@kbd{M-x vc-revision-cherry-pick}} directly, this can make it easier
+to be sure you are cherry-picking the revision you intend.
+
 @ifnottex
 @include vc1-xtra.texi
 @end ifnottex