1*usr_32.txt*	For Vim version 7.3.  Last change: 2010 Jul 20
2
3		     VIM USER MANUAL - by Bram Moolenaar
4
5			      The undo tree
6
7
8Vim provides multi-level undo.  If you undo a few changes and then make a new
9change you create a branch in the undo tree.  This text is about moving
10through 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
19Table of contents: |usr_toc.txt|
20
21==============================================================================
22*32.1*	Undo up to a file write
23
24Sometimes you make several changes, and then discover you want to go back to
25when you have last written the file.  You can do that with this command: >
26
27	:earlier 1f
28
29The "f" stands for "file" here.
30
31You can repeat this command to go further back in the past.  Or use a count
32different from 1 to go back faster.
33
34If you go back too far, go forward again with: >
35
36	:later 1f
37
38Note that these commands really work in time sequence.  This matters if you
39made changes after undoing some changes.  It's explained in the next section.
40
41Also note that we are talking about text writes here.  For writing the undo
42information in a file see |undo-persistence|.
43
44==============================================================================
45*32.2*	Numbering changes
46
47In section |02.5| we only discussed one line of undo/redo.  But it is also
48possible to branch off.  This happens when you undo a few changes and then
49make a new change.  The new changes become a branch in the undo tree.
50
51Let'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
53two 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
65If we now undo one change, back to "one too", and change "one" to "me" we
66create 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
78You 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|
80takes you to "me too".  Thus undo and redo go up and down in the tree, using
81the branch that was last used.
82
83What matters here is the order in which the changes are made.  Undo and redo
84are not considered changes in this context.  After each change you have a new
85state of the text.
86
87Note that only the changes are numbered, the text shown in the tree above has
88no identifier.  They are mostly referred to by the number of the change above
89it.  But sometimes by the number of one of the changes below it, especially
90when moving up in the tree, so that you know which change was just undone.
91
92==============================================================================
93*32.3*	Jumping around the tree
94
95So how do you get to "one two" now?  You can use this command: >
96
97	:undo 2
98
99The text is now "one two", you are below change 2.  You can use the |:undo|
100command to jump to below any change in the tree.
101
102Now 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
118Now you change your mind and want to go back to "me too".  Use the |g-|
119command.  This moves back in time.  Thus it doesn't walk the tree upwards or
120downwards, but goes to the change made before.
121
122You can repeat |g-| and you will see the text change:
123	me too ~
124	one two ~
125	one too ~
126	one ~
127
128Use |g+| to move forward in time:
129	one ~
130	one too ~
131	one two ~
132	me too ~
133	not two ~
134
135Using |: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
138You can type a count before |g-| and |g+| to repeat them.
139
140==============================================================================
141*32.4*	Time travelling
142
143When you have been working on text for a while the tree grows to become big.
144Then you may want to go to the text of some minutes ago.
145
146To 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
153Here you can see the number of the leaves in each branch and when the change
154was made.  Assuming we are below change 4, at "not two", you can go back ten
155seconds with this command: >
156
157	:earlier 10s
158
159Depending on how much time you took for the changes you end up at a certain
160position 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
165To travel forward in time again use the |:later| command: >
166
167	:later 1m
168
169The arguments are "s", "m" and "h", just like with |:earlier|.
170
171If you want even more details, or want to manipulate the information, you can
172use the |undotree()| function.  To see what it returns: >
173
174	:echo undotree()
175
176==============================================================================
177
178Next chapter: |usr_40.txt|  Make new commands
179
180Copyright: see |manual-copyright|  vim:tw=78:ts=8:ft=help:norl:
181