A Vim Plugin for indicating changes as colored bars using signs.
Switch branches/tags
Nothing to show
Pull request Compare This branch is 398 commits behind chrisbra:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
autoload
doc
plugin
.gitignore
Makefile
README
changes.vba

README

*ChangesPlugin.txt*  Print indication of changed lines for a buffer 

Author:  Christian Brabandt <cb@256bit.org>
Version: 0.12 Tue, 31 Jan 2012 22:07:31 +0100
Copyright: (c) 2010 by Christian Brabandt        *ChangesPlugin-copyright*
           The VIM LICENSE applies to ChangesPlugin.txt (see |copyright|)
           except use unicode instead of "Vim".  NO WARRANTY, EXPRESS OR
           IMPLIED.  USE AT-YOUR-OWN-RISK.

==============================================================================
1. Contents                                                   *ChangesPlugin*

  1.  Contents......................................: |ChangesPlugin|
  2.  Manual........................................: |ChangesPlugin-manual|
  3.  Configuration.................................: |ChangesPlugin-Config|
   3.1 Highlighting whole lines.....................: |ChangesPlugin-hlLine|
   3.2 Auto-refresh changes.........................: |ChangesPlugin-aucmd|
   3.3 Show the meaning of the indicator bars.......: |ChangesPlugin-bars|
   3.4 Specify different colors.....................: |ChangesPlugin-colors|
   3.5 Check against a file in a VCS................: |ChangesPlugin-VCS|
  4.  ChangesPlugin Feedback........................: |ChangesPlugin-Feedback|
  5.  ChangesPlugin History.........................: |ChangesPlugin-history|

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

                                                       *ChangesPlugin-manual*
2. Functionality

This plugin was written to help visualize which lines have been changes since
editing started for a file. The plugin was inspired by so called changed-bars,
available at other editors, such as Embarcadero C++ Builder (there it is
called Change Bars, see:
http://edn.embarcadero.com/article/33453#6PersonalDeveloperProductivity)
or Visual Studio where it is called indicator margin (see
http://blog.eveningcreek.com/?p=151).

ChangesPlugin.vim uses the |diff|-feature of vim and compares the actual
buffer with it's saved state. In order to highlight the indicator signs at the
first column, its using |signs|. For newly added lines, the first column will
be displayed with a leading '+' and highlighted using the DiffAdd highlighting
(see |hl-DiffAdd|), deleted lines will be indicated by a '-' with a
DiffDelete highlighting (see |hl-DiffDelete|) and modified lines will be
displayed using '*' and a DiffChange highlighting (see |hl-DiffChange|).

Note, that a '-' will be shown on the next line after the deleted lines. A
range of consecutive deleted lines will be displayed by only one '-'

This means, that in order to use this plugin you need a vim, that was built
with |+signs|-support and |+diff|-support and you also need an executable diff
command. If neither of these conditions are met, changePlugin.vim will issue a
warning and abort.

                                                         *:EC* *:EnableChanges*
By default the plugin is not enabled. To enable it enter >
    :EnableChanges
When you run this command, ChangesPlugin.vim diffs the current file agains
its saved file on disk and displays the changes in the first column.

If you like to display the Changes against a different file, simply supply its
filename as optional argument to that command, e.g. >
    :EnableChanges ~/project/foobar.c
would display the Signs as if your current file has been diffed against the
file ~/project/foobar.c

Alternatively, you can enter the shortcut >
     :EC
which basically calls :EnableChanges and supports the same arguments.

                                                        *:DC* *:DisableChanges*
If you want to disable the plugin, enter >
    :DisableChanges
or alternatively, you can enter the shortcut >
     :DC
and the Display of Changes will be disabled.

                                                     *:TCV* *:ToggleChangeView*
You can toggle, between turning on and off the indicator bars, using >
     :ToggleChangeView
or alternatively: >
     :TCV
to toggle the display of indicator bars.

                                                     *:CC* *:ChangesCpation*
You are probably wondering, what those strange looking signs mean. You can use
either >
    :CC
or >
    :ChangesCaptions
to let the Plugin display a small caption, so you know what each sign means
and how they are colored.

                                                 *:CL* *:ChangesLineOverview*
If you are editing a huge file with several hundreds of lines, it may be hard
to find the lines that have been changed. >
    :CL
or >
    :ChangesLineOverview        
provide an easy view to only see all modified lines. This will open the
|location-list| buffer where you can easily see the affected lines. Pushing
enter on any line, allows you to easily jump to that line in the buffer.

                                                 *:CD* *:ChangesDiffMode*
You might want to keep the diff-window open, so you can use it for modifying
your buffer using e.g. |:diffput| or |:diffget|
Therefore ChangesPlugin defines the two commands >
    :CD
and >
    :ChangesDiffMode
If you issue any of these commands, a vertical split buffer will open,
that contains the changes from either your VCS or from the unmodified buffer
as it is saved on disk. See |copy-diffs| for how to merge changes between
those two buffers.

==============================================================================
                                                        *ChangesPlugin-Config*
3. Configuring ChangesPlugin.vim

There are several different configuration options available.

                                                        *ChangesPlugin-hlLine*
3.1 Highlighte the whole line

By default, ChangesPlugin.vim will only indicate a change in the first column.
Setting g:changes_hl_lines to 1 will highlight the whole line. By default this
variable is unset (which is the same as setting it to 0).
If you'd like to have this, set this variable in your |.vimrc| >
    :let g:changes_hl_lines=1
<

                                                        *ChangesPlugin-aucmd*
3.2 Auto-refresh the changes

By default ChangesPlugin.vim will not automatically update the view. You can
however configure it to do so. This will use an |CursorHold| and |InsertLeave|
utocommand to update the indicator signs after |'updatetime'| seconds in
Normal mode when no key is pressed. To enable this feature, put this in your
|.vimrc| >
    let g:changes_autocmd=1

This autocommand checks, whether there have been changes to the file, or else
it won't update the view.

                                                        *ChangesPlugin-bars*
3.3 Show what the indicator signs mean.

By default, whenever you run |:EnableChanges|, changesVim will print a short
status message, what each sign means. If you don't want this, put this in your
|.vimrc| >
    :let g:changes_verbose=0
and achangesPlugin won't display this message again. You can always issue the
|CL| command to find out, what each sign means.
                                                        *ChangesPlugin-colors*

3.4 Specify different colors.

changesVim uses the highlighting used for |diff| mode to indicate the change
in a buffer. This is consistent, since when you're already used to |vimdiff|
you'll probably also know the highlighting. If for any reason you do not like
the colors, you have to define your own highlighting items.
If for example you want the DiffAdd highlighting to be displayed like White on
a Blue background, you can define it as follows in your |.vimrc| >

    :hi DiffAdd term=bold ctermbg=4 guibg=DarkBlue

In the same way, you can change DiffDelete for indicating deleted lines and
DiffChange for indicating modified lines. You can also specify your favorite
highlighting colors using your own build |colorscheme|.

                                                          *ChangesPlugin-VCS*
3.5 Check differences against a checked-in file from a VCS

Warning: This feature is rather experimental. So use it with care. 

You can configure ChangesPlugin to check the differrences of the current
buffer not only against the file stored on disk, but rather query a Version
Control System (VCS) for its latest version and indicate changes based on
this version. 

Currently, ChangesPlugin supports these VCS Systems:
    - git
    - cvs
    - bzr
    - svn
    - svk
    - hg

To enable this feature, you need to set the variable g:changes_vcs_check to
1. ChangesPlugin will then try to auto-detect, which of the above supported
VCS-Systems is in use. That means, if it can't detect neither of git, cvs,
svn, bzr or hg it will assume you are using svk. This may fail obviously, so
you can always force ChangesPlugin to use any of the above by setting the 
g:changes_vcs_system Variable.

To enable this feature, you need to set the g:changes_vcs_check variable to 1.
The following example enables this feature and ensures, EnablePlugin is using
git as VCS, so these lines have been entered in the |.vimrc| >
    :let g:changes_vcs_check=1
    :let g:changes_vcs_system='git'

Note, that depending on the VCS System you use, this might slow down
ChangesPlugin significantly. Especially CVS seems to be very slow.

Note also, that setting g:changes_vcs_system is setting a global variable (see
|g:-var|) and therefore would set the VCS for every buffer opened in vim (thus
you could use changesPlugin only with one single VCS). However, guessing the
VCS System should work fairely well and in case it doesn't, please report a
bug to the maintainer of the plugin. Setting g:changes_vcs_check will however
disable the check against the on-disk version of a buffer.

==============================================================================
4. ChangesPlugin Feedback                           *ChangesPlugin-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=3052

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

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

==============================================================================
5. ChangesPlugin History                                *ChangesPlugin-history*
    0.13: (unreleased):
                        BF: Plugin used :EnableDisplayChanges, but
                        documentation talked about EnableChanges
                        (same for DisableChanges)
                        BF: Don't load the autoload script when sourcing
                        the plugin (reported by Sergey Kholev, thanks!)
    0.12: Jan, 31, 2012:
                        NF: Fix issue #3 from github (check changes against
                            any file, suggested by Alessio Bolognino, Thanks!)
                        BF: Fix E117 error (patch by Mate Gabri, Thanks!)
                        BF: Check, that the current file is readable, before
                            diffing (patch by Mate Gabri, Thanks!)
                        BF: Sometimes, the previous Window is not accessible
                            anymore
                            (http://github.com/chrisbra/changesPlugin/issues/5
                            by Mate Gabri, Thanks!)
    0.11: May 04, 2010: BF: Document, that |InsertLeave| autocommand is used
                            as autocommand
                        BF: generate the help file with 'et' set, so that the
                            README at github looks prettier
                        BF: When staying in diff mode, don't reset 'fdm'
                            and apply syntax coloring to scratch buffer
                        BF: the check for the diff executable does not work
                            as expected (Reported by Sergey Khorev),
                            additionally outputting the Warnings did not work
                            in that case
    0.10: Apr 28, 2010: NF: Fixed Issue 1 from github
                            (http://github.com/chrisbra/changesPlugin/issues/1/find)
    0.9: Apr 24, 2010:  NF: You can now use different VCS Systems for each
                            buffer you are using.
                        NF: Stay in diff mode
                        BF: Fix the display of deleted signs
                        BF: Undefining old signs, so that changing
                            g:changes_hl_lines works
                        BF: Some more error handling.
                        NF: Show an overview for changed lines in location-list
                            (|:CL|)
                        NF: Show what each sign means using |:CC|
    0.8: Apr 22, 2010:  NF: Renamed the helpfile, to make it more obvious, 
                        that it refers to a plugin
                        NF: Outputting name of checked file, if checking
                            against VCS
                        BF: Don't check for empty files.
                        BF: Reworked the Message function
                        BF: Don't try to place signs, if there are no
                            differences
                            (unreleased, VCS successfully tested with
                             git, hg, svn, cvs, bzr)
    0.7: Apr 19, 2010:  NF: Check against a file in a VCS
                            (unreleased, first working version,
                            needs to be checked for each VCS)
    0.6: Apr 12, 2010:  BF: fixed a missing highlight for DiffText
    0.5: Apr 12, 2010:  BF: error when trying to access b:diffhl in the
                            scratch buffer. This should be fixed now (thanks
                            Jeet Sukumaran!)
                        BF: Use the correct highlighting groups (thanks Jeet
                            Sukumaran!)
    0.4: Apr 12, 2010:  NF: |ToggleChangesView|
                        NF: The autocommand checks, if the buffer has been
                            modified, since the last time.
                        BF: Do not mess with signs, that have not been placed
                            by ChangesPlugin.vim
                        BF: CleanUp was seriously messed up (sorry, I must
                            have been asleep, when writing that)
                        BF: Take care of 'foldcolumn' setting, which would be
                            overwritten by the signs-column
    0.3: Apr 11, 2010:  BF: redraw, so that the diff window will not be
                            displayed
                        NF: enabled GLVS (see |GLVS|)
    0.2: Apr 11, 2010:  Added Documentation
                        created an autoload version
    0.1: Apr 10, 2010:  First working version

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