.vim/doc/gundo.txt

   1 *gundo.txt*   Graph your undo tree so you can actually USE it.
   2
   3 Making Vim's undo tree usable by humans.
   4
   5 ==============================================================================
   6 CONTENTS                                                      *Gundo-contents*
   7
   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|
  27
  28 ==============================================================================
  29 1. Intro                                                          *GundoIntro*
  30
  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.
  34
  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
  37 you can get it back.
  38
  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.
  42
  43 Gundo is a plugin to make browsing this ridiculously powerful undo tree less
  44 painful.
  45
  46 ==============================================================================
  47 2. Usage                                                          *GundoUsage*
  48
  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
  51 graph: >
  52
  53     nnoremap <F5> :GundoToggle<CR>
  54
  55 Change the mapped key to suit your taste. We'll stick with F5 because that's
  56 what the author uses.
  57
  58 Now you can press F5 to toggle the undo graph and preview pane, which will
  59 look something like this: >
  60
  61       Undo graph                          File
  62     +-----------------------------------+------------------------------------+
  63     | " Gundo for something.txt [1]     |one                                 |
  64     | " j/k  - move between undo states |two                                 |
  65     | " <cr> - revert to that state     |three                               |
  66     |                                   |five                                |
  67     | @  [5] 3 hours ago                |                                    |
  68     | |                                 |                                    |
  69     | | o  [4] 4 hours ago              |                                    |
  70     | | |                               |                                    |
  71     | o |  [3] 4 hours ago              |                                    |
  72     | | |                               |                                    |
  73     | o |  [2] 4 hours ago              |                                    |
  74     | |/                                |                                    |
  75     | o  [1] 4 hours ago                |                                    |
  76     | |                                 |                                    |
  77     | o  [0] Original                   |                                    |
  78     +-----------------------------------+                                    |
  79     | --- 3 2010-10-12 06:27:35 PM      |                                    |
  80     | +++ 5 2010-10-12 07:38:37 PM      |                                    |
  81     | @@ -1,3 +1,4                      |                                    |
  82     |  one                              |                                    |
  83     |  two                              |                                    |
  84     |  three                            |                                    |
  85     | +five                             |                                    |
  86     +-----------------------------------+------------------------------------+
  87       Preview pane
  88
  89 Your current position in the undo tree is marked with an '@' character. Other
  90 nodes are marked with an 'o' character.
  91
  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
  94 k keys.
  95
  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.
  98
  99 As you move between undo states the preview pane will show you a unified diff
 100 of the change that state made.
 101
 102 Pressing enter on a state (or double clicking on it) will revert the contents
 103 of the file to match that state.
 104
 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.
 108
 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.
 114
 115 Pressing q while in the undo graph will close it.  You can also just press your
 116 toggle mapping key.
 117
 118 ==============================================================================
 119 3. Configuration                                                 *GundoConfig*
 120
 121 You can tweak the behavior of Gundo by setting a few variables in your :vimrc
 122 file. For example: >
 123
 124     let g:gundo_width = 60
 125     let g:gundo_preview_height = 40
 126     let g:gundo_right = 1
 127
 128 ------------------------------------------------------------------------------
 129 3.1 g:gundo_width                                                *gundo_width*
 130
 131 Set the horizontal width of the Gundo graph (and preview).
 132
 133 Default: 45
 134
 135 ------------------------------------------------------------------------------
 136 3.2 g:gundo_preview_height                              *gundo_preview_height*
 137
 138 Set the vertical height of the Gundo preview.
 139
 140 Default: 15
 141
 142 ------------------------------------------------------------------------------
 143 3.3 g:gundo_preview_bottom                              *gundo_preview_bottom*
 144
 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.
 147
 148 Example:
 149
 150    +--------+            +--------+
 151    !g!      !            !      !g!
 152    !g!      !     or     !      !g!
 153    !g!______!            !______!g!
 154    !g!pppppp!            !pppppp!g!
 155    +--------+            +--------+
 156
 157 Default: 0
 158
 159 ------------------------------------------------------------------------------
 160 3.4 g:gundo_right                                                *gundo_right*
 161
 162 Set this to 1 to make the Gundo graph (and preview) open on the right side
 163 instead of the left.
 164
 165 Default: 0 (off, open on the left side)
 166
 167 ------------------------------------------------------------------------------
 168 3.5 g:gundo_help                                                  *gundo_help*
 169
 170 Set this to 0 to disable the help text in the Gundo graph window.
 171
 172 Default: 1 (show the help)
 173
 174 ------------------------------------------------------------------------------
 175 3.6 g:gundo_disable                                            *gundo_disable*
 176
 177 Set this to 1 to disable Gundo entirely.
 178
 179 Useful if you use the same ~/.vim folder on multiple machines, and some of
 180 them may not have Python support.
 181
 182 Default: 0 (Gundo is enabled as usual)
 183
 184 ------------------------------------------------------------------------------
 185 3.7 g:gundo_map_move_older, g:gundo_map_move_newer      *gundo_map_move_older*
 186                                                         *gundo_map_move_newer*
 187
 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.
 190
 191 Default: gundo_map_move_older = "j"
 192          gundo_map_move_newer = "k"
 193
 194 ------------------------------------------------------------------------------
 195 3.8 g:gundo_close_on_revert                            *gundo_close_on_revert*
 196
 197 Set this to 1 to automatically close the Gundo windows when reverting.
 198
 199 Default: 0 (windows do not automatically close)
 200
 201 ------------------------------------------------------------------------------
 202 3.9 g:gundo_preview_statusline                      *gundo_preview_statusline*
 203     g:gundo_tree_statusline                            *gundo_tree_statusline*
 204
 205 Set these to a string to display it as the status line for each Gundo window.
 206
 207 Default: unset (windows use the default statusline)
 208
 209 ==============================================================================
 210 4. License                                                      *GundoLicense*
 211
 212 GPLv2+. Look it up.
 213
 214 ==============================================================================
 215 5. Bugs                                                            *GundoBugs*
 216
 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
 219
 220 ==============================================================================
 221 6. Contributing                                            *GundoContributing*
 222
 223 Think you can make this plugin better? Awesome. Fork it on BitBucket or GitHub
 224 and send a pull request.
 225
 226 BitBucket: http://bitbucket.org/sjl/gundo.vim/
 227 GitHub: http://github.com/sjl/gundo.vim/
 228
 229 ==============================================================================
 230 7. Changelog                                                  *GundoChangelog*
 231
 232 v2.3.0
 233     * Add statusline configuration.
 234 v2.2.2
 235     * More performance improvements.
 236 v2.2.1
 237     * Refactoring and performance improvements.
 238 v2.2.0
 239     * Add the g:gundo_close_on_revert setting.
 240     * Fix a bug with the splitbelow setting.
 241 v2.1.1
 242     * Fix a bug with the movement key mappings.
 243 v2.1.0
 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.
 251 v2.0.0
 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
 257       state.
 258     * Fix movement commands with counts in the graph.
 259 v1.0.0
 260     * Initial stable release.
 261
 262 ==============================================================================
 263 8. Credits                                                      *GundoCredits*
 264
 265 The graphing code was all taken from Mercurial, hence the GPLv2+ license.
 266
 267 The plugin was heavily inspired by histwin.vim, and the code for scratch.vim
 268 helped the author get started.
 269
 270 ==============================================================================