New commands for outgoing diffs including uncommitted changes

spwhitton · spwhitton · commit 29e673a77b14 · 2025-08-30T11:44:53.000+01:00
* lisp/vc/vc.el (vc-root-diff-outgoing-base)
(vc-diff-outgoing-base): New commands (bug#62940).
* lisp/vc/vc-hooks.el (vc-prefix-map): Bind them.
* doc/emacs/vc1-xtra.texi (Outgoing Base Diffs):
* etc/NEWS: Document them.
* doc/emacs/emacs.texi (Outgoing Base Diffs): New node.
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
@@ -869,6 +869,7 @@ Miscellaneous Commands and Features of VC
 * 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.
+* Outgoing Base Diffs::   Diffs including all outstanding changes on a branch.
 * 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/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi
@@ -15,6 +15,7 @@
 * 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.
+* Outgoing Base Diffs:: Diffs including all outstanding changes on a branch.
 * 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.
@@ -298,6 +299,90 @@ 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 Outgoing Base Diffs
+@subsubsection Commands for diffs including all outstanding changes
+@cindex outstanding changes
+
+@table @kbd
+@item C-x v B =
+Display diffs of changes to the VC fileset since the merge base of this
+branch and its upstream counterpart (@code{vc-diff-outgoing-base}).
+
+@item C-x v B D
+Display all changes since the merge base of this branch and its upstream
+counterpart (@code{vc-root-diff-outgoing-base}).
+@end table
+
+For decentralized version control systems (@pxref{VCS Repositories}),
+these commands provide specialized versions of @kbd{C-x v M D} (see
+@pxref{Merge Bases}) which also take into account the state of upstream
+repositories.  These commands are useful both when working on a single
+branch and when developing features on a separate branch
+(@pxref{Branches}).  These two cases involve using the commands
+differently, and so we will describe them separately.
+
+First, consider working on a single branch.  @dfn{Outstanding changes}
+are those which you haven't yet pushed upstream.  This includes both
+unpushed commits and uncommitted changes in your working tree.  In many
+cases the reason these changes are not pushed yet is that they are not
+finished: the changes committed so far don't make sense in isolation.
+
+@kindex C-x v B =
+@findex vc-diff-outgoing-base
+@kindex C-x v B D
+@findex vc-root-diff-outgoing-base
+Type @kbd{C-x v B D} (@code{vc-root-diff-outgoing-base}) to display a
+summary of all these changes, committed and uncommitted.  This summary
+is in the form of a diff of what committing and pushing (@pxref{Pulling
+/ Pushing}) all these changes would do to the upstream repository.  You
+can use @kbd{C-x v B =} (@code{vc-diff-outgoing-base}) instead to limit
+the display of changes to the current VC fileset.  (The difference
+between @w{@kbd{C-x v B D}} and @w{@kbd{C-x v B =}} is like the
+difference between @kbd{C-x v D} and @kbd{C-x v =} (@pxref{Old
+Revisions}).)@footnote{Another point of comparison is that these
+commands are like @w{@kbd{C-x v O =}} (@code{vc-fileset-diff-outgoing})
+and @kbd{C-x v O D} (@code{vc-root-diff-outgoing}) except that they
+include uncommitted changes in the reported diffs.  Like those other
+commands, you can use a prefix argument to specify a particular upstream
+location.}
+
+Second, consider developing a feature on a separate branch.  Call this
+the @dfn{feature branch},@footnote{Many version control workflows
+involve developing new features on isolated branches.  However, the term
+``feature branch'' is usually reserved for a particular kind of isolated
+branch, one that other branches are repeatedly merged into.
+
+That doesn't matter to this explanation, so we use ``feature branch'' to
+refer to the separate branch used for developing the feature even though
+whether it is really a feature branch depends on other aspects of the
+branching workflow in use.} and call the branch from which the feature
+branch was originally created the @dfn{trunk} or @dfn{development
+trunk}.
+
+In this case, outstanding changes is a more specific notion than just
+unpushed and uncommitted changes on the feature branch.  You're not
+finished sharing changes with your collaborators until they have been
+merged into the trunk, and pushed.  Therefore, in this example,
+outstanding changes are those which haven't yet been integrated into the
+upstream repository's development trunk.  That means committed changes
+on the feature branch that haven't yet been merged into the trunk, plus
+uncommitted changes.
+
+@cindex outgoing base, version control
+The @dfn{outgoing base} is the upstream location for which the changes
+are destined once they are no longer outstanding.  In this case, that's
+the upstream version of the trunk, to which you and your collaborators
+push finished work.
+
+To display a summary of outgoing changes in this multi-branch example,
+supply a prefix argument, by typing @w{@kbd{C-u C-x v B =}} or
+@w{@kbd{C-u C-x v B D}}.  When prompted, enter the outgoing base.
+Exactly what you must supply here depends on the name of your
+development trunk and the version control system in use.  For example,
+with Git, usually you will enter @kbd{origin/master}.  We hope to
+improve these commands such that no prefix argument is required in the
+multi-branch case, too.
+
 @node Other Working Trees
 @subsubsection Multiple Working Trees for One Repository
 
diff --git a/etc/NEWS b/etc/NEWS
@@ -2173,6 +2173,14 @@ include were committed and will be pushed.
 'vc-diff-incoming' and 'vc-diff-outgoing' are similar but limited to the
 current VC fileset.
 
++++
+*** New commands to report diffs of outstanding changes.
+'C-x v B =' ('vc-diff-outgoing-base') and 'C-x v B D'
+('vc-root-diff-outgoing-base') report diffs of changes since the merge
+base with the remote branch, including uncommitted changes.
+They are useful to view all outstanding (unmerged, unpushed) changes on
+the current branch.
+
 +++
 *** New user option 'vc-use-incoming-outgoing-prefixes'.
 If this is customized to non-nil, 'C-x v I' and 'C-x v O' become prefix
diff --git a/lisp/vc/vc-hooks.el b/lisp/vc/vc-hooks.el
@@ -952,6 +952,8 @@ In the latter case, VC mode is deactivated for this buffer."
   "O"   #'vc-log-outgoing
   "M L" #'vc-log-mergebase
   "M D" #'vc-diff-mergebase
+  "B =" #'vc-diff-outgoing-base
+  "B D" #'vc-root-diff-outgoing-base
   "m"   #'vc-merge
   "r"   #'vc-retrieve-tag
   "s"   #'vc-create-tag
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
@@ -2575,6 +2575,9 @@ When unspecified REMOTE-LOCATION is the place \\[vc-push] would push to.
 When called interactively with a prefix argument, prompt for REMOTE-LOCATION.
 In some version control systems REMOTE-LOCATION can be a remote branch name.
 
+This command is like `vc-root-diff-outgoing-base' except that it does
+not include uncommitted changes.
+
 See `vc-use-incoming-outgoing-prefixes' regarding giving this command a
 global binding."
   (interactive (list (vc--maybe-read-remote-location)))
@@ -2589,6 +2592,9 @@ When called interactively with a prefix argument, prompt for REMOTE-LOCATION.
 In some version control systems REMOTE-LOCATION can be a remote branch name.
 When called from Lisp optional argument FILESET overrides the VC fileset.
 
+This command is like `vc-diff-outgoing-base' except that it does not
+include uncommitted changes.
+
 See `vc-use-incoming-outgoing-prefixes' regarding giving this command a
 global binding."
   ;; For this command, for distributed VCS, we want to ignore
@@ -2629,6 +2635,71 @@ global binding."
                                        (car fileset))
                       (called-interactively-p 'interactive))))
 
+;; For the following two commands, the default meaning for
+;; REMOTE-LOCATION may become dependent on whether we are on a
+;; shorter-lived or longer-lived ("trunk") branch.  If we are on the
+;; trunk then it will always be the place `vc-push' would push to.  If
+;; we are on a shorter-lived branch, it may instead become the remote
+;; trunk branch from which the shorter-lived branch was branched.  That
+;; way you can use these commands to get a summary of all unmerged work
+;; outstanding on the short-lived branch.
+;;
+;; The obstacle to doing this is that VC lacks any distinction between
+;; shorter-lived and trunk branches.  But we all work with both of
+;; these, for almost any VCS workflow.  E.g. modern workflows which
+;; eschew traditional feature branches still have a long-lived trunk
+;; plus shorter-lived local branches for merge requests or patch series.
+;; --spwhitton
+
+;;;###autoload
+(defun vc-root-diff-outgoing-base (&optional remote-location)
+  "Report diff of all changes since the merge base with REMOTE-LOCATION.
+The merge base with REMOTE-LOCATION means the common ancestor of the
+working revision and REMOTE-LOCATION.
+Uncommitted changes are included in the diff.
+
+When unspecified REMOTE-LOCATION is the place \\[vc-push] would push to.
+This default meaning for REMOTE-LOCATION may change in a future release
+of Emacs.
+
+When called interactively with a prefix argument, prompt for
+REMOTE-LOCATION.  In some version control systems, REMOTE-LOCATION can
+be a remote branch name.
+
+This command is like `vc-root-diff-outgoing' except that it includes
+uncommitted changes."
+  (interactive (list (vc--maybe-read-remote-location)))
+  (vc--with-backend-in-rootdir "VC root-diff"
+    (vc-diff-outgoing-base remote-location `(,backend (,rootdir)))))
+
+;;;###autoload
+(defun vc-diff-outgoing-base (&optional remote-location fileset)
+  "Report changes to VC fileset since the merge base with REMOTE-LOCATION.
+
+The merge base with REMOTE-LOCATION means the common ancestor of the
+working revision and REMOTE-LOCATION.
+Uncommitted changes are included in the diff.
+
+When unspecified REMOTE-LOCATION is the place \\[vc-push] would push to.
+This default meaning for REMOTE-LOCATION may change in a future release
+of Emacs.
+
+When called interactively with a prefix argument, prompt for
+REMOTE-LOCATION.  In some version control systems, REMOTE-LOCATION can
+be a remote branch name.
+
+This command is like to `vc-fileset-diff-outgoing' except that it
+includes uncommitted changes."
+  (interactive (list (vc--maybe-read-remote-location) nil))
+  (let* ((fileset (or fileset (vc-deduce-fileset t)))
+         (backend (car fileset))
+         (incoming (vc--incoming-revision backend
+                                          (or remote-location ""))))
+    (vc-diff-internal vc-allow-async-diff fileset
+                      (vc-call-backend backend 'mergebase incoming)
+                      nil
+                      (called-interactively-p 'interactive))))
+
 (declare-function ediff-load-version-control "ediff" (&optional silent))
 (declare-function ediff-vc-internal "ediff-vers"
                   (rev1 rev2 &optional startup-hooks))
