*histwin.txt*	For Vim version 7.3	Last change: 2010 Nov. 18

Author:  Christian Brabandt <cb@256bit.org>
Copyright: (c) 2009, 2010 by Christian Brabandt           *histwin-copyright*
           The VIM LICENSE applies to histwin.vim and histwin.txt
           (see |copyright|) except use histwin instead of "Vim".
           NO WARRANTY, EXPRESS OR IMPLIED.  USE AT-YOUR-OWN-RISK.

=============================================================================
1. Contents                                                 *histwin-contents*

1. Contents.................................................|histwin-contents|
2. Functionality............................................|histwin-plugin|
   Opening the Undo-Tree Window.............................|histwin-browse|
   Using tags...............................................|histwin-tags|
3. Keybindings..............................................|histwin-keys|
4. Configuration............................................|histwin-config|
   Configuraion Variables...................................|histwin-var|
   Color Configuration......................................|histwin-color|
   Undolevels settings......................................|histwin-ut|
   Configuring the preview window...........................|histwin-prev|
   Highlight changed lines..................................|histwin-highl|
5. Feedback.................................................|histwin-feedback|
6. History..................................................|histwin-history|

=============================================================================
                                                    *histwin-plugin* *histwin*
2. Functionality

This plugin was written to allow an easy way of browsing the |undo-tree|, that
is available with Vim. This allows to go back to any change that has been made
previously, because these states are remembered by Vim within a branch in the
undo-history. You can use |g-| or |g+| to move in Vim within the different
undo-branches.

Unfortunately, going back to any state isn't very comfortable and you always
need to remember at what time you did that change. Therefore the
histwin-Plugin allows to easily view the available states and branch back to
any of these states. It opens a new window, which contains all available
states and using this plugin allows you to tag a previous change or go back to
a particular state.

						*histwin-browse* *:UB* *:Histwin*
2.1 Opening the Undo-Tree Window

By default you can open the Undo-Tree Window by issuing :UB (Mnemonic:
UndoBrowse). Alternatively, you can use the command :Histwin
If you do this, you will see a window that looks like this:

+------------------------------------------------------+ `
|Undo-Tree: FILENAME           |#!/bin/bash            | `
|======================        |                       | `
|                              |                       | `
|" actv. keys in this window   |if [ $# -ne 2 ];  the  | `
|" I toggles help screen       |    echo "Name: $0: arg| `
|" <Enter> goto undo branch    |    echo               | `
|" <C-L>   Update view         |    exit 1             | `
|" T       Tag sel. branch     |fi                     | `
|" P       Toggle view         |                       | `
|" D       Diff sel. branch    |if true; then          | `
|" U       Preview unif. Diff  |                       | `
|" R       Replay sel. branch  |    dir="${1%/*}"      | `
|" C       Clear all tags      |    file="${1##*/}"    | `
|" Q       Quit window         |    target="${2}/${di  | `
|"                             |    if [ ! -e "${targ  | `
|" Undo-Tree, v0.20            |        mkdir -p "$ta  | `
|                              |        mv "$1" "$tar  | `
|Nr   Time   Fl  Tag           |                       | `
|1)   Sep 01    /Start Editing/|                       | `
|2)   Sep 01 !  /First draft/  |                       | `
|3) 23:01:22                   |                       | `
|4) 23:02:57 *  /Release 1/    |                       | `
|5) 23:05:04                   |                       | `
+------------------------------------------------------+ `

This shows an extract of a sample file on the right side. The window on the
left side, contains an overview of all available states that are known for
this buffer or that have been tagged to remember that change.

The first line contains 'Undo-Tree: filename' so that the user knows, for
which file this window shows the available undo-branches. This is the heading.

Following the heading is a small information banner, that contains the most
important key combinations, that are available in this window. 

After that list, all available undo-changes are displayed. This is a list,
that contains the number, the time this change was made, some flags and the
tags, that have been entered.

The flags can be any of '!' or '*'. The '!' indicates, that this particular
undo branch (that was probably tagged before) isn't available any more. The
'*'  indicates, if that particular undo branch has been saved before (but is
only visible in the dense view). See |histwin-ut| on why certain states might
become inaccessible and what can be done against it. 

In the detailed view, that is by default displayed, when you press 'P', the
undo branch list will possibly be much longer. That is, because in this view,
each save state will be displayed (along with it's save number). You
can imagine, that this list might become very long.

Additionally, the Change number, that identifies each change in the undo tree
will be displayed. The change number can be used with the |:undo| command to
jump to a particular change and the save number is useful with the |:earlier|
and |:later| commands. 

The active undo-branch on the right side is highlighted with the UBActive
highlighting and the cursor will be positioned on that line. Use >

:hi UBActive

to see how it will be highlighted. See also |histwin-color|.


                                                               *histwin-tags*

By default, tags that you enter will be volatile. That is, whenever you quit
Vim, these tags are lost. Currently there is no way, to store or retrieve old
tags.

This behaviour was okay, until with Vim 7.3 the new permanent undo feature was
included into Vim which makes undo information available even after restarting
Vim. Starting with Vim 7.3 it is often desirable, to also store the tag
information permanently.

There is an easy way, to store your tag information easily, though. You can
make use of the |viminfo| file, that stores states and search patterns and a
like for later use. If you include the '!' flag when setting the option, vim
will also store global variables, which then will be read back when restarting
Vim (or by use of |rviminfo|). So if you like your tags be stored permanently,
be sure, that you set your viminfo option correctly. See also 'viminfo'

(Note, Storing Dicts and Lists in the viminfo file is supported since Vim
7.3.30 and is currently an experimental feature of the histwin plugin. Since
the histwin plugin stores needs to store a nested Dictionary, Vim might still
fail reading it back correctly)

==============================================================================
                                                               *histwin-keys*
3. Keybindings

By default, the following keys are active in Normal mode in the Undo-Tree
window:

'Enter'  Go to the branch, on which is selected with the cursor. By default,
         if switching to an older branch, the buffer will be set to
         'nomodifiable'. If you don't want that, you need to set the
         g:undo_tree_nomod variable to off (see |histwin-var|).
'<C-L>'  Update the window
'T'      Tag the branch, that is selected. You'll be prompted for a tag.
         To make the tag permanent, see |histwin-tags|
'P'      Toggle view (the change-number and save number will be displayed).
         You can use this number to go directly to that change (see |:undo|).
         Additionally the saved counter will be displayed, which can be used
         to go directly to the text version of a file write using |later| or
         |earlier|.
'D'      Start diff mode with the branch that is selected by the cursor.
         (see |08.7|)
'U'      Open the preview window with a unified diff between the selected
         branch and the current state of the buffer. (This requires that a
         diff executable is found in your path, see |histwin-prev| for
         adjusting the diff-options and also for having the preview-window
         automatically opened after 'updatetime').
'R'      Replay all changes, that have been made from the beginning.
         (see |histwin-config| for adjusting the speed)
'C'      Clear all tags.
'Q'      Quit window
'X'      Purge Undo history

==============================================================================
                                                *histwin-var* *histwin-config*
4.1 Configuration variables

You can adjust several parameters for the Undo-Tree window, by setting some
variables in your .vimrc file.

------------------------------------------------------------------------------

4.1.1 Disable printing the help

To always show only a small information banner, set this in your .vimrc
(by default this variable is 1) >

    :let g:undo_tree_help = 0

------------------------------------------------------------------------------

4.1.2 Display more details

To always display the detailed view (which includes the Change number and the
file save counter), set the g:undo_tree_dtl=0:
(by default, this variable is 1) >

    :let g:undo_tree_dtl = 0

The change number can be used to directly jump to a undo state using |:undo|
and the save counter can be used to directly go to the buffer's state when the
file was written using |:earlier| and |:later|

------------------------------------------------------------------------------

4.1.3 Customize the replay speed

The speed with which to show each change, when replaying a undo-branch can be
adjusted by setting to a value in milliseconds. If not specified, this is
100ms. >

    :let g:undo_tree_speed=200

------------------------------------------------------------------------------

4.1.4 Adjust the window size.

You can adjust the windows size by setting g:undo_tree_wdth to the number of
columns you like. By default this is considered 30. When the change number is
included in the list (see above), this value will increase by 10. >

    :let g:undo_tree_wdth=40

This will change the width of the window to 40 or 50, if the change number
is included.

------------------------------------------------------------------------------

4.1.5 Read-only and writable buffer states

By default, old buffer states are set read only and you cannot modify these.
This was done, since the author of the plugin started browsing the undo
branches and started changing older versions over and over again. This is
really confusing, since you start creating even more branches and you might
end up fixing old bugs over and over.

This is what happened to the author of this plugin, so now there is a
configuration available that will set old buffers to be only read-only.
Currently, this works, by detecting, if the cursor was on the last branch in
the histwin window, and if the cursor was not on the last branch, the buffer
will be set 'nomodifiable'. You can always set the buffer to be modifiable by
issuing: >

    :setl modifiable

The default is to set the buffer read only. To disable this, you can set the
g:undo_tree_nomod variable in your |.vimrc| like this: >

    :let g:undo_tree_nomod = 0

------------------------------------------------------------------------------

                                                               *histwin-color*
4.2 Color configuration

If you want to customize the colors, you can simply change the following
groups, that are defined by the Undo-Tree Browser:

UBTitle   this defines the color of the title file-name. By default this links
          to Title (see |hl-Title|)
UBInfo    this defines how the information banner looks like. By default this
          links to Comment.
UBList    this group defines the List items at the start e.g. 1), 2), This
          links  to Identifier.
UBTime    this defines, how the time is displayed. This links to Underlined.
UBTag     This defines, how the tag should be highlighted. By default this
          links to Special
UBDelim   This group defines the look of the delimiter for the tag. By default
          this links to Ignore
UBActive  This group defines how the active selection is displayed. By default
          this links to PmenuSel (see |hl-PmenuSel|)
UBKey     This group defines, how keys are displayed within the information
          banner. By default, this links to SpecialKey (see |hl-SpecialKey|)

Say you want to change the color for the Tag values and you think, it should
look like |IncSerch|, so you can do this in your .vimrc file: >

:hi link UBTag IncSearch

------------------------------------------------------------------------------

                                                               *histwin-ut*
4.3 Undolevel settings

When using Vim's |persistent-undo| feature and making many changes, you might
encounter the situation, when some of your tags will be flagged with an '!'.
This happens, when these undo-states are not available any more. This happens
especially, when making so many changes, that your 'undolevels' setting
interferes. Basically you have done so many changes, that your first changes
will already be deleted. So the obvious fix is to set the 'undolevels' setting
to a much higher value, like 10,000 or even higher. This will however increase
the memory usage quite a lot.

------------------------------------------------------------------------------
                                                                *histwin-prev*
4.4 Configuring diff options, for display in the preview-window

If you press 'U' in the histwin, the |preview-window| will open and display
a diff (by default in unified diff format) of the selected undo branch and
your buffer. This requires however, that a diff executable is found in your
path. The default paramters for the diff executable are: >

    diff -au 

This means, diff will treat all files as text (-a) and create a unified diff
(with 3 lines of unified context). You can however use your own format. If for
example you prefer context diffs, set the g:undo_tree_diffparam variable like
this in your |.vimrc|: >

    let g:undo_tree_diffparam = 'diff -c'

Note, that you need to specify the diff utility explicitly. This enables you
to even use a different tool then diff (but even then to work correctly,
you'll need a diff binary in your path).

Additionally, you can configure the histwin plugin to automatically open the
|preview-window| after 'updatetime' milliseconds have past without a key
press in Normal mode. To enable this, set the  g:undo_tree_preview_aucmd
variable in your |.vimrc| to 1 like this: >

    let g:undo_tree_preview_aucmd = 1

To disable this, simply set g:undo_tree_preview_aucmd to zero and Close and
Reopen the histwin window.

------------------------------------------------------------------------------

						    *histwin-highl*
						    *:HistID*
4.5 Highlight changed lines

The histwin plugin also allows to automatically highlight those lines, that
have been changed since the last save. It does so by placing small signs in
the first column:

  '+' This is the sign for an added line
  '-' This is the sign for a deleted line
  '*' This is the sign for a modified line

This feature needs a Vim with |+signs| support, so if this does not work for
you, check the |:version| output.

To enable this feature, set the g:undo_tree_highlight_changes variable, e.g.
in your |.vimrc| >

  :let g:undo_tree_highlight_changes=1
<
When this variable is set, Vim sets up an |CursorHold| autocommand, thatt will
check your buffer for changes against the last saved version. To disable this
feature, simply set this variable to 0.

If you don't want to have these signs put on permanently, you can also invoke
the command (:HistID, Mnemonic, IndicateDifferences) manually: >

    :HistID
<
which will place the signs in your buffer only once and is not as disturbing
as an auto command is.

==============================================================================
                                                           *histwin-feedback*
5. Feedback

Feedback is always welcome. If you like the plugin, please rate it at the
vim-page:
http://www.vim.org/scripts/script.php?script_id=2932

You can also follow the development of the plugin at github:
http://github.com/chrisbra/histwin.vim

Please don't hesitate to report any bugs to the maintainer, mentioned in the
third line of this document.

==============================================================================
                                                            *histwin-history*
6. histwin History

0.26 
        - prevent loading of autoload script too early (reported by Sergey
	  Khorev, thanks!)
	- apply &fenc setting before writing file for diff (patch by Ben
	  Fritz, thanks!)
0.25    - fixes issue 2 from github
	  https://github.com/chrisbra/histwin/issues/2
	  (When 'splitright' is set, Diffing a previous undo branch
	  separates the window layout, reported by bootleq, thanks!)
0.24    - :ID is already defined by visincr plugin
          instead use the command :HistID
0.23    - Purge Undo history with 'X'
0.22    - Display signs for changed lines
        - |:ID|
        - small code improvements
0.21    - more standard like help files
        - make sure, the autoload script is only called when needed
	  (and not on startup)
0.20    - Enable storing the tags as Dicionary in .viminfo
          (this might not work as expected, cause we are storing a nested
          Dictionary)
        - Show a diff in the preview window when pressing P (or on autocommand
          CursorHold if enabled)
        - a little bit code cleanup (as always ;))
        - correctly catch E830 and give an error message (reported by D.
          Fishburn)
0.19    - Make sure the first entry will be tagged "Start Editing"
0.18    - don't leave the buffer in nomodifiable state (reported by Dave
          Doran)
0.17    - don't hide the initial entry (for Vim < 7.3.005)
0.16    - more bugfixing. :UB throws errors in Vim before 7.3.005 fix that
0.15    - Fixed bug when no undo-tree was available (partly by Ben Boeckel.
          Thanks!)
        - More error handling (when the cursor is not on a list item)
        - Commenting out the entry to store the histdict in a global variable,
          that should be written to the .viminfo file (but is not yet
          supported by plain vim)
0.14    - don't fix the width of the histwin window
        - now use the undotree() function by default (if patch 7.3.005 is
          included)
        - display save states in the detailed view
        - display the '!' when a state is not accessible anymore
        - fixed an annoying bug, that when jumping to a particular undo state,
          the plugin would jump to the wrong state (I hate octal mode)
        - Make displaying the time much more reliable and also don't display
          the time, if the change happened more than 24h ago (instead, display
          the date, when this change was done).
        - slightly improved error handling.
        - prepare plugin, to permantly store the undotags in the viminfo file
          (this isn't supported by a plain vanilla vim and requires a patch)
        - A major rewrite (code cleanup, better documentation)
0.13    - New version that uses Vim 7.3 persistent undo features
          |new-persistent-undo|
        - Display saved counter in detailed view
        - Display indicator for saved branches.
        - in diff mode, don't set the original buffer to be nomodifiable
          (so you can always merge chunks).
        - Check for Vim Version 7.3 (the plugin won't work with older versions
          of Vim)
0.12    - Small extension to the help file
        - generate help file with 'et' set, so the README at github looks
          better
        - Highlight the key binding using |hl-SpecialKey|
        - The help tag for the color configuration was wrong.
0.11    - Set old buffers read only (disable the setting via the 
          g:undo_tree_nomod variable
        - Make sure, Warning Messages are really displayed using :unsilent
0.10    - Fixed annoying Resizing bug
        - linebreak tags, if they are too long
        - dynamically grow the histwin window, for longer tags (up
          to a maximum)
        - Bugfix: Always indicate the correct branch
        - Added a few try/catch statements and some error handling
0.9     - Error handling for Replaying (it may not work always)
        - Documentation
        - Use syntax highlighting
        - Tagging finally works
0.8     - code cleanup
        - make speed of the replay adjustable. Use g:undo_tree_speed to set
          time in milliseconds
0.7.2   - make sure, when switching to a different undo-branch, the undo-tree
          will be reloaded
        - check 'undolevel' settings  
0.7.1   - fixed a problem with mapping the keys which broke the Undo-Tree keys
          (I guess I don't fully understand, when to use s: and <sid>)
0.7     - created autoloadPlugin (patch by Charles Campbell) Thanks!
        - enabled GLVS (patch by Charles Campbell) Thanks!
        - cleaned up old comments
        - deleted :noautocmd which could cause trouble with other plugins
        - small changes in coding style (<sid> to s:, fun instead of fu)
        - made Plugin available as histwin.vba
        - Check for availability of :UB before defining it
          (could already by defined Blockquote.vim does for example)
0.6     - fix missing bufname() when creating the undo_tree window
        - make undo_tree window a little bit smaller
          (size is adjustable via g:undo_tree_wdth variable)
0.5     - add missing endif (which made version 0.4 unusuable)
0.4     - Allow diffing with selected branch
        - highlight current version
        - Fix annoying bug, that displays 
          --No lines in buffer--
0.3     - Use changenr() to determine undobranch
        - <C-L> updates view
        - allow switching to initial load state, before
          buffer was edited
==============================================================================
vim:tw=78:ts=8:ft=help:norl: