1 *gundo.txt* Graph your undo tree so you can actually USE it.
3 Making Vim's undo tree usable by humans.
5 ==============================================================================
6 CONTENTS *Gundo-contents*
8 1. Intro .......................... |GundoIntro|
9 2. Usage .......................... |GundoUsage|
10 3. Configuration .................. |GundoConfig|
11 3.1 gundo_width ............... |gundo_width|
12 3.2 gundo_preview_height ...... |gundo_preview_height|
13 3.3 gundo_preview_bottom ...... |gundo_preview_bottom|
14 3.4 gundo_right ............... |gundo_right|
15 3.5 gundo_help ................ |gundo_help|
16 3.6 gundo_disable ............. |gundo_disable|
17 3.7 gundo_map_move_older ...... |gundo_map_move_older|
18 gundo_map_move_newer ...... |gundo_map_move_newer|
19 3.8 gundo_close_on_revert ..... |gundo_close_on_revert|
20 3.9 gundo_preview_statusline .. |gundo_preview_statusline|
21 gundo_tree_statusline ..... |gundo_tree_statusline|
22 4. License ........................ |GundoLicense|
23 5. Bugs ........................... |GundoBugs|
24 6. Contributing ................... |GundoContributing|
25 7. Changelog ...................... |GundoChangelog|
26 8. Credits ........................ |GundoCredits|
28 ==============================================================================
31 You know that Vim lets you undo changes like any text editor. What you might
32 not know is that it doesn't just keep a list of your changes -- it keeps
33 a goddamed |:undo-tree| of them.
35 Say you make a change (call it X), undo that change, and then make another
36 change (call it Y). With most editors, change X is now gone forever. With Vim
39 The problem is that trying to do this in the real world is painful. Vim gives
40 you an |:undolist| command that shows you the leaves of the tree. Good luck
41 finding the change you want in that list.
43 Gundo is a plugin to make browsing this ridiculously powerful undo tree less
46 ==============================================================================
49 We'll get to the technical details later, but if you're a human the first
50 thing you need to do is add a mapping to your |:vimrc| to toggle the undo
53 nnoremap <F5> :GundoToggle<CR>
55 Change the mapped key to suit your taste. We'll stick with F5 because that's
58 Now you can press F5 to toggle the undo graph and preview pane, which will
59 look something like this: >
62 +-----------------------------------+------------------------------------+
63 | " Gundo for something.txt [1] |one |
64 | " j/k - move between undo states |two |
65 | " <cr> - revert to that state |three |
67 | @ [5] 3 hours ago | |
69 | | o [4] 4 hours ago | |
71 | o | [3] 4 hours ago | |
73 | o | [2] 4 hours ago | |
75 | o [1] 4 hours ago | |
78 +-----------------------------------+ |
79 | --- 3 2010-10-12 06:27:35 PM | |
80 | +++ 5 2010-10-12 07:38:37 PM | |
86 +-----------------------------------+------------------------------------+
89 Your current position in the undo tree is marked with an '@' character. Other
90 nodes are marked with an 'o' character.
92 When you toggle open the graph Gundo will put your cursor on your current
93 position in the tree. You can move up and down the graph with the j and
96 You can move to the top of the graph (the newest state) with gg and to the
97 bottom of the graph (the oldest state) with G.
99 As you move between undo states the preview pane will show you a unified diff
100 of the change that state made.
102 Pressing enter on a state (or double clicking on it) will revert the contents
103 of the file to match that state.
105 You can use p on a state to make the preview window show the diff between
106 your current state and the selected state, instead of a preview of what the
107 selected state changed.
109 Pressing P while on a state will initiate "play to" mode targeted at that
110 state. This will replay all the changes between your current state and the
111 target, with a slight pause after each change. It's mostly useless, but can be
112 fun to watch and see where your editing lags -- that might be a good place to
113 define a new mapping to speed up your editing.
115 Pressing q while in the undo graph will close it. You can also just press your
118 ==============================================================================
119 3. Configuration *GundoConfig*
121 You can tweak the behavior of Gundo by setting a few variables in your :vimrc
124 let g:gundo_width = 60
125 let g:gundo_preview_height = 40
126 let g:gundo_right = 1
128 ------------------------------------------------------------------------------
129 3.1 g:gundo_width *gundo_width*
131 Set the horizontal width of the Gundo graph (and preview).
135 ------------------------------------------------------------------------------
136 3.2 g:gundo_preview_height *gundo_preview_height*
138 Set the vertical height of the Gundo preview.
142 ------------------------------------------------------------------------------
143 3.3 g:gundo_preview_bottom *gundo_preview_bottom*
145 Force the preview window below current windows instead of below the graph.
146 This gives the preview window more space to show the unified diff.
150 +--------+ +--------+
153 !g!______! !______!g!
154 !g!pppppp! !pppppp!g!
155 +--------+ +--------+
159 ------------------------------------------------------------------------------
160 3.4 g:gundo_right *gundo_right*
162 Set this to 1 to make the Gundo graph (and preview) open on the right side
165 Default: 0 (off, open on the left side)
167 ------------------------------------------------------------------------------
168 3.5 g:gundo_help *gundo_help*
170 Set this to 0 to disable the help text in the Gundo graph window.
172 Default: 1 (show the help)
174 ------------------------------------------------------------------------------
175 3.6 g:gundo_disable *gundo_disable*
177 Set this to 1 to disable Gundo entirely.
179 Useful if you use the same ~/.vim folder on multiple machines, and some of
180 them may not have Python support.
182 Default: 0 (Gundo is enabled as usual)
184 ------------------------------------------------------------------------------
185 3.7 g:gundo_map_move_older, g:gundo_map_move_newer *gundo_map_move_older*
186 *gundo_map_move_newer*
188 These options let you change the keys that navigate the undo graph. This is
189 useful if you use a Dvorak keyboard and have changed your movement keys.
191 Default: gundo_map_move_older = "j"
192 gundo_map_move_newer = "k"
194 ------------------------------------------------------------------------------
195 3.8 g:gundo_close_on_revert *gundo_close_on_revert*
197 Set this to 1 to automatically close the Gundo windows when reverting.
199 Default: 0 (windows do not automatically close)
201 ------------------------------------------------------------------------------
202 3.9 g:gundo_preview_statusline *gundo_preview_statusline*
203 g:gundo_tree_statusline *gundo_tree_statusline*
205 Set these to a string to display it as the status line for each Gundo window.
207 Default: unset (windows use the default statusline)
209 ==============================================================================
210 4. License *GundoLicense*
214 ==============================================================================
217 If you find a bug please post it on the issue tracker:
218 http://bitbucket.org/sjl/gundo.vim/issues?status=new&status=open
220 ==============================================================================
221 6. Contributing *GundoContributing*
223 Think you can make this plugin better? Awesome. Fork it on BitBucket or GitHub
224 and send a pull request.
226 BitBucket: http://bitbucket.org/sjl/gundo.vim/
227 GitHub: http://github.com/sjl/gundo.vim/
229 ==============================================================================
230 7. Changelog *GundoChangelog*
233 * Add statusline configuration.
235 * More performance improvements.
237 * Refactoring and performance improvements.
239 * Add the g:gundo_close_on_revert setting.
240 * Fix a bug with the splitbelow setting.
242 * Fix a bug with the movement key mappings.
244 * Warnings about having an incompatible Vim and/or Python installation
245 are now deferred until the first time you try to use Gundo, instead
246 of being displayed on launch.
247 * The <j> and <k> mappings are now configurable with
248 g:gundo_map_move_older and g:gundo_map_move_newer.
249 * The o, <Up> and <Down> keys are now mapped in the Gundo pane.
250 * Improve and add several unit tests for Gundo.
252 * Make GundoToggle close the Gundo windows if they're visible but not the
253 current window, instead of moving to them.
254 * Add the g:gundo_help setting.
255 * Add the g:gundo_disable setting.
256 * Add the 'p' mapping to preview the result of reverting to the selected
258 * Fix movement commands with counts in the graph.
260 * Initial stable release.
262 ==============================================================================
263 8. Credits *GundoCredits*
265 The graphing code was all taken from Mercurial, hence the GPLv2+ license.
267 The plugin was heavily inspired by histwin.vim, and the code for scratch.vim
268 helped the author get started.
270 ==============================================================================