You know that Vim lets you undo changes like any text editor. What you might not know is that it doesn't just keep a list of your changes — it keeps a goddamed tree of them.
Say you make a change (call it X), undo that change, and then make another change (call it Y). With most editors, change X is now gone forever. With Vim you can get it back.
The problem is that trying to do this in the real world is painful. Vim gives
you an :undolist
command that shows you the leaves of the tree. Good luck
finding the change you want in that list.
Gundo is a plugin to make browsing this ridiculously powerful undo tree less painful.
Check out this quick screencast if you want to see it in action.
Gundo requires Vim 7.3+ compiled with Python support, and Python 2.4+.
Use Pathogen. Don't use pathogen? Start.
hg clone http://bitbucket.org/sjl/gundo.vim ~/.vim/bundle/gundo
There's a git mirror if you prefer:
git clone http://github.com/sjl/gundo.vim.git ~/.vim/bundle/gundo
Add a mapping to your ~/.vimrc (change the key to suit your taste):
nnoremap <F5> :GundoToggle<CR>
We'll get to the technical details later, but if you're a human the first thing you need to do is add a mapping to your vimrc file to toggle the undo graph:
nnoremap <F5> :GundoToggle<CR>
Change the mapped key to suit your taste. We'll stick with <F5>
because that's
what the author uses.
Now you can press <F5>
to toggle the undo graph and preview pane, which will
look something like this:
Undo graph File +-----------------------------------+---------------------------+ | " Gundo for something.txt [1] |one | | " j/k - move between undo states |two | | " <cr> - revert to that state |three | | |five | | @ [5] 3 hours ago | | | | | | | | o [4] 4 hours ago | | | | | | | | o | [3] 4 hours ago | | | | | | | | o | [2] 4 hours ago | | | |/ | | | o [1] 4 hours ago | | | | | | | o [0] Original | | +-----------------------------------+ | | --- 3 2010-10-12 06:27:35 PM | | | +++ 5 2010-10-12 07:38:37 PM | | | @@ -1,3 +1,4 | | | one | | | two | | | three | | | +five | | +-----------------------------------+---------------------------+ Preview pane
Your current position in the undo tree is marked with an @
character. Other
nodes are marked with an o
character.
When you toggle open the graph Gundo will put your cursor on your current
position in the tree. You can move up and down the graph with the j
and
k
keys.
You can move to the top of the graph (the newest state) with gg
and to the
bottom of the graph (the oldest state) with G
.
As you move between undo states the preview pane will show you a unified diff of the change that state made.
Pressing return
on a state (or double clicking on it) will
revert the contents of the file to match that state.
You can use p
on a state to make the preview window show the
diff between your current state and the selected state, instead of a preview
of what the selected state changed.
Pressing P
while on a state will initiate "play to" mode targeted at that
state. This will replay all the changes between your current state and the
target, with a slight pause after each change. It's mostly useless, but can be
fun to watch and see where your editing lags — that might be a good place to
define a new mapping to speed up your editing.
Pressing q
while in the undo graph will close it. You can also just press your
toggle mapping key.
You can tweak the behavior of Gundo by setting a few variables in your :vimrc file. For example:
let g:gundo_width = 60 let g:gundo_preview_height = 40 let g:gundo_right = 1
Set the horizontal width of the Gundo graph (and preview).
Default: 45
Set the vertical height of the Gundo preview.
Default: 15
Force the preview window below current windows instead of below the graph. This gives the preview window more space to show the unified diff.
Example:
+--------+ +--------+ !g! ! ! !g! !g! ! or ! !g! !g!______! !______!g! !g!pppppp! !pppppp!g! +--------+ +--------+
Default: 0
Set this to 1 to make the Gundo graph (and preview) open on the right side instead of the left.
Default: 0 (off, open on the left side)
Set this to 0 to disable the help text in the Gundo graph window.
Default: 1 (show the help)
Set this to 1 to disable Gundo entirely.
Useful if you use the same ~/.vim
folder on
multiple machines, and some of them may not have Python support.
Default: 0 (Gundo is enabled as usual)
These options let you change the keys that navigate the undo graph. This is useful if you use a Dvorak keyboard and have changed your movement keys.
Default:
gundo_map_move_older: "j"
gundo_map_move_newer: "k"
If you find a bug please post it on the issue tracker.
Fork the repository on BitBucket or GitHub and send a pull request.
Make sure you document your changes in the following places:
README.markdown
file.site/index.html
file.doc/gundo.txt
file.j
and k
mappings are
now configurable with
g:gundo_map_move_older
and
g:gundo_map_move_newer
.
o
, Up
and
Down
keys are now mapped in the
Gundo pane.
GundoToggle
close the Gundo windows if they're
visible but not the current window, instead of moving to them.
g:gundo_disable
setting.g:gundo_help
setting.p
mapping to preview the result of
reverting to the selected state.
The graphing code was all taken from Mercurial, hence the GPLv2+ license.
The plugin was heavily inspired by histwin.vim, and the code for scratch.vim helped the author get started.