sponsor Vim development Vim logo Vim Book Ad

IndentCommentPrefix : Keep comment prefix in column 1 when indenting.

 script karma  Rating 14/5, Downloaded by 2786  Comments, bugs, improvements  Vim wiki

created by
Ingo Karkat
script type
Indent commands like >>, << and i_CTRL-T, i_CTRL-D in insert mode
indent the entire line. For some kinds of comments, like the big boilerplate
at the file header etc., the comment prefix (e.g. # for Perl scripts) should
remain at the first column, though.
This plugin modifies these indent commands so that the comment prefix remains
in the first column, and the indenting takes place between the comment prefix
and the comment text. For that, it uses the comment configuration provided by
the buffer's 'comment' option, which is set by most filetype plugins; this can
be tweaked via plugin configuration.

On a line like this:
# My comment.

The >> command now keeps the # prefix in column 1, and just indents the
comment text:
#       My comment.

This only works if there is at least one whitespace character after the prefix
(so that comments like ###### do not become #       ######).
Progressive de-indenting will remove all whitespace between prefix and comment
text, or leave a single space in between if the 'comments' setting requires a
blank after the comment prefix.

An optional [count] of lines can be supplied to the >> and << commands, as
In visual mode, the optional [count] specifies how many 'shiftwidth's should
be indented; the v_> and v_< commands operate on all highlighted lines.

With the optional repeat.vim script, the commands can also be repeated via ..

The same behavior is available in insert mode via the i_CTRL-T and
i_CTRL-D mappings:

CTRL-T          Insert one shiftwidth of indent at the start of the current
                line, after any comment prefix. The indent is always rounded
                to a 'shiftwidth'.

CTRL-D          Delete one shiftwidth of indent at the start of the current
                line, after any comment prefix. The indent is always rounded
                to a 'shiftwidth'.

CTRL-G CTRL-T   Insert a single space of indent at the start of the current
                line, after any comment prefix, and toggle the behavior of
                i_CTRL-D to continue inserting a single space instead of one

CTRL-G CTRL-D   Delete a single space of indent at the start of the current
                line, after any comment prefix, and toggle the behavior of
                i_CTRL-D to continue deleting a single space instead of one

In case you want to indent lines including the comment prefix, the original
indent behavior is mapped to g>> in normal mode and g> in visual mode.
There's only a need for the corresponding g<< dedent mappings when using the
g:IndentCommentPrefix_Whitelist, because those prefixes will work not just
in column 1 (where dedenting is not possible), but in any column.
Alternatively, you could also use the >{motion} command, as the > and <
operators aren't modified by this plugin.
install details
The code is hosted in a Git repo at
You can use your favorite plugin manager, or "git clone" into a directory used
for Vim packages. Releases are on the "stable" branch, the latest unstable
development snapshot on "master".

This script is also packaged as a vimball. If you have the "gunzip"
decompressor in your PATH, simply edit the *.vmb.gz package in Vim; otherwise,
decompress the archive first, e.g. using WinZip. Inside Vim, install by
sourcing the vimball or via the :UseVimball command.
    vim IndentCommentPrefix*.vmb.gz
    :so %
To uninstall, use the :RmVimball command.

- Requires Vim 7.0 or higher.
- Requires the ingo-library.vim plugin (vimscript #4433), version 1.005 or
- repeat.vim (vimscript #2136) plugin (optional)

For a permanent configuration, put the following commands into your vimrc:

By default, indenting behavior with all comment prefixes defined in the
'comments' option is modified. To disable the keeping in column 1 for some
prefixes, add each prefix to the following (buffer-local or global) List
    let g:IndentCommentPrefix_Blacklist = ['#', '>']

If you want to modify the indenting behavior for certain prefixes not just in
column 1, but with any existing indent, add each prefix to the following
(buffer-local or global) List variable. These prefixes do not need to be
contained in 'comments' then.
    let g:IndentCommentPrefix_Whitelist = ['REMARK:']

You may want to use a different 'shiftwidth' or 'expandtab' setting for
indenting with a comment prefix (vs. "normal" indenting without comments), you
can define the settings globally (or alternatively for the current buffer)
    let g:IndentCommentPrefix_IndentSettingsOverride = 'shiftwidth=3 expandtab'

If you want to use different mappings instead of overriding the default
commands, map your keys to the <Plug>IndentCommentPrefix... mapping targets
_before_ sourcing the script (e.g. in your vimrc):
    imap <C-t> <Plug>IndentCommentPrefixIndent
    imap <C-d> <Plug>IndentCommentPrefixDedent
    nmap <Leader>>     <Plug>IndentCommentPrefix0
    vmap <Leader>>     <Plug>IndentCommentPrefix0
    nmap <Leader><lt>  <Plug>IndentCommentPrefix1
    vmap <Leader><lt>  <Plug>IndentCommentPrefix1

If you don't want the alternative g>> and g<< mappings for the original indent
commands, set the following variable _before_ sourcing the plugin:
    let g:IndentCommentPrefix_alternativeOriginalCommands = 0

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
IndentCommentPrefix-1.40.vmb.gz 1.40 2017-12-23 7.0 Ingo Karkat - Supply 'i' flag (since Vim 7.4.601) to execute the insert mode in/dedent before typeahead (to avoid breaking macro playbacks).
- ENH: Define <Plug>-imaps for <C-d> / <C-t> to allow remapping of those, too.
- ENH: Add IndentCommentPrefix#InsertToggled() wrapper for IndentCommentPrefix#InsertMode() that implements toggling of 'shiftwidth' / single space indenting via a separate toggle mapping.
- ENH: Allow overriding the 'shiftwidth' and 'expandtab' indent settings for indenting of comment prefixes via
IndentCommentPrefix-1.32.vmb.gz 1.32 2013-11-19 7.0 Ingo Karkat - Add special case to handle the (rather obscure) |i_0_CTRL-D| and |i_^_CTRL-D| commands, which were broken by the plugin's insert mode mapping.
- Add dependency to ingo-library (vimscript #4433). *** You need to separately install ingo-library (vimscript #4433) version 1.005 (or higher)! ***
IndentCommentPrefix-1.31.vmb.gz 1.31 2013-01-25 7.0 Ingo Karkat Also define opposite g<< commands with g:IndentCommentPrefix_alternativeOriginalCommands. It's good for consistency (my muscle memory often cannot distingish indenting from dedenting), and necessary when using the g:IndentCommentPrefix_Whitelist, because those work not just in column 1 (where dedenting is not possible), but in any column.
IndentCommentPrefix-1.30.vmb.gz 1.30 2012-12-13 7.0 Ingo Karkat - ENH: Add global and buffer-local whitelists / blacklists to explicitly include / exclude certain comment prefixes.
- Handle readonly and nomodifiable buffers by printing just the warning / error, without the multi-line function error.
- FIX: Now handling three-piece comments correctly. The start may set a positive indent offset for the middle and end comment prefixes that must be considered.
- FIX: Suppress 'ignorecase' in s:Literal().
IndentCommentPrefix.vba.gz 1.10 2011-03-30 7.0 Ingo Karkat - Split off separate documentation and autoload script. Now publishing as Vimball.
- BUG: Only report changes if more than 'report' lines where indented; I got the meaning of 'report' wrong the first time.
- BUG: Could not use 999>> to indent all remaining lines.
- BUG: Normal-mode mapping didn't necessarily put the cursor on the first non-blank character after the comment prefix if 'nostartofline' is set.
- ENH: In normal and visual mode, set the change marks '[ and ]' similar to what Vim does.
IndentCommentPrefix.vim 1.02 2009-10-06 7.0 Ingo Karkat Do not define mappings for select mode; printable characters should start insert mode.
IndentCommentPrefix.vim 1.01.009 2009-07-05 7.0 Ingo Karkat BF: When 'report' is less than the default 2, the :substitute and << / >> commands created additional messages, causing a hit-enter prompt.  Now also reporting a single-line change when 'report' is 0 (to be consistent with the built-in indent commands).
IndentCommentPrefix.vim 1.00.008 2009-02-23 7.0 Ingo Karkat BF: Fixed "E61: Nested *" that occurred when shifting a line with a comment prefix containing multiple asterisks in a row (e.g. '**').
BF: Info message (given when indenting multiple lines) always printed "1 time" even when a [count] was specified in visual mode.
IndentCommentPrefix.vim 1.00.007 2009-01-29 7.0 Ingo Karkat Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.