{"id":13485296,"url":"https://github.com/ntpeters/vim-better-whitespace","last_synced_at":"2026-03-16T14:05:30.687Z","repository":{"id":13958263,"uuid":"16658541","full_name":"ntpeters/vim-better-whitespace","owner":"ntpeters","description":"Better whitespace highlighting for Vim","archived":false,"fork":false,"pushed_at":"2024-06-12T20:38:15.000Z","size":119,"stargazers_count":1368,"open_issues_count":19,"forks_count":82,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-10-30T19:42:58.146Z","etag":null,"topics":["trailing-spaces","trailing-whitespaces","vim","whitespace"],"latest_commit_sha":null,"homepage":null,"language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ntpeters.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-02-09T02:55:47.000Z","updated_at":"2024-10-26T22:09:23.000Z","dependencies_parsed_at":"2024-01-13T21:52:58.874Z","dependency_job_id":null,"html_url":"https://github.com/ntpeters/vim-better-whitespace","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntpeters%2Fvim-better-whitespace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntpeters%2Fvim-better-whitespace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntpeters%2Fvim-better-whitespace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntpeters%2Fvim-better-whitespace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ntpeters","download_url":"https://codeload.github.com/ntpeters/vim-better-whitespace/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245892510,"owners_count":20689509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["trailing-spaces","trailing-whitespaces","vim","whitespace"],"created_at":"2024-07-31T17:01:54.418Z","updated_at":"2025-12-17T11:23:43.705Z","avatar_url":"https://github.com/ntpeters.png","language":"Vim Script","funding_links":[],"categories":["Vim Script","Vim"],"sub_categories":["Chess :chess_pawn:"],"readme":"# Vim Better Whitespace Plugin\n\nThis plugin causes all trailing whitespace characters (see [Supported Whitespace\nCharacters](#supported-whitespace-characters) below) to be highlighted. Whitespace for the current line will\nnot be highlighted while in insert mode. It is possible to disable current line highlighting while in other\nmodes as well (see options below). A helper function `:StripWhitespace` is also provided to make whitespace\ncleaning painless.\n\nHere is a screenshot of this plugin at work:\n![Example Screenshot](http://i.imgur.com/St7yHth.png)\n\n## Installation\nThere are a few ways you can go about installing this plugin:\n\n1.  If you have [Vundle](https://github.com/gmarik/Vundle.vim) you can simply add:\n    ```vim\n    Plugin 'ntpeters/vim-better-whitespace'\n    ```\n    to your `.vimrc` file then run:\n    ```vim\n    :PluginInstall\n    ```\n2.  If you are using [Pathogen](https://github.com/tpope/vim-pathogen), you can just run the following command:\n    ```\n    git clone git://github.com/ntpeters/vim-better-whitespace.git ~/.vim/bundle/vim-better-whitespace\n    ```\n3.  While this plugin can also be installed by copying its contents into your `~/.vim/` directory, I would\n    highly recommend using one of the above methods as they make managing your Vim plugins painless.\n\n## Usage\nWhitespace highlighting is enabled by default, with a highlight color of red.\n\n*  To set a custom highlight color, just call:\n    ```vim\n    highlight ExtraWhitespace ctermbg=\u003cdesired_color\u003e\n    ```\n   or\n\n    ```vim\n    let g:better_whitespace_ctermcolor='\u003cdesired_color\u003e'\n    ```\n   Similarly, to set gui color:\n\n    ```vim\n    let g:better_whitespace_guicolor='\u003cdesired_color\u003e'\n    ```\n\n*  To enable highlighting and stripping whitespace on save by default, use respectively\n    ```vim\n    let g:better_whitespace_enabled=1\n    let g:strip_whitespace_on_save=1\n    ```\n    Set them to 0 to disable this default behaviour. See below for the blacklist of file types\n    and per-buffer settings.\n\n*  To enable/disable/toggle whitespace highlighting in a buffer, call one of:\n    ```vim\n    :EnableWhitespace\n    :DisableWhitespace\n    :ToggleWhitespace\n    ```\n\n*  The highlighting for the current line in normal mode can be disabled in two ways:\n    *  ```vim\n       let g:current_line_whitespace_disabled_hard=1\n       ```\n        This will maintain whitespace highlighting as it is, but may cause a\n        slow down in Vim since it uses the CursorMoved event to detect and\n        exclude the current line.\n\n    *  ```vim\n       let g:current_line_whitespace_disabled_soft=1\n       ```\n       This will use syntax based highlighting, so there shouldn't be a\n       performance hit like with the `hard` option.  The drawback is that this\n       highlighting will have a lower priority and may be overwritten by higher\n       priority highlighting.\n\n*  To clean extra whitespace, call:\n    ```vim\n    :StripWhitespace\n    ```\n    By default this operates on the entire file. To restrict the portion of\n    the file that it cleans, either give it a range or select a group of lines\n    in visual mode and then execute it.\n\n    *  There is an operator (defaulting to `\u003cleader\u003es`) to clean whitespace.\n        For example, in normal mode, `\u003cleader\u003esip` will remove trailing whitespace from the\n        current paragraph.\n\n        You can change the operator it, for example to set it to _s, using:\n        ```vim\n        let g:better_whitespace_operator='_s'\n        ```\n        Now `\u003cnumber\u003e_s\u003cspace\u003e` strips whitespace on \\\u003cnumber\\\u003e lines, and `_s\u003cmotion\u003e` on the\n        lines affected by the motion given. Set to the empty string to deactivate the operator.\n\n        Note: This operator will not be mapped if an existing, user-defined\n        mapping is detected for the provided operator value.\n\n*  To enable/disable stripping of extra whitespace on file save for a buffer, call one of:\n    ```vim\n    :EnableStripWhitespaceOnSave\n    :DisableStripWhitespaceOnSave\n    :ToggleStripWhitespaceOnSave\n    ```\n    This will strip all trailing whitespace everytime you save the file for all file types.\n\n    *  If you want this behaviour by default for all filetypes, add the following to your `~/.vimrc`:\n\n        ```vim\n        let g:strip_whitespace_on_save = 1\n        ```\n\n        For exceptions of all see ```g:better_whitespace_filetypes_blacklist```.\n\n    *  If you would prefer to only strip whitespace for certain filetypes, add\n        the following to your `~/.vimrc`:\n\n        ```vim\n        autocmd FileType \u003cdesired_filetypes\u003e EnableStripWhitespaceOnSave\n        ```\n\n        where `\u003cdesired_filetypes\u003e` is a comma separated list of the file types you want\n        to be stripped of whitespace on file save ( ie. `javascript,c,cpp,java,html,ruby` )\n\n    *  If you want to disable automatically stripping whitespace for large files, you can specify\n       a maximum number of lines (e.g. 1000) by adding the following to your `~/.vimrc`:\n\n       ```vim\n       let g:strip_max_file_size = 1000\n       ```\n\n       This overrides `let g:strip_whitespace_on_save` but not `:EnableStripWhitespaceOnSave`.\n       Set to `0` to deactivate.\n\n    *  By default, you will be asked for confirmation before whitespace is\n       stripped when you save the file. This can be disabled by adding the\n       following to your `~/.vimrc`:\n       ```\n       let g:strip_whitespace_confirm=0\n       ```\n\n    *  By default, all the lines in the file will have their trailing whitespace stripped\n       when you save the file. This can be changed to only the modified lines, by adding\n       the following to your `~/.vimrc`:\n       ```\n       let g:strip_only_modified_lines=1\n       ```\n\n    *  You can override the binary used to check which lines have been modified in the file.\n       For example to force a 'diff' installed in a different prefix and ignoring the changes\n       due to tab expansions, you can set the following:\n       ```\n       let g:diff_binary='/usr/local/bin/diff -E'\n       ```\n\n*  To disable the highlighting for specific file types, add the following to your `~/.vimrc`:\n    ```vim\n    let g:better_whitespace_filetypes_blacklist=['\u003cfiletype1\u003e', '\u003cfiletype2\u003e', '\u003cetc\u003e']\n    ```\n    This replaces the filetypes from the default list of blacklisted filetypes. The\n    default types that are blacklisted are:\n    ```vim\n    ['diff', 'git', 'gitcommit', 'unite', 'qf', 'help', 'markdown', 'fugitive']\n    ```\n    If you prefer to also keep these default filetypes ignored, simply include them in the\n    blacklist:\n    ```vim\n    let g:better_whitespace_filetypes_blacklist=['\u003cfiletype1\u003e', '\u003cfiletype2\u003e', '\u003cetc\u003e',\n                                            'diff', 'git', 'gitcommit', 'unite', 'qf', 'help', 'markdown', 'fugitive']\n    ```\n\n    This blacklist can be overriden on a per-buffer basis using the buffer toggle enable and\n    disable commands presented above. For example:\n    ```vim\n    \" highlight whitespace in markdown files, though stripping remains disabled by the blacklist\n    :autocmd FileType markdown EnableWhitespace\n    \" Do not modify kernel files, even though their type is not blacklisted and highlighting is enabled\n    :autocmd BufRead /usr/src/linux* DisableStripWhitespaceOnSave\n    ```\n\n*  To strip white lines at the end of the file when stripping whitespace, set this option in your `.vimrc`:\n    ```vim\n    let g:strip_whitelines_at_eof=1\n    ```\n\n*  To highlight space characters that appear before or in-between tabs, add the following to your `.vimrc`:\n    ```vim\n    let g:show_spaces_that_precede_tabs=1\n    ```\n    Such spaces can **not** be automatically removed by this plugin, though you can try\n    [`=` to fix indentation](http://vimdoc.sourceforge.net/htmldoc/change.html#=).\n    You can still navigate to the highlighted spaces with Next/PrevTrailingWhitespace (see below), and fix\n    them manually.\n\n*  To ignore lines that contain only whitespace, set the following in your `.vimrc`:\n    ```vim\n    let g:better_whitespace_skip_empty_lines=1\n    ```\n\n*  To navigate to the previous or next trailing whitespace, you can use commands that you\n    can map thusly in your `.vimrc`:\n    ```vim\n    nnoremap ]w :NextTrailingWhitespace\u003cCR\u003e\n    nnoremap [w :PrevTrailingWhitespace\u003cCR\u003e\n    ```\n    Note: those command take an optional range as argument, so you can for example select some\n    text in visual mode and search only inside it:\n    ```vim\n    :'\u003c,'\u003eNextTrailingWhitespace\n    ```\n\n*  To enable verbose output for each command, set verbosity in your `.vimrc`:\n    ```vim\n    let g:better_whitespace_verbosity=1\n    ```\n\n## Supported Whitespace Characters\nDue to the fact that the built-in whitespace character class for patterns (`\\s`)\nonly matches against tabs and spaces, this plugin defines its own list of\nhorizontal whitespace characters to match for both highlighting and stripping.\n\nThis is list should match against all ASCII and Unicode horizontal whitespace\ncharacters:\n```\n    U+0009   TAB\n    U+0020   SPACE\n    U+00A0   NO-BREAK SPACE\n    U+1680   OGHAM SPACE MARK\n    U+180E   MONGOLIAN VOWEL SEPARATOR\n    U+2000   EN QUAD\n    U+2001   EM QUAD\n    U+2002   EN SPACE\n    U+2003   EM SPACE\n    U+2004   THREE-PER-EM SPACE\n    U+2005   FOUR-PER-EM SPACE\n    U+2006   SIX-PER-EM SPACE\n    U+2007   FIGURE SPACE\n    U+2008   PUNCTUATION SPACE\n    U+2009   THIN SPACE\n    U+200A   HAIR SPACE\n    U+200B   ZERO WIDTH SPACE\n    U+202F   NARROW NO-BREAK SPACE\n    U+205F   MEDIUM MATHEMATICAL SPACE\n    U+3000   IDEOGRAPHIC SPACE\n    U+FEFF   ZERO WIDTH NO-BREAK SPACE\n```\n\nA file is provided with samples of each of these characters to check the plugin\nworking with them: whitespace_examples.txt\n\nIf you encounter any additional whitespace characters I have missed here,\nplease submit a pull request.\n\n## Screenshots\nHere are a couple more screenshots of the plugin at work.\n\nThis screenshot shows the current line not being highlighted in insert mode:\n![Insert Screenthot](http://i.imgur.com/RNHR9KX.png)\n\nThis screenshot shows the current line not being highlighted in normal mode(`CurrentLineWhitespaceOff hard`):\n![Normal Screenshot](http://i.imgur.com/o888Z7b.png)\n\nThis screenshot shows that highlighting works fine for spaces, tabs, and a mixture of both:\n![Tabs Screenshot](http://i.imgur.com/bbsVRUf.png)\n\n## Frequently Asked Questions\nHopefully some of the most common questions will be answered here.  If you still have a question\nthat I have failed to address, please open an issue and ask it!\n\n**Q:  Why is trailing whitespace such a big deal?**\n\nA:  In most cases it is not a syntactical issue, but rather is a common annoyance among\n    programmers.\n\n\n**Q:  Why not just use `listchars` with `SpecialKey` highlighting?**\n\nA:  I tried using `listchars` to show trail characters with `SpecialKey` highlighting applied.\n    Using this method the characters would still show on the current line for me even when the\n    `SpecialKey` foreground highlight matched the `CursorLine` background highlight.\n\n\n**Q:  Okay, so `listchars` doesn't do exactly what you want, why not just use a `match` in your `vimrc`?**\n\nA:  I am using `match` in this plugin, but I've also added a way to exclude the current line in\n    insert mode and/or normal mode.\n\n\n**Q:  If you just want to exclude the current line, why not just use syntax-based highlight rather\n    than using `match` and `CursorMoved` events?**\n\nA:  Syntax-based highlighting is an option in this plugin.  It is used to omit the current line when\n    using `CurrentLineWhitespaceOff soft`. The only issue with this method is that `match` highlighing\n    takes higher priorty than syntax highlighting. For example, when using a plugin such as\n    [Indent Guides](https://github.com/nathanaelkane/vim-indent-guides), syntax-based highlighting of\n    extra whitespace will not highlight additional white space on emtpy lines.\n\n\n**Q:  I already have my own method of removing white space, why is the method used in this plugin better?**\n\nA:  It may not be, depending on the method you are using. The method used in this plugin strips extra\n    white space and then restores the cursor position and last search history.\n\n\n**Q:  Most of this is pretty easy to just add to users' `vimrc` files. Why make it a plugin?**\n\nA:  It is true that a large part of this is fairly simple to make a part of an individuals\n    configuration in their `vimrc`.  I wanted to provide something that is easy to setup and use\n    for both those new to Vim and others who don't want to mess around setting up this\n    functionality in their `vimrc`.\n\n**Q:  Can you add indentation highlighting for spaces/tabs? Can you add highlighting for other\n    types of white space?**\n\nA:  No, and no. Sorry, but both are outside the scope of this plugin. The purpose of this plugin\n    is to provide a better experience for showing and dealing with extra white space. There is already an\n    amazing plugin for showing indentation in Vim called [Indent\n    Guides](https://github.com/nathanaelkane/vim-indent-guides). For other types of white space highlighting,\n    [listchars](http://vimdoc.sourceforge.net/htmldoc/options.html#'listchars') should be sufficient.\n\n**Q:  I have a better way to do something in this plugin. OR You're doing something stupid/wrong/bad.**\n\nA:  If you know of a better way to do something I am attempting in this plugin, or if I am doing\n    something improperly/not reccomended then let me know! Please either open an issue informing\n    me or make the changes yourself and open a pull request. If I am doing something that is bad\n    or can be improved, I am more than willing to hear about it!\n\n## Deprecated commands\nToggling the current line whitespace mode is now a plugin configuration,\nand can not be done dynamically anymore. Thus the folowing commands are now deprecated:\n\n```vim\n:CurrentLineWhitespaceOff \u003clevel\u003e\n```\nwhere `\u003clevel\u003e` is either `hard` or `soft`, and:\n\n```vim\n:CurrentLineWhitespaceOn\n```\n\nIf you really miss this feature, its withdrawal can easily be overriden\nby adding the following to the vimrc (after loading the plugin initially):\n\n```vim\nfun! BetterWhitespaceCurrentLineMode(type)\n        \" set setting to whatever was passed\n        let g:current_line_whitespace_disabled_soft=a:type == 'soft'\n        let g:current_line_whitespace_disabled_hard=a:type == 'hard'\n        \" reload plugin\n        unlet! g:loaded_better_whitespace_plugin\n        runtime plugin/better-whitespace.vim\n        \" Re-override the deprecated commands\n        command! -nargs=1 CurrentLineWhitespaceOff call BetterWhitespaceCurrentLineMode(\u003cf-args\u003e)\n        command! CurrentLineWhitespaceOn call BetterWhitespaceCurrentLineMode('off')\n        \" Manually trigger change for current buffer.\n        \" BufWinEnter will take care of the rest.\n        filetype detect\nendfun\n\n\" Override deprecated commands, after (!) loading plugin\ncommand! -nargs=1 CurrentLineWhitespaceOff call BetterWhitespaceCurrentLineMode(\u003cf-args\u003e)\ncommand! CurrentLineWhitespaceOn call BetterWhitespaceCurrentLineMode('off')\n```\n\n## Promotion\nIf you like this plugin, please star it on Github and vote it up at Vim.org!\n\nRepository exists at: http://github.com/ntpeters/vim-better-whitespace\n\nPlugin also hosted at: http://www.vim.org/scripts/script.php?script_id=4859\n\n## Credits\nOriginally inspired by: https://github.com/bronson/vim-trailing-whitespace\n\nBased on:\n\nhttp://sartak.org/2011/03/end-of-line-whitespace-in-vim.html\n\nhttp://vim.wikia.com/wiki/Highlight_unwanted_spaces\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fntpeters%2Fvim-better-whitespace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fntpeters%2Fvim-better-whitespace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fntpeters%2Fvim-better-whitespace/lists"}