blob: 1ed2ecd05a17871422a8428de95e9d151def721a [file] [log] [blame]
Bram Moolenaarfff2bee2010-05-15 13:56:02 +02001*undo.txt* For Vim version 7.3a. Last change: 2009 Apr 12
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
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|
Bram Moolenaare224ffa2006-03-01 00:01:28 +0000133. Undo blocks |undo-blocks|
Bram Moolenaar1f4d4de2006-03-14 23:00:46 +0000144. Undo branches |undo-branches|
Bram Moolenaar55debbe2010-05-23 23:34:36 +0200155. Undo persistence |undo-persistence|
166. Remarks about undo |undo-remarks|
Bram Moolenaar071d4272004-06-13 20:20:40 +000017
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}
Bram Moolenaar55debbe2010-05-23 23:34:36 +020026 *E830*
Bram Moolenaarefd2bf12006-03-16 21:41:35 +000027:u[ndo] {N} Jump to after change number {N}. See |undo-branches|
28 for the meaning of {N}. {not in Vi}
29
Bram Moolenaar071d4272004-06-13 20:20:40 +000030 *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==============================================================================
Bram Moolenaare224ffa2006-03-01 00:01:28 +0000813. 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
Bram Moolenaar57657d82006-04-21 22:12:41 +000091 *:undoj* *:undojoin* *E790*
Bram Moolenaare224ffa2006-03-01 00:01:28 +000092:undoj[oin] Join further changes with the previous undo block.
93 Warning: Use with care, it may prevent the user from
Bram Moolenaar57657d82006-04-21 22:12:41 +000094 properly undoing changes. Don't use this after undo
95 or redo.
Bram Moolenaare224ffa2006-03-01 00:01:28 +000096 {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
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100110To 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|
Bram Moolenaar55debbe2010-05-23 23:34:36 +0200113Setting the value of 'undolevels' also breaks undo. Even when the new value
114is equal to the old value.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100115
Bram Moolenaare224ffa2006-03-01 00:01:28 +0000116==============================================================================
Bram Moolenaar18144c82006-04-12 21:52:12 +00001174. Undo branches *undo-branches* *undo-tree*
Bram Moolenaar1f4d4de2006-03-14 23:00:46 +0000118
Bram Moolenaar76916e62006-03-21 21:23:25 +0000119Above 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.
Bram Moolenaar1f4d4de2006-03-14 23:00:46 +0000123
Bram Moolenaarc01140a2006-03-24 22:21:52 +0000124This is explained in the user manual: |usr_32.txt|.
Bram Moolenaar1f4d4de2006-03-14 23:00:46 +0000125
Bram Moolenaarefd2bf12006-03-16 21:41:35 +0000126 *:undol* *:undolist*
127:undol[ist] List the leafs in the tree of changes. Example:
128 number changes time ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000129 4 10 10:34:11
130 18 4 11:01:46
Bram Moolenaarefd2bf12006-03-16 21:41:35 +0000131
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.
Bram Moolenaara800b422010-06-27 01:15:55 +0200138 For more details use the |undotree()| function.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +0000139
Bram Moolenaar1f4d4de2006-03-14 23:00:46 +0000140 *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
149 *g+*
150g+ Go to newer text state. With a count repeat that many
151 times. {not in Vi}
152 *:lat* *:later*
153:later {count} Go to newer text state {count} times.
154:later {N}s Go to newer text state about {N} seconds later.
155:later {N}m Go to newer text state about {N} minutes later.
156:later {N}h Go to newer text state about {N} hours later.
157
Bram Moolenaarefd2bf12006-03-16 21:41:35 +0000158
Bram Moolenaar1f4d4de2006-03-14 23:00:46 +0000159Note that text states will become unreachable when undo information is cleared
160for 'undolevels'.
161
162Don't be surprised when moving through time shows multiple changes to take
163place at a time. This happens when moving through the undo tree and then
164making a new change.
165
166EXAMPLE
167
168Start with this text:
169 one two three ~
170
171Delete the first word by pressing "x" three times:
172 ne two three ~
173 e two three ~
174 two three ~
175
176Now undo that by pressing "u" three times:
177 e two three ~
178 ne two three ~
179 one two three ~
180
181Delete the second word by pressing "x" three times:
182 one wo three ~
183 one o three ~
184 one three ~
185
186Now undo that by using "g-" three times:
187 one o three ~
188 one wo three ~
Bram Moolenaar1f4d4de2006-03-14 23:00:46 +0000189 two three ~
190
191You are now back in the first undo branch, after deleting "one". Repeating
192"g-" will now bring you back to the original text:
193 e two three ~
194 ne two three ~
195 one two three ~
196
197Jump to the last change with ":later 1h":
198 one three ~
199
200And back to the start again with ":earlier 1h":
201 one two three ~
202
203
204Note that using "u" and CTRL-R will not get you to all possible text states
205while repeating "g-" and "g+" does.
206
207==============================================================================
Bram Moolenaar55debbe2010-05-23 23:34:36 +02002085. Undo persistence *undo-persistence* *persistent-undo*
209
210When unloading a buffer Vim normally destroys the tree of undos created for
211that buffer. By setting the 'undofile' option, Vim will automatically save
212your undo history when you write a file and restore undo history when you edit
213the file again.
214
215The 'undofile' option is checked after writing a file, before the BufWritePost
216autocommands. If you want to control what files to write undo information
217for, you can use a BufWritePre autocommand: >
218 au BufWritePre /tmp/* setlocal noundofile
219
220Vim saves undo trees in a separate undo file, one for each edited file, using
221a simple scheme that maps filesystem paths directly to undo files. Vim will
222detect if an undo file is no longer synchronized with the file it was written
223for (with a hash of the file contents) and ignore it when the file was changed
224after the undo file was written, to prevent corruption.
225
226Undo files are normally saved in the same directory as the file. This can be
227changed with the 'undodir' option.
228
Bram Moolenaara3ff49f2010-05-30 22:48:02 +0200229When the file is encrypted, the text in the undo file is also crypted. The
230same key and method is used. |encryption|
231
Bram Moolenaar55debbe2010-05-23 23:34:36 +0200232You can also save and restore undo histories by using ":wundo" and ":rundo"
233respectively:
234 *:wundo* *:rundo*
235:wundo[!] {file}
236 Write undo history to {file}.
237 When {file} exists and it does not look like an undo file
238 (the magic number at the start of the file is wrong), then
239 this fails, unless the ! was added.
240 If it exists and does look like an undo file it is
241 overwritten.
242 {not in Vi}
243
244:rundo {file} Read undo history from {file}.
245 {not in Vi}
246
247You can use these in autocommands to explicitly specify the name of the
248history file. E.g.: >
249
Bram Moolenaara17d4c12010-05-30 18:30:36 +0200250 au BufReadPost * call ReadUndo()
251 au BufWritePost * call WriteUndo()
252 func ReadUndo()
253 if filereadable(expand('%:h'). '/UNDO/' . expand('%:t'))
254 rundo %:h/UNDO/%:t
255 endif
256 endfunc
257 func WriteUndo()
258 let dirname = expand('%:h') . '/UNDO'
259 if !isdirectory(dirname)
260 call mkdir(dirname)
261 endif
262 wundo %:h/UNDO/%:t
263 endfunc
Bram Moolenaar55debbe2010-05-23 23:34:36 +0200264
265You should keep 'undofile' off, otherwise you end up with two undo files for
266every write.
Bram Moolenaara17d4c12010-05-30 18:30:36 +0200267
268You can use the |undofile()| function to find out the file name that Vim would
269use.
Bram Moolenaar55debbe2010-05-23 23:34:36 +0200270
271Note that while reading/writing files and 'undofile' is set most errors will
272be silent, unless 'verbose' is set. With :wundo and :rundo you will get more
273error messages, e.g., when the file cannot be read or written.
274
275NOTE: undo files are never deleted by Vim. You need to delete them yourself.
276
277Reading an existing undo file may fail for several reasons:
278*E822* It cannot be opened, because the file permissions don't allow it.
279*E823* The magic number at the start of the file doesn't match. This usually
280 means it is not an undo file.
281*E824* The version number of the undo file indicates that it's written by a
282 newer version of Vim. You need that newer version to open it. Don't
283 write the buffer if you want to keep the undo info in the file.
Bram Moolenaar7db5fc82010-05-24 11:59:29 +0200284"File contents changed, cannot use undo info"
Bram Moolenaar55debbe2010-05-23 23:34:36 +0200285 The file text differs from when the undo file was written. This means
Bram Moolenaar7db5fc82010-05-24 11:59:29 +0200286 the undo file cannot be used, it would corrupt the text. This also
287 happens when 'encoding' differs from when the undo file was written.
Bram Moolenaar9db58062010-05-29 20:33:07 +0200288*E825* The undo file does not contain valid contents and cannot be used.
Bram Moolenaar56be9502010-06-06 14:20:26 +0200289*E826* The undo file is encrypted but decryption failed.
290*E827* The undo file is encrypted but this version of Vim does not support
291 encryption. Open the file with another Vim.
292*E832* The undo file is encrypted but 'key' is not set, the text file is not
293 encrypted. This would happen if the text file was written by Vim
294 encrypted at first, and later overwritten by not encrypted text.
295 You probably want to delete this undo file.
Bram Moolenaar6ed8ed82010-05-30 20:40:11 +0200296"Not reading undo file, owner differs"
297 The undo file is owned by someone else than the owner of the text
298 file. For safety the undo file is not used.
Bram Moolenaar55debbe2010-05-23 23:34:36 +0200299
300Writing an undo file may fail for these reasons:
301*E828* The file to be written cannot be created. Perhaps you do not have
302 write permissions in the directory.
Bram Moolenaar6ed8ed82010-05-30 20:40:11 +0200303"Cannot write undo file in any directory in 'undodir'"
304 None of the directories in 'undodir' can be used.
Bram Moolenaar55debbe2010-05-23 23:34:36 +0200305"Will not overwrite with undo file, cannot read"
306 A file exists with the name of the undo file to be written, but it
307 cannot be read. You may want to delete this file or rename it.
308"Will not overwrite, this is not an undo file"
309 A file exists with the name of the undo file to be written, but it
310 does not start with the right magic number. You may want to delete
311 this file or rename it.
Bram Moolenaar6ed8ed82010-05-30 20:40:11 +0200312"Skipping undo file write, noting to undo"
313 There is no undo information not be written, nothing has been changed
314 or 'undolevels' is negative.
Bram Moolenaar55debbe2010-05-23 23:34:36 +0200315*E829* An error occurred while writing the undo file. You may want to try
316 again.
317
318==============================================================================
3196. Remarks about undo *undo-remarks*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000320
321The number of changes that are remembered is set with the 'undolevels' option.
322If it is zero, the Vi-compatible way is always used. If it is negative no
323undo is possible. Use this if you are running out of memory.
324
Bram Moolenaar945e2db2010-06-05 17:43:32 +0200325 *clear-undo*
326When you set 'undolevels' to -1 the undo information is not immediately
327cleared, this happens at the next change. To force clearing the undo
328information you can use these commands: >
329 :let old_undolevels = &undolevels
330 :set undolevels=-1
331 :exe "normal a \<BS>\<Esc>"
332 :let &undolevels = old_undolevels
333 :unlet old_undolevels
334
Bram Moolenaar071d4272004-06-13 20:20:40 +0000335Marks for the buffer ('a to 'z) are also saved and restored, together with the
336text. {Vi does this a little bit different}
337
338When all changes have been undone, the buffer is not considered to be changed.
339It is then possible to exit Vim with ":q" instead of ":q!" {not in Vi}. Note
340that this is relative to the last write of the file. Typing "u" after ":w"
341actually changes the buffer, compared to what was written, so the buffer is
342considered changed then.
343
344When manual |folding| is being used, the folds are not saved and restored.
345Only changes completely within a fold will keep the fold as it was, because
346the first and last line of the fold don't change.
347
348The numbered registers can also be used for undoing deletes. Each time you
349delete text, it is put into register "1. The contents of register "1 are
350shifted to "2, etc. The contents of register "9 are lost. You can now get
351back the most recent deleted text with the put command: '"1P'. (also, if the
352deleted text was the result of the last delete or copy operation, 'P' or 'p'
353also works as this puts the contents of the unnamed register). You can get
354back the text of three deletes ago with '"3P'.
355
356 *redo-register*
357If you want to get back more than one part of deleted text, you can use a
358special feature of the repeat command ".". It will increase the number of the
359register used. So if you first do ""1P", the following "." will result in a
360'"2P'. Repeating this will result in all numbered registers being inserted.
361
362Example: If you deleted text with 'dd....' it can be restored with
363 '"1P....'.
364
365If you don't know in which register the deleted text is, you can use the
366:display command. An alternative is to try the first register with '"1P', and
367if it is not what you want do 'u.'. This will remove the contents of the
368first put, and repeat the put command for the second register. Repeat the
369'u.' until you got what you want.
370
371 vim:tw=78:ts=8:ft=help:norl: