vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

undo.txt (17858B)


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