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

From: Eli Zaretskii <[email-masked]>
Date: Thu, 10 Oct 2024 08:27:30 +0300

> Date: Thu, 10 Oct 2024 03:26:23 +0300
> Cc: [email-masked], [email-masked], [email-masked]
> From: Dmitry Gutov <[email-masked]>
> 
> 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).  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.

> 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.