diff options
Diffstat (limited to 'runtime/doc/undo.txt')
| -rw-r--r-- | runtime/doc/undo.txt | 412 |
1 files changed, 412 insertions, 0 deletions
diff --git a/runtime/doc/undo.txt b/runtime/doc/undo.txt new file mode 100644 index 0000000..b6c9809 --- /dev/null +++ b/runtime/doc/undo.txt @@ -0,0 +1,412 @@ +*undo.txt* For Vim version 8.1. Last change: 2019 Jan 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 through 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, except when +the owner of the undo file is the current user. 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| + +Note that text properties are not stored in the undo file. You can restore +text properties so long as a buffer is loaded, but you cannot restore them +from an undo file. Rationale: It would require the associated text property +types to be defined in exactly the same was as before, which cannot be +guaranteed. + +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:noet:ft=help:norl: |