gundo.vim/doc/gundo.txt

*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|
        3.10 gundo_auto_preview ........ |gundo_auto_preview|
        3.11 gundo_playback_delay ...... |gundo_playback_delay|
        3.12 gundo_return_on_revert .... |gundo_return_on_revert|
    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 <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 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)

------------------------------------------------------------------------------
3.10 g:gundo_auto_preview                                 *gundo_auto_preview*

Set this to 0 to disable automatically rendering preview diffs as you move
through the undo tree (you can still render a specific diff with r).  This can
be useful on large files and undo trees to speed up Gundo.

Default: 1 (automatically preview diffs)

------------------------------------------------------------------------------
3.11 g:gundo_playback_delay                             *gundo_playback_delay*

This is the delay in milliseconds between each change when running 'play to'
mode. Set this to a higher number for a slower playback or to a lower number
for a faster playback.

Default: 60

------------------------------------------------------------------------------
3.12 g:gundo_return_on_revert                         *gundo_return_on_revert*

Set this to 0 to keep focus in the Gundo window after a revert.

Default: 1

==============================================================================
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.6.0
    * Fix several Python-related bugs.
    * Add g:gundo_return_on_revert option.
v2.5.0
    * Fix the help window to take custom mappings into account.
    * Add g:gundo_playback_delay option.
v2.4.0
    * Add auto preview option.
    * Add 'r' mapping to preview current state.
    * Add public gundo#GundoShow() and gundo#GundoHide() functions.
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 <j> and <k> mappings are now configurable with
      g:gundo_map_move_older and g:gundo_map_move_newer.
    * The o, <Up> and <Down> 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.

==============================================================================