X-Git-Url: http://git.iain.cx/?a=blobdiff_plain;f=.vim%2Fdoc%2Fgundo.txt;fp=.vim%2Fdoc%2Fgundo.txt;h=ee9a0d42efbb204b477ed860b5ef61f14160bfc2;hb=47ff5806af2ee0d85d1026cc6a1bd6219bdb9e26;hp=0000000000000000000000000000000000000000;hpb=a0a218b2d904a23bf4cd0f2758cf59b847c24c4f;p=profile.git diff --git a/.vim/doc/gundo.txt b/.vim/doc/gundo.txt new file mode 100644 index 0000000..ee9a0d4 --- /dev/null +++ b/.vim/doc/gundo.txt @@ -0,0 +1,270 @@ +*gundo.txt* Graph your undo tree so you can actually USE it. + +Making Vim's undo tree usable by humans. + +============================================================================== +CONTENTS *Gundo-contents* + + 1. Intro .......................... |GundoIntro| + 2. Usage .......................... |GundoUsage| + 3. Configuration .................. |GundoConfig| + 3.1 gundo_width ............... |gundo_width| + 3.2 gundo_preview_height ...... |gundo_preview_height| + 3.3 gundo_preview_bottom ...... |gundo_preview_bottom| + 3.4 gundo_right ............... |gundo_right| + 3.5 gundo_help ................ |gundo_help| + 3.6 gundo_disable ............. |gundo_disable| + 3.7 gundo_map_move_older ...... |gundo_map_move_older| + gundo_map_move_newer ...... |gundo_map_move_newer| + 3.8 gundo_close_on_revert ..... |gundo_close_on_revert| + 3.9 gundo_preview_statusline .. |gundo_preview_statusline| + gundo_tree_statusline ..... |gundo_tree_statusline| + 4. License ........................ |GundoLicense| + 5. Bugs ........................... |GundoBugs| + 6. Contributing ................... |GundoContributing| + 7. Changelog ...................... |GundoChangelog| + 8. Credits ........................ |GundoCredits| + +============================================================================== +1. Intro *GundoIntro* + +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 |:undo-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. + +============================================================================== +2. Usage *GundoUsage* + +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| to toggle the undo +graph: > + + nnoremap :GundoToggle + +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 | + | " - 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 enter 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. + +============================================================================== +3. Configuration *GundoConfig* + +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 + +------------------------------------------------------------------------------ +3.1 g:gundo_width *gundo_width* + +Set the horizontal width of the Gundo graph (and preview). + +Default: 45 + +------------------------------------------------------------------------------ +3.2 g:gundo_preview_height *gundo_preview_height* + +Set the vertical height of the Gundo preview. + +Default: 15 + +------------------------------------------------------------------------------ +3.3 g:gundo_preview_bottom *gundo_preview_bottom* + +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 + +------------------------------------------------------------------------------ +3.4 g:gundo_right *gundo_right* + +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) + +------------------------------------------------------------------------------ +3.5 g:gundo_help *gundo_help* + +Set this to 0 to disable the help text in the Gundo graph window. + +Default: 1 (show the help) + +------------------------------------------------------------------------------ +3.6 g:gundo_disable *gundo_disable* + +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) + +------------------------------------------------------------------------------ +3.7 g:gundo_map_move_older, g:gundo_map_move_newer *gundo_map_move_older* + *gundo_map_move_newer* + +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" + +------------------------------------------------------------------------------ +3.8 g:gundo_close_on_revert *gundo_close_on_revert* + +Set this to 1 to automatically close the Gundo windows when reverting. + +Default: 0 (windows do not automatically close) + +------------------------------------------------------------------------------ +3.9 g:gundo_preview_statusline *gundo_preview_statusline* + g:gundo_tree_statusline *gundo_tree_statusline* + +Set these to a string to display it as the status line for each Gundo window. + +Default: unset (windows use the default statusline) + +============================================================================== +4. License *GundoLicense* + +GPLv2+. Look it up. + +============================================================================== +5. Bugs *GundoBugs* + +If you find a bug please post it on the issue tracker: +http://bitbucket.org/sjl/gundo.vim/issues?status=new&status=open + +============================================================================== +6. Contributing *GundoContributing* + +Think you can make this plugin better? Awesome. Fork it on BitBucket or GitHub +and send a pull request. + +BitBucket: http://bitbucket.org/sjl/gundo.vim/ +GitHub: http://github.com/sjl/gundo.vim/ + +============================================================================== +7. Changelog *GundoChangelog* + +v2.3.0 + * Add statusline configuration. +v2.2.2 + * More performance improvements. +v2.2.1 + * Refactoring and performance improvements. +v2.2.0 + * Add the g:gundo_close_on_revert setting. + * Fix a bug with the splitbelow setting. +v2.1.1 + * Fix a bug with the movement key mappings. +v2.1.0 + * Warnings about having an incompatible Vim and/or Python installation + are now deferred until the first time you try to use Gundo, instead + of being displayed on launch. + * The and mappings are now configurable with + g:gundo_map_move_older and g:gundo_map_move_newer. + * The o, and keys are now mapped in the Gundo pane. + * Improve and add several unit tests for Gundo. +v2.0.0 + * Make GundoToggle close the Gundo windows if they're visible but not the + current window, instead of moving to them. + * Add the g:gundo_help setting. + * Add the g:gundo_disable setting. + * Add the 'p' mapping to preview the result of reverting to the selected + state. + * Fix movement commands with counts in the graph. +v1.0.0 + * Initial stable release. + +============================================================================== +8. Credits *GundoCredits* + +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. + +==============================================================================