| *undo.txt* For Vim version 8.0. Last change: 2014 May 24 |
| |
| |
| 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| |
| |
| 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: |