"changed on disk" revert-buffer help text?

"changed on disk" revert-buffer help text?

[Bob Proulx]

Here is a very minor wording issue that makes me question what I think
I know.  Is it a wording problem?  Or is something more deep happening?

I often run into this when editing a file in a git repository and then
doing something with git such as switching branches or something.  In
that case the file is modified outside of emacs and emacs is detecting
and reporting this when I attempt to change the buffer.

The minibuffer correctly tells me of this case:

  myfile changed on disk; really edit the buffer? (y, n, r or C-h)

Then because I want help I C-h to print the associated help:

  You want to modify a buffer whose disk file has changed
  since you last read it in or saved it with this buffer.

  If you say `y' to go ahead and modify this buffer,
  you risk ruining the work of whoever rewrote the file.
  If you say `r' to revert, the contents of the buffer are refreshed
  from the file on disk.
  If you say `n', the change you started to make will be aborted.

  Usually, you should type `n' and then `\[revert-buffer]',
  to get the latest version of the file, then make the change again.

The 'r' command conveniently allows me to revert-buffer, usually what
I want to do, and then modify it.  That's great.

But then that last paragraph says, "Usually, you should type `n' and
then `\[revert-buffer]', to get the latest version of the file, then
make the change again."  Isn't that exactly what the 'r' command does?
Why isn't, "Usually you should type `r' to `\[revert-buffer]' to get
the latest version of the file, then make the change again." the text
there?  Is there some deeper something that is happening with 'r' that
is hinted at there that means we wouldn't want to "usally" use it?

Thanks,
Bob

Re: "changed on disk" revert-buffer help text?

[Narendra Joshi]

Bob Proulx <bob@proulx.com> writes:
> But then that last paragraph says, "Usually, you should type `n' and
> then `\[revert-buffer]', to get the latest version of the file, then
> make the change again."  Isn't that exactly what the 'r' command does?
> Why isn't, "Usually you should type `r' to `\[revert-buffer]' to get
> the latest version of the file, then make the change again." the text
> there?  Is there some deeper something that is happening with 'r' that
> is hinted at there that means we wouldn't want to "usally" use it?

This is what the code does:

#+begin_src 
(cond ((memq answer '(?? ?\C-h))
	       (ask-user-about-supersession-help)
	       (setq answer nil))
	      ((eq answer ?r)
	       ;; Ask for confirmation if buffer modified
	       (revert-buffer nil (not (buffer-modified-p)))
	       (signal 'file-supersession
		       (list "File reverted" fn)))
	      ((eq answer ?n)
	       (signal 'file-supersession
		       (list "File changed on disk" fn))))
#+end_src

So, nothing happens when we press ?n.

--
Narendra Joshi

Re: "changed on disk" revert-buffer help text?

[Bob Proulx]

Narendra Joshi wrote:
> Bob Proulx writes:
> > But then that last paragraph says, "Usually, you should type `n' and
> > then `\[revert-buffer]', to get the latest version of the file, then
> > make the change again."  Isn't that exactly what the 'r' command does?
> > Why isn't, "Usually you should type `r' to `\[revert-buffer]' to get
> > the latest version of the file, then make the change again." the text
> > there?  Is there some deeper something that is happening with 'r' that
> > is hinted at there that means we wouldn't want to "usally" use it?
> 
> This is what the code does:
>...
> 	      ((eq answer ?r)
> 	       ;; Ask for confirmation if buffer modified
> 	       (revert-buffer nil (not (buffer-modified-p)))
> 	       (signal 'file-supersession
> 		       (list "File reverted" fn)))

Thank you.  That confirms what I was thinking.

> So, nothing happens when we press ?n.

Yes but I was asking about ?r and why that would be different from
pressing 'n' and then M-x revert-buffer.  :-)

Thanks for the research.  I think that last paragraph in the help text
needs to be updated.  I will send in a bug ticket for exactly that as
soon as I get a little bit of free time.

Bob