comment.txt (4816B)
1 *comment.txt* For Vim version 9.1. Last change: 2025 Jun 22 2 3 4 VIM REFERENCE MANUAL 5 6 Commenting and un-commenting text. 7 8 ============================================================================== 9 10 See |comment-install| on how to activate this package. 11 12 The comment.vim package, allows to toggle comments for a single line, a range 13 of lines or a selected text object. It defines the following mappings: 14 15 *o_gc* 16 gc{motion} to toggle comments for the selected motion 17 *v_gc* 18 {Visual}gc to comment/uncomment the highlighted lines. 19 20 Since gc operates on a motion, it can be used with any motion, for example _ 21 to comment the current line, or ip to comment the current paragraph. 22 Default mappings are defined for `gc_` and `gc$`: 23 *gcc* 24 gcc to comment/uncomment current line (same as `gc_`) 25 26 *gC* 27 gC to comment/uncomment to end of current line (same as `gc$`) 28 29 Commenting to the end of a line using `gC` works whenever the filetype plugin 30 supports it (that is, whenever the comment marker precedes the code) and falls 31 back to `gcc` otherwise. 32 33 Note: using `gC` may not always result in valid comment markers depending on 34 the language used. 35 36 Additionally, the plugin defines a comment text-object which requires syntax 37 highlighting to be enabled. 38 *v_ac* *ac* 39 ac "a comment", select current or next comment. 40 Leading and trailing white space is included. 41 Trailing newlines are included too. 42 *v_ic* *ic* 43 ic "inner comment", select current or next comment. 44 45 This plugin uses the buffer-local 'commentstring' option value to add or remove 46 comment markers to the selected lines. Whether it will comment or un-comment 47 depends on the range of lines to act upon. When all of the lines in range 48 have comment markers, all lines will be un-commented, if it doesn't, the lines 49 will be commented out. Blank and empty lines are ignored. 50 51 The value of 'commentstring' is the same for the entire buffer and determined 52 by its filetype (|filetypes|). To adapt it within the buffer for embedded 53 languages, you can use a plug-in such as 54 https://github.com/suy/vim-context-commentstring. 55 56 The comment marker will always be padded with blanks whether or not the 57 'commentstring' value contains whitespace around "%s". 58 59 If the mapping does not seem to work (or uses wrong comment markers), it might 60 be because of several reasons: 61 - the filetype is not detected by Vim, see |new-filetype|, 62 - filetype plugins are not enabled, see |:filetype-plugin-on| or 63 - the filetype plugin does not set the (correct) 'commentstring' option. 64 65 You can simply configure this using the following autocommand (e.g. for legacy 66 Vim script): > 67 68 autocmd Filetype vim :setlocal commentstring="%s 69 70 This example sets the " as start of a comment for legacy Vim script. For Vim9 71 script, you would instead use the "#" char: > 72 73 autocmd Filetype vim :setlocal commentstring=#\ %s 74 75 ============================================================================== 76 Options: 77 78 *g:comment_first_col* 79 *b:comment_first_col* 80 By default comment chars are added in front of the line, i.e. if the line 81 was indented, commented line would stay indented as well. 82 83 However some filetypes require a comment char on the first column, use this option 84 to change default behaviour. 85 86 Use g:comment_first_col to change it globally or b:comment_first_col to 87 target specific filetype(s). 88 89 *g:comment_mappings* 90 Set to false to disable the default keyboard mappings, e.g. in your vimrc 91 > 92 let g:comment_mappings = v:false 93 < 94 This option must be set before the package is activated using |packadd|. 95 96 ============================================================================== 97 Mappings: 98 99 The following |<Plug>| mappings are included, which you can use to customise the 100 keyboard mappings. 101 102 *<Plug>(comment-toggle)* 103 Normal and visual modes, mapped to gc by default 104 105 *<Plug>(comment-toggle-line)* 106 Normal mode only, mapped to gcc by default 107 108 *<Plug>(comment-toggle-end)* 109 Normal mode only, mapped to gC by default 110 111 *<Plug>(comment-text-object-inner)* 112 Operator pending and visual modes, mapped to ic by default 113 114 *<Plug>(comment-text-object-outer)* 115 Operator pending and visual modes, mapped to ac by default 116 117 The default keyboard mappings are shown below, you can copy these if you wish 118 to customise them in your vimrc: 119 > 120 nmap gc <Plug>(comment-toggle) 121 xmap gc <Plug>(comment-toggle) 122 nmap gcc <Plug>(comment-toggle-line) 123 nmap gC <Plug>(comment-toggle-end) 124 125 omap ic <Plug>(comment-text-object-inner) 126 omap ac <Plug>(comment-text-object-outer) 127 xmap ic <Plug>(comment-text-object-inner) 128 xmap ac <Plug>(comment-text-object-outer) 129 < 130 ============================================================================== 131 vim:tw=78:ts=8:fo=tcq2:ft=help: