Add a unit test. This here is a grey triangle moment, folks.
| author |
Steve Losh <steve@stevelosh.com> |
| date |
Wed, 10 Nov 2010 19:52:08 -0500 |
| parents |
e1365403fefc |
| children |
206d80115d82 |
<!DOCTYPE html>
<html>
<head>
<title>Gundo - Visualize your Vim Undo Tree</title>
<link rel="stylesheet/less" href="style.less" type="text/css">
<script src="less.js" type="text/javascript"></script>
<script type="text/javascript">
/* <![CDATA[ */
(function() {
var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
s.type = 'text/javascript';
s.async = true;
s.src = 'http://api.flattr.com/js/0.5.0/load.js?mode=auto';
t.parentNode.insertBefore(s, t);
})();
/* ]]> */
</script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-15328874-3']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div id="repos">
<a href="http://bitbucket.org/sjl/gundo.vim/">Mercurial Repository</a><br/>
<a href="http://github.com/sjl/gundo.vim/">Git Repository</a><br/>
<a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="http://bitbucket.org/sjl/gundo.vim/"></a>
</div>
<div class="wrap">
<header>
<h1>Gundo</h1>
<h2>Graph your Vim undo tree in style.</h2>
</header>
<section>
<a href="http://www.flickr.com/photos/sjl7678/5093114605/"
title="gundo by stevelosh, on Flickr"
><img src="http://farm5.static.flickr.com/4113/5093114605_ebc46d6494_m.jpg"
width="234" height="240" alt="gundo" /></a>
<p>
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 <a href="http://vim.wikia.com/wiki/Using_undo_branches">tree</a> of them.
</p>
<p>
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.
</p>
<p>
The problem is that trying to do this in the real world is painful. Vim gives
you an <code>:undolist</code> command that shows you the leaves of the tree. Good luck
finding the change you want in that list.
</p>
<p>
Gundo is a plugin to make browsing this ridiculously powerful undo tree less
painful.
</p>
<p>
Check out this
<a href="http://screenr.com/M9l">quick screencast</a>
if you want to see it in action.
</p>
</section>
<nav>
<ol>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#installation">Installation</a></li>
<li><a href="#usage">Usage</a></li>
<li>
<a href="#configuration">Configuration</a>
<ul>
<li><a href="#gundo_width">g:gundo_width</a></li>
<li><a href="#gundo_preview_height">g:gundo_preview_height</a></li>
<li><a href="#gundo_preview_bottom">g:gundo_preview_bottom</a></li>
<li><a href="#gundo_right">g:gundo_right</a></li>
<li><a href="#gundo_help">g:gundo_help</a></li>
<li><a href="#gundo_disable">g:gundo_disable</a></li>
</ul>
</li>
<li><a href="#license">License</a></li>
<li><a href="#bugs">Bugs</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#changelog">Changelog</a></li>
<li><a href="#credits">Credits</a></li>
</ol>
</nav>
<section>
<a name="requirements"></a>
<h1>Requirements</h1>
<p>
Gundo requires Vim 7.3+ compiled with Python support, and Python 2.4+.
</p>
</section>
<section>
<a name="installation"></a>
<h1>Installation</h1>
<p>Use Pathogen. Don't use pathogen? Start.</p>
<pre>hg clone http://bitbucket.org/sjl/gundo.vim ~/.vim/bundle/gundo</pre>
<p>There's a git mirror if you prefer:</p>
<pre>git clone http://github.com/sjl/gundo.vim.git ~/.vim/bundle/gundo</pre>
<p>Add a mapping to your ~/.vimrc (change the key to suit your taste):</p>
<pre>nnoremap <F5> :GundoToggle<CR></pre>
</section>
<section>
<a name="usage"></a>
<h1>Usage</h1>
<p>
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:
</p>
<pre>nnoremap <F5> :GundoToggle<CR></pre>
<p>
Change the mapped key to suit your taste. We'll stick with <code><F5></code> because that's
what the author uses.
</p>
<p>
Now you can press <code><F5></code> to toggle the undo graph and preview pane, which will
look something like this:
</p>
<pre>
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
</pre>
<p>
Your current position in the undo tree is marked with an <code>@</code> character. Other
nodes are marked with an <code>o</code> character.
</p>
<p>
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 <code>j</code> and
<code>k</code> keys.
</p>
<p>
You can move to the top of the graph (the newest state) with <code>gg</code> and to the
bottom of the graph (the oldest state) with <code>G</code>.
</p>
<p>
As you move between undo states the preview pane will show you a unified diff
of the change that state made.
</p>
<p>
Pressing <code>return</code> on a state (or double clicking on it) will
revert the contents of the file to match that state.
</p>
<p>
You can use <code>p</code> 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.
</p>
<p>
Pressing <code>P</code> 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.
</p>
<p>
Pressing <code>q</code> while in the undo graph will close it. You can also just press your
toggle mapping key.
</p>
</section>
<section>
<a name="configuration"></a>
<h1>Configuration</h1>
<p>
You can tweak the behavior of Gundo by setting a few variables
in your :vimrc file. For example:
</p>
<pre>
let g:gundo_width = 60
let g:gundo_preview_height = 40
let g:gundo_right = 1
</pre>
<a name="gundo_width"></a>
<h2>g:gundo_width</h2>
<p>Set the horizontal width of the Gundo graph (and preview).</p>
<p>Default: 45</p>
<a name="gundo_preview_height"></a>
<h2>g:gundo_preview_height</h2>
<p>Set the vertical height of the Gundo preview.</p>
<p>Default: 15</p>
<a name="gundo_preview_bottom"></a>
<h2>g:gundo_preview_bottom</h2>
<p>
Force the preview window below current windows instead of below
the graph. This gives the preview window more space to show the
unified diff.
</p>
<p>Example:</p>
<pre>
+--------+ +--------+
!g! ! ! !g!
!g! ! or ! !g!
!g!______! !______!g!
!g!pppppp! !pppppp!g!
+--------+ +--------+
</pre>
<p>Default: 0</p>
<a name="gundo_right"></a>
<h2>g:gundo_right</h2>
<p>
Set this to 1 to make the Gundo graph (and preview) open on the
right side instead of the left.
</p>
<p>Default: 0 (off, open on the left side)</p>
<a name="gundo_help"></a>
<h2>g:gundo_help</h2>
<p>Set this to 0 to disable the help text in the Gundo graph window.</p>
<p>Default: 1 (show the help)</p>
<a name="gundo_disable"></a>
<h2>g:gundo_disable</h2>
<p>Set this to 1 to disable Gundo entirely.</p>
<p>
Useful if you use the same <code>~/.vim</code> folder on
multiple machines, and some of them may not have Python support.
</p>
<p>Default: 0 (Gundo is enabled as usual)</p>
</section>
<section>
<a name="license"></a>
<h1>License</h1>
<p><a href="http://www.opensource.org/licenses/gpl-2.0.php">GPLv2+</a>.</p>
</section>
<section>
<a name="bugs"></a>
<h1>Bugs</h1>
<p>
If you find a bug please post it on the
<a href="http://bitbucket.org/sjl/gundo.vim/issues?status=new&status=open">issue tracker</a>.
</p>
</section>
<section>
<a name="contributing"></a>
<h1>Contributing</h1>
<p>
Fork the repository on
<a href="http://bitbucket.org/sjl/gundo.vim/">BitBucket</a>
or
<a href="http://github.com/sjl/gundo.vim/">GitHub</a>
and send a pull request.
</p>
<p>Make sure you document your changes in the following places:</p>
<ul>
<li>The <code>README.markdown</code> file.</li>
<li>The <code>site/index.html</code> file.</li>
<li>The <code>doc/gundo.txt</code> file.</li>
</ul>
</section>
<section>
<a name="changelog"></a>
<h1>Changelog</h1>
<ol class="changelog">
<li>v2.0.0
<ul>
<li>
Make <code>GundoToggle</code> close the Gundo windows if they're
visible but not the current window, instead of moving to them.
</li>
<li>Add the <code>g:gundo_disable</code> setting.</li>
<li>Add the <code>g:gundo_help</code> setting.</li>
<li>
Add the <code>p</code> mapping to preview the result of
reverting to the selected state.
</li>
<li>Fix movement commands with counts in the graph.</li>
</ul>
</li>
<li>v1.0.0
<ul>
<li>Initial stable release.</li>
</ul>
</li>
</ol>
</section>
<section>
<a name="credits"></a>
<h1>Credits</h1>
<p>
The graphing code was all taken from Mercurial, hence the
GPLv2+ license.
</p>
<p>
The plugin was heavily inspired by histwin.vim, and the code
for scratch.vim helped the author get started.
</p>
</section>
<footer>
Gundo was written by
<a href="http://stevelosh.com">Steve Losh</a>
with a lot of help from others.
</footer>
</div>
</body>
</html>