190 lines
8.2 KiB
Plaintext
190 lines
8.2 KiB
Plaintext
*linediff.txt* Diff two blocks of text
|
|
|
|
==============================================================================
|
|
CONTENTS *linediff* *linediff-contents*
|
|
|
|
Installation...........................: |linediff-installation|
|
|
Usage..................................: |linediff-usage|
|
|
Commands...............................: |linediff-commands|
|
|
Settings...............................: |linediff-settings|
|
|
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.
|
|
Specifying ! discards unsaved changes made in the temporary
|
|
buffers.
|
|
|
|
==============================================================================
|
|
SETTINGS *linediff-settings*
|
|
|
|
*g:linediff_indent*
|
|
>
|
|
let g:linediff_indent = 1
|
|
<
|
|
|
|
Default value: 0
|
|
|
|
If this flag is set to 1, linediff will reindent the diffed sections in order
|
|
to minimize differences caused by formatting. This may change the buffers'
|
|
contents.
|
|
|
|
*g:linediff_buffer_type*
|
|
>
|
|
let g:linediff_buffer_type = 'scratch'
|
|
<
|
|
Default value: "tempfile"
|
|
|
|
This variable can have one of two values, "scratch" or "tempfile".
|
|
|
|
If it is set to "scratch", the created proxy buffer is not connected to any
|
|
file. The benefit is that the filename can then be set to be an informative
|
|
string instead of a weird temporary filename. The drawback is that you can't
|
|
run some external commands on this buffer, since there is no real backing
|
|
file.
|
|
|
|
If it is set to "tempfile" (the default), the proxy buffer is actually a
|
|
temporary file. The benefit is that you run external commands that expect an
|
|
actual file (like executing |:make|). The drawback is that the only way to
|
|
display information on the proxy is by hacking the statusline, which may cause
|
|
issues and can't work reliably on all statuslines.
|
|
|
|
*g:linediff_first_buffer_command*
|
|
*g:linediff_second_buffer_command*
|
|
>
|
|
let g:linediff_first_buffer_command = 'new'
|
|
let g:linediff_second_buffer_command = 'vertical new'
|
|
<
|
|
|
|
Default values: "tabnew" and "rightbelow vertical new", respectively.
|
|
|
|
These variables control what commands are used to open the two temporary
|
|
buffers. By default, the first one will open a blank new tab, and the second
|
|
one will split it vertically, from the right. This should ensure a pretty
|
|
sensible setup.
|
|
|
|
As an example, you can set them like so:
|
|
>
|
|
let g:linediff_first_buffer_command = 'leftabove new'
|
|
let g:linediff_second_buffer_command = 'rightbelow vertical new'
|
|
<
|
|
With this, the buffers will be positioned in a split above the current buffer,
|
|
the first one on the left, and the second one on the right.
|
|
|
|
You can control the positioning with judicious use of |:rightbelow| and
|
|
|:leftabove|. If you omit these commands, the view will simply follow your
|
|
default settings when opening new splits.
|
|
|
|
==============================================================================
|
|
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:
|