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

[Dmitry Gutov <dmitry@gutov.dev>]

On 10/10/2024 08:27, Eli Zaretskii wrote:
>> Date: Thu, 10 Oct 2024 03:26:23 +0300
>> Cc: sbaugh@janestreet.com, 62940@debbugs.gnu.org, fgunbin@fastmail.fm
>> From: Dmitry Gutov <dmitry@gutov.dev>
>>
>> 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.
> 
> What I had in mind was to explain what we mean by "last pushed
> revision".  AFAICT, you use "the previous revision when the fileset
> changed" instead.  IMO, this terminology has the same problem: it
> doesn't account for changing branches or remotes, for example.  We
> should somehow qualify the description by those situations (which I
> agree are somewhat exceptional, but definitely not rare enough to be
> ignored).

Not sure what you mean by changing branches, given the revision default 
that is used is determined by the tip of the local branch.

> Moreover, the patch to which I posted the comments uses
> "last pushed revision" all over the place, so if we want to use your
> proposed terminology instead, we had better modified the doc strings
> to use it as well.

It's another term, we'll actually need both (possibly rephrased).

>> 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.
> 
> I don't see a reason why explaining that should take more than a
> couple of sentences.
> 
>> Should this be a whole separate node, "Reading Revisions for Diff With
>> Completion"?
> 
> I don't think that is needed.  If we think some parts of the
> description are "too much detail", we could have them in footnotes.

Okay, check out this attempt. It might be considered too cluttered. 
Perhaps you will have suggestions for improvement.

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 99219b7f5d7..d50219f0688 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -881,13 +881,16 @@ Old Revisions

  @kindex C-u C-x v =
    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
-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.
+@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.  The first one has several default
+values: the revision before the last one when the fileset changed, and
+the last revision of the current branch's upstream.
+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.

    Instead of the revision ID, some version control systems let you
  specify revisions in other formats.  For instance, under Bazaar you
@@ -921,6 +924,9 @@ Old Revisions
  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).
+The first one has several default values: the revision before the last
+one when the fileset changed, and the last revision of the current
+branch's upstream.

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