#Vim Better Whitespace Plugin
This plugin causes all trailing whitespace characters (see Supported Whitespace Characters below) to be
highlighted. Whitespace for the current line will not be highlighted
while in insert mode. It is possible to disable current line highlighting while in other
modes as well (see options below). A helper function
:StripWhitespace is also provided
to make whitespace cleaning painless.
##Installation There are a few ways you can go about installing this plugin:
- If you have Vundle you can simply add:
.vimrcfile then run:
- If you are using Pathogen, you can just run the following command:
git clone git://github.com/ntpeters/vim-better-whitespace.git ~/.vim/bundle/vim-better-whitespace
- While this plugin can also be installed by copying its contents into your
~/.vim/directory, I would highly recommend using one of the above methods as they make managing your Vim plugins painless.
##Usage Whitespace highlighting is enabled by default, with a highlight color of red.
To set a custom highlight color, just call:
highlight ExtraWhitespace ctermbg=<desired_color>
To toggle whitespace highlighting on/off, call:
To disable highlighting for the current line in normal mode call:
hardwill maintain whitespace highlighting as it is, but may cause a slow down in Vim since it uses the CursorMoved event to detect and exclude the current line.
softwill use syntax based highlighting, so there shouldn't be a performance hit like with the
hardoption. The drawback is that this highlighting will have a lower priority and may be overwritten by higher priority highlighting.
To re-enable highlighting for the current line in normal mode:
To clean extra whitespace, call:
By default this operates on the entire file. To restrict the portion of the file that it cleans, either give it a range or select a group of lines in visual mode and then execute it.
To enable/disable stripping of extra whitespace on file save, call:
This will strip all trailing whitespace everytime you save the file for all file types.
If you want this behaviour by default for all filetypes, add the following to your
autocmd BufEnter * EnableStripWhitespaceOnSave
For exceptions of all see
If you would prefer to only strip whitespace for certain filetypes, add the following to your
autocmd FileType <desired_filetypes> autocmd BufEnter <buffer> EnableStripWhitespaceOnSave
<desired_filetypes>is a comma separated list of the file types you want to be stripped of whitespace on file save ( ie.
<buffer>is a keyword here denoting operation on the current buffer and should stay just as it appears in the line above.
To disable this plugin for specific file types, add the following to your
let g:better_whitespace_filetypes_blacklist=['<filetype1>', '<filetype2>', '<etc>']
This replaces the filetypes from the default list of blacklisted filetypes. The default types that are blacklisted are:
['diff', 'gitcommit', 'unite', 'qf', 'help', 'markdown']
If you do not want any of these filetypes unignored, simply include them in the blacklist:
let g:better_whitespace_filetypes_blacklist=['<filetype1>', '<filetype2>', '<etc>', 'diff', 'gitcommit', 'unite', 'qf', 'help']
To enable verbose output for each command, set verbosity in your
##Supported Whitespace Characters
Due to the fact that the built-in whitespace character class for patterns (
only matches against tabs and spaces, this plugin defines its own list of
horizontal whitepsace characters to match for both highlighting and stripping.
This is list should match against all ASCII and Unicode horizontal whitespace characters:
U+0009 TAB U+0020 SPACE U+00A0 NO-BREAK SPACE U+1680 OGHAM SPACE MARK U+180E MONGOLIAN VOWEL SEPARATOR U+2000 EN QUAD U+2001 EM QUAD U+2002 EN SPACE U+2003 EM SPACE U+2004 THREE-PER-EM SPACE U+2005 FOUR-PER-EM SPACE U+2006 SIX-PER-EM SPACE U+2007 FIGURE SPACE U+2008 PUNCTUATION SPACE U+2009 THIN SPACE U+200A HAIR SPACE U+200B ZERO WIDTH SPACE U+202F NARROW NO-BREAK SPACE U+205F MEDIUM MATHEMATICAL SPACE U+3000 IDEOGRAPHIC SPACE U+FEFF ZERO WIDTH NO-BREAK SPACE
A file is provided with samples of each of these characters to check the plugin working with them: whitespace_examples.txt
If you encounter any additional whitespace characters I have missed here, please submit a pull request.
##Screenshots Here are a couple more screenshots of the plugin at work.
##Frequently Asked Questions Hopefully some of the most common questions will be answered here. If you still have a question that I have failed to address, please open an issue and ask it!
Q: Why is trailing whitespace such a big deal?
A: In most cases it is not a syntactical issue, but rather is a common annoyance among programmers.
Q: Why not just use
A: I tried using
listchars to show trail characters with
SpecialKey highlighting applied.
Using this method the characters would still show on the current line for me even when the
SpecialKey foreground highlight matched the
CursorLine background highlight.
Q: Okay, so
listchars doesn't do exactly what you want, why not just use a
match in your
A: I am using
match in this plugin, but I've also added a way to exclude the current line in
insert mode and/or normal mode.
Q: If you just want to exclude the current line, why not just use syntax-based highlight rather
A: Syntax-based highlighting is an option in this plugin. It is used to omit the current line when
CurrentLineWhitespaceOff soft. The only issue with this method is that
takes higher priorty than syntax highlighting. For example, when using a plugin such as
Indent Guides, syntax-based highlighting of
extra whitespace will not highlight additional white space on emtpy lines.
Q: I already have my own method of removing white space, why is the method used in this plugin better?
A: It may not be, depending on the method you are using. The method used in this plugin strips extra white space and then restores the cursor position and last search history.
Q: Most of this is pretty easy to just add to users'
vimrc files. Why make it a plugin?
A: It is true that a large part of this is fairly simple to make a part of an individuals
configuration in their
vimrc. I wanted to provide something that is easy to setup and use
for both those new to Vim and others who don't want to mess around setting up this
functionality in their
Q: Can you add indentation highlighting for spaces/tabs? Can you add highlighting for other types of white space?
A: No, and no. Sorry, but both are outside the scope of this plugin. The purpose of this plugin is to provide a better experience for showing and dealing with extra white space. There is already an amazing plugin for showing indentation in Vim called Indent Guides. For other types of white space highlighting, listchars should be sufficient.
Q: I have a better way to do something in this plugin. OR You're doing something stupid/wrong/bad.
A: If you know of a better way to do something I am attempting in this plugin, or if I am doing something improperly/not reccomended then let me know! Please either open an issue informing me or make the changes yourself and open a pull request. If I am doing something that is bad or can be improved, I more than willing to hear about it!
##Promotion If you like this plugin, please star it on Github and vote it up at Vim.org!
Repository exists at: http://github.com/ntpeters/vim-better-whitespace
Plugin also hosted at: http://www.vim.org/scripts/script.php?script_id=4859
##Credits Originally inspired by: https://github.com/bronson/vim-trailing-whitespace