GNU bug report logs - #80037
31.0.50; Improving 'C-u C-x v l/L' and merging 'C-x v B' into 'C-x v b'

Previous Next

To reply to this bug, email your comments to 80037 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: bug-gnu-emacs <at> gnu.org
Subject: 31.0.50; Improving 'C-u C-x v l/L' and merging 'C-x v B' into 'C-x
 v b'
Date: Fri, 19 Dec 2025 16:34:09 +0000

X-debbugs-cc: sbaugh <at> janestreet.com, dmitry <at> gutov.dev, juri <at> linkov.net

Spencer suggested to me off-list that the new 'C-x v B' keymap could be
merged into 'C-x v b', and we have been hashing out a proposal.  This is
a more involved alternative to the proposal I made on emacs-devel a few
days ago.[1]

The new 'C-x v B' keymap contains commands to show the outstanding work
on a branch.  On a trunk branch, such as 'master', that means work you
haven't yet committed plus work you haven't yet pushed.  On a feature
branch, such as 'feature/igc', that means all work that hasn't yet been
merged into the relevant trunk branch (in this case, again, 'master').

See bug#80006 regarding the implementation of these new commands.
In this bug I want to focus on the user interface at the highest level,
in order to make an assessment of the breaking change proposal.
Let's set aside, initially, the renaming and obsoleting of functions.

Here is what the NEWS entries for this change would be.  I'll follow
them up with some further justification for why I think this is an
acceptable breaking change.

--8<---------------cut here---------------start------------->8---
*** 'C-u C-x v l' now prompts for a revision or branch to log.
Previously, 'C-u C-x v l' prompted for a revision ID that was used only
to position point in the log buffer, and also a number specifying the
maximum number of revisions to show.

The old prefix argument was not very useful because it would only work
if the revision ID specified was on the current branch.  Now, so long as
the revision ID is present in the repository, 'C-u C-x v l' will print a
log containing that revision ID.

You can still specify the maximum number of revisions to show using a
numeric prefix argument, e.g. 'C-u 999 C-x v l'.  You can specify a
numeric limit and also be prompted for a revision ID with an additional
'C-u' after your numeric prefix, like this: 'C-u 999 C-u C-x v l'.  You
can position point in the log by doing a plain 'C-x v l' and then using
'C-s' to search forward for the revision ID.

We have implemented this change by changing the default binding of
'C-x v l' to a new command.  Therefore, if you prefer, you can undo this
change like this:

    (keymap-global-set "C-x v l" #'vc-print-log)

*** 'C-u C-x v L' now prompts for a revision or branch to log.
Previously, 'C-u C-x v L' prompted for a number specifying the maximum
number of revisions to show.  Now it prompts for a revision or branch
from which to start the log.

You can still specify a limit with a numeric prefix argument, e.g.
'C-u 999 C-x v L'.  You can specify a numeric limit and also be prompted
for a revision ID to log with an additional 'C-u' after your numeric
prefix, like this: 'C-u 999 C-u C-x v L'.

We have implemented this change by changing the default binding of
'C-x v L' to a new command.  Therefore, if you prefer, you can undo this
change like this:

    (keymap-global-set "C-x v l" #'vc-print-root-log)

*** 'C-x v b l' is no longer bound to 'vc-print-branch-log'.
The new 'C-u C-x v L', described in the previous entry, is equivalent to
'vc-print-branch-log', and therefore the 'C-x v b l' key sequence has
been freed up for another use (described below).
If you prefer, you can undo this change like this:

    (keymap-global-set "C-x v b l" #'vc-print-branch-log)

*** New commands to show information about outstanding changes.
Outstanding changes on a branch are ...
Emacs has some new commands to display summaries of outstanding changes
on the current branch:

- 'C-x v b l': Show a log of outstanding changes to the current fileset.
- 'C-x v b L': Show a log of all outstanding changes.
- 'C-x v b =': Show a diff of outstanding changes to the current fileset.
- 'C-x v b D': Show a diff of all outstanding changes.
- 'C-x v b +': Pull from this branch's outgoing base.

The outgoing base means ...
What counts as outstanding changes is controlled by ...
--8<---------------cut here---------------end--------------->8---

Here are why this seems like an acceptable breaking change:

- It's easy for users to switch back to the old commands, and any Lisp
  calling the commands programmatically is entirely unaffected.

- The change to 'C-u C-x v l' wrt revision IDs is a usability
  improvement to existing functionality, not truly new functionality.
  It still prompts for a revision ID, and still leaves point positioned
  on the log entry for that revision.  And indeed it will do so
  successfully more often.

- Regarding the LIMIT changes to 'C-x v l' and 'C-x v L', prompting for
  the numeric limit is strange for an Emacs command.  Normally such
  limits have to be specified with a numeric prefix argument.  So it's
  only a small step to say that this now has to be done here too.
  (And the existing commands already accept a LIMIT supplied this way.)

- In the thread on the previous proposal,[1] we thought that it is okay
  to move 'C-x v b l' somewhere else because it was the wrong key
  sequence to begin with (because it is a root log, the last key should
  be uppercase), and the binding has only been around for a couple of
  releases.

- For all logging commands, a C-u prefix argument will now consistently
  mean "log something other than the current branch".  This covers
  C-x v l, C-x v L, C-x v O l, C-x v O L, C-x v I l, C-x v I L, and all
  the new outstanding changes commands.  That's much easier to remember
  than the strange prefix arguments to C-x v l and C-x v L.

- The old vc-print-branch-log was actually "print a log starting at this
  branch *or* this revision ID".  For modern VCS you often want to print
  logs starting at arbitrary revision IDs.  So moving that functionality
  away from a command and sub-keymap that only referred to "branches" is
  more mnemonic.

- We are able to get rid of a whole sub-keymap, 'C-x v B'.

- The new outstanding changes commands gain more mnemonic bindings.  The
  thought is, if you're on a shorter-lived branch that will later be
  merged into a trunk (very common with modern forge workflows, and also
  the feature/foo branches we use in emacs.git) then it makes sense to
  ask for "the branch diff" which is just, what effects on the trunk
  will merging this branch into it have?  And that's precisely C-x v b =
  and C-x v b D on this new scheme.

- One point in the other direction is that currently commands under
  'C-x v b' always operate on a branch other than the current branch,
  but that wouldn't be the case with the new outstanding changes
  commands.  I think this is okay.

[1]  https://lists.gnu.org/archive/html/emacs-devel/2025-12/msg00394.html

-- 
Sean Whitton

Message #8 received at 80037 <at> debbugs.gnu.org (full text, mbox):

From: Spencer Baugh <sbaugh <at> janestreet.com>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: 80037 <at> debbugs.gnu.org, juri <at> linkov.net, dmitry <at> gutov.dev
Subject: Re: bug#80037: 31.0.50; Improving 'C-u C-x v l/L' and merging 'C-x
 v B' into 'C-x v b'
Date: Fri, 19 Dec 2025 11:46:00 -0500

I agree with all this, it seems like it would be a great improvement.

One more point in favor of C-u C-x v l/L prompting for a revision: that
would be more consistent with the behavior of C-u C-x v =/D, which also
prompt for a revision.

Message #11 received at 80037 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: dmitry <at> gutov.dev, 80037 <at> debbugs.gnu.org, juri <at> linkov.net,
 sbaugh <at> janestreet.com
Subject: Re: bug#80037: 31.0.50;
 Improving 'C-u C-x v l/L' and merging 'C-x v B' into 'C-x v b'
Date: Sat, 20 Dec 2025 10:47:02 +0200

> Cc: sbaugh <at> janestreet.com, dmitry <at> gutov.dev, juri <at> linkov.net
> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Date: Fri, 19 Dec 2025 16:34:09 +0000
> 
> *** 'C-u C-x v l' now prompts for a revision or branch to log.
> Previously, 'C-u C-x v l' prompted for a revision ID that was used only
> to position point in the log buffer, and also a number specifying the
> maximum number of revisions to show.
> 
> The old prefix argument was not very useful because it would only work
> if the revision ID specified was on the current branch.  Now, so long as
> the revision ID is present in the repository, 'C-u C-x v l' will print a
> log containing that revision ID.

Why cannot this change be combined with the ability to specify the
maximum number of revisions to show?  That would make this proposed
breaking change to be almost 100% compatible with previous behavior.

> You can still specify the maximum number of revisions to show using a
> numeric prefix argument, e.g. 'C-u 999 C-x v l'.

What will this mean/do in VCS where revisions are specified by
numbers?

> You can specify a
> numeric limit and also be prompted for a revision ID with an additional
> 'C-u' after your numeric prefix, like this: 'C-u 999 C-u C-x v l'.

This is IMO extremely complicated and clumsy.  It is also without
precedent in Emacs, AFAIK.

> You
> can position point in the log by doing a plain 'C-x v l' and then using
> 'C-s' to search forward for the revision ID.

Yes, but then you are basically saying that the previous capability of
specifying a revision was not needed and can be removed.  I cannot
agree, given how old this feature is.

> *** 'C-u C-x v L' now prompts for a revision or branch to log.
> Previously, 'C-u C-x v L' prompted for a number specifying the maximum
> number of revisions to show.  Now it prompts for a revision or branch
> from which to start the log.

Another breaking change.  And why is it so important to start the
global log from a specific revision, let alone specify a branch, with
modern VCSes?  IME, specifying how many revisions to show is much more
frequently needed.

> Emacs has some new commands to display summaries of outstanding changes
> on the current branch:
> 
> - 'C-x v b l': Show a log of outstanding changes to the current fileset.
> - 'C-x v b L': Show a log of all outstanding changes.
> - 'C-x v b =': Show a diff of outstanding changes to the current fileset.
> - 'C-x v b D': Show a diff of all outstanding changes.
> - 'C-x v b +': Pull from this branch's outgoing base.

"C-x v b" was previously a prefix for commands that took a branch as
an argument and/or prompted for a branch.  This was easy to remember
and was mnemonically a good UI.  The above bindings break this
mnemonics, and I don't think I see why it was deemed a good idea to
use "C-x v b" for them -- what is the "b" part about?

So, another breaking change in the UI, which from where I stand is a
Bad Thing.

> Here are why this seems like an acceptable breaking change:

Sorry, I'm not convinced, see below.

> - It's easy for users to switch back to the old commands, and any Lisp
>   calling the commands programmatically is entirely unaffected.

This can be said about almost every breaking change we make: we always
strive to provide a way to revert to old behavior.  But that doesn't
change the fact that a change is breaking, and that we should avoid
doing that if possible.

> - The change to 'C-u C-x v l' wrt revision IDs is a usability
>   improvement to existing functionality, not truly new functionality.
>   It still prompts for a revision ID, and still leaves point positioned
>   on the log entry for that revision.  And indeed it will do so
>   successfully more often.

This could be done in backward-compatible fashion, I think, see above.

> - Regarding the LIMIT changes to 'C-x v l' and 'C-x v L', prompting for
>   the numeric limit is strange for an Emacs command.  Normally such
>   limits have to be specified with a numeric prefix argument.  So it's
>   only a small step to say that this now has to be done here too.
>   (And the existing commands already accept a LIMIT supplied this way.)

There's nothing wrong with a command that asks for a numeric input if
the prefix arg is already taken.  And the proposed "C-u NNN C-u"
prefix is actually more outlandish, at least IME.

> - In the thread on the previous proposal,[1] we thought that it is okay
>   to move 'C-x v b l' somewhere else because it was the wrong key
>   sequence to begin with (because it is a root log, the last key should
>   be uppercase), and the binding has only been around for a couple of
>   releases.

This could have been done without all the other breakage, couldn't it?

> - For all logging commands, a C-u prefix argument will now consistently
>   mean "log something other than the current branch".  This covers
>   C-x v l, C-x v L, C-x v O l, C-x v O L, C-x v I l, C-x v I L, and all
>   the new outstanding changes commands.  That's much easier to remember
>   than the strange prefix arguments to C-x v l and C-x v L.

I think this is a wrong aspect of a command to look for consistency.
What the prefix argument means is inherently specific to the command
(with the sole exception of when the prefix specifies the repetition
count).  In particular, I see no reason to make the "l" and "L"
commands interpret the argument in the same way, since these are
fundamentally different commands with today's VCSes.  So this
justification doesn't convince me; on the contrary, it sounds like you
tried to achieve consistency in the wrong place.

> - The old vc-print-branch-log was actually "print a log starting at this
>   branch *or* this revision ID".  For modern VCS you often want to print
>   logs starting at arbitrary revision IDs.  So moving that functionality
>   away from a command and sub-keymap that only referred to "branches" is
>   more mnemonic.

This looks like someone's personal preferences forced upon all Emacs
users.  I almost _never_ need to print a log starting from some
arbitrary revision ID.  I do sometimes need to print a log of a
non-current branch, and I definitely almost always want to show the
log of the current branch from its HEAD.  So, for me at least, the
above is a change for the worse, because it goes against my workflows.
I dare to assume that there are other Emacs users like me.  In
addition, this convention was there for ages.  So it seems like we are
breaking a very useful and veteran UI principle in favor of someone's
personal preferences.  Our way of handling different preferences is by
either providing user options or by providing alternative commands.
Why couldn't this have been done here, instead of so many breaking
changes?

> - The new outstanding changes commands gain more mnemonic bindings.  The
>   thought is, if you're on a shorter-lived branch that will later be
>   merged into a trunk (very common with modern forge workflows, and also
>   the feature/foo branches we use in emacs.git) then it makes sense to
>   ask for "the branch diff" which is just, what effects on the trunk
>   will merging this branch into it have?  And that's precisely C-x v b =
>   and C-x v b D on this new scheme.

Why couldn't this have been done without breaking existing UIs?  The
outstanding-changes commands are new, so we could do anything we like
for them, including find good bindings.  I don't understand why these
new commands required breaking changes, and you have never explained
that.  If there were some alternatives that were considered and
rejected, how about showing those alternatives and explaining why you
rejected them?

> - One point in the other direction is that currently commands under
>   'C-x v b' always operate on a branch other than the current branch,
>   but that wouldn't be the case with the new outstanding changes
>   commands.  I think this is okay.

I don't, sorry.  I find no justification for breaking the "branch"
mnemonics of "C-x v b" prefix.

In sum, I urge you to try to find a better solution that doesn't break
so many long-time UI assumptions and conventions.

P.S. Such a significant change should have been discussed on
emacs-devel, not in a bug report.

Message #14 received at 80037 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: dmitry <at> gutov.dev, juri <at> linkov.net, sbaugh <at> janestreet.com,
 80037 <at> debbugs.gnu.org
Subject: Re: bug#80037: 31.0.50; Improving 'C-u C-x v l/L' and merging 'C-x
 v B' into 'C-x v b'
Date: Sat, 20 Dec 2025 11:35:44 +0000

Hello Eli,

Thank you for reviewing.  What I presented was the most thoroughgoing
possible set of breaking changes in this area, and I would be happy if
we can find a subset of them that will appear to be improvements from
the perspectives of all (or almost all) users.

In particular, it is very interesting to hear that you regularly specify
the LIMIT and don't ever start a log from a particular revision.
That is the opposite of my own experience -- I don't believe I have ever
specified a LIMIT (instead I use the "Show 2x more" button) but I often
use C-x v b l to start a log at a particular revision.

I don't doubt that your usage matches plenty of other people's, so this
is important input.  I want to do right by both these sets of users.

> "C-x v b" was previously a prefix for commands that took a branch as
> an argument and/or prompted for a branch.  This was easy to remember
> and was mnemonically a good UI.  The above bindings break this
> mnemonics, and I don't think I see why it was deemed a good idea to
> use "C-x v b" for them -- what is the "b" part about?

This is the most important point.  The idea is that the outstanding
changes on a feature branch can be thought of as "the feature branch
diff" or "the feature branch log".  So if you use those commands a lot,
the 'b L' and 'b D' have "branch log" and "branch diff" as mnemonics.

But if you mostly use the commands under 'C-x v b' which take a branch
as an argument, then we have clashing mnemonics, indeed.

As the idea of 'C-x v b' for commands which take a branch as an argument
is fundamentally simpler, and is already in place, probably it should
take precedence.

So here is an alternative set of changes, incorporating various
suggestions you made:

- Do the changes to 'C-x v b' discussed in the other thread.

- Add a feature to 'C-u C-x v l' where if the revision ID specified does
  not appear in the log (because it's on another branch), try to print a
  log of a branch containing that revision ID, or fall back to printing
  a log starting at that revision ID.

  The UI is slightly tricky because populating the log buffer is async.
  Therefore we can't do a y/n prompt only after discovering that the
  specified revision ID does not appear in the log, because the user
  might be typing in another buffer.
  (Making the log printing non-async for the sake of this feature would
  be too much of a UI snappiness regression.)

  So we could have it on by default with an option to disable.
  I.e., Emacs would automatically replace the contents of
  *vc-change-log* with another branch's log or a log starting at the
  revision ID the user specified if, after the original log of the
  current branch has finished printing, that revision does not appear in
  it.  If someone really doesn't want this they can toggle a defcustom
  to get back the behaviour of only printing a log once.

- Define new commands to replace 'C-x v l' and 'C-x v L' which have a
  prefix argument to prompt for a revision to start the log at, *and* a
  limit.  Don't bind these anywhere, but suggest binding them to
  'C-x v l' and 'C-x v L' in NEWS, for those users who don't find the
  existing prefix arguments to 'C-x v l' and 'C-x v L' useful.
  (Discard the 'C-u 999 C-u' idea.)

- Bind all the new outstanding change commands under 'C-x v B'.

> Why couldn't this have been done without breaking existing UIs?  The
> outstanding-changes commands are new, so we could do anything we like
> for them, including find good bindings.  I don't understand why these
> new commands required breaking changes, and you have never explained
> that.  If there were some alternatives that were considered and
> rejected, how about showing those alternatives and explaining why you
> rejected them?

To be clear, the breaking changes definitely aren't necessary, as we can
just put the new commands under 'C-x v B'.
My idea was not to outright reject that option, but just the thought
that there may be more mnemonic options, and it might combine well with
improving the old prefix arguments.

> P.S. Such a significant change should have been discussed on
> emacs-devel, not in a bug report.

Ah, good point.  I think the smaller set of changes I've proposed in
this message probably doesn't need to go to -devel but let me know if
you disagree.

-- 
Sean Whitton

Message #17 received at 80037 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: dmitry <at> gutov.dev, juri <at> linkov.net, sbaugh <at> janestreet.com,
 80037 <at> debbugs.gnu.org
Subject: Re: bug#80037: 31.0.50; Improving 'C-u C-x v l/L' and merging 'C-x
 v B' into 'C-x v b'
Date: Sat, 20 Dec 2025 14:00:34 +0200

> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Cc: dmitry <at> gutov.dev,  80037 <at> debbugs.gnu.org,  juri <at> linkov.net,
>   sbaugh <at> janestreet.com
> Date: Sat, 20 Dec 2025 11:35:44 +0000
> 
> In particular, it is very interesting to hear that you regularly specify
> the LIMIT

No, I said that I _sometimes_ use LIMIT.  However, in most cases, I'm
only interested in the latest part of the log, starting from HEAD, so
some default value of LIMIT that is not too large should be okay for
my uses.

> and don't ever start a log from a particular revision.

What is the purpose of doing such a strange thing?  If I'm interested
in specific portions of VC history, I use "C-x v h" and sometimes
"C-x v g" (the latter usually when the backend can't follow renames or
significant/complex changes which break vc-region-history).

> That is the opposite of my own experience -- I don't believe I have ever
> specified a LIMIT (instead I use the "Show 2x more" button) but I often
> use C-x v b l to start a log at a particular revision.

When/why do you need to see a log that starts from some non-HEAD
revision?

> > "C-x v b" was previously a prefix for commands that took a branch as
> > an argument and/or prompted for a branch.  This was easy to remember
> > and was mnemonically a good UI.  The above bindings break this
> > mnemonics, and I don't think I see why it was deemed a good idea to
> > use "C-x v b" for them -- what is the "b" part about?
> 
> This is the most important point.  The idea is that the outstanding
> changes on a feature branch can be thought of as "the feature branch
> diff" or "the feature branch log".  So if you use those commands a lot,
> the 'b L' and 'b D' have "branch log" and "branch diff" as mnemonics.

But outstanding changes happen on non-feature branches as well.  It is
IMO confusing to treat feature branches differently in this regard.
Whether the current branch is a feature branch or anything else
(including master) is entirely in my head; VC commands apply to any
kind of branch, and the backend has no idea what will be the use of
the branch I'm on.  E.g., I could be working on master implementing
some feature, and during that work treat master as a kind-of feature
branch, delaying updating from upstream until I'm done.

> But if you mostly use the commands under 'C-x v b' which take a branch
> as an argument, then we have clashing mnemonics, indeed.
> 
> As the idea of 'C-x v b' for commands which take a branch as an argument
> is fundamentally simpler, and is already in place, probably it should
> take precedence.
> 
> So here is an alternative set of changes, incorporating various
> suggestions you made:
> 
> - Do the changes to 'C-x v b' discussed in the other thread.

Please point to the thread, as I don't have a clear idea what changes
do you allude to here.

> - Add a feature to 'C-u C-x v l' where if the revision ID specified does
>   not appear in the log (because it's on another branch), try to print a
>   log of a branch containing that revision ID, or fall back to printing
>   a log starting at that revision ID.

This is problematic, IMO.  A revision could be absent because the user
simply mistyped it.  Also, if there are many branches in the
repository, looking for the right branch could be slow.  Finally, and
most importantly, you assume that revision IDs are absolute, i.e. not
local to the branch.  This is false for Bazaar at least, and might be
wrong in other cases as well.

> - Define new commands to replace 'C-x v l' and 'C-x v L' which have a
>   prefix argument to prompt for a revision to start the log at, *and* a
>   limit.  Don't bind these anywhere, but suggest binding them to
>   'C-x v l' and 'C-x v L' in NEWS, for those users who don't find the
>   existing prefix arguments to 'C-x v l' and 'C-x v L' useful.
>   (Discard the 'C-u 999 C-u' idea.)

This is okay, and we could also find some suitable bindings for these
commands if that makes sense.

> - Bind all the new outstanding change commands under 'C-x v B'.

Why not "C-x v o"?

> > P.S. Such a significant change should have been discussed on
> > emacs-devel, not in a bug report.
> 
> Ah, good point.  I think the smaller set of changes I've proposed in
> this message probably doesn't need to go to -devel but let me know if
> you disagree.

I'd prefer to have all of this discussion on emacs-devel, as I expect
us to have some difficulty to distinguish between parts of this that
are simple enough to be kept on the bug tracker.  People who read and
participate in the emacs-devel discussion should have the full picture
at their disposal.

Message #20 received at 80037 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: dmitry <at> gutov.dev, 80037 <at> debbugs.gnu.org, sbaugh <at> janestreet.com,
 juri <at> linkov.net
Subject: Re: bug#80037: 31.0.50; Improving 'C-u C-x v l/L' and merging 'C-x
 v B' into 'C-x v b'
Date: Sat, 20 Dec 2025 12:36:57 +0000

Hello,

On Sat 20 Dec 2025 at 02:00pm +02, Eli Zaretskii wrote:

>> and don't ever start a log from a particular revision.
>
> What is the purpose of doing such a strange thing?  If I'm interested
> in specific portions of VC history, I use "C-x v h" and sometimes
> "C-x v g" (the latter usually when the backend can't follow renames or
> significant/complex changes which break vc-region-history).
>
>> That is the opposite of my own experience -- I don't believe I have ever
>> specified a LIMIT (instead I use the "Show 2x more" button) but I often
>> use C-x v b l to start a log at a particular revision.
>
> When/why do you need to see a log that starts from some non-HEAD
> revision?

This happen for me with Git repositories where there are commits on some
remote branch but not on any of my local branches.  Someone in an e-mail
or web forum discussion posts the commit IDs of a series of commits
fixing a bug on some branch somewhere.  I do a git fetch, copy the
commit ID of the last revision in the series from the mail or web page,
and yank it to vc-git-branch-log's prompt.  That will immediately show
me all the commits the person was talking about, with easy access to
view both the diffs and the log messages.  The alternative is to figure
out the remote branch the commits are on, log that, and then find the
commits somewhere down it.  That's much more fiddly, because Git doesn't
make working with remote branches easy (and I don't want to create a
local branch just for this read-only operation).

>> This is the most important point.  The idea is that the outstanding
>> changes on a feature branch can be thought of as "the feature branch
>> diff" or "the feature branch log".  So if you use those commands a lot,
>> the 'b L' and 'b D' have "branch log" and "branch diff" as mnemonics.
>
> But outstanding changes happen on non-feature branches as well.  It is
> IMO confusing to treat feature branches differently in this regard.
> Whether the current branch is a feature branch or anything else
> (including master) is entirely in my head; VC commands apply to any
> kind of branch, and the backend has no idea what will be the use of
> the branch I'm on.  E.g., I could be working on master implementing
> some feature, and during that work treat master as a kind-of feature
> branch, delaying updating from upstream until I'm done.

Yes, that's right, and indeed over in #80006 one of the goals is to make
sure the commands work well on non-feature branches too.

>> - Do the changes to 'C-x v b' discussed in the other thread.
>
> Please point to the thread, as I don't have a clear idea what changes
> do you allude to here.

Yes, I should have linked to it again:
<https://lists.gnu.org/archive/html/emacs-devel/2025-12/msg00394.html>

>> - Add a feature to 'C-u C-x v l' where if the revision ID specified does
>>   not appear in the log (because it's on another branch), try to print a
>>   log of a branch containing that revision ID, or fall back to printing
>>   a log starting at that revision ID.
>
> This is problematic, IMO.  A revision could be absent because the user
> simply mistyped it.  Also, if there are many branches in the
> repository, looking for the right branch could be slow.  Finally, and
> most importantly, you assume that revision IDs are absolute, i.e. not
> local to the branch.  This is false for Bazaar at least, and might be
> wrong in other cases as well.

Hrm, all good points.  I'll leave this aside until I can think of a
better design for it, then.

>> - Bind all the new outstanding change commands under 'C-x v B'.
>
> Why not "C-x v o"?

The "B" was meant to be mnemonic for "base" because the outstanding
changes are determined by comparison with a base commit which is often a
merge base.

Using "o" for "outstanding" instead is worth considering.

My first thought would be that the notions of outstanding and outgoing
changes are similar but not the same, and so someone might easily mix up
'C-x v o' and 'C-x v O'.

But maybe most people will use only one of these two sets of commands
most of the time, so it would be okay?  WDYT?

> I'd prefer to have all of this discussion on emacs-devel, as I expect
> us to have some difficulty to distinguish between parts of this that
> are simple enough to be kept on the bug tracker.  People who read and
> participate in the emacs-devel discussion should have the full picture
> at their disposal.

Okay.  How do you think it would be best to move the discussion?
I could post a summary, or just a pointer back to this bug.

-- 
Sean Whitton

Message #23 received at 80037 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: dmitry <at> gutov.dev, 80037 <at> debbugs.gnu.org, sbaugh <at> janestreet.com,
 juri <at> linkov.net
Subject: Re: bug#80037: 31.0.50; Improving 'C-u C-x v l/L' and merging 'C-x
 v B' into 'C-x v b'
Date: Sat, 20 Dec 2025 16:54:36 +0200

> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Cc: dmitry <at> gutov.dev,  juri <at> linkov.net,  sbaugh <at> janestreet.com,
>   80037 <at> debbugs.gnu.org
> Date: Sat, 20 Dec 2025 12:36:57 +0000
> 
> On Sat 20 Dec 2025 at 02:00pm +02, Eli Zaretskii wrote:
> 
> > When/why do you need to see a log that starts from some non-HEAD
> > revision?
> 
> This happen for me with Git repositories where there are commits on some
> remote branch but not on any of my local branches.  Someone in an e-mail
> or web forum discussion posts the commit IDs of a series of commits
> fixing a bug on some branch somewhere.

And those commits are not at or near HEAD of that branch?

If so, this is quite a specialized situation, and I cannot imagine it
to happen frequently.  How about making "C-x v b l" allow a prefix
argument, which will let you specify a revision?  Then the command
could work similar to "C-x v L".  We could also modify "C-x v L" such
that if the prefix is -1, it will ask for REVISION, but display the
log _starting_ at that REVISION, not just of that REVISION.  And the
prefix argument of "C-x v b l" could behave the same.  Or maybe we
could have "C-x v b L" doing that.

So there's more than one way of satisfying that need without breaking
any previous behavior.

> I do a git fetch, copy the
> commit ID of the last revision in the series from the mail or web page,
> and yank it to vc-git-branch-log's prompt.  That will immediately show
> me all the commits the person was talking about, with easy access to
> view both the diffs and the log messages.  The alternative is to figure
> out the remote branch the commits are on, log that, and then find the
> commits somewhere down it.

With my suggestions above, you'd need to know the branch, yes, but
otherwise it's not fiddly IMO.  And one needs to know the branch
anyway, when working with changes from another branch.

> That's much more fiddly, because Git doesn't
> make working with remote branches easy (and I don't want to create a
> local branch just for this read-only operation).

Once you did a "git fetch", the stuff is already in your clone, so
what do you mean by "don't want to create a local branch"?

> >> - Do the changes to 'C-x v b' discussed in the other thread.
> >
> > Please point to the thread, as I don't have a clear idea what changes
> > do you allude to here.
> 
> Yes, I should have linked to it again:
> <https://lists.gnu.org/archive/html/emacs-devel/2025-12/msg00394.html>

If you mean moving "C-x v b l" to "C-x v b L", then I think it's okay.

> >> - Bind all the new outstanding change commands under 'C-x v B'.
> >
> > Why not "C-x v o"?
> 
> The "B" was meant to be mnemonic for "base" because the outstanding
> changes are determined by comparison with a base commit which is often a
> merge base.
> 
> Using "o" for "outstanding" instead is worth considering.
> 
> My first thought would be that the notions of outstanding and outgoing
> changes are similar but not the same, and so someone might easily mix up
> 'C-x v o' and 'C-x v O'.
> 
> But maybe most people will use only one of these two sets of commands
> most of the time, so it would be okay?  WDYT?

We trust people not to mix "C-x v l" with "C-x v L", so why not trust
them not tro confuse "o" with "O"?

> > I'd prefer to have all of this discussion on emacs-devel, as I expect
> > us to have some difficulty to distinguish between parts of this that
> > are simple enough to be kept on the bug tracker.  People who read and
> > participate in the emacs-devel discussion should have the full picture
> > at their disposal.
> 
> Okay.  How do you think it would be best to move the discussion?
> I could post a summary, or just a pointer back to this bug.

A pointer should be enough, IMO.

Thanks.

Message #26 received at 80037 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: dmitry <at> gutov.dev, juri <at> linkov.net, sbaugh <at> janestreet.com,
 80037 <at> debbugs.gnu.org
Subject: Re: bug#80037: 31.0.50; Improving 'C-u C-x v l/L' and merging 'C-x
 v B' into 'C-x v b'
Date: Sat, 20 Dec 2025 15:23:00 +0000

Hello,

On Sat 20 Dec 2025 at 04:54pm +02, Eli Zaretskii wrote:

> And those commits are not at or near HEAD of that branch?

Often they are not, because I'm trying to extract them to backport them
to an older release.

> How about making "C-x v b l" allow a prefix argument, which will let
> you specify a revision?
> [...]
> We could also modify "C-x v L" such that if the prefix is -1, it will
> ask for REVISION, but display the log _starting_ at that REVISION, not
> just of that REVISION.  And the prefix argument of "C-x v b l" could
> behave the same.  Or maybe we could have "C-x v b L" doing that.
>
> So there's more than one way of satisfying that need without breaking
> any previous behavior.

Thanks for reminding me that we could use a negative prefix argument to
have one of these special meanings.

I believe, though, that if we are going to retain a global binding for
the current behavior of vc-print-branch-log ('C-x v b L', in accordance
with the other thread), then there is no need to add anything else,
because vc-print-branch-log already satisfies the need of logging
branches or printing logs starting at arbitrary revisions.

> With my suggestions above, you'd need to know the branch, yes, but
> otherwise it's not fiddly IMO.  And one needs to know the branch
> anyway, when working with changes from another branch.

No, you don't need to.  You can cherry-pick them by revision ID.

>> That's much more fiddly, because Git doesn't
>> make working with remote branches easy (and I don't want to create a
>> local branch just for this read-only operation).
>
> Once you did a "git fetch", the stuff is already in your clone, so
> what do you mean by "don't want to create a local branch"?

I don't want to create a local branch tracking the remote branch because
I don't in general care about that remote branch.  It may be one of tens
of branches that upstream have hanging around, that are irrelevant to
me.

I only create local branches where I intend to make and push new commits
on that branch.  I think that's the usual way to use Git branches.
For example, I assume you don't have a local branch right now tracking
remotes/origin/scratch/tzz/auth-source-reveal-mode that we have on
Savannah (to pick a random example).
You only have a remote-tracking branch for that.

> We trust people not to mix "C-x v l" with "C-x v L", so why not trust
> them not tro confuse "o" with "O"?

Hmm, yes, good point.  So that should be okay.

So if we don't see any counterarguments, I'll plan to move the existing
'C-x v B' commands under 'C-x v o'.  Thanks again for the idea.

> A pointer should be enough, IMO.

Thanks, done that.

-- 
Sean Whitton

Message #29 received at 80037 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Sean Whitton <spwhitton <at> spwhitton.name>
Cc: dmitry <at> gutov.dev, juri <at> linkov.net, sbaugh <at> janestreet.com,
 80037 <at> debbugs.gnu.org
Subject: Re: bug#80037: 31.0.50; Improving 'C-u C-x v l/L' and merging 'C-x
 v B' into 'C-x v b'
Date: Sat, 20 Dec 2025 17:47:57 +0200

> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Cc: dmitry <at> gutov.dev,  80037 <at> debbugs.gnu.org,  sbaugh <at> janestreet.com,
>   juri <at> linkov.net
> Date: Sat, 20 Dec 2025 15:23:00 +0000
> 
> > With my suggestions above, you'd need to know the branch, yes, but
> > otherwise it's not fiddly IMO.  And one needs to know the branch
> > anyway, when working with changes from another branch.
> 
> No, you don't need to.  You can cherry-pick them by revision ID.

Sure, but in practice, how many times did you do that without knowing
the name of the branch?

> > Once you did a "git fetch", the stuff is already in your clone, so
> > what do you mean by "don't want to create a local branch"?
> 
> I don't want to create a local branch tracking the remote branch because
> I don't in general care about that remote branch.  It may be one of tens
> of branches that upstream have hanging around, that are irrelevant to
> me.

Once again, if we are talking about Git, doing "git fetch" already
brings the branch down to your clone, doesn't it?  A branch is just a
pointer in Git, as you well know, so "creating a remote branch" is
basically a no-op, once the objects are in your clone.

Message #32 received at 80037 <at> debbugs.gnu.org (full text, mbox):

From: Sean Whitton <spwhitton <at> spwhitton.name>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: dmitry <at> gutov.dev, 80037 <at> debbugs.gnu.org, sbaugh <at> janestreet.com,
 juri <at> linkov.net
Subject: Re: bug#80037: 31.0.50; Improving 'C-u C-x v l/L' and merging 'C-x
 v B' into 'C-x v b'
Date: Sun, 21 Dec 2025 17:58:13 +0000

Hello,

On Sat 20 Dec 2025 at 05:47pm +02, Eli Zaretskii wrote:

>> From: Sean Whitton <spwhitton <at> spwhitton.name>
>> Cc: dmitry <at> gutov.dev,  80037 <at> debbugs.gnu.org,  sbaugh <at> janestreet.com,
>>   juri <at> linkov.net
>> Date: Sat, 20 Dec 2025 15:23:00 +0000
>>
>> > With my suggestions above, you'd need to know the branch, yes, but
>> > otherwise it's not fiddly IMO.  And one needs to know the branch
>> > anyway, when working with changes from another branch.
>>
>> No, you don't need to.  You can cherry-pick them by revision ID.
>
> Sure, but in practice, how many times did you do that without knowing
> the name of the branch?
>
>> > Once you did a "git fetch", the stuff is already in your clone, so
>> > what do you mean by "don't want to create a local branch"?
>>
>> I don't want to create a local branch tracking the remote branch because
>> I don't in general care about that remote branch.  It may be one of tens
>> of branches that upstream have hanging around, that are irrelevant to
>> me.
>
> Once again, if we are talking about Git, doing "git fetch" already
> brings the branch down to your clone, doesn't it?  A branch is just a
> pointer in Git, as you well know, so "creating a remote branch" is
> basically a no-op, once the objects are in your clone.

My experience with this has been that while the remote branch name is
accessible to me if I want to hunt through the web interface, and as you
say a 'git fetch' is enough to create it, revision IDs are much more
immediately available.

Therefore, I am glad that we have vc-print-branch-log and that it works
for revision IDs, too.

-- 
Sean Whitton

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.