sponsor Vim development Vim logo Vim Book Ad

ShowTrailingWhitespace : Detect unwanted whitespace at the end of lines.

 script karma  Rating 45/14, Downloaded by 518    Comments, bugs, improvements  Vim wiki

created by
Ingo Karkat
 
script type
utility
 
description
DESCRIPTION
This plugin highlights whitespace at the end of each line (except when typing
at the end of a line). It uses the matchadd()-function, therefore doesn't
interfere with syntax highlighting and leaves the :match command for other
uses.
Highlighting can be switched on/off globally and for individual buffers. The
plugin comes with exceptions for certain filetypes, where certain lines can /
must include trailing whitespace; additional patterns can be configured.

SEE ALSO
Many plugins also come with a command to strip off the trailing whitespace;
this plugin separates this into the companion DeleteTrailingWhitespace.vim
plugin (vimscript #3967), which can even remove the trailing whitespace
automatically on each write.

To quickly locate the occurrences of trailing whitespace, you can use the
companion JumpToTrailingWhitespace.vim plugin (vimscript #3968).

RELATED WORKS
There are already a number of plugins for this purpose, most based on this
VimTip:
    http://vim.wikia.com/wiki/Highlight_unwanted_spaces
However, most of them use the older :match command and are not as flexible.
- smartmatcheol.vim (vimscript #2635) highlights based on file extension or
  name.
- trailing-whitespace (vimscript #3201) uses :match.
- bad-whitespace (vimscript #3735) uses :match, allows on/off/toggling via
  commands.
- Trailer Trash (vimscript #3938) uses :match.
- DynamicSigns (vimscript #3965) can show whitespace errors (also mixed
  indent) in the sign column.

USAGE
By default, trailing whitespace is highlighted in all Vim buffers. Some users
may want to selectively enable / disable this for certain filetypes, or files
in a particular directory hierarchy, or toggle this on demand. Since it's
difficult to accommodate all these demands with short and easy mappings and
commands, this plugin does not define any of them, and leaves it to you to
tailor the plugin to your needs. See ShowTrailingWhitespace-configuration
below.
 
install details
INSTALLATION
This script is packaged as a vimball. If you have the "gunzip" decompressor
in your PATH, simply edit the *.vmb.gz package in Vim; otherwise, decompress
the archive first, e.g. using WinZip. Inside Vim, install by sourcing the
vimball or via the :UseVimball command.
    vim ShowTrailingWhitespace*.vmb.gz
    :so %
To uninstall, use the :RmVimball command.

DEPENDENCIES
- Requires Vim 7.1 with "matchadd()", or Vim 7.2 or higher.

CONFIGURATION
For a permanent configuration, put the following commands into your vimrc:

To change the highlighting colors:
    highlight ShowTrailingWhitespace ctermbg=Red guibg=Red

By default, highlighting is enabled for all buffers, and you can (selectively)
disable it. To work from the opposite premise, launch Vim with highlighting
disabled:
    let g:ShowTrailingWhitespace = 0

In addition to toggling the highlighting on/off via
g:ShowTrailingWhitespace, the decision can also be influenced by buffer
settings or the environment. By default, buffers that are not persisted to
disk (unless they are scratch buffers) or not modifiable (like user interface
windows from various plugins) are skipped. You can disable this filtering:
    let g:ShowTrailingWhitespace_FilterFunc = ''
or install your own custom filter function instead:
    let g:ShowTrailingWhitespace_FilterFunc = function('MyFunc')

Highlighting can be enabled / disabled globally and for individual buffers.
Analog to the :set and :setlocal commands, you can define the following
commands:
    command! -bar ShowTrailingWhitespaceOn          call ShowTrailingWhitespace#Set(1,1)
    command! -bar ShowTrailingWhitespaceOff         call ShowTrailingWhitespace#Set(0,1)
    command! -bar ShowTrailingWhitespaceBufferOn    call ShowTrailingWhitespace#Set(1,0)
    command! -bar ShowTrailingWhitespaceBufferOff   call ShowTrailingWhitespace#Set(0,0)
To set the local highlighting back to its global value (like :set {option}<
does), the following command can be defined:
    command! -bar ShowTrailingWhitespaceBufferClear call ShowTrailingWhitespace#Reset()

You can also define a quick mapping to toggle the highlighting (here, locally;
for global toggling use ShowTrailingWhitespace#Toggle(1):
    nnoremap <silent> <Leader>t$ :<C-u>call ShowTrailingWhitespace#Toggle(0)<Bar>echo (ShowTrailingWhitespace#IsSet() ? 'Show trailing whitespace' : 'Not showing trailing whitespace')<CR>

For some filetypes, in certain places, trailing whitespace is part of the
syntax or even mandatory. If you don't want to be bothered by these showing up
as false positives, you can augment the regular expression so that these
places do not match. The ShowTrailingWhitespace#SetLocalExtraPattern()
function takes a regular expression that is prepended to the pattern for the
trailing whitespace. For a certain filetype, this is best set in a file
    ftplugin/{filetype}_ShowTrailingWhitespace.vim

INTEGRATION
The ShowTrailingWhitespace#IsSet() function can be used to query the on/off
status for the current buffer, e.g. for use in the statusline.

To obtain the pattern for matching trailing whitespace, including any
ShowTrailingWhitespace-exceptions, you can use the function
ShowTrailingWhitespace#Pattern(0).
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
ShowTrailingWhitespace-1.01.vmb.gz 1.01 2013-12-14 7.0 Ingo Karkat - Minor: Also exclude quickfix and help buffers from detection.
- Add whitespace exception for the "dosbatch" filetype.
ShowTrailingWhitespace.vba.gz 1.00 2012-03-16 7.0 Ingo Karkat Initial upload
ip used for rating: 54.83.230.41

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
SourceForge.net Logo