runtime/doc/undo.txt

   1 *undo.txt*      For Vim version 7.1.  Last change: 2006 Apr 30
   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 ==============================================================================
 110 4. Undo branches                                *undo-branches* *undo-tree*
 111
 112 Above we only discussed one line of undo/redo.  But it is also possible to
 113 branch off.  This happens when you undo a few changes and then make a new
 114 change.  The undone changes become a branch.  You can go to that branch with
 115 the following commands.
 116
 117 This is explained in the user manual: |usr_32.txt|.
 118
 119                                                         *:undol* *:undolist*
 120 :undol[ist]             List the leafs in the tree of changes.  Example:
 121                                 number changes   time ~
 122                                 4      10        10:34:11
 123                                 18     4         11:01:46
 124
 125                         The "number" column is the change number.  This number
 126                         continuously increases and can be used to identify a
 127                         specific undo-able change, see |:undo|.
 128                         The "changes" column is the number of changes to this
 129                         leaf from the root of the tree.
 130                         The "time" column is the time this change was made.
 131
 132                                                         *g-*
 133 g-                      Go to older text state.  With a count repeat that many
 134                         times.  {not in Vi}
 135                                                         *:ea* *:earlier*
 136 :earlier {count}        Go to older text state {count} times.
 137 :earlier {N}s           Go to older text state about {N} seconds before.
 138 :earlier {N}m           Go to older text state about {N} minutes before.
 139 :earlier {N}h           Go to older text state about {N} hours before.
 140
 141                                                         *g+*
 142 g+                      Go to newer text state.  With a count repeat that many
 143                         times.  {not in Vi}
 144                                                         *:lat* *:later*
 145 :later {count}          Go to newer text state {count} times.
 146 :later {N}s             Go to newer text state about {N} seconds later.
 147 :later {N}m             Go to newer text state about {N} minutes later.
 148 :later {N}h             Go to newer text state about {N} hours later.
 149
 150
 151 Note that text states will become unreachable when undo information is cleared
 152 for 'undolevels'.
 153
 154 Don't be surprised when moving through time shows multiple changes to take
 155 place at a time.  This happens when moving through the undo tree and then
 156 making a new change.
 157
 158 EXAMPLE
 159
 160 Start with this text:
 161         one two three ~
 162
 163 Delete the first word by pressing "x" three times:
 164         ne two three ~
 165         e two three ~
 166          two three ~
 167
 168 Now undo that by pressing "u" three times:
 169         e two three ~
 170         ne two three ~
 171         one two three ~
 172
 173 Delete the second word by pressing "x" three times:
 174         one wo three ~
 175         one o three ~
 176         one  three ~
 177
 178 Now undo that by using "g-" three times:
 179         one o three ~
 180         one wo three ~
 181          two three ~
 182
 183 You are now back in the first undo branch, after deleting "one".  Repeating
 184 "g-" will now bring you back to the original text:
 185         e two three ~
 186         ne two three ~
 187         one two three ~
 188
 189 Jump to the last change with ":later 1h":
 190         one  three ~
 191
 192 And back to the start again with ":earlier 1h":
 193         one two three ~
 194
 195
 196 Note that using "u" and CTRL-R will not get you to all possible text states
 197 while repeating "g-" and "g+" does.
 198
 199 ==============================================================================
 200 5. Remarks about undo                                   *undo-remarks*
 201
 202 The number of changes that are remembered is set with the 'undolevels' option.
 203 If it is zero, the Vi-compatible way is always used.  If it is negative no
 204 undo is possible.  Use this if you are running out of memory.
 205
 206 Marks for the buffer ('a to 'z) are also saved and restored, together with the
 207 text.  {Vi does this a little bit different}
 208
 209 When all changes have been undone, the buffer is not considered to be changed.
 210 It is then possible to exit Vim with ":q" instead of ":q!" {not in Vi}.  Note
 211 that this is relative to the last write of the file.  Typing "u" after ":w"
 212 actually changes the buffer, compared to what was written, so the buffer is
 213 considered changed then.
 214
 215 When manual |folding| is being used, the folds are not saved and restored.
 216 Only changes completely within a fold will keep the fold as it was, because
 217 the first and last line of the fold don't change.
 218
 219 The numbered registers can also be used for undoing deletes.  Each time you
 220 delete text, it is put into register "1.  The contents of register "1 are
 221 shifted to "2, etc.  The contents of register "9 are lost.  You can now get
 222 back the most recent deleted text with the put command: '"1P'.  (also, if the
 223 deleted text was the result of the last delete or copy operation, 'P' or 'p'
 224 also works as this puts the contents of the unnamed register).  You can get
 225 back the text of three deletes ago with '"3P'.
 226
 227                                                 *redo-register*
 228 If you want to get back more than one part of deleted text, you can use a
 229 special feature of the repeat command ".".  It will increase the number of the
 230 register used.  So if you first do ""1P", the following "." will result in a
 231 '"2P'.  Repeating this will result in all numbered registers being inserted.
 232
 233 Example:        If you deleted text with 'dd....' it can be restored with
 234                 '"1P....'.
 235
 236 If you don't know in which register the deleted text is, you can use the
 237 :display command.  An alternative is to try the first register with '"1P', and
 238 if it is not what you want do 'u.'.  This will remove the contents of the
 239 first put, and repeat the put command for the second register.  Repeat the
 240 'u.' until you got what you want.
 241
 242  vim:tw=78:ts=8:ft=help:norl: