Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/preservim/nerdcommenter

Vim plugin for intensely nerdy commenting powers
https://github.com/preservim/nerdcommenter

comment commenting vim vim-plugin vim-plugins

Last synced: 2 days ago
JSON representation

Vim plugin for intensely nerdy commenting powers

Awesome Lists containing this project

README 

        
# NERD Commenter



[![Vint](https://github.com/preservim/nerdcommenter/workflows/Vint/badge.svg)](https://github.com/preservim/nerdcommenter/actions?workflow=Vint)



Comment functions so powerful—no comment necessary.



## Installation



### Via Plugin Manager (Recommended)



  Vim Plug

    

#### [Vim-Plug](https://github.com/junegunn/vim-plug)



1. Add `Plug 'preservim/nerdcommenter'` to your vimrc file.

2. Reload your vimrc or restart

3. Run `:PlugInstall`



  Vundle



#### [Vundle](https://github.com/VundleVim/Vundle.vim) or similar



1. Add `Plugin 'preservim/nerdcommenter'` to your vimrc file.

2. Reload your vimrc or restart

3. Run `:BundleInstall`



  NeoBundle

  

#### [NeoBundle](https://github.com/Shougo/neobundle.vim)



1. Add `NeoBundle 'preservim/nerdcommenter'` to your vimrc file.

2. Reload your vimrc or restart

3. Run `:NeoUpdate`



  Pathogen

  

#### [Pathogen](https://github.com/tpope/vim-pathogen)



```sh

cd ~/.vim/bundle

git clone https://github.com/preservim/nerdcommenter.git

```



  Vim 8+ Packages



    git clone https://github.com/preservim/nerdcommenter.git ~/.vim/pack/vendor/start/nerdcommenter



### Manual Installation



  Unix

  

#### Unix



(For Neovim, change `~/.vim/` to `~/.config/nvim/`.)



```sh

curl -fLo ~/.vim/plugin/nerdcommenter.vim --create-dirs \

  https://raw.githubusercontent.com/preservim/nerdcommenter/master/plugin/nerdcommenter.vim

curl -fLo ~/.vim/doc/nerdcommenter.txt --create-dirs \

  https://raw.githubusercontent.com/preservim/nerdcommenter/master/doc/nerdcommenter.txt

curl -fLo ~/.vim/autoload/nerdcommenter.vim --create-dirs \

  https://raw.githubusercontent.com/preservim/nerdcommenter/master/autoload/nerdcommenter.vim

```



  Windows

#### Windows (PowerShell)



```powershell

md ~\vimfiles\plugin

md ~\vimfiles\doc

$pluguri = 'https://raw.githubusercontent.com/preservim/nerdcommenter/master/plugin/nerdcommenter.vim'

$docsuri = 'https://raw.githubusercontent.com/preservim/nerdcommenter/master/doc/nerdcommenter.txt'

(New-Object Net.WebClient).DownloadFile($pluguri, $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath("~\vimfiles\plugin\nerdcommenter.vim"))

(New-Object Net.WebClient).DownloadFile($docsuri, $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath("~\vimfiles\doc\nerdcommenter.txt"))

```



### Post Installation



Make sure that you have filetype plugins enabled, as the plugin makes use of **|commentstring|** where possible (which is usually set in a filetype plugin). See **|filetype-plugin-on|** for details, but the short version is make sure this line appears in your vimrc:



```sh

filetype plugin on

```



## Usage



### Documentation



Please see the vim help system for full documentation of all options: `:help nerdcommenter`



### Settings



Several settings can be added to your vimrc to change the default behavior. Some examples:



```vim

" Create default mappings

let g:NERDCreateDefaultMappings = 1



" Add spaces after comment delimiters by default

let g:NERDSpaceDelims = 1



" Use compact syntax for prettified multi-line comments

let g:NERDCompactSexyComs = 1



" Align line-wise comment delimiters flush left instead of following code indentation

let g:NERDDefaultAlign = 'left'



" Set a language to use its alternate delimiters by default

let g:NERDAltDelims_java = 1



" Add your own custom formats or override the defaults

let g:NERDCustomDelimiters = { 'c': { 'left': '/**','right': '*/' } }



" Allow commenting and inverting empty lines (useful when commenting a region)

let g:NERDCommentEmptyLines = 1



" Enable trimming of trailing whitespace when uncommenting

let g:NERDTrimTrailingWhitespace = 1



" Enable NERDCommenterToggle to check all selected lines is commented or not 

let g:NERDToggleCheckAllLines = 1

```



### Default mappings



> **Note:** You can turn off settings default mappings to provide your own from scratch (look at the [Settings list](#settings) above)



The following key mappings are provided by default (there is also a menu provided that contains menu items corresponding to all the below mappings):



Most of the following mappings are for normal/visual mode only. The **|NERDCommenterInsert|** mapping is for insert mode only.



  * `[count]cc` **|NERDCommenterComment|**



    Comment out the current line or text selected in visual mode.



  * `[count]cn` **|NERDCommenterNested|**



    Same as cc but forces nesting.



  * `[count]c` **|NERDCommenterToggle|**



    Toggles the comment state of the selected line(s). If the topmost selected line is commented, all selected lines are uncommented and vice versa.



  * `[count]cm` **|NERDCommenterMinimal|**



    Comments the given lines using only one set of multipart delimiters.



  * `[count]ci` **|NERDCommenterInvert|**



    Toggles the comment state of the selected line(s) individually.



  * `[count]cs` **|NERDCommenterSexy|**



    Comments out the selected lines with a pretty block formatted layout.



  * `[count]cy` **|NERDCommenterYank|**



    Same as cc except that the commented line(s) are yanked first.



  * `c$` **|NERDCommenterToEOL|**



    Comments the current line from the cursor to the end of line.



  * `cA` **|NERDCommenterAppend|**



    Adds comment delimiters to the end of line and goes into insert mode between them.



  * **|NERDCommenterInsert|**



    Adds comment delimiters at the current cursor position and inserts between. Disabled by default.



  * `ca` **|NERDCommenterAltDelims|**



    Switches to the alternative set of delimiters.



  * `[count]cl` **|NERDCommenterAlignLeft**

    `[count]cb` **|NERDCommenterAlignBoth**



    Same as **|NERDCommenterComment|** except that the delimiters are aligned down the left side (`cl`) or both sides (`cb`).



  * `[count]cu` **|NERDCommenterUncomment|**



    Uncomments the selected line(s).



## Motions



While the plugin does not directly support motions, you can leverage its support for selections to do something very similar. For example, to add motions to toggle comments on the paragraph text object you could use:

```vim

nnoremap  c} V}:call nerdcommenter#Comment('x', 'toggle')

nnoremap  c{ V{:call nerdcommenter#Comment('x', 'toggle')

```



## Contributions



This plugin was originally written in 2007 by [Martin Grenfell (@scrooloose)](https://github.com/scrooloose/). Lots of features and many of the supported filetypes have come from [community contributors](https://github.com/preservim/nerdcommenter/graphs/contributors). Since 2016 it has been maintained primarily by [Caleb Maclennan (@alerque)](https://github.com/alerque). Additional file type support, bug fixes, and new feature contributons are all welcome, please send them as Pull Requests on Github. If you can't contribute yourself please also feel free to open issues to report problems or request features.