bug#35290: 27.0.50; Outdated vc-revert documentation

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

bug#35290: 27.0.50; Outdated vc-revert documentation

Mauro Aranda
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.


Reply | Threaded
Open this post in threaded view
|

bug#35290: 27.0.50; Outdated vc-revert documentation

Mauro Aranda
Tags: patch

How about the following?

Best regards,
Mauro.

El lun., 15 abr. 2019 a las 12:59, Mauro Aranda (<[hidden email]>) 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.



0001-Update-vc-revert-documentation.patch (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

bug#35290: 27.0.50; Outdated vc-revert documentation

Eli Zaretskii
In reply to this post by Mauro Aranda
> From: Mauro Aranda <[hidden email]>
> 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.



Reply | Threaded
Open this post in threaded view
|

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.



Reply | Threaded
Open this post in threaded view
|

bug#35290: 27.0.50; Outdated vc-revert documentation

Mauro Aranda
In reply to this post by Eli Zaretskii
> 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.
Reply | Threaded
Open this post in threaded view
|

bug#35290: 27.0.50; Outdated vc-revert documentation

Eli Zaretskii
In reply to this post by Dmitry Gutov
> Cc: [hidden email]
> From: Dmitry Gutov <[hidden email]>
> 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.



Reply | Threaded
Open this post in threaded view
|

bug#35290: 27.0.50; Outdated vc-revert documentation

Eli Zaretskii
In reply to this post by Mauro Aranda
> From: Mauro Aranda <[hidden email]>
> Date: Mon, 15 Apr 2019 14:44:38 -0300
> Cc: [hidden email]
>
> 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.



Reply | Threaded
Open this post in threaded view
|

bug#35290: 27.0.50; Outdated vc-revert documentation

Dmitry Gutov
In reply to this post by Eli Zaretskii
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.



Reply | Threaded
Open this post in threaded view
|

bug#35290: 27.0.50; Outdated vc-revert documentation

Mauro Aranda
> 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.
Reply | Threaded
Open this post in threaded view
|

bug#35290: 27.0.50; Outdated vc-revert documentation

Eli Zaretskii
> From: Mauro Aranda <[hidden email]>
> Date: Mon, 15 Apr 2019 19:25:52 -0300
> Cc: [hidden email]
>
> > 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.