GNU bug report logs - #38575
27.0.50; Document that `diff' arguments OLD and NEW can be buffers

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 38575 in the body.
You can then email your comments to 38575 AT debbugs.gnu.org in the normal way.

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

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

From: Phil Sainty <psainty <at> orcon.net.nz>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.0.50; Document that `diff' arguments OLD and NEW can be buffers
Date: Thu, 12 Dec 2019 19:46:40 +1300

The docstring for `diff' is:

    (diff OLD NEW &optional SWITCHES NO-ASYNC)

    Find and display the differences between OLD and NEW files.
    When called interactively, read NEW, then OLD, using the
    minibuffer.  The default for NEW is the current buffer’s file
    name, and the default for OLD is a backup file for NEW, if one
    exists.  If NO-ASYNC is non-nil, call diff synchronously.

    When called interactively with a prefix argument, prompt
    interactively for diff switches.  Otherwise, the switches
    specified in the variable ‘diff-switches’ are passed to the
    diff command.


However either (or both) of OLD and NEW may alternatively be buffers,
with temporary files automatically created as necessary.  This happens
via `diff-file-local-copy' called by `diff-no-select'.

This feature is utilised by `diff-buffer-with-file', and is far too
useful to be undocumented by `diff'.

I suggest the following additional paragraph:

    Non-interactively, OLD and NEW may each be buffers, in which
    case a temporary file will be used.


If that wording is ok, I can commit the change.


-Phil

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

From: Phil Sainty <psainty <at> orcon.net.nz>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: 27.0.50; Document that `diff' arguments OLD and NEW can be buffers
Date: Thu, 12 Dec 2019 20:44:15 +1300

This feature dates to the following commit, which I believe was
first released in 24.1.

Because this seems such a useful feature, I'm inclined to add a
NEWS entry as well, with the note "This change was made in Emacs
24.1, but wasn't documented until now."


-Phil



commit b2e4481906ec08e2c6072b6fe14dd1efca4784b9
Author: Stefan Monnier <monnier <at> iro.umontreal.ca>
Date:   Mon Nov 22 14:22:03 2010 -0500

    Cleanup diff-buffer-with-file.
    * lisp/vc/diff.el (diff-old-temp-file, diff-new-temp-file): Remove.
    (diff-sentinel): Get them as arguments instead.
    (diff-old-file, diff-new-file, diff-extra-args): Remove.
    (diff-file-local-copy, diff-better-file-name): New funs.
    (diff-no-select): Rename from diff-into-buffer.
    Support buffers additionally to files.  Move `buf' arg.  Don't 
display buf.
    Prefer closures to buffer-local variables.
    (diff): Adjust accordingly.
    (diff-buffer-with-file): Move from files.el.
    * lisp/files.el (diff-buffer-with-file): Move to vc/diff.el.
    (diff-buffer-internal): Remove.
    (diff-buffer-buffer): Remove.
    (save-some-buffers-action-alist): Use diff-no-select so as not to 
guess
    the buffer name used, and so as not to mess up windows and frames.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Phil Sainty <psainty <at> orcon.net.nz>
Cc: 38575 <at> debbugs.gnu.org
Subject: Re: bug#38575: 27.0.50;
 Document that `diff' arguments OLD and NEW can be buffers
Date: Thu, 12 Dec 2019 11:21:43 +0200

> Date: Thu, 12 Dec 2019 19:46:40 +1300
> From: Phil Sainty <psainty <at> orcon.net.nz>
> 
> This feature is utilised by `diff-buffer-with-file', and is far too
> useful to be undocumented by `diff'.

Agreed.

> I suggest the following additional paragraph:
> 
>      Non-interactively, OLD and NEW may each be buffers, in which
>      case a temporary file will be used.

Why is it important to mention the fact that we use temporary files in
this case?  It sounds like an implementation detail.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Phil Sainty <psainty <at> orcon.net.nz>
Cc: 38575 <at> debbugs.gnu.org
Subject: Re: bug#38575: 27.0.50;
 Document that `diff' arguments OLD and NEW can be buffers
Date: Thu, 12 Dec 2019 11:23:00 +0200

> Date: Thu, 12 Dec 2019 20:44:15 +1300
> From: Phil Sainty <psainty <at> orcon.net.nz>
> 
> This feature dates to the following commit, which I believe was
> first released in 24.1.
> 
> Because this seems such a useful feature, I'm inclined to add a
> NEWS entry as well, with the note "This change was made in Emacs
> 24.1, but wasn't documented until now."

Fine with me, thanks.

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

From: Phil Sainty <psainty <at> orcon.net.nz>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 38575 <at> debbugs.gnu.org
Subject: Re: bug#38575: 27.0.50; Document that `diff' arguments OLD and NEW
 can be buffers
Date: Thu, 12 Dec 2019 23:15:37 +1300

On 12/12/19 10:21 PM, Eli Zaretskii wrote:
>> I suggest the following additional paragraph:
>>
>>      Non-interactively, OLD and NEW may each be buffers, in which
>>      case a temporary file will be used.
> 
> Why is it important to mention the fact that we use temporary files
> in this case?  It sounds like an implementation detail.

It is, but I think it's a helpful detail to include, to eliminate
potential confusion regarding how a buffer can be a valid input, when
the rest of the description is about files.

The user might otherwise wonder whether Emacs is actually using the
external diff program in this case (vs using some internal functions
to process the buffer text directly to produce a diff).

I'm ok with omitting it if you're not convinced.


-Phil

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Phil Sainty <psainty <at> orcon.net.nz>
Cc: 38575 <at> debbugs.gnu.org
Subject: Re: bug#38575: 27.0.50; Document that `diff' arguments OLD and NEW
 can be buffers
Date: Thu, 12 Dec 2019 13:35:02 +0200

> Cc: 38575 <at> debbugs.gnu.org
> From: Phil Sainty <psainty <at> orcon.net.nz>
> Date: Thu, 12 Dec 2019 23:15:37 +1300
> 
> The user might otherwise wonder whether Emacs is actually using the
> external diff program in this case (vs using some internal functions
> to process the buffer text directly to produce a diff).

They have the sources to solve this confusion.

> I'm ok with omitting it if you're not convinced.

I'd prefer to omit that, because we may one day find a way of running
programs with input redirected from a buffer, or something.  Not a
strong opinion, though.

Thanks.

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

From: Phil Sainty <psainty <at> orcon.net.nz>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 38575 <at> debbugs.gnu.org
Subject: Re: bug#38575: 27.0.50; Document that `diff' arguments OLD and NEW
 can be buffers
Date: Sat, 14 Dec 2019 21:22:13 +1300

[Message part 1 (text/plain, inline)]

I ended up adding a `diff-buffers' command to provide better user
support for this feature.

Patch attached for review.


-Phil

[0001-New-command-diff-buffers.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Phil Sainty <psainty <at> orcon.net.nz>
Cc: 38575 <at> debbugs.gnu.org
Subject: Re: bug#38575: 27.0.50; Document that `diff' arguments OLD and NEW
 can be buffers
Date: Sat, 14 Dec 2019 11:03:40 +0200

> Cc: 38575 <at> debbugs.gnu.org
> From: Phil Sainty <psainty <at> orcon.net.nz>
> Date: Sat, 14 Dec 2019 21:22:13 +1300
> 
> I ended up adding a `diff-buffers' command to provide better user
> support for this feature.
> 
> Patch attached for review.

LGTM, thanks.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Phil Sainty <psainty <at> orcon.net.nz>, 38575 <at> debbugs.gnu.org
Subject: Re: bug#38575: 27.0.50; Document that `diff' arguments OLD and NEW
 can be buffers
Date: Fri, 21 Aug 2020 17:01:09 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> I ended up adding a `diff-buffers' command to provide better user
>> support for this feature.
>> 
>> Patch attached for review.
>
> LGTM, thanks.

Looks like this patch was applied at the time, but the bug report
remains open, so I'm closing it now.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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