vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

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: