*spotdiff.txt*  A range and area selectable `:diffthis` to compare partially

Last Change: 2025/10/23
Version:     6.0
Author:      Rick Howe (Takumi Ohtani) <rdcxy754@ybb.ne.jp>
Copyright:   (c) 2014-2025 by Rick Howe
License:     MIT

INTRODUCTION                                            *spotdiff*

Vim provides a diff mode which is useful to see differences between windows.
However, it always shows the differences for entire line. And it can not
compare a sequence of words within a line, and sentences and paragraphs which
are separated into several lines.

To compare partially everywhere in any window, this plugin provides two groups
of commands, which are alternative to vim original `:diffthis`, `:diffoff`,
and `:diffupdate`. One is for which allows to select a range of lines in diff
mode. Another is for which allows to select the Visual, motion, and text
object area in non-diff normal mode. Both work independently in a tab page.

==============================================================================
Selecting a range of lines                              *spotdiff-range*

There are `:Diffthis`, `:Diffoff`, and `:Diffupdate` commands available.

You can use `:Diffthis` to specify a range of lines to be compared. And can
use `:Diffoff` to reset and `:Diffupdate` to update the differences.

Do not use vim original diff commands together with this plugin's ones. Try
`:Diffoff!` to reset all in a trouble.

If you have installed |diffchar.vim| plugin
(https://github.com/rickhowe/diffchar.vim), you can see the exact differences
and use their options and keymaps.

Commands ~

:[range]Diffthis
    Select a range of lines with [range] (default: current line) and make the
    current window diff mode. The selected lines are highlighted in
    |hl-CursorColumn|. Shortly after the two separate windows become diff
    mode, `:Diffthis` shows the differences for selected lines in each window.
    It is also possible to select two ranges of lines in the same window. In
    that case, `:Diffthis` opens a temporary new window at above or below (or
    left or right if "vertical" is included in the 'diffopt' option) of the
    current one, copies selected lines to it, and shows the difference with
    source window.

:Diffoff[!]
    Clear the selected range of lines and reset diff mode for the current
    window. If `!` flag is specified, clear and reset for all windows in the
    current tab page. The temporary window created by `:Diffthis` will be
    closed.

:Diffupdate
    Update the differences for the selected range of lines in the current tab
    page.

==============================================================================
Selecting the Visual, motion, and text object area      *spotdiff-area*

There are `:VDiffthis`, `:VDiffoff`, and `:VDiffupdate` commands available.

You can use `:VDiffthis` to specify the Visual area to be compared. And can
use `:VDiffoff` to reset and `:VDiffupdate` to update the differences. Note
that those commands work in non-diff normal mode.

While showing the exact differences, when the cursor is moved on a difference
unit, you can see its corresponding unit highlighted in |hl-Cursor|, according
to the |g:DiffPairVisible| option.

You can use `]b` or `]e` to jump cursor to start or end position of the next
difference unit, and `[b` or `[e` to the start or end position of the previous
unit.

This plugin provides the corresponding mappings to those commands, such as
<Plug>(VDiffthis) and <Plug>(VDiffoff). As a default, <Leader>t and <Leader>o
keys are mapped to them and, for example, "v$<Leader>t" selects the text from
the current cursor position to the end of line and "3vis<Leader>t" selects the
next 3 sentences as the Visual area. And "<Leader>o" clears the selected area.

In addition to selecting the Visual area, you can use <Leader>t as a custom
operator followed by a motion or a text object command, which will set those
selected area as the Visual one and then call `:VDiffthis`. For example,
"<Leader>t$" and "<Leader>t3is" work same as above examples.

Commands ~

:[range]VDiffthis[!]
    Select the characterwise, linewise, or blockwise Visual area most recently
    used in the current window. If [range] (default: current line) is not
    specified as "'<,'>" and different from the last Visual area, those
    specified lines are selected as linewise area instead. The selected area
    is highlighted in |hl-DiffChange| with "italic", and then will be compared
    as a single combined line. Shortly after the two area are selected,
    `:VDiffthis` compares them based on the |g:DiffUnit| option and "icase",
    "iwhite", "iwhiteall" and "iwhiteeol" flags in the 'diffopt' option. In
    addition, when "indent-heuristic" is specified, positioning of the
    added/deleted diff units is adjusted to make them easier to read. Then
    their differences are shown using the |g:DiffColors| option. It is also
    possible to select two area in the same window. If `!` flag is specified,
    each line is separately compared, which would be useful particular for
    columns in a table on blockwise area. Redundant lines in the line-by-line
    comparison are shown with "strikethrough".

:VDiffoff[!]
    Clear the selected area in the current window and reset the differences.
    When there are two area selected in the same window, both area will be
    cleared. But either one is cleared if the current cursor is located within
    it. If `!` flag is specified, clear and reset all area in the current tab
    page.

:VDiffupdate
    Compare the selected area again and show their differences in the current
    tab page, when you make changes to the selected area or you want to change
    the |g:DiffUnit| or |g:DiffColors| option or some flags in the 'diffopt'
    option.

Options ~

* These options are same as those used in the |diffchar.vim| plugin.

|g:DiffUnit|, |t:DiffUnit|
    A type of diff unit
    'Char'    : any single character
    'Word1'   : \w\+ word and any \W single character (default)
    'Word2'   : non-space and space words
    'Word3'   : \< or \> character class boundaries (set by 'iskeyword' option)
    'word'    : see `word`
    'WORD'    : see `WORD`
    '[{del}]' : one or more diff unit delimiters (e.g. "[,:\t<>]")
    '/{pat}/' : a pattern to split into diff units (e.g. '/.\{4}\zs/')

|g:DiffColors|, |t:DiffColors|
    Matching colors for changed units (|hl-DiffAdd| for added units)
    0       : |hl-DiffText| (default)
    1       : |hl-DiffText| + a few (3, 4, ...) highlight groups
    2       : |hl-DiffText| + several (7, 8, ...) highlight groups
    3       : |hl-DiffText| + many (11, 12, ...) highlight groups
    100     : all available highlight groups in random order
    [{hlg}] : a list of your favorite highlight groups

|g:DiffPairVisible|, |t:DiffPairVisible|
    Visibility of corresponding diff units
    0 : disable
    1 : highlight with |hl-Cursor| (default)

Keymaps ~

* These keymaps are same as those used in the |diffchar.vim| plugin.

<Plug>JumpDiffCharPrevStart (default: `[b`)
    Jump cursor to the start position of the previous difference unit

<Plug>JumpDiffCharNextStart (default: `]b`)
    Jump cursor to the start position of the next difference unit

<Plug>JumpDiffCharPrevEnd (default: `[e`)
    Jump cursor to the end position of the previous difference unit

<Plug>JumpDiffCharNextEnd (default: `]e`)
    Jump cursor to the end position of the next difference unit

* These keymaps are used only in this plugin.

<Plug>(VDiffthis) (default: `<Leader>t`)
    Call `:VDiffthis` for the visually selected area
    Set the selected motion and text object area as the Visual one and then
        call `:VDiffthis`

<Plug>(VDiffthis!) (default: `<Leader>T`)
    Call `:VDiffthis!` for the visually selected area
    Set the selected motion and text object area as the Visual one and then
        call `:VDiffthis!`

<Plug>(VDiffoff) (default: `<Leader>o`)
    Call `:VDiffoff` in the current window

<Plug>(VDiffoff!) (default: `<Leader>O`)
    Call `:VDiffoff!` in the current tab page

<Plug>(VDiffupdate) (default: `<Leader>u`)
    Call `:VDiffupdate` in the current tab page

==============================================================================
CHANGE HISTORY                                          *spotdiff-history*

6.0
* Updated to support vim 9.0 and nvim 0.7.0 or later with major internal
  changes.
* Fixed some defects including E957 and E734 errors on nvim 0.10.0 or later.

5.2
* Implemented to update the differences shortly after the text is changed.

5.1
* Added to open a temporary new window at left or right in |:Diffthis| command
  if "vertical" is included in the 'diffopt' option.

5.0
* Changed to support vim 8.2 and nvim 0.4.4 or later.
* Added some minor changes such as an error check in `:Diffthis` command.

4.5
* Implemented to redefine visual area highlight groups whenever the color
  scheme is loaded.
* Updated |g:DiffUnit| and |g:DiffColors| options to reflect those updated in
  the |diffchar.vim| 9.1.
  - Added vim original 'word' and 'WORD' units, one or more unit delimiters,
    and a custom pattern to split into diff units in |g:DiffUnit| option.
  - Changed the category of |g:DiffColors| option as a few, several, and many
    numbers of matching colors, depending on the loaded color scheme.
  - Added a list of your favorite highlight groups in |g:DiffColors| option.

4.4
* Enhanced to make diff units easier to read when "indent-heuristic" is
  specified in the 'diffopt' option.
* Fixed some defects.

4.3
* Updated to check a new WinClosed event (patch-8.2.3591) to appropriately
  clear the selected range or area and reset its differences when a window is
  closed.

4.2
* Changed `:VDiffoff` command to check the current cursor position and find
  which of two selected area is to be cleared in the same window.

4.1
* Added the keymaps which correspond to the `:VDiffthis`, `:VDiffoff`, and
  `:VDiffupdate` commands.
* Added a custom operator which can select the motion and text object area by
  using the 'operatorfunc' option.
* Added [range] to `:VDiffoff` to clear either one of selected area in the
  same window.
* Added the diffchar's |g:DiffPairVisible| option which highlights a
  corresponding diff unit.
* Added the diffchar's keymaps which jump cursor to the start/end position of
  the next/previous diff unit.

4.0
* Added `:VDiffthis`, `:VDiffoff`, and `:VDiffupdate` commands to select the
  Visual area to be compared as a single combined line or multiple separate
  lines.
* Removed to use Conceal and Sign features in `:Diffthis` command.

3.2
* Changed to use |hl-CursorLine|, instead of underline and '-' in the fold
  column, to indicate the selected lines.

3.1
* Set a plugin specific expression to 'diffexpr' option while spot diff'ed to
  disable a new internal diff (patch-8.1.360).

3.0
* Disable a new internal diff in 'diffopt' option (patch-8.1.360) to prevent
  unselected lines to be incorrectly diff'ed. And make this plugin work well
  even if an external diff command is not available.
* Open a temporary window, when `:Diffthis` is used twice in a single window,
  highly enough to display all selected lines. And close it when `:Diffoff` is
  used not only in it but also in the original window.
* Support new iwhiteall and iwhiteeol of 'diffopt' option.
* Removed a support for vim version 7.x.

2.2
* Added `:Diffupdate` command.

2.1
* The selected lines are all underlined using sign feature, in addition to a
  '-' in the fold column, to make them more visible.
* Fixed some defects.

2.0
* `:Diffthis` indicates the selected lines with a '-' in the fold column.
* `:Diffthis` always highlighted other lines than selected with |hl-Conceal|,
  but `!` is required as optionally.

1.1
* `:Diffthis` highlights other lines than selected with |hl-Conceal|, instead
  of showing selected lines with sign feature.
* `:Diffthis` and `:Diffoff` try to repair any diff mode mismatch, instead of
  stopping with error messages.
* The 'diffopt' foldcolumn:{n} option was ignored, but follows it as vim does.
* A temporary new window, which opens when `:Diffthis` is used twice in a
  single window, was sometimes too large, but shows as few as those lines.

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