runtime/doc/undo.txt

   1 *undo.txt*      For Vim version 7.2.  Last change: 2009 Apr 12
   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.  {Vi: only one level}
  23
  24                                                         *:u* *:un* *:undo*
  25 :u[ndo]                 Undo one change.  {Vi: only one level}
  26
  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*
  31 CTRL-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*
  38 U                       Undo all latest changes on one line.  {Vi: while not
  39                         moved off of it}
  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 command.
  69 The redo command repeats the previous undo command.  It does NOT repeat a
  70 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                         {not in Vi}
  97
  98 This is most useful when you need to prompt the user halfway a change.  For
  99 example in a function that calls |getchar()|.  Do make sure that there was a
 100 related change before this that you must join with.
 101
 102 This doesn't work by itself, because the next key press will start a new
 103 change again.  But you can do something like this: >
 104
 105         :undojoin | delete
 106
 107 After this an "u" command will undo the delete command and the previous
 108 change.
 109
 110 To do the opposite, break a change into two undo blocks, in Insert mode use
 111 CTRL-G u.  This is useful if you want an insert command to be undoable in
 112 parts.  E.g., for each sentence.  |i_CTRL-G_u|
 113
 114 ==============================================================================
 115 4. Undo branches                                *undo-branches* *undo-tree*
 116
 117 Above we only discussed one line of undo/redo.  But it is also possible to
 118 branch off.  This happens when you undo a few changes and then make a new
 119 change.  The undone changes become a branch.  You can go to that branch with
 120 the following commands.
 121
 122 This is explained in the user manual: |usr_32.txt|.
 123
 124                                                         *:undol* *:undolist*
 125 :undol[ist]             List the leafs in the tree of changes.  Example:
 126                                 number changes   time ~
 127                                 4      10        10:34:11
 128                                 18     4         11:01:46
 129
 130                         The "number" column is the change number.  This number
 131                         continuously increases and can be used to identify a
 132                         specific undo-able change, see |:undo|.
 133                         The "changes" column is the number of changes to this
 134                         leaf from the root of the tree.
 135                         The "time" column is the time this change was made.
 136
 137                                                         *g-*
 138 g-                      Go to older text state.  With a count repeat that many
 139                         times.  {not in Vi}
 140                                                         *:ea* *:earlier*
 141 :earlier {count}        Go to older text state {count} times.
 142 :earlier {N}s           Go to older text state about {N} seconds before.
 143 :earlier {N}m           Go to older text state about {N} minutes before.
 144 :earlier {N}h           Go to older text state about {N} hours before.
 145
 146                                                         *g+*
 147 g+                      Go to newer text state.  With a count repeat that many
 148                         times.  {not in Vi}
 149                                                         *:lat* *:later*
 150 :later {count}          Go to newer text state {count} times.
 151 :later {N}s             Go to newer text state about {N} seconds later.
 152 :later {N}m             Go to newer text state about {N} minutes later.
 153 :later {N}h             Go to newer text state about {N} hours later.
 154
 155
 156 Note that text states will become unreachable when undo information is cleared
 157 for 'undolevels'.
 158
 159 Don't be surprised when moving through time shows multiple changes to take
 160 place at a time.  This happens when moving through the undo tree and then
 161 making a new change.
 162
 163 EXAMPLE
 164
 165 Start with this text:
 166         one two three ~
 167
 168 Delete the first word by pressing "x" three times:
 169         ne two three ~
 170         e two three ~
 171          two three ~
 172
 173 Now undo that by pressing "u" three times:
 174         e two three ~
 175         ne two three ~
 176         one two three ~
 177
 178 Delete the second word by pressing "x" three times:
 179         one wo three ~
 180         one o three ~
 181         one  three ~
 182
 183 Now undo that by using "g-" three times:
 184         one o three ~
 185         one wo three ~
 186          two three ~
 187
 188 You are now back in the first undo branch, after deleting "one".  Repeating
 189 "g-" will now bring you back to the original text:
 190         e two three ~
 191         ne two three ~
 192         one two three ~
 193
 194 Jump to the last change with ":later 1h":
 195         one  three ~
 196
 197 And back to the start again with ":earlier 1h":
 198         one two three ~
 199
 200
 201 Note that using "u" and CTRL-R will not get you to all possible text states
 202 while repeating "g-" and "g+" does.
 203
 204 ==============================================================================
 205 5. Undo persistence                                     *undo-persistence*
 206
 207 Exiting Vim normally destroys the tree of undos created in that session, but
 208 by setting the 'undofile' option, Vim will automatically save your undo
 209 history in a file and restore it when you edit the file again. You can also
 210 save and restore undo histories manually by typing ":wundo" and ":rundo"
 211 respectively.
 212
 213                                                         *:wundo* *:rundo*
 214 :wundo {file}   Write undo history to file, or to 'undodir' by default.
 215                         {not in Vi}
 216 :rundo {file}   Read undo history from file, or from 'undodir' by default.
 217                         {not in Vi}
 218
 219 Vim saves undo trees in a separate undo file per file, using a simple scheme
 220 that maps filesystem paths directly to undo files. Vim will detect if an
 221 undo file is no longer synchronized with the file it was written for (by
 222 comparing filesystem mtimes) and ignore it if necessary to prevent corruption.
 223
 224 Undo files are saved by default in .vim/undo, but this location can be
 225 changed by setting the 'undodir' option.
 226
 227 ==============================================================================
 228 6. Remarks about undo                                   *undo-remarks*
 229
 230 The number of changes that are remembered is set with the 'undolevels' option.
 231 If it is zero, the Vi-compatible way is always used.  If it is negative no
 232 undo is possible.  Use this if you are running out of memory.
 233
 234 Marks for the buffer ('a to 'z) are also saved and restored, together with the
 235 text.  {Vi does this a little bit different}
 236
 237 When all changes have been undone, the buffer is not considered to be changed.
 238 It is then possible to exit Vim with ":q" instead of ":q!" {not in Vi}.  Note
 239 that this is relative to the last write of the file.  Typing "u" after ":w"
 240 actually changes the buffer, compared to what was written, so the buffer is
 241 considered changed then.
 242
 243 When manual |folding| is being used, the folds are not saved and restored.
 244 Only changes completely within a fold will keep the fold as it was, because
 245 the first and last line of the fold don't change.
 246
 247 The numbered registers can also be used for undoing deletes.  Each time you
 248 delete text, it is put into register "1.  The contents of register "1 are
 249 shifted to "2, etc.  The contents of register "9 are lost.  You can now get
 250 back the most recent deleted text with the put command: '"1P'.  (also, if the
 251 deleted text was the result of the last delete or copy operation, 'P' or 'p'
 252 also works as this puts the contents of the unnamed register).  You can get
 253 back the text of three deletes ago with '"3P'.
 254
 255                                                 *redo-register*
 256 If you want to get back more than one part of deleted text, you can use a
 257 special feature of the repeat command ".".  It will increase the number of the
 258 register used.  So if you first do ""1P", the following "." will result in a
 259 '"2P'.  Repeating this will result in all numbered registers being inserted.
 260
 261 Example:        If you deleted text with 'dd....' it can be restored with
 262                 '"1P....'.
 263
 264 If you don't know in which register the deleted text is, you can use the
 265 :display command.  An alternative is to try the first register with '"1P', and
 266 if it is not what you want do 'u.'.  This will remove the contents of the
 267 first put, and repeat the put command for the second register.  Repeat the
 268 'u.' until you got what you want.
 269
 270  vim:tw=78:ts=8:ft=help:norl: