sponsor Vim development Vim logo go to HTTPS page Vim Book Ad

Spiffy Foldtext : easy foldtext via a format string, with added features

 script karma  Rating 1/1, Downloaded by 240    Comments, bugs, improvements  Vim wiki

created by
Tim Holt
script type
A customizable foldtext function that properly takes into account the actual
width of the displayable area of your windows. You are thus able to
right-justify a portion of it, usually meta-data like line count and fold

At the center of the plugin is a special format string. By customizing its
value, you can create your own custom foldtext in a single line in your vimrc.

This plugin is meant to be drop-in-able without the need to make any
adjustments--with nice default settings that increase the clarity of your
partially folded windows. There are no functions mapped or in need of mapping.

The official repository for this plugin is located on bitbucket, at
https://bitbucket.org/atimholt/spiffy_foldtext , but a skeleton git repository
(containing just numbered releases) is kept on github, at
https://github.com/atimholt/spiffy_foldtext for the sake of plugin managers
that don't support Mercurial, like Vundle.

                               The Format String

The format string is customizable by setting the "SpiffyFoldtext_format"
variable, prepended with "g:" for global scope, "b:" for buffer-local scope,
or "w:" for window-local scope--each scope overriding those listed before it.
The format string contains control triggers and literal text describing how
your folded lines will render. For example, here's the default (more or less):

        if has('multi_byte')
            let g:SpiffyFoldtext_format = "%c{═}  %<%f{═}╡ %4n lines ╞═%l{╤═}"
            let g:SpiffyFoldtext_format = "%c{=}  %<%f{=}| %4n lines |=%l{/=}"

Or, more simply (I'll take the ascii-only version for the sake of

        let g:SpiffyFoldtext_format = "%c{=}  %<%f{=}| %4n lines |=%l{/=}"

The plugin parses this string upon first run, then 'compiles' it to your
foldtext each time vim needs to determine what to display on a line that
represents a folded region. In a display area 70 characters wide, the above
example would make this sample text:

    Some text with a foldmarker {{{                                      
        Some indented text        with a wide whitespace region {{{      

fold to look like this:

    Some text with a foldmarker {{{                                      
    === Some indented text ====== with a wide whitespace |    3 lines |=/=

or this:

    Some text with a foldmarker {{{  ======================|    5 lines |=

Here's a sampling of what some of the example translates to. See the plugin's
help (:help spiffy_foldtext) for more information on the rest:


This trigger places the text of the fold region's first line into your
foldtext. As given here, its indentation and wider whitespace regions will be
filled with the '=' character. See :help spiffy_foldtext-%c.

   "  "

This inserts two literal spaces.


This represents the split between what will be left-aligned in your foldtext
and what will be right aligned. The leftward angle bracket is meant as a
mnemonic to indicate that, should all the contents of the foldtext be too wide
for the display area, the content to the right of this trigger will overwrite
part of the content to the left. See :help spiffy_foldtext-%<.


If the content of the foldtext doesn't fill up the entire display region, the
foldtext will be filled with '='s at this point, to the amount needed to
right-align the right-align section. See :help spiffy_foldtext-%f{}.

install details
There are a few supported ways to install this plugin:

                                   Old style:

If you just don't care, simply copy the files into your run time and run the

    :helptags $VIMRUNTIME/doc

Putting whatever directory the docs for the plugin ended up in.

This is *not* recommended. It's not even the *easiest* way nowadays. Try one of
the methods below.


Unzip the files into your bundle folder. Or do the following:

Navigate to your bundle directory. By default, this will be something like

Then run the command:

    hg clone https://bitbucket.org/atimholt/spiffy_foldtext


Insert the following line into your vimrc, under the conditions described by the
Vundle documentation:

    Bundle 'atimholt/spiffy_foldtext'


Insert the following line into your vimrc, under the conditions described by the
NeoBundle documentation:

    NeoBundle 'atimholt/spiffy_foldtext'

Or, if you want a slightly better guarantee that you really have the latest

    NeoBundle 'bb:atimholt/spiffy_foldtext', {'type': 'hg'}

This still puts you in the default branch, which is kept stable.

                             Other Plugin managers:

Other plugin managers are likely easily adapted to installing this plugin, using
instructions similar to one of the above. See your plugin manager's

Rating scripts is only available on the HTTPS page

script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
spiffy_foldtext_1_1.7z 1.1 2014-05-28 7.0 Tim Holt changelog (1.1):
  - Added window local fold-text, to override global fold text or buffer local
    foldtext when present.
  - Added buffer local fold-text, to override global fold text when present.
  - Unit tests for stability and changeability (not really a feature)
  - Added %[some number]fl trigger, inserting fold level
spiffy_foldtext_1_0.tar.gz 1.0 2014-04-09 7.0 Tim Holt 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.
SourceForge.net Logo