bug#35290: 27.0.50; Outdated vc-revert documentation

bug#35290: 27.0.50; Outdated vc-revert documentation

[Mauro Aranda]

[-- Attachment #1: Type: text/plain, Size: 541 bytes --]

In the same spirit as Bug#33084 [1], the documentation of vc-revert is
outdated.

1) C-h r
2) m VC Undo

Read this sentence:
Note that ‘C-x v u’ cannot be reversed with the usual undo commands
(see Undo), so use it with care.

To check it is outdated:
1) emacs -Q
2) C-x C-f FILE-UNDER-VERSION-CONTROL
3) Make some changes and then C-x C-s
4) Revert: C-x v u
5) Confirm: yes RET
6) After reverting is done, type C-/
7) Observe that you got your changes back.

[1]: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=33084

[-- Attachment #2: Type: text/html, Size: 761 bytes --]

bug#35290: 27.0.50; Outdated vc-revert documentation

[Mauro Aranda]

[-- Attachment #1.1: Type: text/plain, Size: 741 bytes --]

Tags: patch

How about the following?

Best regards,
Mauro.

El lun., 15 abr. 2019 a las 12:59, Mauro Aranda (<maurooaranda@gmail.com>)
escribió:

> In the same spirit as Bug#33084 [1], the documentation of vc-revert is
> outdated.
>
> 1) C-h r
> 2) m VC Undo
>
> Read this sentence:
> Note that ‘C-x v u’ cannot be reversed with the usual undo commands
> (see Undo), so use it with care.
>
> To check it is outdated:
> 1) emacs -Q
> 2) C-x C-f FILE-UNDER-VERSION-CONTROL
> 3) Make some changes and then C-x C-s
> 4) Revert: C-x v u
> 5) Confirm: yes RET
> 6) After reverting is done, type C-/
> 7) Observe that you got your changes back.
>
> [1]: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=33084
>
>

[-- Attachment #1.2: Type: text/html, Size: 1280 bytes --]

[-- Attachment #2: 0001-Update-vc-revert-documentation.patch --]
[-- Type: text/x-patch, Size: 1311 bytes --]

From 6a74521e9ab8211f03a3e3cc6e941c2abd3d8e47 Mon Sep 17 00:00:00 2001
From: Mauro Aranda <maurooaranda@gmail.com>
Date: Mon, 15 Apr 2019 12:58:36 -0300
Subject: [PATCH] Update vc-revert documentation

* doc/emacs/maintaining.texi (VC Undo): Document that it is possible
to use undo commands after vc-revert.  (Bug#35290)
---
 doc/emacs/maintaining.texi | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index fd0119e..6f10033 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1093,8 +1093,9 @@ VC Undo
 If you agree, the fileset is reverted.  If you don't want @kbd{C-x v
 u} to show a diff, set the variable @code{vc-revert-show-diff} to
 @code{nil} (you can still view the diff directly with @kbd{C-x v =};
-@pxref{Old Revisions}).  Note that @kbd{C-x v u} cannot be reversed
-with the usual undo commands (@pxref{Undo}), so use it with care.
+@pxref{Old Revisions}).  Because reverting acts like a single
+modification of the buffer contents, it is possible to bring all
+the reverted changes back with a single @code{undo} command (@pxref{Undo}).
 
   On locking-based version control systems, @kbd{C-x v u} leaves files
 unlocked; you must lock again to resume editing.  You can also use
-- 
2.7.4

bug#35290: 27.0.50; Outdated vc-revert documentation

[Eli Zaretskii]

> From: Mauro Aranda <maurooaranda@gmail.com>
> Date: Mon, 15 Apr 2019 12:54:45 -0300
> 
> 1) C-h r
> 2) m VC Undo
> 
> Read this sentence:
> Note that ‘C-x v u’ cannot be reversed with the usual undo commands
> (see Undo), so use it with care.
> 
> To check it is outdated:
> 1) emacs -Q
> 2) C-x C-f FILE-UNDER-VERSION-CONTROL
> 3) Make some changes and then C-x C-s
> 4) Revert: C-x v u
> 5) Confirm: yes RET
> 6) After reverting is done, type C-/
> 7) Observe that you got your changes back.

I believe this is a misunderstanding due to the inherent ambiguity of
"undo" in this context.  The text wants to say that you cannot undo
the effect in the repository, not in the buffer that visits the file.

Thanks.

bug#35290: 27.0.50; Outdated vc-revert documentation

[Dmitry Gutov]

On 15.04.2019 19:14, Eli Zaretskii wrote:
> The text wants to say that you cannot undo
> the effect in the repository, not in the buffer that visits the file.

What is the effect you're referring to? vc-revert doesn't call 'git 
revert' or anything like it.

bug#35290: 27.0.50; Outdated vc-revert documentation

[Mauro Aranda]

[-- Attachment #1: Type: text/plain, Size: 435 bytes --]

> I believe this is a misunderstanding due to the inherent ambiguity of
> "undo" in this context.  The text wants to say that you cannot undo
> the effect in the repository, not in the buffer that visits the file.

Hello Eli, thanks for your quick answer.

I'm not fully convinced, though.  It isn't clear to me why is worth
mentioning undo commands, if the text isn't about undoing changes
in the buffer itself.

Best regards,
Mauro.

[-- Attachment #2: Type: text/html, Size: 649 bytes --]

bug#35290: 27.0.50; Outdated vc-revert documentation

[Eli Zaretskii]

> Cc: 35290@debbugs.gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 15 Apr 2019 20:16:39 +0300
> 
> On 15.04.2019 19:14, Eli Zaretskii wrote:
> > The text wants to say that you cannot undo
> > the effect in the repository, not in the buffer that visits the file.
> 
> What is the effect you're referring to? vc-revert doesn't call 'git 
> revert' or anything like it.

Another misunderstanding: I said "repository", but meant both the
history part and the working tree part of it.

bug#35290: 27.0.50; Outdated vc-revert documentation

[Eli Zaretskii]

> From: Mauro Aranda <maurooaranda@gmail.com>
> Date: Mon, 15 Apr 2019 14:44:38 -0300
> Cc: 35290@debbugs.gnu.org
> 
> I'm not fully convinced, though.  It isn't clear to me why is worth
> mentioning undo commands

Because the section is called "VC Undo", I guess.

bug#35290: 27.0.50; Outdated vc-revert documentation

[Dmitry Gutov]

On 15.04.2019 21:19, Eli Zaretskii wrote:

>> On 15.04.2019 19:14, Eli Zaretskii wrote:
>>> The text wants to say that you cannot undo
>>> the effect in the repository, not in the buffer that visits the file.
>>
>> What is the effect you're referring to? vc-revert doesn't call 'git
>> revert' or anything like it.
> 
> Another misunderstanding: I said "repository", but meant both the
> history part and the working tree part of it.

You can undo the working tree part of it with M-x undo and saving the file.

I'm fairly sure the report is correct, and the phrasing in the manual is 
referring to the situation where, not too long ago, vc-revert cleared 
the buffer undo history. It does not do that anymore, it's just one more 
change now.

bug#35290: 27.0.50; Outdated vc-revert documentation

[Mauro Aranda]

[-- Attachment #1: Type: text/plain, Size: 659 bytes --]

> Because the section is called "VC Undo", I guess.

OK.  But I fail to see a reason why a user, after reading the Undo
section, would expect that M-x undo acts upon anything that is not
buffer text.  That is what made me think (perhaps wrongly) that the
sentence is about the old behavior of revert-buffer.

At the least, I think the documentation could be improved.  Some of the
things vc-revert does can be reversed (e.g., bring back the reverted
changes in the affected buffers) and other changes cannot (or might not,
I'm not sure of the right wording here).  If that is correct, then both the
current text and my proposed patch fail to make that clear.

[-- Attachment #2: Type: text/html, Size: 840 bytes --]

bug#35290: 27.0.50; Outdated vc-revert documentation

[Eli Zaretskii]

> From: Mauro Aranda <maurooaranda@gmail.com>
> Date: Mon, 15 Apr 2019 19:25:52 -0300
> Cc: 35290@debbugs.gnu.org
> 
> > Because the section is called "VC Undo", I guess.
> 
> OK.  But I fail to see a reason why a user, after reading the Undo
> section, would expect that M-x undo acts upon anything that is not
> buffer text.  That is what made me think (perhaps wrongly) that the
> sentence is about the old behavior of revert-buffer.
> 
> At the least, I think the documentation could be improved.  Some of the
> things vc-revert does can be reversed (e.g., bring back the reverted
> changes in the affected buffers) and other changes cannot (or might not,
> I'm not sure of the right wording here).  If that is correct, then both the
> current text and my proposed patch fail to make that clear.

OK, I simply removed that sentence from the manual.

Thanks.