==============================================================================
CONTENTS                                      *linediff* *linediff-contents*

    Installation...........................: |linediff-installation|
    Usage..................................: |linediff-usage|
    Commands...............................: |linediff-commands|
    Internals..............................: |linediff-internals|
    Issues.................................: |linediff-issues|


==============================================================================
INSTALLATION                                           *linediff-installation*

There are several ways to install the plugin. The recommended one is by using
Tim Pope's pathogen (http://www.vim.org/scripts/script.php?script_id=2332). In
that case, you can clone the plugin's git repository like so:
>
    git clone git://github.com/AndrewRadev/linediff.vim.git ~/.vim/bundle/linediff
<
If your vim configuration is under git version control, you could also set up
the repository as a submodule, which would allow you to update more easily.
The command is (provided you're in ~/.vim):
>
    git submodule add git://github.com/AndrewRadev/linediff.vim.git bundle/linediff
<

Another way is to simply copy all the essential directories inside the ~.vim/
directory: plugin, autoload, doc.

==============================================================================
USAGE                                                         *linediff-usage*

The plugin provides a simple command, |:Linediff|, which is used to diff two
separate blocks of text.

A simple example:

    def one
      two
    end

    def two
      three
    end

If we mark the first three lines, starting from "def one", in visual mode, and
execute the |:Linediff| command, the signs "1-" will be placed at the start
and at the end of the visual mode's range. Doing the same thing on the bottom
half of the code, starting from "def two", will result in the signs "2-"
placed there. After that, a new tab will be opened with the two blocks of code
in vertical splits, diffed against each other.

The two buffers are temporary, but when any one of them is saved, its original
buffer is updated. Note that this doesn't save the original buffer, just
performs the change. Saving is something you should do later.

Executing the command |:LinediffReset| will delete the temporary buffers and
remove the signs.

Executing a new |:Linediff| will do the same as |:LinediffReset|, but will
also initiate a new diff process.

The statuslines of the two temporary buffers will be changed to contain:
    - The original buffer
    - The starting line of the selected segment
    - The ending line of the selected segment

If you're using a custom statusline and it contains "%f" (the current file's
name), that token will simply be substituted by the above data. Otherwise, the
entire statusline will be set to a custom one.

==============================================================================
COMMANDS                                                   *linediff-commands*

                                              *:Linediff*
:Linediff         The main interface of the plugin. Needs to be executed on a
                  range of lines, which will be marked with a sign. On the
                  selection of the second such range, the command will open a
                  tab with the two ranges in vertically split windows and
                  perform a diff on them. Saving one of the two buffers will
                  automatically update the original buffer the text was taken
                  from.

                  When executed for a third time, a new line diff is
                  initiated, and the current process is reset, much like the
                  effect of |LinediffReset| would be.


                                              *:LinediffReset*
:LinediffReset    Removes the signs denoting the diffed regions and deletes
                  the temporary buffers, used for the diff. The original
                  buffers are untouched by this, which means that any updates
                  to them, performed by the diff process will remain.

==============================================================================
INTERNALS                                                 *linediff-internals*

When a block of text is diffed with the plugin, a "Differ" object is
initialized with its relevant data. The differ contains information about the
buffer number, filetype, start and end lines of the text, and a few other
things. Almost all functions the plugin uses are scoped to this object in
order to keep the interface simple. They're located under
"autoload/linediff/differ.vim" and should be fairly understandable.

Functions that are general-purpose utilities are placed in
"autoload/linediff/util.vim".

The two differ objects that are required for the two diff buffers are linked
to each other out of necessity. If they originate from a single buffer,
updating one would move the lines of the other, so that one would have to be
updated as well. Apart from that, they have no interaction.

==============================================================================
ISSUES                                                       *linediff-issues*

You shouldn't linediff two pieces of text that overlap. Not that anything
horribly bad will happen, it just won't work as you'd hope to. I don't feel
like it's a very important use case, but if someone requests sensible
behaviour in that case, I should be able to get it working.

To report any issues or offer suggestions, use the bugtracker of the github
project at http://github.com/AndrewRadev/linediff.vim/issues

vim:tw=78:sw=4:ft=help:norl: