Subject: Re: bug#62940: 29.0.60; vc: no easy way to get diff of all outgoing changes

From: Dmitry Gutov <[email-masked]>
Date: Thu, 10 Oct 2024 03:26:23 +0300

Hi Eli,

On 14/09/2024 10:12, Eli Zaretskii wrote:
> More importantly, this change must be accompanied with a suitable
> update of the user manual, where we should explain what commit is
> suggested as the default.  "Last pushed revision" is somewhat vague
> and inaccurate, because the user could switch branches or remotes, or
> do something else.  We should find a more accurate description.  Also,
> the doc string of vc-root-diff needs to be updated with this
> information.

I wonder how you'd like to see these changes described.

For example, here's how I could document the just-pushed change 
(related, but for a different bug), rev a295d7de9e8.

If we also add the story about the second default being the upstream 
revision, with a description of how such is determined, it might 
overload the text. Maybe for no good reason if most people don't use 
'C-u' with 'C-x v =' anyway, even if for some it's handy.

Should this be a whole separate node, "Reading Revisions for Diff With 
Completion"?

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 99219b7f5d7..ba60bfddcd1 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -883,11 +883,12 @@ Old Revisions
    To compare two arbitrary revisions of the current VC fileset, call
  @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}.  This
  prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
-diff between those versions of the fileset.  This will not work
+diff between those versions of the fileset.  The first one defaults to
+the previous revision when the fileset changed, and the second defaults
+to nil, which means the contents of the work tree.  This will not work
  reliably for multi-file VC filesets, if the version control system is
-file-based rather than changeset-based (e.g., CVS), since then
-revision IDs for different files would not be related in any
-meaningful way.
+file-based rather than changeset-based (e.g., CVS), since then revision
+IDs for different files would not be related in any meaningful way.

    Instead of the revision ID, some version control systems let you
  specify revisions in other formats.  For instance, under Bazaar you
@@ -920,7 +921,9 @@ Old Revisions
  @code{vc-root-diff} with a prefix argument: @kbd{C-u C-x v D}.  This
  prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
  diff between those versions of the entire version-controlled directory
-trees (RCS, SCCS, CVS, and SRC do not support this feature).
+trees (RCS, SCCS, CVS, and SRC do not support this feature).  The first
+one defaults to the previous revision when the fileset changed, and the
+second defaults to nil, which means the contents of the work tree.

  @vindex vc-diff-switches
    You can customize the @command{diff} options that @kbd{C-x v =} and