405 lines
16 KiB
Text
405 lines
16 KiB
Text
*undo.txt* For Vim version 7.4. Last change: 2012 Mar 04
|
|
|
|
|
|
VIM REFERENCE MANUAL by Bram Moolenaar
|
|
|
|
|
|
Undo and redo *undo-redo*
|
|
|
|
The basics are explained in section |02.5| of the user manual.
|
|
|
|
1. Undo and redo commands |undo-commands|
|
|
2. Two ways of undo |undo-two-ways|
|
|
3. Undo blocks |undo-blocks|
|
|
4. Undo branches |undo-branches|
|
|
5. Undo persistence |undo-persistence|
|
|
6. Remarks about undo |undo-remarks|
|
|
|
|
==============================================================================
|
|
1. Undo and redo commands *undo-commands*
|
|
|
|
<Undo> or *undo* *<Undo>* *u*
|
|
u Undo [count] changes. {Vi: only one level}
|
|
|
|
*:u* *:un* *:undo*
|
|
:u[ndo] Undo one change. {Vi: only one level}
|
|
*E830*
|
|
:u[ndo] {N} Jump to after change number {N}. See |undo-branches|
|
|
for the meaning of {N}. {not in Vi}
|
|
|
|
*CTRL-R*
|
|
CTRL-R Redo [count] changes which were undone. {Vi: redraw
|
|
screen}
|
|
|
|
*:red* *:redo* *redo*
|
|
:red[o] Redo one change which was undone. {Vi: no redo}
|
|
|
|
*U*
|
|
U Undo all latest changes on one line, the line where
|
|
the latest change was made. |U| itself also counts as
|
|
a change, and thus |U| undoes a previous |U|.
|
|
{Vi: while not moved off of the last modified line}
|
|
|
|
The last changes are remembered. You can use the undo and redo commands above
|
|
to revert the text to how it was before each change. You can also apply the
|
|
changes again, getting back the text before the undo.
|
|
|
|
The "U" command is treated by undo/redo just like any other command. Thus a
|
|
"u" command undoes a "U" command and a 'CTRL-R' command redoes it again. When
|
|
mixing "U", "u" and 'CTRL-R' you will notice that the "U" command will
|
|
restore the situation of a line to before the previous "U" command. This may
|
|
be confusing. Try it out to get used to it.
|
|
The "U" command will always mark the buffer as changed. When "U" changes the
|
|
buffer back to how it was without changes, it is still considered changed.
|
|
Use "u" to undo changes until the buffer becomes unchanged.
|
|
|
|
==============================================================================
|
|
2. Two ways of undo *undo-two-ways*
|
|
|
|
How undo and redo commands work depends on the 'u' flag in 'cpoptions'.
|
|
There is the Vim way ('u' excluded) and the vi-compatible way ('u' included).
|
|
In the Vim way, "uu" undoes two changes. In the Vi-compatible way, "uu" does
|
|
nothing (undoes an undo).
|
|
|
|
'u' excluded, the Vim way:
|
|
You can go back in time with the undo command. You can then go forward again
|
|
with the redo command. If you make a new change after the undo command,
|
|
the redo will not be possible anymore.
|
|
|
|
'u' included, the Vi-compatible way:
|
|
The undo command undoes the previous change, and also the previous undo command.
|
|
The redo command repeats the previous undo command. It does NOT repeat a
|
|
change command, use "." for that.
|
|
|
|
Examples Vim way Vi-compatible way ~
|
|
"uu" two times undo no-op
|
|
"u CTRL-R" no-op two times undo
|
|
|
|
Rationale: Nvi uses the "." command instead of CTRL-R. Unfortunately, this
|
|
is not Vi compatible. For example "dwdwu." in Vi deletes two
|
|
words, in Nvi it does nothing.
|
|
|
|
==============================================================================
|
|
3. Undo blocks *undo-blocks*
|
|
|
|
One undo command normally undoes a typed command, no matter how many changes
|
|
that command makes. This sequence of undo-able changes forms an undo block.
|
|
Thus if the typed key(s) call a function, all the commands in the function are
|
|
undone together.
|
|
|
|
If you want to write a function or script that doesn't create a new undoable
|
|
change but joins in with the previous change use this command:
|
|
|
|
*:undoj* *:undojoin* *E790*
|
|
:undoj[oin] Join further changes with the previous undo block.
|
|
Warning: Use with care, it may prevent the user from
|
|
properly undoing changes. Don't use this after undo
|
|
or redo.
|
|
{not in Vi}
|
|
|
|
This is most useful when you need to prompt the user halfway a change. For
|
|
example in a function that calls |getchar()|. Do make sure that there was a
|
|
related change before this that you must join with.
|
|
|
|
This doesn't work by itself, because the next key press will start a new
|
|
change again. But you can do something like this: >
|
|
|
|
:undojoin | delete
|
|
|
|
After this an "u" command will undo the delete command and the previous
|
|
change.
|
|
|
|
To do the opposite, break a change into two undo blocks, in Insert mode use
|
|
CTRL-G u. This is useful if you want an insert command to be undoable in
|
|
parts. E.g., for each sentence. |i_CTRL-G_u|
|
|
Setting the value of 'undolevels' also breaks undo. Even when the new value
|
|
is equal to the old value.
|
|
|
|
==============================================================================
|
|
4. Undo branches *undo-branches* *undo-tree*
|
|
|
|
Above we only discussed one line of undo/redo. But it is also possible to
|
|
branch off. This happens when you undo a few changes and then make a new
|
|
change. The undone changes become a branch. You can go to that branch with
|
|
the following commands.
|
|
|
|
This is explained in the user manual: |usr_32.txt|.
|
|
|
|
*:undol* *:undolist*
|
|
:undol[ist] List the leafs in the tree of changes. Example:
|
|
number changes when saved ~
|
|
88 88 2010/01/04 14:25:53
|
|
108 107 08/07 12:47:51
|
|
136 46 13:33:01 7
|
|
166 164 3 seconds ago
|
|
|
|
The "number" column is the change number. This number
|
|
continuously increases and can be used to identify a
|
|
specific undo-able change, see |:undo|.
|
|
The "changes" column is the number of changes to this
|
|
leaf from the root of the tree.
|
|
The "when" column is the date and time when this
|
|
change was made. The four possible formats are:
|
|
N seconds ago
|
|
HH:MM:SS hour, minute, seconds
|
|
MM/DD HH:MM:SS idem, with month and day
|
|
YYYY/MM/DD HH:MM:SS idem, with year
|
|
The "saved" column specifies, if this change was
|
|
written to disk and which file write it was. This can
|
|
be used with the |:later| and |:earlier| commands.
|
|
For more details use the |undotree()| function.
|
|
|
|
*g-*
|
|
g- Go to older text state. With a count repeat that many
|
|
times. {not in Vi}
|
|
*:ea* *:earlier*
|
|
:earlier {count} Go to older text state {count} times.
|
|
:earlier {N}s Go to older text state about {N} seconds before.
|
|
:earlier {N}m Go to older text state about {N} minutes before.
|
|
:earlier {N}h Go to older text state about {N} hours before.
|
|
:earlier {N}d Go to older text state about {N} days before.
|
|
|
|
:earlier {N}f Go to older text state {N} file writes before.
|
|
When changes were made since the last write
|
|
":earlier 1f" will revert the text to the state when
|
|
it was written. Otherwise it will go to the write
|
|
before that.
|
|
When at the state of the first file write, or when
|
|
the file was not written, ":earlier 1f" will go to
|
|
before the first change.
|
|
|
|
*g+*
|
|
g+ Go to newer text state. With a count repeat that many
|
|
times. {not in Vi}
|
|
*:lat* *:later*
|
|
:later {count} Go to newer text state {count} times.
|
|
:later {N}s Go to newer text state about {N} seconds later.
|
|
:later {N}m Go to newer text state about {N} minutes later.
|
|
:later {N}h Go to newer text state about {N} hours later.
|
|
:later {N}d Go to newer text state about {N} days later.
|
|
|
|
:later {N}f Go to newer text state {N} file writes later.
|
|
When at the state of the last file write, ":later 1f"
|
|
will go to the newest text state.
|
|
|
|
|
|
Note that text states will become unreachable when undo information is cleared
|
|
for 'undolevels'.
|
|
|
|
Don't be surprised when moving through time shows multiple changes to take
|
|
place at a time. This happens when moving through the undo tree and then
|
|
making a new change.
|
|
|
|
EXAMPLE
|
|
|
|
Start with this text:
|
|
one two three ~
|
|
|
|
Delete the first word by pressing "x" three times:
|
|
ne two three ~
|
|
e two three ~
|
|
two three ~
|
|
|
|
Now undo that by pressing "u" three times:
|
|
e two three ~
|
|
ne two three ~
|
|
one two three ~
|
|
|
|
Delete the second word by pressing "x" three times:
|
|
one wo three ~
|
|
one o three ~
|
|
one three ~
|
|
|
|
Now undo that by using "g-" three times:
|
|
one o three ~
|
|
one wo three ~
|
|
two three ~
|
|
|
|
You are now back in the first undo branch, after deleting "one". Repeating
|
|
"g-" will now bring you back to the original text:
|
|
e two three ~
|
|
ne two three ~
|
|
one two three ~
|
|
|
|
Jump to the last change with ":later 1h":
|
|
one three ~
|
|
|
|
And back to the start again with ":earlier 1h":
|
|
one two three ~
|
|
|
|
|
|
Note that using "u" and CTRL-R will not get you to all possible text states
|
|
while repeating "g-" and "g+" does.
|
|
|
|
==============================================================================
|
|
5. Undo persistence *undo-persistence* *persistent-undo*
|
|
|
|
When unloading a buffer Vim normally destroys the tree of undos created for
|
|
that buffer. By setting the 'undofile' option, Vim will automatically save
|
|
your undo history when you write a file and restore undo history when you edit
|
|
the file again.
|
|
|
|
The 'undofile' option is checked after writing a file, before the BufWritePost
|
|
autocommands. If you want to control what files to write undo information
|
|
for, you can use a BufWritePre autocommand: >
|
|
au BufWritePre /tmp/* setlocal noundofile
|
|
|
|
Vim saves undo trees in a separate undo file, one for each edited file, using
|
|
a simple scheme that maps filesystem paths directly to undo files. Vim will
|
|
detect if an undo file is no longer synchronized with the file it was written
|
|
for (with a hash of the file contents) and ignore it when the file was changed
|
|
after the undo file was written, to prevent corruption. An undo file is also
|
|
ignored if its owner differs from the owner of the edited file. Set 'verbose'
|
|
to get a message about that when opening a file.
|
|
|
|
Undo files are normally saved in the same directory as the file. This can be
|
|
changed with the 'undodir' option.
|
|
|
|
When the file is encrypted, the text in the undo file is also crypted. The
|
|
same key and method is used. |encryption|
|
|
|
|
You can also save and restore undo histories by using ":wundo" and ":rundo"
|
|
respectively:
|
|
*:wundo* *:rundo*
|
|
:wundo[!] {file}
|
|
Write undo history to {file}.
|
|
When {file} exists and it does not look like an undo file
|
|
(the magic number at the start of the file is wrong), then
|
|
this fails, unless the ! was added.
|
|
If it exists and does look like an undo file it is
|
|
overwritten. If there is no undo-history, nothing will be
|
|
written.
|
|
Implementation detail: Overwriting happens by first deleting
|
|
the existing file and then creating a new file with the same
|
|
name. So it is not possible to overwrite an existing undofile
|
|
in a write-protected directory.
|
|
{not in Vi}
|
|
|
|
:rundo {file} Read undo history from {file}.
|
|
{not in Vi}
|
|
|
|
You can use these in autocommands to explicitly specify the name of the
|
|
history file. E.g.: >
|
|
|
|
au BufReadPost * call ReadUndo()
|
|
au BufWritePost * call WriteUndo()
|
|
func ReadUndo()
|
|
if filereadable(expand('%:h'). '/UNDO/' . expand('%:t'))
|
|
rundo %:h/UNDO/%:t
|
|
endif
|
|
endfunc
|
|
func WriteUndo()
|
|
let dirname = expand('%:h') . '/UNDO'
|
|
if !isdirectory(dirname)
|
|
call mkdir(dirname)
|
|
endif
|
|
wundo %:h/UNDO/%:t
|
|
endfunc
|
|
|
|
You should keep 'undofile' off, otherwise you end up with two undo files for
|
|
every write.
|
|
|
|
You can use the |undofile()| function to find out the file name that Vim would
|
|
use.
|
|
|
|
Note that while reading/writing files and 'undofile' is set most errors will
|
|
be silent, unless 'verbose' is set. With :wundo and :rundo you will get more
|
|
error messages, e.g., when the file cannot be read or written.
|
|
|
|
NOTE: undo files are never deleted by Vim. You need to delete them yourself.
|
|
|
|
Reading an existing undo file may fail for several reasons:
|
|
*E822* It cannot be opened, because the file permissions don't allow it.
|
|
*E823* The magic number at the start of the file doesn't match. This usually
|
|
means it is not an undo file.
|
|
*E824* The version number of the undo file indicates that it's written by a
|
|
newer version of Vim. You need that newer version to open it. Don't
|
|
write the buffer if you want to keep the undo info in the file.
|
|
"File contents changed, cannot use undo info"
|
|
The file text differs from when the undo file was written. This means
|
|
the undo file cannot be used, it would corrupt the text. This also
|
|
happens when 'encoding' differs from when the undo file was written.
|
|
*E825* The undo file does not contain valid contents and cannot be used.
|
|
*E826* The undo file is encrypted but decryption failed.
|
|
*E827* The undo file is encrypted but this version of Vim does not support
|
|
encryption. Open the file with another Vim.
|
|
*E832* The undo file is encrypted but 'key' is not set, the text file is not
|
|
encrypted. This would happen if the text file was written by Vim
|
|
encrypted at first, and later overwritten by not encrypted text.
|
|
You probably want to delete this undo file.
|
|
"Not reading undo file, owner differs"
|
|
The undo file is owned by someone else than the owner of the text
|
|
file. For safety the undo file is not used.
|
|
|
|
Writing an undo file may fail for these reasons:
|
|
*E828* The file to be written cannot be created. Perhaps you do not have
|
|
write permissions in the directory.
|
|
"Cannot write undo file in any directory in 'undodir'"
|
|
None of the directories in 'undodir' can be used.
|
|
"Will not overwrite with undo file, cannot read"
|
|
A file exists with the name of the undo file to be written, but it
|
|
cannot be read. You may want to delete this file or rename it.
|
|
"Will not overwrite, this is not an undo file"
|
|
A file exists with the name of the undo file to be written, but it
|
|
does not start with the right magic number. You may want to delete
|
|
this file or rename it.
|
|
"Skipping undo file write, nothing to undo"
|
|
There is no undo information to be written, nothing has been changed
|
|
or 'undolevels' is negative.
|
|
*E829* An error occurred while writing the undo file. You may want to try
|
|
again.
|
|
|
|
==============================================================================
|
|
6. Remarks about undo *undo-remarks*
|
|
|
|
The number of changes that are remembered is set with the 'undolevels' option.
|
|
If it is zero, the Vi-compatible way is always used. If it is negative no
|
|
undo is possible. Use this if you are running out of memory.
|
|
|
|
*clear-undo*
|
|
When you set 'undolevels' to -1 the undo information is not immediately
|
|
cleared, this happens at the next change. To force clearing the undo
|
|
information you can use these commands: >
|
|
:let old_undolevels = &undolevels
|
|
:set undolevels=-1
|
|
:exe "normal a \<BS>\<Esc>"
|
|
:let &undolevels = old_undolevels
|
|
:unlet old_undolevels
|
|
|
|
Marks for the buffer ('a to 'z) are also saved and restored, together with the
|
|
text. {Vi does this a little bit different}
|
|
|
|
When all changes have been undone, the buffer is not considered to be changed.
|
|
It is then possible to exit Vim with ":q" instead of ":q!" {not in Vi}. Note
|
|
that this is relative to the last write of the file. Typing "u" after ":w"
|
|
actually changes the buffer, compared to what was written, so the buffer is
|
|
considered changed then.
|
|
|
|
When manual |folding| is being used, the folds are not saved and restored.
|
|
Only changes completely within a fold will keep the fold as it was, because
|
|
the first and last line of the fold don't change.
|
|
|
|
The numbered registers can also be used for undoing deletes. Each time you
|
|
delete text, it is put into register "1. The contents of register "1 are
|
|
shifted to "2, etc. The contents of register "9 are lost. You can now get
|
|
back the most recent deleted text with the put command: '"1P'. (also, if the
|
|
deleted text was the result of the last delete or copy operation, 'P' or 'p'
|
|
also works as this puts the contents of the unnamed register). You can get
|
|
back the text of three deletes ago with '"3P'.
|
|
|
|
*redo-register*
|
|
If you want to get back more than one part of deleted text, you can use a
|
|
special feature of the repeat command ".". It will increase the number of the
|
|
register used. So if you first do ""1P", the following "." will result in a
|
|
'"2P'. Repeating this will result in all numbered registers being inserted.
|
|
|
|
Example: If you deleted text with 'dd....' it can be restored with
|
|
'"1P....'.
|
|
|
|
If you don't know in which register the deleted text is, you can use the
|
|
:display command. An alternative is to try the first register with '"1P', and
|
|
if it is not what you want do 'u.'. This will remove the contents of the
|
|
first put, and repeat the put command for the second register. Repeat the
|
|
'u.' until you got what you want.
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|