1*undo.txt* For Vim version 7.3. Last change: 2010 Jul 20 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Undo and redo *undo-redo* 8 9The basics are explained in section |02.5| of the user manual. 10 111. Undo and redo commands |undo-commands| 122. Two ways of undo |undo-two-ways| 133. Undo blocks |undo-blocks| 144. Undo branches |undo-branches| 155. Undo persistence |undo-persistence| 166. Remarks about undo |undo-remarks| 17 18============================================================================== 191. Undo and redo commands *undo-commands* 20 21<Undo> or *undo* *<Undo>* *u* 22u Undo [count] changes. {Vi: only one level} 23 24 *:u* *:un* *:undo* 25:u[ndo] Undo one change. {Vi: only one level} 26 *E830* 27:u[ndo] {N} Jump to after change number {N}. See |undo-branches| 28 for the meaning of {N}. {not in Vi} 29 30 *CTRL-R* 31CTRL-R Redo [count] changes which were undone. {Vi: redraw 32 screen} 33 34 *:red* *:redo* *redo* 35:red[o] Redo one change which was undone. {Vi: no redo} 36 37 *U* 38U Undo all latest changes on one line. {Vi: while not 39 moved off of it} 40 41The last changes are remembered. You can use the undo and redo commands above 42to revert the text to how it was before each change. You can also apply the 43changes again, getting back the text before the undo. 44 45The "U" command is treated by undo/redo just like any other command. Thus a 46"u" command undoes a "U" command and a 'CTRL-R' command redoes it again. When 47mixing "U", "u" and 'CTRL-R' you will notice that the "U" command will 48restore the situation of a line to before the previous "U" command. This may 49be confusing. Try it out to get used to it. 50The "U" command will always mark the buffer as changed. When "U" changes the 51buffer back to how it was without changes, it is still considered changed. 52Use "u" to undo changes until the buffer becomes unchanged. 53 54============================================================================== 552. Two ways of undo *undo-two-ways* 56 57How undo and redo commands work depends on the 'u' flag in 'cpoptions'. 58There is the Vim way ('u' excluded) and the vi-compatible way ('u' included). 59In the Vim way, "uu" undoes two changes. In the Vi-compatible way, "uu" does 60nothing (undoes an undo). 61 62'u' excluded, the Vim way: 63You can go back in time with the undo command. You can then go forward again 64with the redo command. If you make a new change after the undo command, 65the redo will not be possible anymore. 66 67'u' included, the Vi-compatible way: 68The undo command undoes the previous change, and also the previous undo command. 69The redo command repeats the previous undo command. It does NOT repeat a 70change command, use "." for that. 71 72Examples Vim way Vi-compatible way ~ 73"uu" two times undo no-op 74"u CTRL-R" no-op two times undo 75 76Rationale: Nvi uses the "." command instead of CTRL-R. Unfortunately, this 77 is not Vi compatible. For example "dwdwu." in Vi deletes two 78 words, in Nvi it does nothing. 79 80============================================================================== 813. Undo blocks *undo-blocks* 82 83One undo command normally undoes a typed command, no matter how many changes 84that command makes. This sequence of undo-able changes forms an undo block. 85Thus if the typed key(s) call a function, all the commands in the function are 86undone together. 87 88If you want to write a function or script that doesn't create a new undoable 89change but joins in with the previous change use this command: 90 91 *:undoj* *:undojoin* *E790* 92:undoj[oin] Join further changes with the previous undo block. 93 Warning: Use with care, it may prevent the user from 94 properly undoing changes. Don't use this after undo 95 or redo. 96 {not in Vi} 97 98This is most useful when you need to prompt the user halfway a change. For 99example in a function that calls |getchar()|. Do make sure that there was a 100related change before this that you must join with. 101 102This doesn't work by itself, because the next key press will start a new 103change again. But you can do something like this: > 104 105 :undojoin | delete 106 107After this an "u" command will undo the delete command and the previous 108change. 109 110To do the opposite, break a change into two undo blocks, in Insert mode use 111CTRL-G u. This is useful if you want an insert command to be undoable in 112parts. E.g., for each sentence. |i_CTRL-G_u| 113Setting the value of 'undolevels' also breaks undo. Even when the new value 114is equal to the old value. 115 116============================================================================== 1174. Undo branches *undo-branches* *undo-tree* 118 119Above we only discussed one line of undo/redo. But it is also possible to 120branch off. This happens when you undo a few changes and then make a new 121change. The undone changes become a branch. You can go to that branch with 122the following commands. 123 124This is explained in the user manual: |usr_32.txt|. 125 126 *:undol* *:undolist* 127:undol[ist] List the leafs in the tree of changes. Example: 128 number changes time ~ 129 4 10 10:34:11 130 18 4 11:01:46 131 132 The "number" column is the change number. This number 133 continuously increases and can be used to identify a 134 specific undo-able change, see |:undo|. 135 The "changes" column is the number of changes to this 136 leaf from the root of the tree. 137 The "time" column is the time this change was made. 138 For more details use the |undotree()| function. 139 140 *g-* 141g- Go to older text state. With a count repeat that many 142 times. {not in Vi} 143 *:ea* *:earlier* 144:earlier {count} Go to older text state {count} times. 145:earlier {N}s Go to older text state about {N} seconds before. 146:earlier {N}m Go to older text state about {N} minutes before. 147:earlier {N}h Go to older text state about {N} hours before. 148:earlier {N}d Go to older text state about {N} days before. 149 150:earlier {N}f Go to older text state {N} file writes before. 151 When changes were made since the laste write 152 ":earlier 1f" will revert the text to the state when 153 it was written. Otherwise it will go to the write 154 before that. 155 When at the state of the first file write, or when 156 the file was not written, ":earlier 1f" will go to 157 before the first change. 158 159 *g+* 160g+ Go to newer text state. With a count repeat that many 161 times. {not in Vi} 162 *:lat* *:later* 163:later {count} Go to newer text state {count} times. 164:later {N}s Go to newer text state about {N} seconds later. 165:later {N}m Go to newer text state about {N} minutes later. 166:later {N}h Go to newer text state about {N} hours later. 167:later {N}d Go to newer text state about {N} days later. 168 169:later {N}f Go to newer text state {N} file writes later. 170 When at the state of the last file write, ":later 1f" 171 will go to the newest text state. 172 173 174Note that text states will become unreachable when undo information is cleared 175for 'undolevels'. 176 177Don't be surprised when moving through time shows multiple changes to take 178place at a time. This happens when moving through the undo tree and then 179making a new change. 180 181EXAMPLE 182 183Start with this text: 184 one two three ~ 185 186Delete the first word by pressing "x" three times: 187 ne two three ~ 188 e two three ~ 189 two three ~ 190 191Now undo that by pressing "u" three times: 192 e two three ~ 193 ne two three ~ 194 one two three ~ 195 196Delete the second word by pressing "x" three times: 197 one wo three ~ 198 one o three ~ 199 one three ~ 200 201Now undo that by using "g-" three times: 202 one o three ~ 203 one wo three ~ 204 two three ~ 205 206You are now back in the first undo branch, after deleting "one". Repeating 207"g-" will now bring you back to the original text: 208 e two three ~ 209 ne two three ~ 210 one two three ~ 211 212Jump to the last change with ":later 1h": 213 one three ~ 214 215And back to the start again with ":earlier 1h": 216 one two three ~ 217 218 219Note that using "u" and CTRL-R will not get you to all possible text states 220while repeating "g-" and "g+" does. 221 222============================================================================== 2235. Undo persistence *undo-persistence* *persistent-undo* 224 225When unloading a buffer Vim normally destroys the tree of undos created for 226that buffer. By setting the 'undofile' option, Vim will automatically save 227your undo history when you write a file and restore undo history when you edit 228the file again. 229 230The 'undofile' option is checked after writing a file, before the BufWritePost 231autocommands. If you want to control what files to write undo information 232for, you can use a BufWritePre autocommand: > 233 au BufWritePre /tmp/* setlocal noundofile 234 235Vim saves undo trees in a separate undo file, one for each edited file, using 236a simple scheme that maps filesystem paths directly to undo files. Vim will 237detect if an undo file is no longer synchronized with the file it was written 238for (with a hash of the file contents) and ignore it when the file was changed 239after the undo file was written, to prevent corruption. 240 241Undo files are normally saved in the same directory as the file. This can be 242changed with the 'undodir' option. 243 244When the file is encrypted, the text in the undo file is also crypted. The 245same key and method is used. |encryption| 246 247You can also save and restore undo histories by using ":wundo" and ":rundo" 248respectively: 249 *:wundo* *:rundo* 250:wundo[!] {file} 251 Write undo history to {file}. 252 When {file} exists and it does not look like an undo file 253 (the magic number at the start of the file is wrong), then 254 this fails, unless the ! was added. 255 If it exists and does look like an undo file it is 256 overwritten. 257 {not in Vi} 258 259:rundo {file} Read undo history from {file}. 260 {not in Vi} 261 262You can use these in autocommands to explicitly specify the name of the 263history file. E.g.: > 264 265 au BufReadPost * call ReadUndo() 266 au BufWritePost * call WriteUndo() 267 func ReadUndo() 268 if filereadable(expand('%:h'). '/UNDO/' . expand('%:t')) 269 rundo %:h/UNDO/%:t 270 endif 271 endfunc 272 func WriteUndo() 273 let dirname = expand('%:h') . '/UNDO' 274 if !isdirectory(dirname) 275 call mkdir(dirname) 276 endif 277 wundo %:h/UNDO/%:t 278 endfunc 279 280You should keep 'undofile' off, otherwise you end up with two undo files for 281every write. 282 283You can use the |undofile()| function to find out the file name that Vim would 284use. 285 286Note that while reading/writing files and 'undofile' is set most errors will 287be silent, unless 'verbose' is set. With :wundo and :rundo you will get more 288error messages, e.g., when the file cannot be read or written. 289 290NOTE: undo files are never deleted by Vim. You need to delete them yourself. 291 292Reading an existing undo file may fail for several reasons: 293*E822* It cannot be opened, because the file permissions don't allow it. 294*E823* The magic number at the start of the file doesn't match. This usually 295 means it is not an undo file. 296*E824* The version number of the undo file indicates that it's written by a 297 newer version of Vim. You need that newer version to open it. Don't 298 write the buffer if you want to keep the undo info in the file. 299"File contents changed, cannot use undo info" 300 The file text differs from when the undo file was written. This means 301 the undo file cannot be used, it would corrupt the text. This also 302 happens when 'encoding' differs from when the undo file was written. 303*E825* The undo file does not contain valid contents and cannot be used. 304*E826* The undo file is encrypted but decryption failed. 305*E827* The undo file is encrypted but this version of Vim does not support 306 encryption. Open the file with another Vim. 307*E832* The undo file is encrypted but 'key' is not set, the text file is not 308 encrypted. This would happen if the text file was written by Vim 309 encrypted at first, and later overwritten by not encrypted text. 310 You probably want to delete this undo file. 311"Not reading undo file, owner differs" 312 The undo file is owned by someone else than the owner of the text 313 file. For safety the undo file is not used. 314 315Writing an undo file may fail for these reasons: 316*E828* The file to be written cannot be created. Perhaps you do not have 317 write permissions in the directory. 318"Cannot write undo file in any directory in 'undodir'" 319 None of the directories in 'undodir' can be used. 320"Will not overwrite with undo file, cannot read" 321 A file exists with the name of the undo file to be written, but it 322 cannot be read. You may want to delete this file or rename it. 323"Will not overwrite, this is not an undo file" 324 A file exists with the name of the undo file to be written, but it 325 does not start with the right magic number. You may want to delete 326 this file or rename it. 327"Skipping undo file write, noting to undo" 328 There is no undo information not be written, nothing has been changed 329 or 'undolevels' is negative. 330*E829* An error occurred while writing the undo file. You may want to try 331 again. 332 333============================================================================== 3346. Remarks about undo *undo-remarks* 335 336The number of changes that are remembered is set with the 'undolevels' option. 337If it is zero, the Vi-compatible way is always used. If it is negative no 338undo is possible. Use this if you are running out of memory. 339 340 *clear-undo* 341When you set 'undolevels' to -1 the undo information is not immediately 342cleared, this happens at the next change. To force clearing the undo 343information you can use these commands: > 344 :let old_undolevels = &undolevels 345 :set undolevels=-1 346 :exe "normal a \<BS>\<Esc>" 347 :let &undolevels = old_undolevels 348 :unlet old_undolevels 349 350Marks for the buffer ('a to 'z) are also saved and restored, together with the 351text. {Vi does this a little bit different} 352 353When all changes have been undone, the buffer is not considered to be changed. 354It is then possible to exit Vim with ":q" instead of ":q!" {not in Vi}. Note 355that this is relative to the last write of the file. Typing "u" after ":w" 356actually changes the buffer, compared to what was written, so the buffer is 357considered changed then. 358 359When manual |folding| is being used, the folds are not saved and restored. 360Only changes completely within a fold will keep the fold as it was, because 361the first and last line of the fold don't change. 362 363The numbered registers can also be used for undoing deletes. Each time you 364delete text, it is put into register "1. The contents of register "1 are 365shifted to "2, etc. The contents of register "9 are lost. You can now get 366back the most recent deleted text with the put command: '"1P'. (also, if the 367deleted text was the result of the last delete or copy operation, 'P' or 'p' 368also works as this puts the contents of the unnamed register). You can get 369back the text of three deletes ago with '"3P'. 370 371 *redo-register* 372If you want to get back more than one part of deleted text, you can use a 373special feature of the repeat command ".". It will increase the number of the 374register used. So if you first do ""1P", the following "." will result in a 375'"2P'. Repeating this will result in all numbered registers being inserted. 376 377Example: If you deleted text with 'dd....' it can be restored with 378 '"1P....'. 379 380If you don't know in which register the deleted text is, you can use the 381:display command. An alternative is to try the first register with '"1P', and 382if it is not what you want do 'u.'. This will remove the contents of the 383first put, and repeat the put command for the second register. Repeat the 384'u.' until you got what you want. 385 386 vim:tw=78:ts=8:ft=help:norl: 387