*undotree.txt*  The undo history visualizer for VIM

Author:         Ming Bai <mbbill AT gmail DOT COM>
Licence:        BSD
Homepage:       https://github.com/mbbill/undotree/

==============================================================================
CONTENTS                                                     *undotree-contents*

    1. Intro ................................ |undotree-intro|
    2. Usage ................................ |undotree-usage|
    3. Configuration ........................ |undotree-config|
        3.1  undotree_WindowLayout .......... |undotree_WindowLayout|
        3.2  undotree_CustomUndotreeCmd...... |undotree_CustomUndotreeCmd|
             undotree_CustomDiffpanelCmd..... |undotree_CustomDiffpanelCmd|
        3.3  undotree_SplitWidth ............ |undotree_SplitWidth|
        3.4  undotree_DiffpanelHeight ....... |undotree_DiffpanelHeight|
        3.5  undotree_DiffAutoOpen .......... |undotree_DiffAutoOpen|
        3.6  undotree_SetFocusWhenToggle .... |undotree_SetFocusWhenToggle|
        3.7  undotree_TreeNodeShape ......... |undotree_TreeNodeShape|
             undotree_TreeVertShape ......... |undotree_TreeVertShape|
             undotree_TreeSplitShape ........ |undotree_TreeSplitShape|
             undotree_TreeReturnShape ....... |undotree_TreeReturnShape|
        3.8  undotree_DiffCommand ........... |undotree_DiffCommand|
        3.9  undotree_RelativeTimestamp ..... |undotree_RelativeTimestamp|
        3.10 undotree_ShortIndicators ....... |undotree_ShortIndicators|
        3.11 undotree_HighlightChangedText .. |undotree_HighlightChangedText|
        3.12 undotree_HighlightSyntaxAdd .... |undotree_HighlightSyntaxAdd|
             undotree_HighlightSyntaxChange . |undotree_HighlightSyntaxChange|
        3.13 Undotree_CustomMap ............. |Undotree_CustomMap|
        3.14 undotree_HelpLine .............. |undotree_HelpLine|
        3.15 undotree_CursorLine ............ |undotree_CursorLine|
        3.16 undotree_UndoDir................ |undotree_UndoDir|
    4. Bugs ................................. |undotree-bugs|
    5. Changelog ............................ |undotree-changelog|
    6. License .............................. |undotree-license|

==============================================================================
1. Intro                                                        *undotree-intro*

The plug-in visualizes undo history and makes it easier to browse and switch
between different undo branches. You might wonder what are undo "branches"?
It's vim feature that allows you to go back to a state when it is overwritten
by a latest edit. For most editors, if you make a change A, then B, then go
back to A and make change C, normally you won't be able to go back to B
because undo history is linear. That's not the case for Vim because it
internally keeps all the edit history like a tree structure, and this plug-in
exposes the tree to you so that you not only can switch back and forth but
also can switch between branches.

Some people have questions about file contents being changed when switching
between undo history states. Don't worry, undotree will NEVER save your data
or write to disk. All it does is to change the current buffer little bit, just
like those auto-completion plug-ins do. It just adds or removes something in
the buffer temporarily, and if you don't like you can always go back to the
last state easily. Let's say, you made some change but didn't save, then you
use undotree and go back to an arbitrary version, your unsaved change doesn't
get lost - it stores in the latest undo history node. Clicking that node on
undotree will bring you back instantly. Play with undo/redo on other editors
is always dangerous because when you step back and accidentally typed
something, boom! You lose your edits. But don't worry, that won't happen in
Vim. Then you might ask what if I make some changes without saving and switch
back to an old version and then exit? Well, imagine what would happen if you
don't have undotree? You lose your latest edits and the file on disk is your
last saved version. This behaviour remains the same with undotree. So, if you
saved, you won't lose anything.

We all know that usually undo/redo is only for the current edit session. It's
stored in memory and once the process exits, the undo history is lost.
Although undotree makes switching between history states easier, it doesn't do
more than that. Sometimes it would be much safer or more convenient to keep
the undo history across edit sessions. In this case you might need to enable a
Vim feature called persistent undo. Let me explain how persistent undo works:
instead of keeping undo history in RAM, persistent undo keeps undo history in
file. Let's say you make a change A, then B, then go back to A and make change
C, then you save the file. Now Vim save the file with content state C, and in
the mean time it saves the entire undo history to a file including state A, B
and C. Next time when you open the file, Vim will also restore undo history.
So you can still go back to B. The history file is incremental, and every
change will be recorded permanently, kind of like Git. You might think that's
too much, well, undotree does provide a way to clean them up. If you need to
enable persistent undo, type :h persistent-undo or follow the instructions
below.

Undotree is written in pure Vim script and doesn't rely on any third party
tools. It's lightweight, simple and fast. It only does what it supposed to do,
and it only runs when you need it.

==============================================================================
2. Usage                                                        *undotree-usage*

Use :UndotreeToggle to toggle the undo-tree panel. You may want to map this
command to whatever hotkey by adding the following line to your vimrc, take F5
for example.
>
    nnoremap <F5> :UndotreeToggle<cr>
<
Markers

  * Every change has a sequence number and it is displayed before timestamps.

  * The current state is marked as > number <.

  * The next state which will be restored by :redo or <ctrl-r> is marked as
    { number }.

  * The [ number ] marks the most recent change.

  * The undo history is sorted by timestamps.

  * Saved changes are marked as s and the big S indicates the most recent
    saved change.

  * Press ? in undotree window for quick help.

Persistent undo

Usually I would like to store the undo files in a separate place like below.
>
    if has("persistent_undo")
       let target_path = expand('~/.undodir')

        " create the directory and any parent directories
        " if the location does not exist.
        if !isdirectory(target_path)
            call mkdir(target_path, "p", 0700)
        endif

        let &undodir=target_path
        set undofile
    endif
<
Alternatively, the persistent undofile can be activated by using the
:UndotreePersistUndo command. This will enable the undofile for the current
buffer only, as undotree utilizes the setlocal undofile function. Once this
command is executed and the persistence undofile is created, the "setlocal
undofile" function will automatically be executed the next time the file is
reopened.

See |undotree_UndoDir|

You may want to map the command to whatever hotkey by adding this following
line to your vimrc, for instance:

    `nnoremap <F6> :UndotreePersistUndo<cr>`

==============================================================================
3. Configuration                                               *undotree-config*

------------------------------------------------------------------------------
3.1 g:undotree_WindowLayout                              *undotree_WindowLayout*

Set the undotree window layout.

Style 1
>
    +----------+------------------------+
    |          |                        |
    |          |                        |
    | undotree |                        |
    |          |                        |
    |          |                        |
    +----------+                        |
    |          |                        |
    |   diff   |                        |
    |          |                        |
    +----------+------------------------+
<
Style 2
>
    +----------+------------------------+
    |          |                        |
    |          |                        |
    | undotree |                        |
    |          |                        |
    |          |                        |
    +----------+------------------------+
    |                                   |
    |   diff                            |
    |                                   |
    +-----------------------------------+
<
Style 3
>
    +------------------------+----------+
    |                        |          |
    |                        |          |
    |                        | undotree |
    |                        |          |
    |                        |          |
    |                        +----------+
    |                        |          |
    |                        |   diff   |
    |                        |          |
    +------------------------+----------+
<
Style 4
>
    +------------------------+----------+
    |                        |          |
    |                        |          |
    |                        | undotree |
    |                        |          |
    |                        |          |
    +------------------------+----------+
    |                                   |
    |                            diff   |
    |                                   |
    +-----------------------------------+
<
Default: 1

------------------------------------------------------------------------------
3.2  g:undotree_CustomUndotreeCmd                   *undotree_CustomUndotreeCmd*
     g:undotree_CustomDiffpanelCmd                 *undotree_CustomDiffpanelCmd*

Set up custom window layout.

Setting |undotree_CustomUndotreeCmd|  will ignore |undotree_SplitWidth|, and
setting |undotree_CustomDiffpanelCmd| will ignore |undotree_DiffpanelHeight|.

An |undotree_CustomUndotreeCmd| will always open the undotree window relative
to the tracked window and |undotree_CustomDiffpanelCmd| will always open the
diffpanel relative to the undotree window.

Useful when

  * absolute positioning commands (|topleft|, |botright|) don't play well
    with other plugins

  * you have a preferred split window layout and would like to use
    UndoTree relative to one specific window only

Examples:

  * To recreate Style 1:
>
    let g:undotree_CustomUndotreeCmd  = 'topleft vertical 30 new'
    let g:undotree_CustomDiffpanelCmd = 'belowright 10 new'
<
  * To recreate Style 2:
>
    let g:undotree_CustomUndotreeCmd  = 'topleft vertical 30 new'
    let g:undotree_CustomDiffpanelCmd = 'botright 10 new'
<
  * A custom layout example:
>
    +------------------------+----------+
    |                        |          |
    |                        |    w     |
    |                        |    i     |
    |                        |    n     |
    |   window_1             |    d     |
    |                        |    o     |
    |                        |    w     |
    |                        |    |     |
    |                        |    2     |
    |                        |          |
    +------------------------+----------+
    |                                   |
    |         window_3                  |
    |                                   |
    +-----------------------------------+
<
    Using the following setup wouldn't mess up the current layout as it
    does not use absolute positioning:
>
    let g:undotree_CustomUndotreeCmd = 'vertical 32 new'
    let g:undotree_CustomDiffpanelCmd= 'belowright 12 new'
<
    Issuing :UndotreeToggle now in window_1 would result in:
>
    +--------+---------------+----------+
    |        |               |          |
    |   u    |               |    w     |
    |   n    |               |    i     |
    |   d    |               |    n     |
    |   o    |   window_1    |    d     |
    |        |               |    o     |
    +--------+               |    w     |
    |        |               |    |     |
    |  diff  |               |    2     |
    |        |               |          |
    +--------+---------------+----------+
    |                                   |
    |         window_3                  |
    |                                   |
    +-----------------------------------+
<
    Executing :UndotreeToggle again would turn off UndoTree (independently
    of which window was active at the time). Moving between window1, window_2
    and window_3 would result in showing the respective window's changelog
    in the undotree panel.

    CAVEAT: To avoid the Vim's default behaviour of equalizing window sizes
            when closing a window, set the 'noequalalways' option.

------------------------------------------------------------------------------
3.3 g:undotree_SplitWidth                                  *undotree_SplitWidth*

Set the undotree window width.

Default: 30

------------------------------------------------------------------------------
3.4 g:undotree_DiffpanelHeight                        *undotree_DiffpanelHeight*

Set the diff window height.

Default: 10

------------------------------------------------------------------------------
3.5 g:undotree_DiffAutoOpen                              *undotree_DiffAutoOpen*

Set this to 1 to auto open the diff window.

Default: 1

------------------------------------------------------------------------------
3.6 g:undotree_SetFocusWhenToggle                  *undotree_SetFocusWhenToggle*

If set to 1, the undotree window will get focus after being opened, otherwise
focus will stay in current window.

Default: 0

------------------------------------------------------------------------------
3.7 g:undotree_TreeNodeShape                            *undotree_TreeNodeShape*
    g:undotree_TreeVertShape                            *undotree_TreeVertShape*
    g:undotree_TreeSplitShape                          *undotree_TreeSplitShape*
    g:undotree_TreeReturnShape                        *undotree_TreeReturnShape*

Set the characters used to draw the tree. Although you can put any character
you want in these shape variables, the only Unicode box drawing characters
that work well are these three. Make sure your font will render them; you can
easily see if that's the case in the last column of this table.

Variable                   | Default       | Unicode Box Character
---------------------------+---------------+-----------------------
g:undotree_TreeNodeShape   | *             |
g:undotree_TreeReturnShape | \ (backslash) | ╲ (U+2572)
g:undotree_TreeVertShape   | | (pipe)      | │ (U+2502)
g:undotree_TreeSplitShape  | / (slash)     | ╱ (U+2571)

------------------------------------------------------------------------------
3.8 g:undotree_DiffCommand                                *undotree_DiffCommand*

Set the command used to get the diff output.

Default: "diff"

------------------------------------------------------------------------------
3.9 g:undotree_RelativeTimestamp                    *undotree_RelativeTimestamp*

Set to 1 to use relative timestamp.

Default: 1

------------------------------------------------------------------------------
3.10 g:undotree_ShortIndicators                       *undotree_ShortIndicators*

Set to 1 to get short timestamps when |undotree_RelativeTimestamp| is also
enabled:
>
         Before     |  After
    ===========================
    (5 seconds ago) |  (5 s)
    ----------------|----------
     (1 minute ago) |  (1 m)
    ----------------|----------
    (2 minutes ago) |  (2 m)
    ----------------|----------
      (1 hour ago)  |  (1 h)
    ----------------|----------
       (Original)   |  (Orig)
<
Default: 0

------------------------------------------------------------------------------
3.11 g:undotree_HighlightChangedText             *undotree_HighlightChangedText*

Set to 1 to highlight the changed text.

Default: 1

------------------------------------------------------------------------------
3.12 g:undotree_HighlightSyntaxAdd                 *undotree_HighlightSyntaxAdd*
     g:undotree_HighlightSyntaxDel                 *undotree_HighlightSyntaxDel*
     g:undotree_HighlightSyntaxChange           *undotree_HighlightSyntaxChange*

Set the highlight linked syntax type.
You may chose your favorite through ":hi" command.

Default: "DiffAdd", "DiffDelete" and "DiffChange"

------------------------------------------------------------------------------
3.13 g:Undotree_CustomMap                                   *Undotree_CustomMap*

There are two ways of changing the default key mappings:
The first way is to define global mappings as the following example:
>
    nmap <buffer> J <plug>UndotreeNextState
    nmap <buffer> K <plug>UndotreePreviousState
<
A better approach is to define the callback function g:Undotree_CustomMap().
The function will be called after the undotree windows is initialized, so the
key mappings only works on the undotree windows.
>
    function g:Undotree_CustomMap()
        nmap <buffer> J <plug>UndotreeNextState
        nmap <buffer> K <plug>UndotreePreviousState
    endfunc
<
List of the commands available for redefinition.
>
    <plug>UndotreeHelp
    <plug>UndotreeClose
    <plug>UndotreeFocusTarget
    <plug>UndotreeClearHistory
    <plug>UndotreeTimestampToggle
    <plug>UndotreeDiffToggle
    <plug>UndotreeNextState
    <plug>UndotreePreviousState
    <plug>UndotreeNextSavedState
    <plug>UndotreePreviousSavedState
    <plug>UndotreeRedo
    <plug>UndotreeUndo
    <plug>UndotreeEnter
<

------------------------------------------------------------------------------
3.14 g:undotree_HelpLine                                     *undotree_HelpLine*

Set to 0 to hide "Press ? for help".

Default: 1

------------------------------------------------------------------------------
3.15 g:undotree_CursorLine

Set to 0 to disable cursorline.

Default: 1

------------------------------------------------------------------------------
3.16 g:undotree_UndoDir                                      *undotree_UndoDir*

Set the path for the persistence undo directory. Due to the differing formats
of the persistence undo files between nvim and vim, the default undodir for
both has been intentionally given different paths. This ensures that users who
use both nvim and vim do not accidentally lose their persistence undo files
due to the different ways in which vim and nvim handle these files.

If the g:undotree_UndoDir is not set and undodir has been set to "." (vim's
default undodir value), then the g:undotree_UndoDir value will be set to:

    -  vim: $HOME/.local/state/undo/vim/
    - nvim: $HOME/.local/state/undo/nvim/

==============================================================================
4. Bugs                                                        *undotree-bugs*

Post any issue and feature request here:
https://github.com/mbbill/undotree/issues

==============================================================================
5. Changelog                                              *undotree-changelog*

Further changes will not be recorded. Please go to github page for more
information.

4.4 (2017-10-15)
    - Autoload plugin functions

4.3 (2013-02-18)
    - Several fixes and enhancements.

4.2 (2012-11-24)
    - Fixed some small issue.

4.1 (2012-09-05)
    - Enhanced tree style.
    - Multi-window switching support.

4.0 (2012-08-30)
    - Live updated highlight for changed text.
    - Customizable key mappings.
    - Fixed some minor bugs.

3.1 (2012-08-25)
    - Add saved status.
    - Add relative timestamp.
    - Add ability of clear undo history.

3.0 (2012-08-24)
    - Add diff panel.
    - Performance improvement.

2.2 (2012-08-21)
    - Stable version.

2.1 (2012-08-20)
    - Fixed some annoying issues.

2.0 (2012-08-19)
    - Hotkey support.
    - Handle undo levels.
    - Auto refresh.
    - And so on.

1.0 (2012-08-18)
    - Initial upload

==============================================================================
6. License                                                    *undotree-license*

BSD

 vim:tw=78:ts=8:ft=help:norl: