share/vim/vim74/doc/usr_32.txt

   1 *usr_32.txt*    For Vim version 7.4.  Last change: 2010 Jul 20
   2
   3                      VIM USER MANUAL - by Bram Moolenaar
   4
   5                               The undo tree
   6
   7
   8 Vim provides multi-level undo.  If you undo a few changes and then make a new
   9 change you create a branch in the undo tree.  This text is about moving
  10 through the branches.
  11
  12 |32.1|  Undo up to a file write
  13 |32.2|  Numbering changes
  14 |32.3|  Jumping around the tree
  15 |32.4|  Time travelling
  16
  17      Next chapter: |usr_40.txt|  Make new commands
  18  Previous chapter: |usr_31.txt|  Exploiting the GUI
  19 Table of contents: |usr_toc.txt|
  20
  21 ==============================================================================
  22 *32.1*  Undo up to a file write
  23
  24 Sometimes you make several changes, and then discover you want to go back to
  25 when you have last written the file.  You can do that with this command: >
  26
  27         :earlier 1f
  28
  29 The "f" stands for "file" here.
  30
  31 You can repeat this command to go further back in the past.  Or use a count
  32 different from 1 to go back faster.
  33
  34 If you go back too far, go forward again with: >
  35
  36         :later 1f
  37
  38 Note that these commands really work in time sequence.  This matters if you
  39 made changes after undoing some changes.  It's explained in the next section.
  40
  41 Also note that we are talking about text writes here.  For writing the undo
  42 information in a file see |undo-persistence|.
  43
  44 ==============================================================================
  45 *32.2*  Numbering changes
  46
  47 In section |02.5| we only discussed one line of undo/redo.  But it is also
  48 possible to branch off.  This happens when you undo a few changes and then
  49 make a new change.  The new changes become a branch in the undo tree.
  50
  51 Let's start with the text "one".  The first change to make is to append
  52 " too".  And then move to the first 'o' and change it into 'w'.  We then have
  53 two changes, numbered 1 and 2, and three states of the text:
  54
  55                 one ~
  56                  |
  57               change 1
  58                  |
  59               one too ~
  60                  |
  61               change 2
  62                  |
  63               one two ~
  64
  65 If we now undo one change, back to "one too", and change "one" to "me" we
  66 create a branch in the undo tree:
  67
  68                 one ~
  69                  |
  70               change 1
  71                  |
  72               one too ~
  73               /     \
  74          change 2  change 3
  75             |         |
  76          one two    me too ~
  77
  78 You can now use the |u| command to undo.  If you do this twice you get to
  79 "one".  Use |CTRL-R| to redo, and you will go to "one too".  One more |CTRL-R|
  80 takes you to "me too".  Thus undo and redo go up and down in the tree, using
  81 the branch that was last used.
  82
  83 What matters here is the order in which the changes are made.  Undo and redo
  84 are not considered changes in this context.  After each change you have a new
  85 state of the text.
  86
  87 Note that only the changes are numbered, the text shown in the tree above has
  88 no identifier.  They are mostly referred to by the number of the change above
  89 it.  But sometimes by the number of one of the changes below it, especially
  90 when moving up in the tree, so that you know which change was just undone.
  91
  92 ==============================================================================
  93 *32.3*  Jumping around the tree
  94
  95 So how do you get to "one two" now?  You can use this command: >
  96
  97         :undo 2
  98
  99 The text is now "one two", you are below change 2.  You can use the |:undo|
 100 command to jump to below any change in the tree.
 101
 102 Now make another change: change "one" to "not":
 103
 104                 one ~
 105                  |
 106               change 1
 107                  |
 108               one too ~
 109               /     \
 110          change 2  change 3
 111             |         |
 112          one two    me too ~
 113             |
 114          change 4
 115             |
 116          not two ~
 117
 118 Now you change your mind and want to go back to "me too".  Use the |g-|
 119 command.  This moves back in time.  Thus it doesn't walk the tree upwards or
 120 downwards, but goes to the change made before.
 121
 122 You can repeat |g-| and you will see the text change:
 123         me too ~
 124         one two ~
 125         one too ~
 126         one ~
 127
 128 Use |g+| to move forward in time:
 129         one ~
 130         one too ~
 131         one two ~
 132         me too ~
 133         not two ~
 134
 135 Using |:undo| is useful if you know what change you want to jump to.  |g-| and
 136 |g+| are useful if you don't know exactly what the change number is.
 137
 138 You can type a count before |g-| and |g+| to repeat them.
 139
 140 ==============================================================================
 141 *32.4*  Time travelling
 142
 143 When you have been working on text for a while the tree grows to become big.
 144 Then you may want to go to the text of some minutes ago.
 145
 146 To see what branches there are in the undo tree use this command: >
 147
 148         :undolist
 149 <       number changes  time ~
 150              3       2  16 seconds ago
 151              4       3  5 seconds ago
 152
 153 Here you can see the number of the leaves in each branch and when the change
 154 was made.  Assuming we are below change 4, at "not two", you can go back ten
 155 seconds with this command: >
 156
 157         :earlier 10s
 158
 159 Depending on how much time you took for the changes you end up at a certain
 160 position in the tree.  The |:earlier| command argument can be "m" for minutes,
 161 "h" for hours and "d" for days.  To go all the way back use a big number: >
 162
 163         :earlier 100d
 164
 165 To travel forward in time again use the |:later| command: >
 166
 167         :later 1m
 168
 169 The arguments are "s", "m" and "h", just like with |:earlier|.
 170
 171 If you want even more details, or want to manipulate the information, you can
 172 use the |undotree()| function.  To see what it returns: >
 173
 174         :echo undotree()
 175
 176 ==============================================================================
 177
 178 Next chapter: |usr_40.txt|  Make new commands
 179
 180 Copyright: see |manual-copyright|  vim:tw=78:ts=8:ft=help:norl: