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. Remarks about undo           |undo-remarks|
  16
  17 ==============================================================================
  18 1. Undo and redo commands                               *undo-commands*
  19
  20 <Undo>          or                                      *undo* *<Undo>* *u*
  21 u                       Undo [count] changes.  {Vi: only one level}
  22
  23                                                         *:u* *:un* *:undo*
  24 :u[ndo]                 Undo one change.  {Vi: only one level}
  25
  26 :u[ndo] {N}             Jump to after change number {N}.  See |undo-branches|
  27                         for the meaning of {N}.  {not in Vi}
  28
  29                                                         *CTRL-R*
  30 CTRL-R                  Redo [count] changes which were undone.  {Vi: redraw
  31                         screen}
  32
  33                                                         *:red* *:redo* *redo*
  34 :red[o]                 Redo one change which was undone.  {Vi: no redo}
  35
  36                                                         *U*
  37 U                       Undo all latest changes on one line.  {Vi: while not
  38                         moved off of it}
  39
  40 The last changes are remembered.  You can use the undo and redo commands above
  41 to revert the text to how it was before each change.  You can also apply the
  42 changes again, getting back the text before the undo.
  43
  44 The "U" command is treated by undo/redo just like any other command.  Thus a
  45 "u" command undoes a "U" command and a 'CTRL-R' command redoes it again.  When
  46 mixing "U", "u" and 'CTRL-R' you will notice that the "U" command will
  47 restore the situation of a line to before the previous "U" command.  This may
  48 be confusing.  Try it out to get used to it.
  49 The "U" command will always mark the buffer as changed.  When "U" changes the
  50 buffer back to how it was without changes, it is still considered changed.
  51 Use "u" to undo changes until the buffer becomes unchanged.
  52
  53 ==============================================================================
  54 2. Two ways of undo                                     *undo-two-ways*
  55
  56 How undo and redo commands work depends on the 'u' flag in 'cpoptions'.
  57 There is the Vim way ('u' excluded) and the vi-compatible way ('u' included).
  58 In the Vim way, "uu" undoes two changes.  In the Vi-compatible way, "uu" does
  59 nothing (undoes an undo).
  60
  61 'u' excluded, the Vim way:
  62 You can go back in time with the undo command.  You can then go forward again
  63 with the redo command.  If you make a new change after the undo command,
  64 the redo will not be possible anymore.
  65
  66 'u' included, the Vi-compatible way:
  67 The undo command undoes the previous change, and also the previous undo command.
  68 The redo command repeats the previous undo command.  It does NOT repeat a
  69 change command, use "." for that.
  70
  71 Examples        Vim way                 Vi-compatible way       ~
  72 "uu"            two times undo          no-op
  73 "u CTRL-R"      no-op                   two times undo
  74
  75 Rationale:  Nvi uses the "." command instead of CTRL-R.  Unfortunately, this
  76             is not Vi compatible.  For example "dwdwu." in Vi deletes two
  77             words, in Nvi it does nothing.
  78
  79 ==============================================================================
  80 3. Undo blocks                                          *undo-blocks*
  81
  82 One undo command normally undoes a typed command, no matter how many changes
  83 that command makes.  This sequence of undo-able changes forms an undo block.
  84 Thus if the typed key(s) call a function, all the commands in the function are
  85 undone together.
  86
  87 If you want to write a function or script that doesn't create a new undoable
  88 change but joins in with the previous change use this command:
  89
  90                                                 *:undoj* *:undojoin* *E790*
  91 :undoj[oin]             Join further changes with the previous undo block.
  92                         Warning: Use with care, it may prevent the user from
  93                         properly undoing changes.  Don't use this after undo
  94                         or redo.
  95                         {not in Vi}
  96
  97 This is most useful when you need to prompt the user halfway a change.  For
  98 example in a function that calls |getchar()|.  Do make sure that there was a
  99 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 an "u" command will undo the delete command and the previous
 107 change.
 108
 109 To do the opposite, break a change into two undo blocks, in Insert mode use
 110 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 ==============================================================================
 114 4. Undo branches                                *undo-branches* *undo-tree*
 115
 116 Above we only discussed one line of undo/redo.  But it is also possible to
 117 branch off.  This happens when you undo a few changes and then make a new
 118 change.  The undone changes become a branch.  You can go to that branch with
 119 the following commands.
 120
 121 This is explained in the user manual: |usr_32.txt|.
 122
 123                                                         *:undol* *:undolist*
 124 :undol[ist]             List the leafs in the tree of changes.  Example:
 125                                 number changes   time ~
 126                                 4      10        10:34:11
 127                                 18     4         11:01:46
 128
 129                         The "number" column is the change number.  This number
 130                         continuously increases and can be used to identify a
 131                         specific undo-able change, see |:undo|.
 132                         The "changes" column is the number of changes to this
 133                         leaf from the root of the tree.
 134                         The "time" column is the time this change was made.
 135
 136                                                         *g-*
 137 g-                      Go to older text state.  With a count repeat that many
 138                         times.  {not in Vi}
 139                                                         *:ea* *:earlier*
 140 :earlier {count}        Go to older text state {count} times.
 141 :earlier {N}s           Go to older text state about {N} seconds before.
 142 :earlier {N}m           Go to older text state about {N} minutes before.
 143 :earlier {N}h           Go to older text state about {N} hours before.
 144
 145                                                         *g+*
 146 g+                      Go to newer text state.  With a count repeat that many
 147                         times.  {not in Vi}
 148                                                         *:lat* *:later*
 149 :later {count}          Go to newer text state {count} times.
 150 :later {N}s             Go to newer text state about {N} seconds later.
 151 :later {N}m             Go to newer text state about {N} minutes later.
 152 :later {N}h             Go to newer text state about {N} hours later.
 153
 154
 155 Note that text states will become unreachable when undo information is cleared
 156 for 'undolevels'.
 157
 158 Don't be surprised when moving through time shows multiple changes to take
 159 place at a time.  This happens when moving through the undo tree and then
 160 making a new change.
 161
 162 EXAMPLE
 163
 164 Start with this text:
 165         one two three ~
 166
 167 Delete the first word by pressing "x" three times:
 168         ne two three ~
 169         e two three ~
 170          two three ~
 171
 172 Now undo that by pressing "u" three times:
 173         e two three ~
 174         ne two three ~
 175         one two three ~
 176
 177 Delete the second word by pressing "x" three times:
 178         one wo three ~
 179         one o three ~
 180         one  three ~
 181
 182 Now undo that by using "g-" three times:
 183         one o three ~
 184         one wo three ~
 185          two three ~
 186
 187 You are now back in the first undo branch, after deleting "one".  Repeating
 188 "g-" will now bring you back to the original text:
 189         e two three ~
 190         ne two three ~
 191         one two three ~
 192
 193 Jump to the last change with ":later 1h":
 194         one  three ~
 195
 196 And back to the start again with ":earlier 1h":
 197         one two three ~
 198
 199
 200 Note that using "u" and CTRL-R will not get you to all possible text states
 201 while repeating "g-" and "g+" does.
 202
 203 ==============================================================================
 204 5. Remarks about undo                                   *undo-remarks*
 205
 206 The number of changes that are remembered is set with the 'undolevels' option.
 207 If it is zero, the Vi-compatible way is always used.  If it is negative no
 208 undo is possible.  Use this if you are running out of memory.
 209
 210 Marks for the buffer ('a to 'z) are also saved and restored, together with the
 211 text.  {Vi does this a little bit different}
 212
 213 When all changes have been undone, the buffer is not considered to be changed.
 214 It is then possible to exit Vim with ":q" instead of ":q!" {not in Vi}.  Note
 215 that this is relative to the last write of the file.  Typing "u" after ":w"
 216 actually changes the buffer, compared to what was written, so the buffer is
 217 considered changed then.
 218
 219 When manual |folding| is being used, the folds are not saved and restored.
 220 Only changes completely within a fold will keep the fold as it was, because
 221 the first and last line of the fold don't change.
 222
 223 The numbered registers can also be used for undoing deletes.  Each time you
 224 delete text, it is put into register "1.  The contents of register "1 are
 225 shifted to "2, etc.  The contents of register "9 are lost.  You can now get
 226 back the most recent deleted text with the put command: '"1P'.  (also, if the
 227 deleted text was the result of the last delete or copy operation, 'P' or 'p'
 228 also works as this puts the contents of the unnamed register).  You can get
 229 back the text of three deletes ago with '"3P'.
 230
 231                                                 *redo-register*
 232 If you want to get back more than one part of deleted text, you can use a
 233 special feature of the repeat command ".".  It will increase the number of the
 234 register used.  So if you first do ""1P", the following "." will result in a
 235 '"2P'.  Repeating this will result in all numbered registers being inserted.
 236
 237 Example:        If you deleted text with 'dd....' it can be restored with
 238                 '"1P....'.
 239
 240 If you don't know in which register the deleted text is, you can use the
 241 :display command.  An alternative is to try the first register with '"1P', and
 242 if it is not what you want do 'u.'.  This will remove the contents of the
 243 first put, and repeat the put command for the second register.  Repeat the
 244 'u.' until you got what you want.
 245
 246  vim:tw=78:ts=8:ft=help:norl: