sponsor Vim development Vim logo Vim Book Ad

FormatToWidth : Apply the gq command to the selected / count width.

 script karma  Rating 25/7, Downloaded by 701  Comments, bugs, improvements  Vim wiki

created by
Ingo Karkat
script type
Vim can reformat lines with the gq command, according to 'textwidth' and
'formatoptions', which is very handy. But sometimes you want to format to a
different width, or just a single block in a vertical column layout. That
requires a temporary :setlocal tw=N, and copying the block elsewhere to
reformat it, which is cumbersome.

This plugin provides a visual mode <Leader>gq command that reformats only the
selection; how exactly depends on the selection mode. The new width is
determined by a passed [count], or the width of the selection's first line.
With this, you can easily reformat lines to a certain width, or a blockwise
selection while leaving the text to the left and right alone.

Inspired by

{Visual}<Leader>gq      Linewise selection: Format the selected text to the
                        width of the first selected line / to [count]
                        Blockwise selection: Format the selected text to the
                        width of the block / to [count] characters, and
                        change the selected text in-place. If the reformatted
                        text consists of less lines, the remainder of the
                        block will consist of spaces. If it's more lines,
                        these will be inserted as additional lines,
                        left-aligned with spaces to the start column of the
                        Characterwise selection: Format the selected text to
                        the width of the first selected line / to [count]
                        characters, and align all following lines to the start
                        column of the selection.

To re-wrap the following text:
    The quick brown fox jumps over the lazy dog.
to a 'textwidth' of 20, you select the entire line, then reformat to the
specified width: V20<Leader>gq
    The quick brown fox
    jumps over the lazy

You have a multi-column layout like this:
    Intro | The quick brown fox       -
          | jumps over the lazy dog.  - (he's very lazy)
Let's reformat the middle column to use all the available space.
You select the entire column as a block, e.g. with f|l<C-V>t-j, then reformat
the selection with <Leader>gq:
    Intro | The quick brown fox jumps -
          | over the lazy dog.        - (he's very lazy)
Okay, but now you want it wider: gv40<Leader>gq reformats to a 40-char column:
    Intro | The quick brown fox jumps over the lazy -
          | dog.                                    - (he's very lazy)
install details
This script is 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 FormatToWidth*.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.018 or

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

If you want to use a different mapping, map your keys to the
<Plug>(FormatToWidth) mapping target _before_ sourcing the script
(e.g. in your vimrc):
    xmap <Leader>gq <Plug>(FormatToWidth)

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
FormatToWidth-1.00.vmb.gz 1.00 2014-04-14 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.