diff options
Diffstat (limited to 'doc/linediff.txt')
-rw-r--r-- | doc/linediff.txt | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/doc/linediff.txt b/doc/linediff.txt new file mode 100644 index 0000000..e6e21ed --- /dev/null +++ b/doc/linediff.txt @@ -0,0 +1,124 @@ +============================================================================== +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: |