*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: