GNU bug report logs -
#62940
29.0.60; vc: no easy way to get diff of all outgoing changes
Previous Next
Reported by: Spencer Baugh <sbaugh <at> janestreet.com>
Date: Tue, 18 Apr 2023 19:13:02 UTC
Severity: wishlist
Found in version 29.0.60
Done: Sean Whitton <spwhitton <at> spwhitton.name>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 62940 in the body.
You can then email your comments to 62940 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 18 Apr 2023 19:13:02 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Spencer Baugh <sbaugh <at> janestreet.com>:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org.
(Tue, 18 Apr 2023 19:13:02 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
Reproduction:
1. Make some local changes and commits
2. C-x v O to see the list of local commits that will be pushed
3. But there's no quick way to get a diff combining all those changes,
which is useful if you've made multiple changes to the same function
over the course of multiple commits, or if you want to review your
changes overall before sending them out for review, or any other things
like that.
C-u C-x v = lets you specify two commits to diff, and the second commit
even defaults to the working revision, but there's no easy way to get
the "base" commit that is before all your local changes. If you're
using git, you can try to remember your upstream branch and type that
in, but that's just a matter of memory. For other VCSs (e.g. hg)
there's no easy way.
I'm working on adding an easy way to do this in vc, but there are
several ways to approach it and I wanted to check first.
A. (my preferred way) Support a M-1 prefix argument for C-x v =, which
will do a diff against the "base" revision, whatever that is.
B. Add a new keybinding in vc-read-revision which will insert the "base"
revision, so you can just use C-u C-x v = and then insert the base
revision at the first prompt. Seems hard to make compatible with
non-default completion frameworks.
C. Add new equivalents to C-x v = and C-x v D which diff against the
base revision. Seems like ugly duplication of keybindings.
D. Make some way to go from a log-view like C-x v O to a diff which
combines all those commits. Could be nice, but seems a little
unintuitive, and also doesn't support including uncommitted changes in
the diff.
Thoughts, suggestions?
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 18 Apr 2023 20:37:01 GMT)
Full text and
rfc822 format available.
Message #8 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 18/04/2023 15:12 -0400, Spencer Baugh wrote:
> Reproduction:
> 1. Make some local changes and commits
> 2. C-x v O to see the list of local commits that will be pushed
> 3. But there's no quick way to get a diff combining all those changes,
> which is useful if you've made multiple changes to the same function
> over the course of multiple commits, or if you want to review your
> changes overall before sending them out for review, or any other things
> like that.
>
> C-u C-x v = lets you specify two commits to diff, and the second commit
> even defaults to the working revision, but there's no easy way to get
> the "base" commit that is before all your local changes. If you're
> using git, you can try to remember your upstream branch and type that
> in, but that's just a matter of memory. For other VCSs (e.g. hg)
> there's no easy way.
>
[...]
> Thoughts, suggestions?
Usually I just do C-x v L, select commits that interest me (via region),
and do M-x log-view-diff.
Have you tried that? What do you miss there?
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 18 Apr 2023 20:45:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 18/04/2023 23:36, Filipp Gunbin wrote:
> Usually I just do C-x v L, select commits that interest me (via region),
> and do M-x log-view-diff.
Just in case: 'log-view-diff' is bound to '='.
That's what I wanted to suggest, too. Or use 'vc-log-outgoing':
C-x v O C-x h =
Which would be D. in the original message. It doesn't support
uncommitted changes, but I would be surprised if it did.
But one can also try this:
C-u C-x v D origin/master ^J
Where origin/master is the name of the upstream branch ref. This should
include uncommitted changes.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 18 Apr 2023 22:01:02 GMT)
Full text and
rfc822 format available.
Message #14 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Filipp Gunbin <fgunbin <at> fastmail.fm> writes:
> Usually I just do C-x v L, select commits that interest me (via region),
> and do M-x log-view-diff.
>
> Have you tried that? What do you miss there?
Wow, amazing, I did not think to try that! After some further
improvements to my vc backend, that is perfect!
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 19 Apr 2023 06:52:01 GMT)
Full text and
rfc822 format available.
Message #17 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> C-x v O C-x h =
>
> Which would be D. in the original message. It doesn't support uncommitted
> changes, but I would be surprised if it did.
It's supported only for vc that inserts a text header in logs like RCS.
I proposed to insert extra line that represents uncommitted git changes,
and I'm using this feature all the time. But the problem is that
it's inserted even when 'C-x v b l' lists another branch
where such line makes no sense.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 21 Apr 2023 18:37:02 GMT)
Full text and
rfc822 format available.
Message #20 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Spencer Baugh <sbaugh <at> janestreet.com> writes:
> Filipp Gunbin <fgunbin <at> fastmail.fm> writes:
>> Usually I just do C-x v L, select commits that interest me (via region),
>> and do M-x log-view-diff.
>>
>> Have you tried that? What do you miss there?
>
> Wow, amazing, I did not think to try that! After some further
> improvements to my vc backend, that is perfect!
After using it for a bit, one issue is that C-x v O shows changes in all
files; it would be nice if there was a way to get outgoing
changes/commits only for the current fileset.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sat, 22 Apr 2023 06:58:01 GMT)
Full text and
rfc822 format available.
Message #23 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> Cc: 62940 <at> debbugs.gnu.org, Filipp Gunbin <fgunbin <at> fastmail.fm>
> From: sbaugh <at> catern.com
> Date: Fri, 21 Apr 2023 18:36:01 +0000 (UTC)
>
> After using it for a bit, one issue is that C-x v O shows changes in all
> files; it would be nice if there was a way to get outgoing
> changes/commits only for the current fileset.
What is the current fileset for "C-x v O"? isn't that "all files"
anyway?
I could understand if you were talking about a VC command invoked from
a vc-dir buffer or a Dired buffer, where you can mark files to be
considered as the current fileset. That would mean your comment is
about the vc-dir command 'O' or the equivalent in Dired. But
otherwise, I'm not sure I understand the UI you have in mind.
And then there's the issue of whether the backend supports what you
want, of course.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sat, 22 Apr 2023 13:01:02 GMT)
Full text and
rfc822 format available.
Message #26 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Eli Zaretskii <eliz <at> gnu.org> writes:
>> Cc: 62940 <at> debbugs.gnu.org, Filipp Gunbin <fgunbin <at> fastmail.fm>
>> From: sbaugh <at> catern.com
>> Date: Fri, 21 Apr 2023 18:36:01 +0000 (UTC)
>>
>> After using it for a bit, one issue is that C-x v O shows changes in all
>> files; it would be nice if there was a way to get outgoing
>> changes/commits only for the current fileset.
>
> What is the current fileset for "C-x v O"? isn't that "all files"
> anyway?
Well, yes, that's the issue. When my current fileset is not "all files"
(for example when I am in an individual file without marking files in a
vc-dir buffer) I would like to be able to see outgoing changes on just
those files. C-x v O overrides the fileset to be "all files" instead.
> I could understand if you were talking about a VC command invoked from
> a vc-dir buffer or a Dired buffer, where you can mark files to be
> considered as the current fileset. That would mean your comment is
> about the vc-dir command 'O' or the equivalent in Dired. But
> otherwise, I'm not sure I understand the UI you have in mind.
1. View a file buffer
2. Hit C-x v O
3. See outgoing changes only for that file
> And then there's the issue of whether the backend supports what you
> want, of course.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sat, 22 Apr 2023 13:18:02 GMT)
Full text and
rfc822 format available.
Message #29 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> From: sbaugh <at> catern.com
> Date: Sat, 22 Apr 2023 13:00:48 +0000 (UTC)
> Cc: sbaugh <at> janestreet.com, 62940 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
>
> 1. View a file buffer
> 2. Hit C-x v O
> 3. See outgoing changes only for that file
I don't think it is TRT to change the behavior of "C-x v O" in the
above scenario. Because it will make it much harder to see the
changes for all the files, since in Emacs you are almost always "in
some file-visiting buffer".
So the above can only be optional behavior, not the default.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sat, 22 Apr 2023 18:34:02 GMT)
Full text and
rfc822 format available.
Message #32 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 22/04/2023 16:17, Eli Zaretskii wrote:
>> From:sbaugh <at> catern.com
>> Date: Sat, 22 Apr 2023 13:00:48 +0000 (UTC)
>> Cc:sbaugh <at> janestreet.com,62940 <at> debbugs.gnu.org,fgunbin <at> fastmail.fm
>>
>> 1. View a file buffer
>> 2. Hit C-x v O
>> 3. See outgoing changes only for that file
> I don't think it is TRT to change the behavior of "C-x v O" in the
> above scenario. Because it will make it much harder to see the
> changes for all the files, since in Emacs you are almost always "in
> some file-visiting buffer".
>
> So the above can only be optional behavior, not the default.
>
>
>
We could add a couple of new commands, with -fileset- in their names.
Couple - for incoming and outgoing.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sat, 22 Apr 2023 19:28:02 GMT)
Full text and
rfc822 format available.
Message #35 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> Date: Sat, 22 Apr 2023 21:33:35 +0300
> Cc: sbaugh <at> janestreet.com, 62940 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
> From: Dmitry Gutov <dmitry <at> gutov.dev>
>
> On 22/04/2023 16:17, Eli Zaretskii wrote:
> > I don't think it is TRT to change the behavior of "C-x v O" in the
> > above scenario. Because it will make it much harder to see the
> > changes for all the files, since in Emacs you are almost always "in
> > some file-visiting buffer".
> >
> > So the above can only be optional behavior, not the default.
>
> We could add a couple of new commands, with -fileset- in their names.
> Couple - for incoming and outgoing.
That would work, of course.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Mon, 14 Aug 2023 19:43:02 GMT)
Full text and
rfc822 format available.
Message #38 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Juri Linkov <juri <at> linkov.net> writes:
>> C-x v O C-x h =
>>
>> Which would be D. in the original message. It doesn't support uncommitted
>> changes, but I would be surprised if it did.
>
> It's supported only for vc that inserts a text header in logs like RCS.
> I proposed to insert extra line that represents uncommitted git changes,
> and I'm using this feature all the time.
Is your patch for this available somewhere? I find myself wanting the
same thing for hg.
> But the problem is that it's inserted even when 'C-x v b l' lists
> another branch where such line makes no sense.
Maybe we could only insert this line if there are actually uncommitted
changes?
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 16 Aug 2023 07:53:02 GMT)
Full text and
rfc822 format available.
Message #41 received at 62940 <at> debbugs.gnu.org (full text, mbox):
>>> C-x v O C-x h =
>>>
>>> Which would be D. in the original message. It doesn't support uncommitted
>>> changes, but I would be surprised if it did.
>>
>> It's supported only for vc that inserts a text header in logs like RCS.
>> I proposed to insert extra line that represents uncommitted git changes,
>> and I'm using this feature all the time.
>
> Is your patch for this available somewhere? I find myself wanting the
> same thing for hg.
Searching the right version in the archives would take much time,
so it's easier just to send the version that I use every day.
Here it is, just 3 new lines:
diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el
index a7763360795..37dc619da5e 100644
--- a/lisp/vc/vc-git.el
+++ b/lisp/vc/vc-git.el
@@ -1419,6 +1419,9 @@ vc-git-print-log
;; read-only.
(let ((inhibit-read-only t))
(with-current-buffer buffer
+ (when (memq vc-log-view-type '(long short))
+ (insert (propertize "(Type 'd' here to show diffs with working version)\n"
+ 'font-lock-face 'shadow)))
(apply #'vc-git-command buffer
'async files
(append
>> But the problem is that it's inserted even when 'C-x v b l' lists
>> another branch where such line makes no sense.
>
> Maybe we could only insert this line if there are actually uncommitted
> changes?
Good idea. Also this line should not be shown in the output of
'vc-print-branch-log'.
PS: Sorry that answering your other requests about the project features
will take a little more time.
Severity set to 'wishlist' from 'normal'
Request was from
Stefan Kangas <stefankangas <at> gmail.com>
to
control <at> debbugs.gnu.org.
(Mon, 11 Sep 2023 23:19:01 GMT)
Full text and
rfc822 format available.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 13 Sep 2024 20:55:01 GMT)
Full text and
rfc822 format available.
Message #46 received at 62940 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Dmitry Gutov <dmitry <at> gutov.dev> writes:
> On 18/04/2023 23:36, Filipp Gunbin wrote:
>> Usually I just do C-x v L, select commits that interest me (via region),
>> and do M-x log-view-diff.
>
> Just in case: 'log-view-diff' is bound to '='.
>
> That's what I wanted to suggest, too. Or use 'vc-log-outgoing':
>
> C-x v O C-x h =
>
> Which would be D. in the original message. It doesn't support
> uncommitted changes, but I would be surprised if it did.
>
> But one can also try this:
>
> C-u C-x v D origin/master ^J
>
> Where origin/master is the name of the upstream branch ref. This
> should include uncommitted changes.
This works great, but is a bit tricky to use because you need to type
the upstream branch ref. I think it would be good to provide that as an
additional default in the prompt for the old revision. The attached
patch does that. (and probably is enough to close this bug)
[0001-Add-a-last-pushed-revision-default-in-the-vc-diff-pr.patch (text/x-patch, inline)]
From 0a48d2973363361211c2e91c4f6c7bb75f16a853 Mon Sep 17 00:00:00 2001
From: Spencer Baugh <sbaugh <at> janestreet.com>
Date: Fri, 13 Sep 2024 16:35:19 -0400
Subject: [PATCH] Add a "last pushed revision" default in the vc-diff prompt
C-u M-x vc-root-diff will prompt for the old revision to use for the
diff. It includes the current working revision as a default.
Now it also includes the last pushed revision as a default, through a
new pushed-revision vc backend function.
* lisp/vc/vc-git.el (vc-git-pushed-revision): Add.
(vc-git-log-outgoing): Use vc-git-pushed-revision.
* lisp/vc/vc-hg.el (vc-hg-pushed-revision): Add.
* lisp/vc/vc.el (vc-default-pushed-revision): Add new backend function
with default implementation returning nil.
(vc-diff-build-argument-list-internal): Add the last pushed revision
as a default. (bug#62940)
---
lisp/vc/vc-git.el | 10 +++++++---
lisp/vc/vc-hg.el | 6 ++++++
lisp/vc/vc.el | 7 +++++++
3 files changed, 20 insertions(+), 3 deletions(-)
diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el
index 2a7c8ae5fc4..4afbb978a3f 100644
--- a/lisp/vc/vc-git.el
+++ b/lisp/vc/vc-git.el
@@ -1512,6 +1512,12 @@ vc-git-print-log
(list "-p"))
'("--")))))))
+(defun vc-git-pushed-revision (_file &optional remote-location)
+ "Return the ref for REMOTE-LOCATION."
+ (if (and remote-location (not (string-empty-p remote-location)))
+ remote-location
+ "@{upstream}"))
+
(defun vc-git-log-outgoing (buffer remote-location)
(vc-setup-buffer buffer)
(apply #'vc-git-command buffer 'async nil
@@ -1520,9 +1526,7 @@ vc-git-log-outgoing
,(format "--pretty=tformat:%s" (car vc-git-root-log-format))
"--abbrev-commit"
,@(ensure-list vc-git-shortlog-switches)
- ,(concat (if (string= remote-location "")
- "@{upstream}"
- remote-location)
+ ,(concat (vc-git-pushed-revision nil remote-location)
"..HEAD"))))
(defun vc-git-log-incoming (buffer remote-location)
diff --git a/lisp/vc/vc-hg.el b/lisp/vc/vc-hg.el
index 876d86dc24f..c0afb225871 100644
--- a/lisp/vc/vc-hg.el
+++ b/lisp/vc/vc-hg.el
@@ -1422,6 +1422,12 @@ vc-hg-log-incoming
(vc-hg-command buffer 1 nil "incoming" "-n" (unless (string= remote-location "")
remote-location)))
+(defun vc-hg-pushed-revision (_file &optional remote-location)
+ "Return a revspec for the last commit not outgoing to REMOTE-LOCATION."
+ (unless remote-location
+ (setq remote-location ""))
+ (format "last(. and not outgoing(%s))" remote-location))
+
(defun vc-hg-log-outgoing (buffer remote-location)
(vc-setup-buffer buffer)
(vc-hg-command buffer 1 nil "outgoing" "-n" (unless (string= remote-location "")
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index 597a1622f5a..0125924cc51 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -2061,6 +2061,11 @@ vc-read-multiple-revisions
INITIAL-INPUT are passed on to `vc-read-revision' directly."
(vc-read-revision prompt files backend default initial-input t))
+(defun vc-default-pushed-revision (_file &optional _remote-location)
+ "Return the last pushed revision of FILE.
+The default is to return nil always."
+ nil)
+
(defun vc-diff-build-argument-list-internal (&optional fileset)
"Build argument list for calling internal diff functions."
(let* ((vc-fileset (or fileset (vc-deduce-fileset t))) ;FIXME: why t? --Stef
@@ -2069,6 +2074,8 @@ vc-diff-build-argument-list-internal
(first (car files))
(rev1-default nil)
) ;; (rev2-default nil)
+ (when-let ((pushed-revision (vc-call-backend backend 'pushed-revision first)))
+ (push pushed-revision rev1-default))
(cond
;; someday we may be able to do revision completion on non-singleton
;; filesets, but not yet.
--
2.39.3
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sat, 14 Sep 2024 02:13:01 GMT)
Full text and
rfc822 format available.
Message #49 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hi!
On 13/09/2024 23:54, Spencer Baugh wrote:
> This works great, but is a bit tricky to use because you need to type
> the upstream branch ref. I think it would be good to provide that as an
> additional default in the prompt for the old revision. The attached
> patch does that. (and probably is enough to close this bug)C-u M-x vc-root-diff will prompt for the old revision to use for the
> diff. It includes the current working revision as a default.
I like the idea. See comments below.
> Now it also includes the last pushed revision as a default, through a
> new pushed-revision vc backend function.* lisp/vc/vc-git.el (vc-git-pushed-revision): Add.
> (vc-git-log-outgoing): Use vc-git-pushed-revision.
> * lisp/vc/vc-hg.el (vc-hg-pushed-revision): Add.
> * lisp/vc/vc.el (vc-default-pushed-revision): Add new backend function
> with default implementation returning nil.
Am I too used to Git, or should this be called upstream-revision or
origin-revision?
The user might have just recently cloned the repository and not pushed
anything yet. Anyway, matter of taste.
(defun vc-hg-pushed-revision (_file &optional remote-location)
> + "Return a revspec for the last commit not outgoing to REMOTE-LOCATION."
> + (unless remote-location
> + (setq remote-location ""))
> + (format "last(. and not outgoing(%s))" remote-location))
Is the second argument even non-nil in the Hg implementation?
(defun vc-diff-build-argument-list-internal (&optional fileset)
> "Build argument list for calling internal diff functions."
> (let* ((vc-fileset (or fileset (vc-deduce-fileset t))) ;FIXME: why t? --Stef
> @@ -2069,6 +2074,8 @@ vc-diff-build-argument-list-internal
> (first (car files))
> (rev1-default nil)
> ) ;; (rev2-default nil)
> + (when-let ((pushed-revision (vc-call-backend backend 'pushed-revision first)))
> + (push pushed-revision rev1-default))
Maybe we would prefer to keep the current suggestion as the first
default, and have the upstream as the second suggestion (on M-n)? For
backward compatibility anyway. I'm not 100% sure - the upstream ref
seems like a more useful default in a lot of cases (and harder to type
out when you do want it), but it's also workflow-specific.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sat, 14 Sep 2024 07:13:01 GMT)
Full text and
rfc822 format available.
Message #52 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> Cc: 62940 <at> debbugs.gnu.org, Filipp Gunbin <fgunbin <at> fastmail.fm>
> Date: Sat, 14 Sep 2024 05:11:48 +0300
> From: Dmitry Gutov <dmitry <at> gutov.dev>
>
> > (vc-git-log-outgoing): Use vc-git-pushed-revision.
> > * lisp/vc/vc-hg.el (vc-hg-pushed-revision): Add.
> > * lisp/vc/vc.el (vc-default-pushed-revision): Add new backend function
> > with default implementation returning nil.
>
> Am I too used to Git, or should this be called upstream-revision or
> origin-revision?
upstream-revision is definitely better than
vc-default-pushed-revision, since some VCSes don't even have the
"push" operation.
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.
> Maybe we would prefer to keep the current suggestion as the first
> default, and have the upstream as the second suggestion (on M-n)? For
> backward compatibility anyway.
Sounds like a good idea to me.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Thu, 10 Oct 2024 00:27:01 GMT)
Full text and
rfc822 format available.
Message #55 received at 62940 <at> debbugs.gnu.org (full text, mbox):
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
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Thu, 10 Oct 2024 05:29:02 GMT)
Full text and
rfc822 format available.
Message #58 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> Date: Thu, 10 Oct 2024 03:26:23 +0300
> Cc: sbaugh <at> janestreet.com, 62940 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
> From: Dmitry Gutov <dmitry <at> 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). 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 11 Oct 2024 01:14:02 GMT)
Full text and
rfc822 format available.
Message #61 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 10/10/2024 08:27, Eli Zaretskii wrote:
>> Date: Thu, 10 Oct 2024 03:26:23 +0300
>> Cc: sbaugh <at> janestreet.com, 62940 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
>> From: Dmitry Gutov <dmitry <at> 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
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 11 Oct 2024 01:35:02 GMT)
Full text and
rfc822 format available.
Message #64 received at 62940 <at> debbugs.gnu.org (full text, mbox):
BTW:
On 13/09/2024 23:54, Spencer Baugh wrote:
> +(defun vc-git-pushed-revision (_file &optional remote-location)
> + "Return the ref for REMOTE-LOCATION."
> + (if (and remote-location (not (string-empty-p remote-location)))
> + remote-location
> + "@{upstream}"))
The function above and the function below
+(defun vc-hg-pushed-revision (_file &optional remote-location)
> + "Return a revspec for the last commit not outgoing to REMOTE-LOCATION."
> + (unless remote-location
> + (setq remote-location ""))
> + (format "last(. and not outgoing(%s))" remote-location))
...seem to be describing different kinds of refs: I think the Hg version
refers to the last commit from the current branch that's present in the
remote (the merge base), whereas the Git version points to the tip of
the remote branch.
Which will be different if the remote has some newer changes added
(perhaps someone else has pushed to it). vc-git-log-outgoing won't
notice the difference because it uses the ".." range, but vc-git-diff
compares two versions directly, so e.g. anything new added to the remote
will be shown as removed in such diff.
We probably want "merge base with remote" for Git as well (git
merge-base @{upstream} HEAD), but it doesn't have a similar short ref
syntax.
Could use "merge-base(@{upstream})" or "@{upstream}.." as a special
value, maybe.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 11 Oct 2024 06:08:02 GMT)
Full text and
rfc822 format available.
Message #67 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> Date: Fri, 11 Oct 2024 04:13:24 +0300
> Cc: sbaugh <at> janestreet.com, 62940 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
> From: Dmitry Gutov <dmitry <at> gutov.dev>
>
> Okay, check out this attempt. It might be considered too cluttered.
> Perhaps you will have suggestions for improvement.
This LGTM, thanks. One minor nit:
> +@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
^^^^^^^^^^
"Second" is ambiguous here (because of how the previous sentence
ends), so I suggest to say "The second revision ID" instead to
disambiguate it.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 11 Oct 2024 14:40:02 GMT)
Full text and
rfc822 format available.
Message #70 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 11/10/2024 04:34, Dmitry Gutov wrote:
> BTW:
>
> On 13/09/2024 23:54, Spencer Baugh wrote:
>> +(defun vc-git-pushed-revision (_file &optional remote-location)
>> + "Return the ref for REMOTE-LOCATION."
>> + (if (and remote-location (not (string-empty-p remote-location)))
>> + remote-location
>> + "@{upstream}"))
>
> The function above and the function below
>
> +(defun vc-hg-pushed-revision (_file &optional remote-location)
>> + "Return a revspec for the last commit not outgoing to REMOTE-
>> LOCATION."
>> + (unless remote-location
>> + (setq remote-location ""))
>> + (format "last(. and not outgoing(%s))" remote-location))
>
> ...seem to be describing different kinds of refs: I think the Hg version
> refers to the last commit from the current branch that's present in the
> remote (the merge base), whereas the Git version points to the tip of
> the remote branch.
>
> Which will be different if the remote has some newer changes added
> (perhaps someone else has pushed to it). vc-git-log-outgoing won't
> notice the difference because it uses the ".." range, but vc-git-diff
> compares two versions directly, so e.g. anything new added to the remote
> will be shown as removed in such diff.
>
> We probably want "merge base with remote" for Git as well (git merge-
> base @{upstream} HEAD), but it doesn't have a similar short ref syntax.
>
> Could use "merge-base(@{upstream})" or "@{upstream}.." as a special
> value, maybe.
Or alternatively if we would prefer to err on the side of warning the
user that the upstream has diverged, I suppose it's the Hg
implementation that would need to change. That can result a simpler
mental model and documentation as well. What would be Hg's corresponding
selector for "tip of upstream branch"?
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 11 Oct 2024 14:41:01 GMT)
Full text and
rfc822 format available.
Message #73 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 11/10/2024 09:07, Eli Zaretskii wrote:
>> +@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
> ^^^^^^^^^^
> "Second" is ambiguous here (because of how the previous sentence
> ends), so I suggest to say "The second revision ID" instead to
> disambiguate it.
Okay, that works.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 11 Oct 2024 15:12:02 GMT)
Full text and
rfc822 format available.
Message #76 received at 62940 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
On Fri, Oct 11, 2024, 10:39 AM Dmitry Gutov <dmitry <at> gutov.dev> wrote:
> On 11/10/2024 04:34, Dmitry Gutov wrote:
> > BTW:
> >
> > On 13/09/2024 23:54, Spencer Baugh wrote:
> >> +(defun vc-git-pushed-revision (_file &optional remote-location)
> >> + "Return the ref for REMOTE-LOCATION."
> >> + (if (and remote-location (not (string-empty-p remote-location)))
> >> + remote-location
> >> + "@{upstream}"))
> >
> > The function above and the function below
> >
> > +(defun vc-hg-pushed-revision (_file &optional remote-location)
> >> + "Return a revspec for the last commit not outgoing to REMOTE-
> >> LOCATION."
> >> + (unless remote-location
> >> + (setq remote-location ""))
> >> + (format "last(. and not outgoing(%s))" remote-location))
> >
> > ...seem to be describing different kinds of refs: I think the Hg version
> > refers to the last commit from the current branch that's present in the
> > remote (the merge base), whereas the Git version points to the tip of
> > the remote branch.
> >
> > Which will be different if the remote has some newer changes added
> > (perhaps someone else has pushed to it). vc-git-log-outgoing won't
> > notice the difference because it uses the ".." range, but vc-git-diff
> > compares two versions directly, so e.g. anything new added to the remote
> > will be shown as removed in such diff.
> >
> > We probably want "merge base with remote" for Git as well (git merge-
> > base @{upstream} HEAD), but it doesn't have a similar short ref syntax.
> >
> > Could use "merge-base(@{upstream})" or "@{upstream}.." as a special
> > value, maybe.
>
> Or alternatively if we would prefer to err on the side of warning the
> user that the upstream has diverged, I suppose it's the Hg
> implementation that would need to change. That can result a simpler
> mental model and documentation as well. What would be Hg's corresponding
> selector for "tip of upstream branch"?
>
I'm not sure, I don't think there's no way to specify that with an hg
revset. Though like most hg users, I don't actually use branches, I use
bookmarks; there's a way to do it with bookmarks, I think. I'll investigate.
I think it's useful to think of these two options relative to vc-outgoing
and vc-incoming. Comparing $1 against $2 is equivalent to getting the diff
from $3:
- working-tree merge-base = vc-outgoing
- merge-base remote-tip = vc-incoming
- working-tree remote-tip = vc-outgoing+vc-incoming
The first two are more useful than the third, I think, since the third
mixes together two sorts of diffs, making it ambiguous which is which.
>
[Message part 2 (text/html, inline)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 11 Oct 2024 20:30:02 GMT)
Full text and
rfc822 format available.
Message #79 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 11/10/2024 18:10, Spencer Baugh wrote:
> Or alternatively if we would prefer to err on the side of warning the
> user that the upstream has diverged, I suppose it's the Hg
> implementation that would need to change. That can result a simpler
> mental model and documentation as well. What would be Hg's
> corresponding
> selector for "tip of upstream branch"?
>
>
> I'm not sure, I don't think there's no way to specify that with an hg
> revset. Though like most hg users, I don't actually use branches, I use
> bookmarks; there's a way to do it with bookmarks, I think. I'll investigate.
Thanks. Or if it doesn't make sense for Hg (for example, if the remote
tip will always be present locally too), that would also be good, then
the current implementation is just right.
> I think it's useful to think of these two options relative to vc-
> outgoing and vc-incoming. Comparing $1 against $2 is equivalent to
> getting the diff from $3:
> - working-tree merge-base = vc-outgoing
> - merge-base remote-tip = vc-incoming
> - working-tree remote-tip = vc-outgoing+vc-incoming
>
> The first two are more useful than the third, I think, since the third
> mixes together two sorts of diffs, making it ambiguous which is which.
Makes sense.
I think #2 might be more conveniently accessed from vc-log-incoming
(which is the only way to view the separate commits and messages).
Anyway, it seems instead of vc-root-diff we can use vc-diff-mergebase,
it has the same completion for revisions. With REV1=@{upstream} and
REV2="", we'll get #1, with reverse - #2. The full key sequence:
C-u C-x v M D @{upstream} RET C-j
Note that vc-*-mergebase is only implemented for Git. But
vc-hg-log-incoming is defined -- that seems to indicate that 'mergebase'
would be useful to support for it too.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 11 Oct 2024 22:40:01 GMT)
Full text and
rfc822 format available.
Message #82 received at 62940 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
On 11/10/2024 23:28, Dmitry Gutov wrote:
>
> Anyway, it seems instead of vc-root-diff we can use vc-diff-mergebase,
> it has the same completion for revisions. With REV1=@{upstream} and
> REV2="", we'll get #1, with reverse - #2. The full key sequence:
>
> C-u C-x v M D @{upstream} RET C-j
>
> Note that vc-*-mergebase is only implemented for Git. But vc-hg-log-
> incoming is defined -- that seems to indicate that 'mergebase' would be
> useful to support for it too.
Here's my current patch.
[vc-upstream-revision.diff (text/x-patch, attachment)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sat, 12 Oct 2024 08:33:02 GMT)
Full text and
rfc822 format available.
Message #85 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> Cc: 62940 <at> debbugs.gnu.org, Filipp Gunbin <fgunbin <at> fastmail.fm>
> Date: Sat, 12 Oct 2024 01:38:38 +0300
> From: Dmitry Gutov <dmitry <at> gutov.dev>
>
> --- 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 revision ID 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,10 @@ 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. The second revision ID defaults to nil, which means
> +the contents of the work tree.
Nitpicking: please use @code{nil} in Texinfo documentation, not a
literal "nil".
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 15 Oct 2024 18:12:02 GMT)
Full text and
rfc822 format available.
Message #88 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Dmitry Gutov <dmitry <at> gutov.dev> writes:
> On 11/10/2024 18:10, Spencer Baugh wrote:
>
>> Or alternatively if we would prefer to err on the side of warning the
>> user that the upstream has diverged, I suppose it's the Hg
>> implementation that would need to change. That can result a simpler
>> mental model and documentation as well. What would be Hg's
>> corresponding
>> selector for "tip of upstream branch"?
>> I'm not sure, I don't think there's no way to specify that with an
>> hg revset. Though like most hg users, I don't actually use
>> branches, I use bookmarks; there's a way to do it with bookmarks, I
>> think. I'll investigate.
>
> Thanks. Or if it doesn't make sense for Hg (for example, if the remote
> tip will always be present locally too), that would also be good, then
> the current implementation is just right.
OK, so I don't see a good way to get "tip of upstream branch" with a
revset in hg. You need to explicitly call "hg incoming" or similar, and
that returns a commit hash. But even so, that doesn't really work with
hg branches, because the incoming commit hash won't actually be present
in the repository... I think.
But, all this is irrelevant. Because, we don't actually care about the
upstream tip on its own: what we actually want is the mergebase of the
upstream tip and the working revision.
We can get that by calling the existing 'mergebase vc method. To do
that, we need some way to specify the upstream tip revision when passing
it to 'mergebase as REV1. (Omitting REV2 seems to just mean "use HEAD
as REV2", which is what we want.) So I see two options:
A. Pass the symbol 'upstream, and have the 'mergebase backends handle it
specially.
B. Add a new 'upstream-tip method; for vc-git this would return
"@{upstream}" and for vc-hg it would return some special sentinel
which vc-hg-mergebase handles.
Thoughts? I'm happy with either of these solutions.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 16 Oct 2024 20:03:02 GMT)
Full text and
rfc822 format available.
Message #91 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 15/10/2024 21:10, Spencer Baugh wrote:
> Dmitry Gutov <dmitry <at> gutov.dev> writes:
>> On 11/10/2024 18:10, Spencer Baugh wrote:
>>
>>> Or alternatively if we would prefer to err on the side of warning the
>>> user that the upstream has diverged, I suppose it's the Hg
>>> implementation that would need to change. That can result a simpler
>>> mental model and documentation as well. What would be Hg's
>>> corresponding
>>> selector for "tip of upstream branch"?
>>> I'm not sure, I don't think there's no way to specify that with an
>>> hg revset. Though like most hg users, I don't actually use
>>> branches, I use bookmarks; there's a way to do it with bookmarks, I
>>> think. I'll investigate.
>>
>> Thanks. Or if it doesn't make sense for Hg (for example, if the remote
>> tip will always be present locally too), that would also be good, then
>> the current implementation is just right.
>
> OK, so I don't see a good way to get "tip of upstream branch" with a
> revset in hg. You need to explicitly call "hg incoming" or similar, and
> that returns a commit hash. But even so, that doesn't really work with
> hg branches, because the incoming commit hash won't actually be present
> in the repository... I think.
I guess the main problem with 'hg incoming' is that it does I/O, and
might take a while - unlike Git's separate step of 'git fetch' which
saved "remote" references to be used by other commands.
> But, all this is irrelevant. Because, we don't actually care about the
> upstream tip on its own: what we actually want is the mergebase of the
> upstream tip and the working revision.
>
> We can get that by calling the existing 'mergebase vc method. To do
> that, we need some way to specify the upstream tip revision when passing
> it to 'mergebase as REV1. (Omitting REV2 seems to just mean "use HEAD
> as REV2", which is what we want.) So I see two options:
>
> A. Pass the symbol 'upstream, and have the 'mergebase backends handle it
> specially.
>
> B. Add a new 'upstream-tip method; for vc-git this would return
> "@{upstream}" and for vc-hg it would return some special sentinel
> which vc-hg-mergebase handles.
>
> Thoughts? I'm happy with either of these solutions.
I think if there is no feasible way to do the same with Hg, we might as
well install a halfway solution for it, which (in your latest proposal)
returns the mergebase already. With a FIXME comment, maybe.
As a result, the core feature will work (the "outgoing" diff), whereas
the "incoming" diff would only be accessible for Git repositories. Also,
with Git, one might need to use vc-log-mergebase when the remote has
diverged.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 16 Oct 2024 20:12:02 GMT)
Full text and
rfc822 format available.
Message #94 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Dmitry Gutov <dmitry <at> gutov.dev> writes:
> On 15/10/2024 21:10, Spencer Baugh wrote:
>> Dmitry Gutov <dmitry <at> gutov.dev> writes:
>>> On 11/10/2024 18:10, Spencer Baugh wrote:
>>>
>>>> Or alternatively if we would prefer to err on the side of warning the
>>>> user that the upstream has diverged, I suppose it's the Hg
>>>> implementation that would need to change. That can result a simpler
>>>> mental model and documentation as well. What would be Hg's
>>>> corresponding
>>>> selector for "tip of upstream branch"?
>>>> I'm not sure, I don't think there's no way to specify that with an
>>>> hg revset. Though like most hg users, I don't actually use
>>>> branches, I use bookmarks; there's a way to do it with bookmarks, I
>>>> think. I'll investigate.
>>>
>>> Thanks. Or if it doesn't make sense for Hg (for example, if the remote
>>> tip will always be present locally too), that would also be good, then
>>> the current implementation is just right.
>> OK, so I don't see a good way to get "tip of upstream branch" with a
>> revset in hg. You need to explicitly call "hg incoming" or similar, and
>> that returns a commit hash. But even so, that doesn't really work with
>> hg branches, because the incoming commit hash won't actually be present
>> in the repository... I think.
>
> I guess the main problem with 'hg incoming' is that it does I/O, and
> might take a while - unlike Git's separate step of 'git fetch' which
> saved "remote" references to be used by other commands.
Right. But note that the Hg revset in my original patch finds what is
effectively the mergebase with upstream, without doing any network IO.
Hg is able to find that mergebase without IO, but actually finding the
upstream tip requires network IO as you said.
>> But, all this is irrelevant. Because, we don't actually care about the
>> upstream tip on its own: what we actually want is the mergebase of the
>> upstream tip and the working revision.
>> We can get that by calling the existing 'mergebase vc method. To do
>> that, we need some way to specify the upstream tip revision when passing
>> it to 'mergebase as REV1. (Omitting REV2 seems to just mean "use HEAD
>> as REV2", which is what we want.) So I see two options:
>> A. Pass the symbol 'upstream, and have the 'mergebase backends
>> handle it
>> specially.
>> B. Add a new 'upstream-tip method; for vc-git this would return
>> "@{upstream}" and for vc-hg it would return some special sentinel
>> which vc-hg-mergebase handles.
>> Thoughts? I'm happy with either of these solutions.
>
> I think if there is no feasible way to do the same with Hg, we might
> as well install a halfway solution for it, which (in your latest
> proposal) returns the mergebase already. With a FIXME comment, maybe.
>
> As a result, the core feature will work (the "outgoing" diff), whereas
> the "incoming" diff would only be accessible for Git
> repositories. Also, with Git, one might need to use vc-log-mergebase
> when the remote has diverged.
Right, that makes sense to me.
Just to be clear, you're suggesting the incoming diff would be
accessible for a Git repository via vc-diff-mergebase, right?
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 16 Oct 2024 23:54:01 GMT)
Full text and
rfc822 format available.
Message #97 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 16/10/2024 23:11, Spencer Baugh wrote:
> Right. But note that the Hg revset in my original patch finds what is
> effectively the mergebase with upstream, without doing any network IO.
Yep. So this is the implementation we can use for now.
>> As a result, the core feature will work (the "outgoing" diff), whereas
>> the "incoming" diff would only be accessible for Git
>> repositories. Also, with Git, one might need to use vc-log-mergebase
>> when the remote has diverged.
>
> Right, that makes sense to me.
>
> Just to be clear, you're suggesting the incoming diff would be
> accessible for a Git repository via vc-diff-mergebase, right?
Right, something like
C-x v B M HEAD RET @{upstream} RET
Actually trying that out brings up the problem that @{upstream} is not
in completions for rev2. We could add it as the next default:
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index a30ba06aec3..2409b4e88a0 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -2068,7 +2073,10 @@ vc-diff-build-argument-list-internal
(backend (car vc-fileset))
(first (car files))
(rev1-default nil)
+ (upstream-revision (vc-call-backend backend 'upstream-revision
first))
) ;; (rev2-default nil)
+ (when upstream-revision
+ (push upstream-revision rev1-default))
(cond
;; someday we may be able to do revision completion on non-singleton
;; filesets, but not yet.
@@ -2087,7 +2095,8 @@ vc-diff-build-argument-list-internal
;; (or rev2-default
"current source"))
(rev1 (vc-read-revision rev1-prompt files backend
rev1-default))
- (rev2 (vc-read-revision rev2-prompt files backend nil))) ;;
rev2-default
+ (rev2 (vc-read-revision rev2-prompt files backend (list ""
+
upstream-revision)))) ;; rev2-default
(when (string= rev1 "") (setq rev1 nil))
(when (string= rev2 "") (setq rev2 nil))
(list files rev1 rev2))))
Or alternatively, we could move both "upstream revision" identifiers to
the revision-completion-table implementations. The result might be a bit
less convenient, but "last ..." and "@{upstream}" will show up in
completions, and after being selected once, will be in the input history
as well. Depending on the frequency of use, that might be okay.
That diffs looks like this:
diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el
index 5a7ffeffc9d..019abfa475c 100644
--- a/lisp/vc/vc-git.el
+++ b/lisp/vc/vc-git.el
@@ -1771,7 +1771,7 @@ vc-git-diff
(defun vc-git-revision-table (_files)
;; What about `files'?!? --Stef
(let (process-file-side-effects
- (table (list "HEAD")))
+ (table (list "HEAD" "@{upstream}")))
(with-temp-buffer
(vc-git-command t nil nil "for-each-ref" "--format=%(refname)")
(goto-char (point-min))
diff --git a/lisp/vc/vc-hg.el b/lisp/vc/vc-hg.el
index 856bea66a6f..90ab47fa6cd 100644
--- a/lisp/vc/vc-hg.el
+++ b/lisp/vc/vc-hg.el
@@ -545,13 +545,15 @@ vc-hg-expanded-log-entry
(buffer-string))))
(defun vc-hg-revision-table (files)
- (let ((default-directory (file-name-directory (car files))))
+ (let ((default-directory (file-name-directory (car files)))
+ (upstream-rev "last(. and not outgoing())"))
(with-temp-buffer
(vc-hg-command t nil nil "branches" "-q")
(vc-hg-command t nil nil "bookmarks" "-q")
(vc-hg-command t nil nil "tags" "-q")
- (split-string
- (buffer-substring-no-properties (point-min) (point-max))))))
+ (cons upstream-rev
+ (split-string
+ (buffer-substring-no-properties (point-min) (point-max)))))))
;; Modeled after the similar function in vc-cvs.el
(defun vc-hg-revision-completion-table (files)
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sun, 11 May 2025 09:33:02 GMT)
Full text and
rfc822 format available.
Message #100 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
On Fri 11 Oct 2024 at 11:10am -04, Spencer Baugh wrote:
> I think it's useful to think of these two options relative to
> vc-outgoing and vc-incoming. Comparing $1 against $2 is equivalent to
> getting the diff from $3:
>
> - working-tree merge-base = vc-outgoing
> - merge-base remote-tip = vc-incoming
> - working-tree remote-tip = vc-outgoing+vc-incoming
>
> The first two are more useful than the third, I think, since the third
> mixes together two sorts of diffs, making it ambiguous which is which.
I agree that the first two are what is most useful. The main use case
for seeing a diff of all outgoing changes is to see a summary of all
your outgoing work, and other people's incoming work isn't usually
relevant to that. When it is relevant, it is so only after pulling and
rebasing or merging.
If that's right, then the notions of "incoming" and "outgoing" are
already well defined by vc-log-outgoing and vc-log-incoming and then I
don't think I follow the motivation for wanting to use the forward
completion mechanism with multiple possible forward completions.
I have a couple of proposals for what to add and change to resolve this
bug:
(1) Add a new vc-log-fileset-outgoing bound to C-x v o. To get a diff
of all outgoing changes, you would use either 'C-x v o C-x h =' or
'C-x v O C-x h ='.
(2) Add these:
C-x v o L -- vc-log-fileset-outgoing
C-x v o D -- vc-diff-fileset-outgoing (equiv to 'C-x v o C-x h =' above)
And a new defcustom which replaces the default C-x v O with these:
C-x v O L -- vc-log-outgoing
C-x v O D -- vc-diff-outgoing (equiv to 'C-x v O C-x h =' above)
I think I prefer option (2). Would be great to hear from others, or if
I've missed something additional that's wanted.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 14 May 2025 22:22:02 GMT)
Full text and
rfc822 format available.
Message #103 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hi Sean,
Thanks for joining the discussion.
On 11/05/2025 12:32, Sean Whitton wrote:
> Hello,
>
> On Fri 11 Oct 2024 at 11:10am -04, Spencer Baugh wrote:
>
>> I think it's useful to think of these two options relative to
>> vc-outgoing and vc-incoming. Comparing $1 against $2 is equivalent to
>> getting the diff from $3:
>>
>> - working-tree merge-base = vc-outgoing
>> - merge-base remote-tip = vc-incoming
>> - working-tree remote-tip = vc-outgoing+vc-incoming
>>
>> The first two are more useful than the third, I think, since the third
>> mixes together two sorts of diffs, making it ambiguous which is which.
>
> I agree that the first two are what is most useful. The main use case
> for seeing a diff of all outgoing changes is to see a summary of all
> your outgoing work, and other people's incoming work isn't usually
> relevant to that. When it is relevant, it is so only after pulling and
> rebasing or merging.
I indeed see less need for the third one, but it might be more useful in
some (?) scenarios and environments where commits are a heavier
operation, and/or one would want to evaluate the full changeset
(compared to the branch's beginning) before making the next commit.
Not sure how often that occurs, though.
> If that's right, then the notions of "incoming" and "outgoing" are
> already well defined by vc-log-outgoing and vc-log-incoming and then I
> don't think I follow the motivation for wanting to use the forward
> completion mechanism with multiple possible forward completions.
It doesn't have to be forward history, but using revision completion
seems like a distinct approach for this problem. And/or being able to
choose revision through the universal prefix.
That can be valuable in that it would augment any command that calls
vc-diff-build-argument-list-internal - including vc-diff-mergebase,
vc-version-diff, vc-log-mergebase, vc-version-ediff.
Again, I don't have specific scenarios in mind, maybe others will
comment with their emphasis.
> I have a couple of proposals for what to add and change to resolve this
> bug:
>
> (1) Add a new vc-log-fileset-outgoing bound to C-x v o. To get a diff
> of all outgoing changes, you would use either 'C-x v o C-x h =' or
> 'C-x v O C-x h ='.
>
> (2) Add these:
> C-x v o L -- vc-log-fileset-outgoing
> C-x v o D -- vc-diff-fileset-outgoing (equiv to 'C-x v o C-x h =' above)
>
> And a new defcustom which replaces the default C-x v O with these:
> C-x v O L -- vc-log-outgoing
> C-x v O D -- vc-diff-outgoing (equiv to 'C-x v O C-x h =' above)
This sounds interesting/useful to me, but we should probably realize
that it amounts to declaring two new submaps - one for incoming and one
for outgoing. Which we would later add new commands to over the years.
> I think I prefer option (2). Would be great to hear from others, or if
> I've missed something additional that's wanted.
To clarify, how do you see the implementation of vc-diff-outgoing? Would
it call the backend action 'log-outgoing' in a background buffer, then
parse the output, call 'previous-revision' with the oldest revision in
the list, and then invoke the diff? That sounds workable but also
somewhat counter to vc's usual approach.
Thinking more about it, the actions 'log-incoming' and 'log-outgoing'
themselves seem more specialized than what we usually want vc backend
actions to be.
They could be re-implemented in terms of 'merge-base' and the currently
proposed 'upstream-revision':
(vc-log-mergebase nil upstream-revision working-revision)
and
(vc-log-mergebase nil working-revision upstream-revision)
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Thu, 15 May 2025 12:58:02 GMT)
Full text and
rfc822 format available.
Message #106 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
On Thu 15 May 2025 at 01:21am +03, Dmitry Gutov wrote:
> I indeed see less need for the third one, but it might be more useful in some
> (?) scenarios and environments where commits are a heavier operation, and/or
> one would want to evaluate the full changeset (compared to the branch's
> beginning) before making the next commit.
>
> Not sure how often that occurs, though.
Right. I think I'd like to see a case where just doing a 'vc-pull'
first is not okay.
>> If that's right, then the notions of "incoming" and "outgoing" are
>> already well defined by vc-log-outgoing and vc-log-incoming and then I
>> don't think I follow the motivation for wanting to use the forward
>> completion mechanism with multiple possible forward completions.
>
> It doesn't have to be forward history, but using revision completion seems
> like a distinct approach for this problem. And/or being able to choose
> revision through the universal prefix.
>
> That can be valuable in that it would augment any command that calls
> vc-diff-build-argument-list-internal - including vc-diff-mergebase,
> vc-version-diff, vc-log-mergebase, vc-version-ediff.
>
> Again, I don't have specific scenarios in mind, maybe others will
> comment with their emphasis.
Right, okay. The flexibility is certainly attractive. I guess I see
the existing -incoming- and -outgoing- commands and there is an obvious
(to me) gap for adding a few additional commands as a simpler solution.
Where stage do you think your thoughts on these virtual revisions are
at? I think I could pretty much go ahead and implement my solution to
this bug now; that is not a reason in itself to go and do it, if you
still want to consider your idea further.
>> I have a couple of proposals for what to add and change to resolve this
>> bug:
>> (1) Add a new vc-log-fileset-outgoing bound to C-x v o. To get a diff
>> of all outgoing changes, you would use either 'C-x v o C-x h =' or
>> 'C-x v O C-x h ='.
>> (2) Add these:
>> C-x v o L -- vc-log-fileset-outgoing
>> C-x v o D -- vc-diff-fileset-outgoing (equiv to 'C-x v o C-x h =' above)
>> And a new defcustom which replaces the default C-x v O with these:
>> C-x v O L -- vc-log-outgoing
>> C-x v O D -- vc-diff-outgoing (equiv to 'C-x v O C-x h =' above)
>
> This sounds interesting/useful to me, but we should probably realize that it
> amounts to declaring two new submaps - one for incoming and one for
> outgoing. Which we would later add new commands to over the years.
We might, yeah, though 'C-x v M' has remained fairly pure.
>> I think I prefer option (2). Would be great to hear from others, or if
>> I've missed something additional that's wanted.
>
> To clarify, how do you see the implementation of vc-diff-outgoing? Would it
> call the backend action 'log-outgoing' in a background buffer, then parse the
> output, call 'previous-revision' with the oldest revision in the list, and
> then invoke the diff? That sounds workable but also somewhat counter to vc's
> usual approach.
I was thinking that the backend would query the remote to find out what
revision to fetch, fetch it, and then diff directly. I.e. there
wouldn't be a need to go via log-outgoing. Perhaps I am missing
something that makes you think it'd have to go via log-outgoing?
> Thinking more about it, the actions 'log-incoming' and 'log-outgoing'
> themselves seem more specialized than what we usually want vc backend actions
> to be.
>
> They could be re-implemented in terms of 'merge-base' and the currently
> proposed 'upstream-revision':
>
> (vc-log-mergebase nil upstream-revision working-revision)
>
> and
>
> (vc-log-mergebase nil working-revision upstream-revision)
Yes, that would be a sensible refactoring.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Thu, 15 May 2025 23:37:02 GMT)
Full text and
rfc822 format available.
Message #109 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 15/05/2025 15:57, Sean Whitton wrote:
> Hello,
>
> On Thu 15 May 2025 at 01:21am +03, Dmitry Gutov wrote:
>
>> I indeed see less need for the third one, but it might be more useful in some
>> (?) scenarios and environments where commits are a heavier operation, and/or
>> one would want to evaluate the full changeset (compared to the branch's
>> beginning) before making the next commit.
>>
>> Not sure how often that occurs, though.
>
> Right. I think I'd like to see a case where just doing a 'vc-pull'
> first is not okay.
Sorry, I was commenting on one thing, but had in mind something
different. Probably the fault of my earlier message which didn't make a
distinction between the working tree and the working revision.
What I was referring to, is the item D. from the original report's
description: being able to make the diff between the last pushed
revision ("upstream revision" or merge-base with it) and the current
state of the working directory, including the uncommitted changes.
IIUC vc-diff-fileset-outgoing wouldn't include those changes, or if it
would, someone would prefer (or like to be able to) making the diff
which doesn't include uncommitted changes.
IOW
git diff origin/HEAD..HEAD
vs
git diff origin/HEAD
>> That can be valuable in that it would augment any command that calls
>> vc-diff-build-argument-list-internal - including vc-diff-mergebase,
>> vc-version-diff, vc-log-mergebase, vc-version-ediff.
>>
>> Again, I don't have specific scenarios in mind, maybe others will
>> comment with their emphasis.
>
> Right, okay. The flexibility is certainly attractive. I guess I see
> the existing -incoming- and -outgoing- commands and there is an obvious
> (to me) gap for adding a few additional commands as a simpler solution.
>
> Where stage do you think your thoughts on these virtual revisions are
> at?
Can't say for sure: a couple of patches I posted implement variants of
this approach, but I'm not clear on whether the UI is good enough to
others' usability. Or big enough an improvement over the current
capability - where one could input the base revision once, and get it
from history later.
> I think I could pretty much go ahead and implement my solution to
> this bug now; that is not a reason in itself to go and do it, if you
> still want to consider your idea further.
Yeah, these approaches don't seem to conflict.
>>> I have a couple of proposals for what to add and change to resolve this
>>> bug:
>>> (1) Add a new vc-log-fileset-outgoing bound to C-x v o. To get a diff
>>> of all outgoing changes, you would use either 'C-x v o C-x h =' or
>>> 'C-x v O C-x h ='.
>>> (2) Add these:
>>> C-x v o L -- vc-log-fileset-outgoing
>>> C-x v o D -- vc-diff-fileset-outgoing (equiv to 'C-x v o C-x h =' above)
>>> And a new defcustom which replaces the default C-x v O with these:
>>> C-x v O L -- vc-log-outgoing
>>> C-x v O D -- vc-diff-outgoing (equiv to 'C-x v O C-x h =' above)
>>
>> This sounds interesting/useful to me, but we should probably realize that it
>> amounts to declaring two new submaps - one for incoming and one for
>> outgoing. Which we would later add new commands to over the years.
>
> We might, yeah, though 'C-x v M' has remained fairly pure.
Fair point. I wonder how many are really aware of this submap, and of
the 'C-x v b' submap as well.
>>> I think I prefer option (2). Would be great to hear from others, or if
>>> I've missed something additional that's wanted.
>>
>> To clarify, how do you see the implementation of vc-diff-outgoing? Would it
>> call the backend action 'log-outgoing' in a background buffer, then parse the
>> output, call 'previous-revision' with the oldest revision in the list, and
>> then invoke the diff? That sounds workable but also somewhat counter to vc's
>> usual approach.
>
> I was thinking that the backend would query the remote to find out what
> revision to fetch, fetch it, and then diff directly. I.e. there
> wouldn't be a need to go via log-outgoing. Perhaps I am missing
> something that makes you think it'd have to go via log-outgoing?
Okay, and to do that we would also need to add a new backend action,
like 'upstream-revision'?
If so, that would be a common ground between several proposals, and thus
a good path forward.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sun, 18 May 2025 11:05:01 GMT)
Full text and
rfc822 format available.
Message #112 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
On Fri 16 May 2025 at 02:36am +03, Dmitry Gutov wrote:
> On 15/05/2025 15:57, Sean Whitton wrote:
>> Hello,
>> On Thu 15 May 2025 at 01:21am +03, Dmitry Gutov wrote:
>>
>>> I indeed see less need for the third one, but it might be more useful in some
>>> (?) scenarios and environments where commits are a heavier operation, and/or
>>> one would want to evaluate the full changeset (compared to the branch's
>>> beginning) before making the next commit.
>>>
>>> Not sure how often that occurs, though.
>> Right. I think I'd like to see a case where just doing a 'vc-pull'
>> first is not okay.
>
> Sorry, I was commenting on one thing, but had in mind something
> different. Probably the fault of my earlier message which didn't make a
> distinction between the working tree and the working revision.
>
> What I was referring to, is the item D. from the original report's
> description: being able to make the diff between the last pushed revision
> ("upstream revision" or merge-base with it) and the current state of the
> working directory, including the uncommitted changes.
Ah, right.
> IIUC vc-diff-fileset-outgoing wouldn't include those changes,
Right.
> or if it would, someone would prefer (or like to be able to) making
> the diff which doesn't include uncommitted changes.
You mean one that *does* include uncommitted changes, right?
> Fair point. I wonder how many are really aware of this submap, and of
> the 'C-x v b' submap as well.
Yeah. Any thoughts on making it more discoverable?
> Okay, and to do that we would also need to add a new backend action, like
> 'upstream-revision'?
>
> If so, that would be a common ground between several proposals, and thus a
> good path forward.
Yes. I'll work on that.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Mon, 19 May 2025 01:50:01 GMT)
Full text and
rfc822 format available.
Message #115 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 18/05/2025 14:04, Sean Whitton wrote:
>> What I was referring to, is the item D. from the original report's
>> description: being able to make the diff between the last pushed revision
>> ("upstream revision" or merge-base with it) and the current state of the
>> working directory, including the uncommitted changes.
>
> Ah, right.
>
>> IIUC vc-diff-fileset-outgoing wouldn't include those changes,
>
> Right.
>
>> or if it would, someone would prefer (or like to be able to) making
>> the diff which doesn't include uncommitted changes.
>
> You mean one that *does* include uncommitted changes, right?
I meant that if we make new commands that will include those changes,
some might like a version that does not. Just the basic theoretical
argument for flexibility.
>> Fair point. I wonder how many are really aware of this submap, and of
>> the 'C-x v b' submap as well.
>
> Yeah. Any thoughts on making it more discoverable?
The 'C-x v M' commands could be added to the manual - if we do think
they will be used often enough.
For the branch submap, the recently added which-key-map will probably
help some.
>> Okay, and to do that we would also need to add a new backend action, like
>> 'upstream-revision'?
>>
>> If so, that would be a common ground between several proposals, and thus a
>> good path forward.
>
> Yes. I'll work on that.
Thank you.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 21 May 2025 12:03:01 GMT)
Full text and
rfc822 format available.
Message #118 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
On Mon 19 May 2025 at 04:49am +03, Dmitry Gutov wrote:
> On 18/05/2025 14:04, Sean Whitton wrote:
>
>>> What I was referring to, is the item D. from the original report's
>>> description: being able to make the diff between the last pushed revision
>>> ("upstream revision" or merge-base with it) and the current state of the
>>> working directory, including the uncommitted changes.
>> Ah, right.
>>
>>> IIUC vc-diff-fileset-outgoing wouldn't include those changes,
>> Right.
>>
>>> or if it would, someone would prefer (or like to be able to) making
>>> the diff which doesn't include uncommitted changes.
>> You mean one that *does* include uncommitted changes, right?
>
> I meant that if we make new commands that will include those changes, some
> might like a version that does not. Just the basic theoretical argument for
> flexibility.
Ah, right. I agree.
>>> Fair point. I wonder how many are really aware of this submap, and of
>>> the 'C-x v b' submap as well.
>> Yeah. Any thoughts on making it more discoverable?
>
> The 'C-x v M' commands could be added to the manual - if we do think they will
> be used often enough.
>
> For the branch submap, the recently added which-key-map will probably help
> some.
Well, I was definitely thinking of adding the incoming and outgoing
commands to the manual, at the very least.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 21 May 2025 19:00:05 GMT)
Full text and
rfc822 format available.
Message #121 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 21/05/2025 15:02, Sean Whitton wrote:
>> The 'C-x v M' commands could be added to the manual - if we do think they will
>> be used often enough.
>>
>> For the branch submap, the recently added which-key-map will probably help
>> some.
>
> Well, I was definitely thinking of adding the incoming and outgoing
> commands to the manual, at the very least.
That sounds good to me, thanks.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Thu, 03 Jul 2025 10:48:02 GMT)
Full text and
rfc822 format available.
Message #124 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
On Mon 19 May 2025 at 04:49am +03, Dmitry Gutov wrote:
> On 18/05/2025 14:04, Sean Whitton wrote:
>
>>> What I was referring to, is the item D. from the original report's
>>> description: being able to make the diff between the last pushed revision
>>> ("upstream revision" or merge-base with it) and the current state of the
>>> working directory, including the uncommitted changes.
>> Ah, right.
>>
>>> IIUC vc-diff-fileset-outgoing wouldn't include those changes,
>> Right.
>>
>>> or if it would, someone would prefer (or like to be able to) making
>>> the diff which doesn't include uncommitted changes.
>> You mean one that *does* include uncommitted changes, right?
>
> I meant that if we make new commands that will include those changes, some
> might like a version that does not. Just the basic theoretical argument for
> flexibility.
Thinking about this a little more, I think that the default should be
not to include uncommitted changes in the outgoing diff. That's because
those uncommitted changes won't be included in a push, so in that sense
they are not, in fact, outgoing.
I think that the prefix argument for my new commands should probably
follow the existing vc-log-incoming and vc-log-outgoing in prompting for
the remote location. Though we could reserve it as a way to request
including uncommitted changes in the diffs.
Or we could leave including uncommitted changes as a task for your
new virtual revisions. Then the user would use those together with
C-x v = and C-x v D. This makes a lot of sense at least to me, because
C-x v = and C-x v D are already about uncommitted changes in most cases.
>>> Fair point. I wonder how many are really aware of this submap, and of
>>> the 'C-x v b' submap as well.
>> Yeah. Any thoughts on making it more discoverable?
>
> The 'C-x v M' commands could be added to the manual - if we do think they will
> be used often enough.
>
> For the branch submap, the recently added which-key-map will probably help
> some.
>
>>> Okay, and to do that we would also need to add a new backend action, like
>>> 'upstream-revision'?
>>>
>>> If so, that would be a common ground between several proposals, and thus a
>>> good path forward.
>> Yes. I'll work on that.
>
> Thank you.
The refactorings of the existing commands in terms of merge bases, and
the new incoming-revision backend action, are all implemented on master,
now.
--
Sean Whitton
Reply sent
to
Sean Whitton <spwhitton <at> spwhitton.name>:
You have taken responsibility.
(Fri, 04 Jul 2025 12:13:02 GMT)
Full text and
rfc822 format available.
Notification sent
to
Spencer Baugh <sbaugh <at> janestreet.com>:
bug acknowledged by developer.
(Fri, 04 Jul 2025 12:13:03 GMT)
Full text and
rfc822 format available.
Message #129 received at 62940-done <at> debbugs.gnu.org (full text, mbox):
Hello,
I've now installed implementations for vc-root-diff-incoming and
vc-root-diff-outgoing on master. I didn't add commands limited to the
current VC fileset for the time being. There is a new user option
vc-use-incoming-outgoing-prefixes to enable global bindings.
I'll close this bug now because the originally requested functionality
has been made available. We can continue to use the bug to discuss
Dmitry's ideas about virtual revisions to refer to the incoming
revision, or possibly clone, retitle and reopen it.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 04 Jul 2025 13:32:02 GMT)
Full text and
rfc822 format available.
Message #132 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> Resent-To: bug-gnu-emacs <at> gnu.org
> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Date: Fri, 04 Jul 2025 13:12:28 +0100
>
> I've now installed implementations for vc-root-diff-incoming and
> vc-root-diff-outgoing on master. I didn't add commands limited to the
> current VC fileset for the time being. There is a new user option
> vc-use-incoming-outgoing-prefixes to enable global bindings.
Thanks, but please improve the doc strings of these new commands:
> +(defun vc-root-diff-incoming (&optional remote-location)
> + "Report diff of all changes that would be pulled from REMOTE-LOCATION.
> +When called interactively with a prefix argument, prompt for REMOTE-LOCATION.
> +In some version control systems REMOTE-LOCATION can be a remote branch name.
> +
> +See `vc-use-incoming-outgoing-prefixes' regarding giving this command a
> +global binding."
This should say what REMOTE-LOCATION defaults to if omitted or nil.
Similar with vc-root-diff-outgoing.
Also, re this:
> + ;; For this command we want to ignore uncommitted changes because
> + ;; those are not outgoing, and the point is to make a comparison
> + ;; between locally committed changes and remote committed changes.
what about VCS like CVS and SVN, where "uncommitted" changes has no
meaning?
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sat, 05 Jul 2025 08:33:03 GMT)
Full text and
rfc822 format available.
Message #135 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
Thanks, I've installed some improvements.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Thu, 10 Jul 2025 14:44:02 GMT)
Full text and
rfc822 format available.
Message #138 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
Having tried vc-use-incoming-outgoing-prefixes (thanks!) I think
it would be nice if vc-dir buffers followed this user option too,
i.e. changing "I" to "I L" and "O" to "O L", and adding "I D" and
"O D" in vc-dir-mode-map, for symmetry with the "C-x v"-prefixed
version.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Fri, 11 Jul 2025 08:32:01 GMT)
Full text and
rfc822 format available.
Message #141 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
On Thu 10 Jul 2025 at 10:42am -04, Amin Bandali wrote:
> Hello,
>
> Having tried vc-use-incoming-outgoing-prefixes (thanks!) I think
> it would be nice if vc-dir buffers followed this user option too,
> i.e. changing "I" to "I L" and "O" to "O L", and adding "I D" and
> "O D" in vc-dir-mode-map, for symmetry with the "C-x v"-prefixed
> version.
Thank you for pointing this out. Now fixed.
--
Sean Whitton
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org.
(Fri, 08 Aug 2025 11:24:06 GMT)
Full text and
rfc822 format available.
bug unarchived.
Request was from
Sean Whitton <spwhitton <at> spwhitton.name>
to
control <at> debbugs.gnu.org.
(Sun, 17 Aug 2025 13:47:02 GMT)
Full text and
rfc822 format available.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sun, 17 Aug 2025 14:07:02 GMT)
Full text and
rfc822 format available.
Message #148 received at 62940 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
reopen 62940
thanks
Hello,
We now have the following DWIM diff commands:
- 'C-x v =' and 'C-x v D' to view uncommitted changes
- 'C-x v I =' and 'C-x v I D' to view incoming changes
- 'C-x v O =' and 'C-x v O D' to view outgoing changes.
We also have 'C-u C-x v =', 'C-u C-x v D' and 'C-x v M D' which prompt.
Outgoing changes here does not include uncommitted changes.
This is based on the idea that typing 'C-x v P' would not push
uncommitted changes, and so in that sense they are not outgoing.
While thinking about how to best add a way to get a diff of outgoing
changes plus uncommitted changes, I now would like to propose we do
something slightly cleverer which is able to address more than one need
for DWIM diffs.
Here are a couple of closely related needs:
(1) You're on the trunk branch. You want to see all your WIP, so, both
outgoing changes and uncommitted work.
(2) You're on a feature branch. You want to know what outstanding work
the feature branch contains: uncommitted work, plus committed work
that hasn't been cherry-picked or merged onto the trunk branch, yet.
We can make these two into the same operation by defining the notion of
a branch's _base branch_. The base branch when working on a trunk
branch is just the current version of that branch at the remote. The
base branch of a feature branch is the trunk branch from which the
feature branch was originally created.
Then both (1) and (2) become: the diff of the merge base of the working
revision with its base branch, plus uncommitted changes.
This way we add one new command which is able to satisfy several
different use cases, including filling the gap of a command which shows
outgoing changes but including uncommitted changes, as was discussed
several times in this bug.
I think this notion of the base branch is coherent and not VCS-specific.
So I propose two more commands, 'C-x v B =' and 'C-x v B D' to get the
diff against the base branch. I've implemented (1). For (2) we need
more design work.
Let me know what you think of this patch.
I haven't done manual and NEWS updates yet.
(As we previously discussed in this bug, I don't think there is a
corresponding need for a command which combined *in*coming changes with
uncommitted change somehow, so I'm ignoring that.)
--
Sean Whitton
[0001-New-commands-for-outgoing-diffs-including-uncommitte.patch (text/x-diff, attachment)]
Did not alter fixed versions and reopened.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org.
(Sun, 17 Aug 2025 14:09:02 GMT)
Full text and
rfc822 format available.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Mon, 18 Aug 2025 06:56:02 GMT)
Full text and
rfc822 format available.
Message #153 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> Outgoing changes here does not include uncommitted changes.
To view uncommitted changes together with committed changes
currently I'm using such advice that adds a static text line
at the top of vc-log:
#+begin_src emacs-lisp
(define-advice vc-git-print-log (:after (_files buffer &optional _shortlog _start-revision _limit) insert-top-line)
(when (and (memq vc-log-view-type '(long short))
(not (memq this-command '(vc-print-branch-log))))
(with-current-buffer buffer
(save-excursion
(goto-char (point-min))
(let ((inhibit-read-only t))
(insert-before-markers-and-inherit
(propertize "(Type 'd' here to show diffs with working version)\n"
'font-lock-face 'shadow)))))))
#+end_src
Then selecting a region that starts from this line
and ends on any vc-log revision line shows the diff
that includes uncommitted changes.
This was discussed in
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=35624#66
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=62940#41
But maybe a special prefix arg could specify the requirement
to include uncommitted changes?
> I think this notion of the base branch is coherent and not VCS-specific.
> So I propose two more commands, 'C-x v B =' and 'C-x v B D' to get the
> diff against the base branch. I've implemented (1). For (2) we need
> more design work.
Do I understand correctly that 'C-x v B =' is shorthand for 'C-x v M D'
without the need to confirm the default branch name and that also
includes uncommitted changes?
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Mon, 18 Aug 2025 15:43:02 GMT)
Full text and
rfc822 format available.
Message #156 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Juri Linkov <juri <at> linkov.net> writes:
>> Outgoing changes here does not include uncommitted changes.
>
> To view uncommitted changes together with committed changes
> currently I'm using such advice that adds a static text line
> at the top of vc-log:
>
> #+begin_src emacs-lisp
> (define-advice vc-git-print-log (:after (_files buffer &optional _shortlog _start-revision _limit) insert-top-line)
> (when (and (memq vc-log-view-type '(long short))
> (not (memq this-command '(vc-print-branch-log))))
> (with-current-buffer buffer
> (save-excursion
> (goto-char (point-min))
> (let ((inhibit-read-only t))
> (insert-before-markers-and-inherit
> (propertize "(Type 'd' here to show diffs with working version)\n"
> 'font-lock-face 'shadow)))))))
> #+end_src
>
> Then selecting a region that starts from this line
> and ends on any vc-log revision line shows the diff
> that includes uncommitted changes.
>
> This was discussed in
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=35624#66
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=62940#41
That is nice and useful and possibly still worth doing, but IMO "C-x v O
l then C-x h then d" is too much typing to do this operation. A
dedicated command seems nicer.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 19 Aug 2025 03:29:02 GMT)
Full text and
rfc822 format available.
Message #159 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hi! Some suggestions on the naming, and it got long, but no pressure.
On 17/08/2025 17:06, Sean Whitton wrote:
> We can make these two into the same operation by defining the notion of
> a branch's_base branch_. The base branch when working on a trunk
> branch is just the current version of that branch at the remote. The
> base branch of a feature branch is the trunk branch from which the
> feature branch was originally created.
Reading this, I would probably understood it better if it said "base
revision with the branch at the remote". Or "remote base revision". Or
"remote mergebase". In the terminology more reminiscent of Git anyway.
+;;;###autoload
> +(defun vc-fileset-diff-base-branch (&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.
I would suggest not to have '-fileset-' in the command name, because
most of our commands work on filesets already, and yet we don't call
them that.
If the main goal was to be able to delegate to it from
vc-root-diff-base-branch, specifying a different fileset, maybe a common
helper could work just as well. Or just keeping the argument, but
without the word in the name.
+;;;###autoload
> +(defun vc-root-diff-base-branch (&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.
I wonder if the revision we diff against here is ever going to be
different from the parent of the first "outgoing" revision.
If no, it seems attractive to have the name somehow close to
'vc-diff-outgoing-...'.
I was thinking of 'vc-diff-mergebase-incoming' (which like Juri noted
seems equivalent) or 'vc-diff-mergebase-outgoing' (which is essentially
the same, because ougoing and incoming will have the same mergebase; and
"outgoing" is the more relevant changeset; but then it's harder to
understand what the mergebase is with). More options:
vc-diff-outgoing-base or vc-diff-branch-base (if "branch base
[revision]" is the notion you were going for).
The "branch base" term - or "base branch" if I'm still not looking at it
right - might be the best idea if there are goals to make more commands
using it, or make it more customizable, like adding an option to
override what the branch base should be for the given repository,
independent of the repo's upstreams configuration.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 19 Aug 2025 07:27:02 GMT)
Full text and
rfc822 format available.
Message #162 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
On Mon 18 Aug 2025 at 09:39am +03, Juri Linkov wrote:
>> Outgoing changes here does not include uncommitted changes.
>
> To view uncommitted changes together with committed changes
> currently I'm using such advice that adds a static text line
> at the top of vc-log:
>
> #+begin_src emacs-lisp
> (define-advice vc-git-print-log (:after (_files buffer &optional _shortlog _start-revision _limit) insert-top-line)
> (when (and (memq vc-log-view-type '(long short))
> (not (memq this-command '(vc-print-branch-log))))
> (with-current-buffer buffer
> (save-excursion
> (goto-char (point-min))
> (let ((inhibit-read-only t))
> (insert-before-markers-and-inherit
> (propertize "(Type 'd' here to show diffs with working version)\n"
> 'font-lock-face 'shadow)))))))
> #+end_src
>
> Then selecting a region that starts from this line
> and ends on any vc-log revision line shows the diff
> that includes uncommitted changes.
>
> This was discussed in
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=35624#66
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=62940#41
Right. I agree with Spencer that it's probably too many keys for what
might be a common compound operation, though.
> But maybe a special prefix arg could specify the requirement
> to include uncommitted changes?
For all the incoming and outgoing commands a single prefix argument
means to prompt for the remote location. So we'd have to use a double
prefix argument. But then, should it prompt for the remote location, or
not? It becomes overloaded quickly. So I think we do need a separate
command.
>> I think this notion of the base branch is coherent and not VCS-specific.
>> So I propose two more commands, 'C-x v B =' and 'C-x v B D' to get the
>> diff against the base branch. I've implemented (1). For (2) we need
>> more design work.
>
> Do I understand correctly that 'C-x v B =' is shorthand for 'C-x v M D'
> without the need to confirm the default branch name and that also
> includes uncommitted changes?
That's right, except for the possible future expansion to a broader
notion of the base branch.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 19 Aug 2025 07:48:01 GMT)
Full text and
rfc822 format available.
Message #165 received at 62940 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Hello,
On Tue 19 Aug 2025 at 06:28am +03, Dmitry Gutov wrote:
> Reading this, I would probably understood it better if it said "base revision
> with the branch at the remote". Or "remote base revision". Or "remote
> mergebase". In the terminology more reminiscent of Git anyway.
Putting either "remote" or "outgoing" in the terminology, one way or
another, is a good idea.
> I would suggest not to have '-fileset-' in the command name, because most of
> our commands work on filesets already, and yet we don't call them that.
>
> If the main goal was to be able to delegate to it from
> vc-root-diff-base-branch, specifying a different fileset, maybe a common
> helper could work just as well. Or just keeping the argument, but without the
> word in the name.
Right, yeah, we don't usually have it there. The reason I've been
adding it to new incoming/outgoing commands is because vc-log-outgoing
and vc-log-incoming should have -root- in them, but don't.
I guess that these new mergebase commands don't need it, though.
> +;;;###autoload
>> +(defun vc-root-diff-base-branch (&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.
>
> I wonder if the revision we diff against here is ever going to be different
> from the parent of the first "outgoing" revision.
>
> If no, it seems attractive to have the name somehow close to
> 'vc-diff-outgoing-...'.
>
> I was thinking of 'vc-diff-mergebase-incoming' (which like Juri noted seems
> equivalent) or 'vc-diff-mergebase-outgoing' (which is essentially the same,
> because ougoing and incoming will have the same mergebase; and "outgoing" is
> the more relevant changeset; but then it's harder to understand what the
> mergebase is with). More options: vc-diff-outgoing-base or vc-diff-branch-base
> (if "branch base [revision]" is the notion you were going for).
I like "outgoing base". It captures that it is related to what the
remote actually has, like -outgoing commands, and also uses the word
"base" which captures my ideas about using the trunk branch from which a
shorter-lived branch was originally branched.
"Outgoing mergebase" might be confusing because that's essentially what
the 'C-x v O' commands already do. Also, the -mergebase commands don't
include uncommitted changes.
> The "branch base" term - or "base branch" if I'm still not looking at it right
> - might be the best idea if there are goals to make more commands using it, or
> make it more customizable, like adding an option to override what the branch
> base should be for the given repository, independent of the repo's upstreams
> configuration.
I'm thinking that if we're able to find a notion of shorter-lived and
longer-lived branches, we may also need some customisation to override
it (in .dir-locals.el) when the default distinction doesn't suit the
repository's workflow. And also, we'll probably find the notion useful
enough to add a few more commands.
Here's a revised patch with things renamed.
--
Sean Whitton
[v2-0001-New-commands-for-outgoing-diffs-including-uncommi.patch (text/x-diff, attachment)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 19 Aug 2025 16:45:05 GMT)
Full text and
rfc822 format available.
Message #168 received at 62940 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Hello,
On Tue 19 Aug 2025 at 08:47am +01, Sean Whitton wrote:
> I'm thinking that if we're able to find a notion of shorter-lived and
> longer-lived branches, we may also need some customisation to override
> it (in .dir-locals.el) when the default distinction doesn't suit the
> repository's workflow. And also, we'll probably find the notion useful
> enough to add a few more commands.
>
> Here's a revised patch with things renamed.
And here is an attempt at documenting these new concepts.
I've put it in vc1-xtra.texi partly because the VC Change Log node is
getting long, and partly because you don't need to know these new
concepts to get most work done with VC.
--
Sean Whitton
[v3-0001-New-commands-for-outgoing-diffs-including-uncommi.patch (text/x-diff, attachment)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 19 Aug 2025 19:09:02 GMT)
Full text and
rfc822 format available.
Message #171 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Date: Tue, 19 Aug 2025 17:44:36 +0100
>
> And here is an attempt at documenting these new concepts.
Thanks.
> +@node Outgoing Base Diffs
> +@subsubsection Commands for diffs including all outstanding changes
Usually, it's a good idea to have a @cindex entry that is similar or
identical to the node's or the section's name. In this case, I'd put
@cindex outstanding changes
there (and remove a later @cindex entry which begins with the same
phrase).
> +@cindex outstanding changes, version control
> +``Outstanding'' changes are those which haven't yet been integrated into
This should be in @dfn, since you are introducing new terminology.
Btw, why are you introducing this terminology after describing the
commands and not before?
> +the development trunk. A simple case of this is unpushed and
> +uncommitted work when using a distributed version control system
> +(@pxref{VCS Repositories}). A more complex case is work-in-progress on
> +a non-trunk branch (sometimes called a ``feature branch'') which, when
> +complete, will be merged into the trunk branch.
> +
> +@cindex outgoing base, version control
> +You can use these commands to obtain a diff of all outstanding changes.
> +For this to work, Emacs needs to know the ``outgoing base'': the remote
> +location for which the changes are destined once they are no longer
> +outstanding. In the simple case described above, that's just the remote
> +location to which @kbd{C-x v P} (@code{vc-push}) would push. In the
> +complex case, that's the remote version of the trunk branch from which
> +you started (``branched'') the non-trunk branch.
> +
> +If the outgoing base is the same as the remote location to which
> +@w{@kbd{C-x v P}} would push, you can just type @kbd{C-x v B =} or
> +@kbd{C-x v B D} without any prefix argument to display all outgoing
> +changes. If the outgoing base is a different remote branch, you must
> +supply a prefix argument and tell Emacs the name of that remote branch.
> +We hope to improve this so that using the commands without prefix
> +arguments works in more complex cases, too.
This description left me a bit confused about all the "vc diff
SOMETHING" commands. I think it's because (a) it explains the logic
and rationale for these commands after introducing the commands, and
(b) because it starts at the wrong starting point. A better starting
point for this is not "C-x v O =", but "C-x v =". (If I'm wrong, then
something else is missing from the description.) In addition, it uses
strange terminology, which we don't use anywhere else, without
explaining it. What is "merge base"? what is "non-trunk branch" and
how is it different from any other branch? And this passage:
> + In the simple case described above, that's just the remote
> +location to which @kbd{C-x v P} (@code{vc-push}) would push. In the
> +complex case, that's the remote version of the trunk branch from which
> +you started (``branched'') the non-trunk branch.
left me completely confused, because it sounds like you are describing
the same situation, but saying they are two different ones?
My suggestion is to elaborate on the use cases these commands are
intended to support, and do it _before_ describing the commands.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Tue, 19 Aug 2025 23:04:02 GMT)
Full text and
rfc822 format available.
Message #174 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 19/08/2025 10:47, Sean Whitton wrote:
>> If the main goal was to be able to delegate to it from
>> vc-root-diff-base-branch, specifying a different fileset, maybe a common
>> helper could work just as well. Or just keeping the argument, but without the
>> word in the name.
>
> Right, yeah, we don't usually have it there. The reason I've been
> adding it to new incoming/outgoing commands is because vc-log-outgoing
> and vc-log-incoming should have -root- in them, but don't.
Yeah, these are special. Personally, I would probably call the commands
added in commit da3973b657d without -fileset- too. But I guess either
way we're going to have names using different schemes now.
Unless we rename vc-log-incoming and vc-log-outgoing to have -root-
inside. But that's probably only worth it if we want to add fileset
versions for them later.
> I guess that these new mergebase commands don't need it, though.
>> I was thinking of 'vc-diff-mergebase-incoming' (which like Juri noted seems
>> equivalent) or 'vc-diff-mergebase-outgoing' (which is essentially the same,
>> because ougoing and incoming will have the same mergebase; and "outgoing" is
>> the more relevant changeset; but then it's harder to understand what the
>> mergebase is with). More options: vc-diff-outgoing-base or vc-diff-branch-base
>> (if "branch base [revision]" is the notion you were going for).
>
> I like "outgoing base". It captures that it is related to what the
> remote actually has, like -outgoing commands, and also uses the word
> "base" which captures my ideas about using the trunk branch from which a
> shorter-lived branch was originally branched.
The new update looks great, thanks.
> "Outgoing mergebase" might be confusing because that's essentially what
> the 'C-x v O' commands already do. Also, the -mergebase commands don't
> include uncommitted changes.
You can have them included if you input nil as REV2, e.g.:
M-x vc-diff-mergebase RET HEAD RET C-j
Anyway, I agree that using the term mergebase would be confusing.
>> The "branch base" term - or "base branch" if I'm still not looking at it right
>> - might be the best idea if there are goals to make more commands using it, or
>> make it more customizable, like adding an option to override what the branch
>> base should be for the given repository, independent of the repo's upstreams
>> configuration.
>
> I'm thinking that if we're able to find a notion of shorter-lived and
> longer-lived branches, we may also need some customisation to override
> it (in .dir-locals.el) when the default distinction doesn't suit the
> repository's workflow. And also, we'll probably find the notion useful
> enough to add a few more commands.
Makes sense.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 20 Aug 2025 12:08:02 GMT)
Full text and
rfc822 format available.
Message #177 received at 62940 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Hello,
On Tue 19 Aug 2025 at 10:07pm +03, Eli Zaretskii wrote:
> This description left me a bit confused about all the "vc diff
> SOMETHING" commands. I think it's because (a) it explains the logic
> and rationale for these commands after introducing the commands, and
> (b) because it starts at the wrong starting point. A better starting
> point for this is not "C-x v O =", but "C-x v =". (If I'm wrong, then
> something else is missing from the description.) In addition, it uses
> strange terminology, which we don't use anywhere else, without
> explaining it. What is "merge base"? what is "non-trunk branch" and
> how is it different from any other branch? And this passage:
>
>> + In the simple case described above, that's just the remote
>> +location to which @kbd{C-x v P} (@code{vc-push}) would push. In the
>> +complex case, that's the remote version of the trunk branch from which
>> +you started (``branched'') the non-trunk branch.
>
> left me completely confused, because it sounds like you are describing
> the same situation, but saying they are two different ones?
>
> My suggestion is to elaborate on the use cases these commands are
> intended to support, and do it _before_ describing the commands.
Thanks. I think that the thing to do first is to document C-x v M D and
C-x v M L in vc1-xtra.texi; I think that when Juri added these he
decided they weren't significant enough to go in the manual, but if I
document them then it will give me the "merge base" terminology to
crossreference. I think that a node for them in vc1-xtra.texi is
independently a good idea, as they are non-trivial to understand.
Let me know what you think of the docs in these revised patches.
--
Sean Whitton
[v4-0001-Document-C-x-v-M-D-and-C-x-v-M-L-in-the-manual.patch (text/x-diff, attachment)]
[v4-0002-New-commands-for-outgoing-diffs-including-uncommi.patch (text/x-diff, attachment)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 20 Aug 2025 12:13:01 GMT)
Full text and
rfc822 format available.
Message #180 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
On Wed 20 Aug 2025 at 02:03am +03, Dmitry Gutov wrote:
> On 19/08/2025 10:47, Sean Whitton wrote:
>
>>> If the main goal was to be able to delegate to it from
>>> vc-root-diff-base-branch, specifying a different fileset, maybe a common
>>> helper could work just as well. Or just keeping the argument, but without the
>>> word in the name.
>> Right, yeah, we don't usually have it there. The reason I've been
>> adding it to new incoming/outgoing commands is because vc-log-outgoing
>> and vc-log-incoming should have -root- in them, but don't.
>
> Yeah, these are special. Personally, I would probably call the commands added
> in commit da3973b657d without -fileset- too. But I guess either way we're
> going to have names using different schemes now.
I've gone ahead with dropping the -fileset-.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 20 Aug 2025 12:27:02 GMT)
Full text and
rfc822 format available.
Message #183 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 20/08/2025 15:12, Sean Whitton wrote:
> I've gone ahead with dropping the -fileset-.
Thanks!
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 20 Aug 2025 14:31:02 GMT)
Full text and
rfc822 format available.
Message #186 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Cc: sbaugh <at> janestreet.com, bandali <at> gnu.org, juri <at> linkov.net,
> dmitry <at> gutov.dev, 62940 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
> Date: Wed, 20 Aug 2025 13:07:16 +0100
>
> > My suggestion is to elaborate on the use cases these commands are
> > intended to support, and do it _before_ describing the commands.
>
> Thanks. I think that the thing to do first is to document C-x v M D and
> C-x v M L in vc1-xtra.texi; I think that when Juri added these he
> decided they weren't significant enough to go in the manual, but if I
> document them then it will give me the "merge base" terminology to
> crossreference. I think that a node for them in vc1-xtra.texi is
> independently a good idea, as they are non-trivial to understand.
>
> Let me know what you think of the docs in these revised patches.
See below, but it's a definite improvement.
> +@item C-x v M D
> +Prompt for two revisions, find the merge base between them, then display
> +all changes between the merge base and the second revision
> +(@code{vc-diff-mergebase}).
> +
> +@item C-x v M L
> +Prompt for two revisions, find the merge base between them, then display
> +the change history for the repository between the merge base and second
> +revision (@code{vc-log-mergebase}).
You use "changes" for the first command and "change history" for the
second. Why not say "diffs" and "log messages" instead? The fact
that you use "history" in the second case also doesn't help to avoid
confusion.
I also would make these summary descriptions shorter, since you repeat
most of the text later in the section. So something like
Display changes between two revisions that have a common merge base.
> +The @dfn{merge base} between two branches is a concept that exists for
> +decentralized version control systems (@pxref{VCS Repositories}). It is
> +the most recent revision that exists on both branches. If neither of
> +the branches were ever merged into the other (@pxref{Merging}), then the
> +merge base is the revision that the older of the two branches was at
> +when the newer branch was created from it (@pxref{Creating Branches}).
> +If one of the branches was ever merged into the other, then the merge
> +base is the revision that effected the most recent such merge.
The first sentence shouldn't be the first one. The first one should
say
The @dfn{merge base} between two branches is the most recent
revision that exists on both branches.
Then you can say something like "This concept is valid only for
decentralized version control systems." (Btw, is that really true?
Branches exist in all VCSes, and the above definition of a merge base
can thus be applied to all of them.)
> +With this understood, we can generalize the concept of a merge base from
> +branches to any two revisions. The merge base between two revisions is
> +the most recent revision that can be found in the revision history of
> +both of the two revisions.@footnote{In fact the concept generalizes to
> +any number of revisions, but Emacs's commands for merge bases work with
> +only two, so we limit ourselves to that.}
I wonder whether it's a good idea to start with "branches" and then
generalize. Why not start with revisions from the get-go? How does
talking about branches help understanding the concept?
> +@kindex C-x v M D
> +@findex vc-diff-mergebase
> +@kindex C-x v M L
> +@findex vc-log-mergebase
> +Merge bases are useful to make certain comparisons between branches, and
> +Emacs provides two commands for doing so.
And here you are talking about "branches" again. Why?
> Each of @kbd{C-x v M D}
> +(@code{vc-diff-mergebase}) and @kbd{C-x v M L} (@code{vc-log-mergebase})
> +prompt for two revisions, find the merge base between them, and then
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
I suggest "find their common merge base" instead. "Between them"
might confuse.
> +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 the remote repository. You can
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"would do to the remote repository". "to" is missing.
> +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 @samp{origin/master}. We hope to
^^^^^^^^^^^^^^^^^^^^
This should use @kbd, not @samp, since it's what the user should type.
Thanks.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Wed, 20 Aug 2025 17:19:02 GMT)
Full text and
rfc822 format available.
Message #189 received at 62940 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Hello,
On Wed 20 Aug 2025 at 05:29pm +03, Eli Zaretskii wrote:
>> +@item C-x v M D
>> +Prompt for two revisions, find the merge base between them, then display
>> +all changes between the merge base and the second revision
>> +(@code{vc-diff-mergebase}).
>> +
>> +@item C-x v M L
>> +Prompt for two revisions, find the merge base between them, then display
>> +the change history for the repository between the merge base and second
>> +revision (@code{vc-log-mergebase}).
>
> You use "changes" for the first command and "change history" for the
> second. Why not say "diffs" and "log messages" instead? The fact
> that you use "history" in the second case also doesn't help to avoid
> confusion.
It has to be "diffs for changes between" not "diffs between" to be
grammatical, I think, so I've used that.
> I also would make these summary descriptions shorter, since you repeat
> most of the text later in the section. So something like
>
> Display changes between two revisions that have a common merge base.
It's not easy to shorten them because the commands don't compare the two
revisions directly, but rather, they compare the merge base of the two
revisions with the second of the two revisions.
(Indeed, for comparing them directly, you'd just use C-u C-x v D.)
I've made them a little shorter but I don't think eliminating "Prompt
for two revisions" is wise.
>> +The @dfn{merge base} between two branches is a concept that exists for
>> +decentralized version control systems (@pxref{VCS Repositories}). It is
>> +the most recent revision that exists on both branches. If neither of
>> +the branches were ever merged into the other (@pxref{Merging}), then the
>> +merge base is the revision that the older of the two branches was at
>> +when the newer branch was created from it (@pxref{Creating Branches}).
>> +If one of the branches was ever merged into the other, then the merge
>> +base is the revision that effected the most recent such merge.
>
> The first sentence shouldn't be the first one. The first one should
> say
>
> The @dfn{merge base} between two branches is the most recent
> revision that exists on both branches.
>
> Then you can say something like "This concept is valid only for
> decentralized version control systems."
Thanks, changed.
> (Btw, is that really true? Branches exist in all VCSes, and the above
> definition of a merge base can thus be applied to all of them.)
The concept of a merge base does not essentially require a decentralized
VCS, indeed. However, the definition I've given does not apply directly
to the centralized VCS we actually support. Specifically, IIUC, for our
centralized VCS, revisions cannot exist on more than one branch.
Although C-x v M D could perhaps be implemented for our centralized VCS,
I'm not sure that C-x v M L could make sense.
I've written this in my latest revision:
It is a concept that arises for decentralized version control
systems (@pxref{VCS Repositories}).
So, that's not claiming that it *can't* arise for a centralised VCS
anymore, but it's still avoiding overcomplicating things given what we
actually have implemented in VC.
>> +With this understood, we can generalize the concept of a merge base from
>> +branches to any two revisions. The merge base between two revisions is
>> +the most recent revision that can be found in the revision history of
>> +both of the two revisions.@footnote{In fact the concept generalizes to
>> +any number of revisions, but Emacs's commands for merge bases work with
>> +only two, so we limit ourselves to that.}
>
> I wonder whether it's a good idea to start with "branches" and then
> generalize. Why not start with revisions from the get-go? How does
> talking about branches help understanding the concept?
My explanation relies on discussing merging, but in `(emacs)Merging' we
only discuss merging between branches, not merging between arbitrary
revisions.
I think this is correct because merging between pure revisions is
something that only makes conceptual sense with some VCS (Git, but not
Mercurial, I think). In addition, it's a very unusual thing to do.
>> +@kindex C-x v M D
>> +@findex vc-diff-mergebase
>> +@kindex C-x v M L
>> +@findex vc-log-mergebase
>> +Merge bases are useful to make certain comparisons between branches, and
>> +Emacs provides two commands for doing so.
>
> And here you are talking about "branches" again. Why?
I've changed this to refer to branches in a parenthetical.
>> Each of @kbd{C-x v M D}
>> +(@code{vc-diff-mergebase}) and @kbd{C-x v M L} (@code{vc-log-mergebase})
>> +prompt for two revisions, find the merge base between them, and then
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> I suggest "find their common merge base" instead. "Between them"
> might confuse.
I think "find their merge base" is okay, but I wouldn't like to
introduce the "common merge base" terminology. I've changed that.
>> +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 the remote repository. You can
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> "would do to the remote repository". "to" is missing.
Fixed, thanks.
>> +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 @samp{origin/master}. We hope to
> ^^^^^^^^^^^^^^^^^^^^
> This should use @kbd, not @samp, since it's what the user should type.
Ah, interesting, thanks.
--
Sean Whitton
[v5-0001-Document-C-x-v-M-D-and-C-x-v-M-L-in-the-manual.patch (text/x-diff, attachment)]
[v5-0002-New-commands-for-outgoing-diffs-including-uncommi.patch (text/x-diff, attachment)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Thu, 21 Aug 2025 05:58:01 GMT)
Full text and
rfc822 format available.
Message #192 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Cc: sbaugh <at> janestreet.com, bandali <at> gnu.org, juri <at> linkov.net,
> dmitry <at> gutov.dev, 62940 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
> Date: Wed, 20 Aug 2025 18:18:37 +0100
>
> > I also would make these summary descriptions shorter, since you repeat
> > most of the text later in the section. So something like
> >
> > Display changes between two revisions that have a common merge base.
>
> It's not easy to shorten them because the commands don't compare the two
> revisions directly, but rather, they compare the merge base of the two
> revisions with the second of the two revisions.
The text I proposed didn't say anything about direct comparison, did
it?
Anyway, this is a summary, so it doesn't have to tell everything. The
details should be left for the main text of the section. But I can
suggest alternatives in case you like them more. For example:
Display changes between two diverged branches.
or
Display changes between two branches that have a common merge base.
This is IMO better than what you are using because your text basically
describes the implementation, not the user-level goal of the commands.
> > (Btw, is that really true? Branches exist in all VCSes, and the above
> > definition of a merge base can thus be applied to all of them.)
>
> The concept of a merge base does not essentially require a decentralized
> VCS, indeed. However, the definition I've given does not apply directly
> to the centralized VCS we actually support.
Then I think we should say that this is _supported_ only for dVCS, not
that the concept is undefined or doesn't arise for centralized VCS.
> Specifically, IIUC, for our
> centralized VCS, revisions cannot exist on more than one branch.
Really? If one invokes "C-u C-x v =", can't one specify revisions
from different CVS branches, as in "1.20" and "1.10.1.5"? And if one
does, won't this compare a certain file between two branches?
But even if this currently doesn't work, someone could make it work,
so the text should not pretend the concept is undefined, only that it
is currently unsupported in some cases.
> Although C-x v M D could perhaps be implemented for our centralized VCS,
> I'm not sure that C-x v M L could make sense.
My point is that when discussing concepts we shouldn't "contaminate"
them because of considerations of what is and isn't currently
implemented.
> I've written this in my latest revision:
>
> It is a concept that arises for decentralized version control
> systems (@pxref{VCS Repositories}).
>
> So, that's not claiming that it *can't* arise for a centralised VCS
> anymore, but it's still avoiding overcomplicating things given what we
> actually have implemented in VC.
I'd remove that sentence entirely, and instead tell that the commands
described in this section are currently implemented only for dVCS.
> >> +With this understood, we can generalize the concept of a merge base from
> >> +branches to any two revisions. The merge base between two revisions is
> >> +the most recent revision that can be found in the revision history of
> >> +both of the two revisions.@footnote{In fact the concept generalizes to
> >> +any number of revisions, but Emacs's commands for merge bases work with
> >> +only two, so we limit ourselves to that.}
> >
> > I wonder whether it's a good idea to start with "branches" and then
> > generalize. Why not start with revisions from the get-go? How does
> > talking about branches help understanding the concept?
>
> My explanation relies on discussing merging, but in `(emacs)Merging' we
> only discuss merging between branches, not merging between arbitrary
> revisions.
>
> I think this is correct because merging between pure revisions is
> something that only makes conceptual sense with some VCS (Git, but not
> Mercurial, I think). In addition, it's a very unusual thing to do.
What is the difference between "merging between branches" and "merging
between pure revisions"? If by the latter you mean merging two
revisions on the same mainline, then (a) reverting can be seen as such
a merge, and (b) the merge base in this case is one of the two
revisions. So there's nothing unusual nor hard to grasp in this case.
Or did you mean something else?
But if we don't want to confuse readers with this kind of merges, then
it makes my point stronger: let's talk _only_ about merging between
branches and merge base of two branches.
> +@item C-x v M L
> +Prompt for two revisions, then display log messages for revisions
> +between the merge base of the two revisions and the second revision
> +(@code{vc-log-mergebase}).
"revisions between the merge base and..." sounds awkward. What are
"revisions between the merge base and the second revision"? The
notion of "between" is not well-defined for revisions. I guess you
mean something like "revisions committed on the branch of the second
revision since the merge base"?
> +If one of the branches was ever merged into the other, then the merge
> +base is the revision that effected the most recent such merge.
"revision that effected"? Wouldn't it be simpler to say
If one of the branches was ever merged into the other, then the
merge base is the most recent such merge point.
> +@table @kbd
> +@item C-x v B =
> +Display diffs of changes to the VC fileset since the merge base with the
> +remote branch (@code{vc-diff-outgoing-base}).
> +
> +@item C-x v B D
> +Display all changes since the merge base with the remote branch
> +(@code{vc-root-diff-outgoing-base}).
> +@end table
I'd drop the "with the remote branch" parts here. The phrase "merge
base with a branch" is confusing, and here it doesn't contribute
anything but confusion.
> +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 remote
> +repositories.
I think it is better to talk about "upstream repository", not about
"remote". We introduce the notion of an upstream repository in
"Pulling / Pushing", and it is more accurate anyway (since it could be
physically on the same machine).
> +First, consider working on a single branch. @dfn{Outstanding changes}
> +are those which you haven't yet shared with your collaborators.
I'd use "haven't yet pushed to upstream" here instead. It is more
general.
> +(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.
Also here: I'd use upstream instead of remote.
Thanks.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Thu, 21 Aug 2025 08:34:02 GMT)
Full text and
rfc822 format available.
Message #195 received at 62940 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Hello,
On Thu 21 Aug 2025 at 08:56am +03, Eli Zaretskii wrote:
> Anyway, this is a summary, so it doesn't have to tell everything. The
> details should be left for the main text of the section. But I can
> suggest alternatives in case you like them more. For example:
>
> Display changes between two diverged branches.
> or
> Display changes between two branches that have a common merge base.
>
> This is IMO better than what you are using because your text basically
> describes the implementation, not the user-level goal of the commands.
Yes, good, something like this is better indeed.
It mustn't imply that the command treats the two branches symmetrically,
however, because actually it is only the changes on the second branch
that are displayed. That's part of what makes it useful.
So I now have:
Report diffs of changes on a divergent branch of development
and something similar for C-x v M L.
>> I've written this in my latest revision:
>>
>> It is a concept that arises for decentralized version control
>> systems (@pxref{VCS Repositories}).
>>
>> So, that's not claiming that it *can't* arise for a centralised VCS
>> anymore, but it's still avoiding overcomplicating things given what we
>> actually have implemented in VC.
>
> I'd remove that sentence entirely, and instead tell that the commands
> described in this section are currently implemented only for dVCS.
Okay. I've put in a comment indicating that the definition itself may
need changing for centralized CVS (but maybe it wouldn't).
>> >> +With this understood, we can generalize the concept of a merge base from
>> >> +branches to any two revisions. The merge base between two revisions is
>> >> +the most recent revision that can be found in the revision history of
>> >> +both of the two revisions.@footnote{In fact the concept generalizes to
>> >> +any number of revisions, but Emacs's commands for merge bases work with
>> >> +only two, so we limit ourselves to that.}
>> >
>> > I wonder whether it's a good idea to start with "branches" and then
>> > generalize. Why not start with revisions from the get-go? How does
>> > talking about branches help understanding the concept?
>>
>> My explanation relies on discussing merging, but in `(emacs)Merging' we
>> only discuss merging between branches, not merging between arbitrary
>> revisions.
>>
>> I think this is correct because merging between pure revisions is
>> something that only makes conceptual sense with some VCS (Git, but not
>> Mercurial, I think). In addition, it's a very unusual thing to do.
>
> What is the difference between "merging between branches" and "merging
> between pure revisions"? If by the latter you mean merging two
> revisions on the same mainline, then (a) reverting can be seen as such
> a merge, and (b) the merge base in this case is one of the two
> revisions. So there's nothing unusual nor hard to grasp in this case.
> Or did you mean something else?
I don't think we are talking about the same thing, which I think
illustrates my point that merging pure revisions is a highly
VCS-specific thing. For example, with Git you can checkout a detached
HEAD and merge arbitrary other revisions into it. Mercurial, on the
other hand, doesn't really have something like detached HEADs, because
of how the branch is part of the commit, not just a pointer.
On the other hand, merging branches is always clear and generally
applicable.
> But if we don't want to confuse readers with this kind of merges, then
> it makes my point stronger: let's talk _only_ about merging between
> branches and merge base of two branches.
I don't think so, because it is useful to input revisions, not just
the names of branches, to the prompts for C-x v M D and C-x v M L.
That's what I've tried to balance with the way I laid out the text.
I think it is accessible, though one option would be to move talk of
revisions into footnotes.
>> +If one of the branches was ever merged into the other, then the merge
>> +base is the revision that effected the most recent such merge.
>
> "revision that effected"? Wouldn't it be simpler to say
>
> If one of the branches was ever merged into the other, then the
> merge base is the most recent such merge point.
If you think it is clear that "merge point" means a revision, that's
fine, yes.
>> +@table @kbd
>> +@item C-x v B =
>> +Display diffs of changes to the VC fileset since the merge base with the
>> +remote branch (@code{vc-diff-outgoing-base}).
>> +
>> +@item C-x v B D
>> +Display all changes since the merge base with the remote branch
>> +(@code{vc-root-diff-outgoing-base}).
>> +@end table
>
> I'd drop the "with the remote branch" parts here. The phrase "merge
> base with a branch" is confusing, and here it doesn't contribute
> anything but confusion.
I don't think it can just be "since the merge base" because the
immediate question is "the merge base of what and what?".
This is better:
since the merge base of the current branch and its upstream counterpart
>> +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 remote
>> +repositories.
>
> I think it is better to talk about "upstream repository", not about
> "remote". We introduce the notion of an upstream repository in
> "Pulling / Pushing", and it is more accurate anyway (since it could be
> physically on the same machine).
Yes, good, thanks.
>> +First, consider working on a single branch. @dfn{Outstanding changes}
>> +are those which you haven't yet shared with your collaborators.
>
> I'd use "haven't yet pushed to upstream" here instead. It is more
> general.
Done.
>> +(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.
>
> Also here: I'd use upstream instead of remote.
Here I'm following all the other -incoming- and -outgoing- commands.
They prompt for the argument in the same way so it is helpful for the
parameter to always have the same name.
I've made a note to look into changing them all to UPSTREAM-LOCATION
later.
--
Sean Whitton
[v6-0001-Document-C-x-v-M-D-and-C-x-v-M-L-in-the-manual.patch (text/x-diff, attachment)]
[v6-0002-New-commands-for-outgoing-diffs-including-uncommi.patch (text/x-diff, attachment)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Thu, 21 Aug 2025 10:42:02 GMT)
Full text and
rfc822 format available.
Message #198 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> From: Sean Whitton <spwhitton <at> spwhitton.name>
> Cc: sbaugh <at> janestreet.com, bandali <at> gnu.org, juri <at> linkov.net,
> dmitry <at> gutov.dev, 62940 <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
> Date: Thu, 21 Aug 2025 09:32:51 +0100
>
> > Display changes between two diverged branches.
> > or
> > Display changes between two branches that have a common merge base.
> >
> > This is IMO better than what you are using because your text basically
> > describes the implementation, not the user-level goal of the commands.
>
> Yes, good, something like this is better indeed.
>
> It mustn't imply that the command treats the two branches symmetrically,
> however, because actually it is only the changes on the second branch
> that are displayed. That's part of what makes it useful.
>
> So I now have:
>
> Report diffs of changes on a divergent branch of development
>
> and something similar for C-x v M L.
Maybe
Report diffs of changes on a branch that diverged from another one.
or
Report diffs of changes on a branch since it diverged from another one.
> >> I think this is correct because merging between pure revisions is
> >> something that only makes conceptual sense with some VCS (Git, but not
> >> Mercurial, I think). In addition, it's a very unusual thing to do.
> >
> > What is the difference between "merging between branches" and "merging
> > between pure revisions"? If by the latter you mean merging two
> > revisions on the same mainline, then (a) reverting can be seen as such
> > a merge, and (b) the merge base in this case is one of the two
> > revisions. So there's nothing unusual nor hard to grasp in this case.
> > Or did you mean something else?
>
> I don't think we are talking about the same thing, which I think
> illustrates my point that merging pure revisions is a highly
> VCS-specific thing. For example, with Git you can checkout a detached
> HEAD and merge arbitrary other revisions into it. Mercurial, on the
> other hand, doesn't really have something like detached HEADs, because
> of how the branch is part of the commit, not just a pointer.
>
> On the other hand, merging branches is always clear and generally
> applicable.
Since the text almost always talks about merging between branches, how
about limiting the manual only to that case?
> > But if we don't want to confuse readers with this kind of merges, then
> > it makes my point stronger: let's talk _only_ about merging between
> > branches and merge base of two branches.
>
> I don't think so, because it is useful to input revisions, not just
> the names of branches, to the prompts for C-x v M D and C-x v M L.
You could say that in a footnote, since most of the text doesn't cover
this anyway.
> > If one of the branches was ever merged into the other, then the
> > merge base is the most recent such merge point.
>
> If you think it is clear that "merge point" means a revision, that's
> fine, yes.
It is only a revision in Git (and maybe Mercurial, I don't really
know). So I didn't want to say "merge-commit". But I think "merge
point" should be clear to all.
> >> +@table @kbd
> >> +@item C-x v B =
> >> +Display diffs of changes to the VC fileset since the merge base with the
> >> +remote branch (@code{vc-diff-outgoing-base}).
> >> +
> >> +@item C-x v B D
> >> +Display all changes since the merge base with the remote branch
> >> +(@code{vc-root-diff-outgoing-base}).
> >> +@end table
> >
> > I'd drop the "with the remote branch" parts here. The phrase "merge
> > base with a branch" is confusing, and here it doesn't contribute
> > anything but confusion.
>
> I don't think it can just be "since the merge base" because the
> immediate question is "the merge base of what and what?".
The detailed description of the command explains that. This is just a
summary, and it is supposed to be short and concise.
> This is better:
>
> since the merge base of the current branch and its upstream counterpart
That's okay, but it is much longer.
> I've made a note to look into changing them all to UPSTREAM-LOCATION
> later.
OK.
Reply sent
to
Sean Whitton <spwhitton <at> spwhitton.name>:
You have taken responsibility.
(Sat, 30 Aug 2025 10:47:03 GMT)
Full text and
rfc822 format available.
Notification sent
to
Spencer Baugh <sbaugh <at> janestreet.com>:
bug acknowledged by developer.
(Sat, 30 Aug 2025 10:47:04 GMT)
Full text and
rfc822 format available.
Message #203 received at 62940-done <at> debbugs.gnu.org (full text, mbox):
Hello,
Thanks again for the feedback. All incorporated, and as a bit of time
has passed, I've installed the patches and am closing this bug.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sun, 31 Aug 2025 01:13:01 GMT)
Full text and
rfc822 format available.
Message #206 received at 62940-done <at> debbugs.gnu.org (full text, mbox):
Hi!
On 30/08/2025 13:46, Sean Whitton wrote:
> Thanks again for the feedback. All incorporated, and as a bit of time
> has passed, I've installed the patches and am closing this bug.
Having really tested it out just now, I have a question.
Calling 'C-x v B D' with a Git repository is not quite instant, while I
intuitively expected it to be.
For example, with Emacs's checkout that has a fairly large pause because
of how Savannah's Git server is.
I suppose it's logical, strictly speaking, that when
vc-diff-outgoing-base calls vc--incoming-revision, the first thing
vc-git-incoming-revision does it call 'git fetch'.
OT2H, I think at least with Git 99% of the time you'd really have to go
out of your way to have the current upstream head reference be outdated,
for the purpose of determining the outgoing base commit. (E.g. maybe
that happens after a 'git push -f' done by somebody else). One exception
is having the current working branch being merged into its base by
someone else, e.g. as a part of the release cycle (merging to main
before a release), but that usually happens after all the work on the
current branch is done, and one usually find out about it through other
channels (e.g. task status notification in email) and the refresh is one
command away, in the terminal.
So maybe we should skip the 'git fetch' step in the -outgoing* commands.
Thoughts?
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sun, 31 Aug 2025 05:17:01 GMT)
Full text and
rfc822 format available.
Message #209 received at 62940 <at> debbugs.gnu.org (full text, mbox):
> Date: Sun, 31 Aug 2025 04:12:00 +0300
> Cc: sbaugh <at> janestreet.com, bandali <at> gnu.org, juri <at> linkov.net,
> 62940-done <at> debbugs.gnu.org, fgunbin <at> fastmail.fm
> From: Dmitry Gutov <dmitry <at> gutov.dev>
>
> Calling 'C-x v B D' with a Git repository is not quite instant, while I
> intuitively expected it to be.
>
> For example, with Emacs's checkout that has a fairly large pause because
> of how Savannah's Git server is.
>
> I suppose it's logical, strictly speaking, that when
> vc-diff-outgoing-base calls vc--incoming-revision, the first thing
> vc-git-incoming-revision does it call 'git fetch'.
>
> OT2H, I think at least with Git 99% of the time you'd really have to go
> out of your way to have the current upstream head reference be outdated,
> for the purpose of determining the outgoing base commit. (E.g. maybe
> that happens after a 'git push -f' done by somebody else). One exception
> is having the current working branch being merged into its base by
> someone else, e.g. as a part of the release cycle (merging to main
> before a release), but that usually happens after all the work on the
> current branch is done, and one usually find out about it through other
> channels (e.g. task status notification in email) and the refresh is one
> command away, in the terminal.
>
> So maybe we should skip the 'git fetch' step in the -outgoing* commands.
>
> Thoughts?
Skipping (or including) the "git fetch" step could be an optional
feature. For example, it could be excluded by default, and included
when the command is invoked with a prefix argument, on the assumption
that in that case the probability of HEAD being outdated is higher.
Users could then force "git fetch" for the current upstream by typing
RET at the prompt.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sun, 31 Aug 2025 09:29:02 GMT)
Full text and
rfc822 format available.
Message #212 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
On Sun 31 Aug 2025 at 04:12am +03, Dmitry Gutov wrote:
> Calling 'C-x v B D' with a Git repository is not quite instant, while I
> intuitively expected it to be.
>
> For example, with Emacs's checkout that has a fairly large pause because of
> how Savannah's Git server is.
>
> I suppose it's logical, strictly speaking, that when vc-diff-outgoing-base
> calls vc--incoming-revision, the first thing vc-git-incoming-revision does it
> call 'git fetch'.
>
> OT2H, I think at least with Git 99% of the time you'd really have to go out of
> your way to have the current upstream head reference be outdated, for the
> purpose of determining the outgoing base commit. (E.g. maybe that happens
> after a 'git push -f' done by somebody else). One exception is having the
> current working branch being merged into its base by someone else, e.g. as a
> part of the release cycle (merging to main before a release), but that usually
> happens after all the work on the current branch is done, and one usually find
> out about it through other channels (e.g. task status notification in email)
> and the refresh is one command away, in the terminal.
>
> So maybe we should skip the 'git fetch' step in the -outgoing* commands.
Thank you both, these are very interesting points.
I hadn't observed this difference between the incoming and outgoing
commands. With incoming you always want to make sure you have fetched
everything. But with outgoing, as all we are doing is finding the merge
base, then at least with Git, indeed, it is only rarely that a change to
the upstream will render your local data invalid.
I think this has to be VCS-specific.
For example, while vc-hg-incoming-revision also stores the revision at
the end of the remote branch locally, there is nothing equivalent to a
remote-tracking branch, so we can't readily make reference to the most
recent result of fetching from the remote.
So I think the implementation can be to add an optional CACHED-OK
argument to the incoming-revision VC API function, which means that the
backend may choose not to fetch.
On Sun 31 Aug 2025 at 08:15am +03, Eli Zaretskii wrote:
> Skipping (or including) the "git fetch" step could be an optional
> feature. For example, it could be excluded by default, and included
> when the command is invoked with a prefix argument, on the assumption
> that in that case the probability of HEAD being outdated is higher.
> Users could then force "git fetch" for the current upstream by typing
> RET at the prompt.
It's certainly very nice to provide a way to force a git fetch by just
typing RET at the prompt.
There could be a defcustom with options to never fetch, fetch when
prompting for the upstream location (the default), and to always fetch.
I'm not sure about this assumption, though. Based on Dmitry's argument,
it doesn't seem to me any more likely that when the command is invoked
with a prefix argument, the probability that the remote-tracking
branches are *sufficiently* out-of-date is higher.
So just turning off fetch for all outgoing commands, with a Git-specific
defcustom to reenable it, is what makes most sense to me right now.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sun, 31 Aug 2025 14:41:03 GMT)
Full text and
rfc822 format available.
Message #215 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 31/08/2025 12:27, Sean Whitton wrote:
> Thank you both, these are very interesting points.
>
> I hadn't observed this difference between the incoming and outgoing
> commands. With incoming you always want to make sure you have fetched
> everything. But with outgoing, as all we are doing is finding the merge
> base, then at least with Git, indeed, it is only rarely that a change to
> the upstream will render your local data invalid.
>
> I think this has to be VCS-specific.
> For example, while vc-hg-incoming-revision also stores the revision at
> the end of the remote branch locally, there is nothing equivalent to a
> remote-tracking branch, so we can't readily make reference to the most
> recent result of fetching from the remote.
>
> So I think the implementation can be to add an optional CACHED-OK
> argument to the incoming-revision VC API function, which means that the
> backend may choose not to fetch.
Sounds ok. Or 'refresh' with reverse meaning.
> On Sun 31 Aug 2025 at 08:15am +03, Eli Zaretskii wrote:
>
>> Skipping (or including) the "git fetch" step could be an optional
>> feature. For example, it could be excluded by default, and included
>> when the command is invoked with a prefix argument, on the assumption
>> that in that case the probability of HEAD being outdated is higher.
>> Users could then force "git fetch" for the current upstream by typing
>> RET at the prompt.
>
> It's certainly very nice to provide a way to force a git fetch by just
> typing RET at the prompt.
> There could be a defcustom with options to never fetch, fetch when
> prompting for the upstream location (the default), and to always fetch.
A user option can work, though I'd start with trying to understand who
is going to use it, and in what scenario.
> I'm not sure about this assumption, though. Based on Dmitry's argument,
> it doesn't seem to me any more likely that when the command is invoked
> with a prefix argument, the probability that the remote-tracking
> branches are *sufficiently* out-of-date is higher.
Or we could use double-prefix for this specific purpose.
But given that the user could also call vc-log-incoming to force that
refresh, maybe an extra way to do the same might not be necessary.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Sun, 31 Aug 2025 17:20:02 GMT)
Full text and
rfc822 format available.
Message #218 received at 62940 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
On Sun, Aug 31, 2025, 10:40 AM Dmitry Gutov <dmitry <at> gutov.dev> wrote:
> On 31/08/2025 12:27, Sean Whitton wrote:
>
> > Thank you both, these are very interesting points.
> >
> > I hadn't observed this difference between the incoming and outgoing
> > commands. With incoming you always want to make sure you have fetched
> > everything. But with outgoing, as all we are doing is finding the merge
> > base, then at least with Git, indeed, it is only rarely that a change to
> > the upstream will render your local data invalid.
> >
> > I think this has to be VCS-specific.
> > For example, while vc-hg-incoming-revision also stores the revision at
> > the end of the remote branch locally, there is nothing equivalent to a
> > remote-tracking branch, so we can't readily make reference to the most
> > recent result of fetching from the remote.
> >
> > So I think the implementation can be to add an optional CACHED-OK
> > argument to the incoming-revision VC API function, which means that the
> > backend may choose not to fetch.
>
> Sounds ok. Or 'refresh' with reverse meaning.
>
> > On Sun 31 Aug 2025 at 08:15am +03, Eli Zaretskii wrote:
> >
> >> Skipping (or including) the "git fetch" step could be an optional
> >> feature. For example, it could be excluded by default, and included
> >> when the command is invoked with a prefix argument, on the assumption
> >> that in that case the probability of HEAD being outdated is higher.
> >> Users could then force "git fetch" for the current upstream by typing
> >> RET at the prompt.
> >
> > It's certainly very nice to provide a way to force a git fetch by just
> > typing RET at the prompt.
> > There could be a defcustom with options to never fetch, fetch when
> > prompting for the upstream location (the default), and to always fetch.
>
> A user option can work, though I'd start with trying to understand who
> is going to use it, and in what scenario.
>
> > I'm not sure about this assumption, though. Based on Dmitry's argument,
> > it doesn't seem to me any more likely that when the command is invoked
> > with a prefix argument, the probability that the remote-tracking
> > branches are *sufficiently* out-of-date is higher.
>
> Or we could use double-prefix for this specific purpose.
>
> But given that the user could also call vc-log-incoming to force that
> refresh, maybe an extra way to do the same might not be necessary.
>
Or they could simply call vc-update, or some other new command to run fetch.
It doesn't seem useful to me to combine fetch with this other command for
version control systems which don't require that. Fetch can just be a
separate command. No need to put it behind double-prefix.
>
[Message part 2 (text/html, inline)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Mon, 01 Sep 2025 08:43:01 GMT)
Full text and
rfc822 format available.
Message #221 received at 62940 <at> debbugs.gnu.org (full text, mbox):
Hello,
Thanks all. I've installed a change to no longer fetch for outgoing
commands with Git. We can consider a defcustom of one form or another
later as concrete user needs arise.
--
Sean Whitton
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#62940; Package
emacs.
(Mon, 01 Sep 2025 12:57:02 GMT)
Full text and
rfc822 format available.
Message #224 received at 62940 <at> debbugs.gnu.org (full text, mbox):
On 01/09/2025 11:42, Sean Whitton wrote:
> Thanks all. I've installed a change to no longer fetch for outgoing
> commands with Git. We can consider a defcustom of one form or another
> later as concrete user needs arise.
Works great, thank you.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org.
(Tue, 30 Sep 2025 11:24:09 GMT)
Full text and
rfc822 format available.
This bug report was last modified 60 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.