Vim Tips Wiki


1,612pages on
this wiki
Tip 108 Printable Monobook Previous Next

created 2001 · complexity basic · version 6.0

It is convenient to temporarily fold away (hide) parts of your file, leaving only an outline of the major parts visible. This tip presents an overview of using folding.

Many programming languages have a syntax file that supports folding. Typically, each function is regarded as a fold that can be opened or closed. With all folds closed, you see only the first line of each function for an overview of the program.

Folding methodsEdit

To activate folding in your text, you will need to set the 'foldmethod' option.

The 'foldmethod' option (abbreviated to 'fdm') is local to each window. It determines what kind of folding applies in the current window. Commonly used values are:

  • manual – folds must be defined by entering commands (such as zf)
  • indent – groups of lines with the same indent form a fold
  • syntax – folds are defined by syntax highlighting
  • expr – folds are defined by a user-defined expression

In addition, 'foldmethod' may have values:

  • marker – special characters can be manually or automatically added to your text to flag the start and end of folds
  • diff – used to fold unchanged text when viewing differences (automatically set in diff mode)

Manual foldingEdit

Normally it is best to use an automatic folding method, but manual folding is simple and useful for dealing with small folds. It is easy to fold an arbitrary block from visual mode by pressing 'v{motion}zf'. Alternatively, this can be used in normal mode, after zf'a for example will fold from the current line to wherever the mark a has been set, or zf3j will fold the next 3 lines. This allows you to see the section you've selected before you fold it. If you just want to enter a few folds in a program that uses braces around blocks ({...}), you can use the command va}zf to create a fold for the block containing the cursor. Use zd to delete a fold (no text is deleted; the fold at the cursor is removed). A quicker way to create a block is with zf{motion}, so the example fold mentioned earlier could also be typed zfa}.

Indent foldingEdit

In the vimrc, set the foldcolumn and foldlevel to the depth of folds you want displayed. A sidebar will appear showing which lines in the file can be folded, or are already folded.

Syntax foldingEdit

Try setting foldmethod=syntax. Many syntax files define folding based on the language syntax, although you may need to enable it by setting syntax file options. If a specific syntax file doesn't define folding, you can define your own.

Note that this particular fold method especially may define too many folds for your liking. You can change this using the 'foldnestmax' option, by setting it to a value low enough for your liking.

Indent folding with manual foldsEdit

If you like the convenience of having Vim define folds automatically by indent level, but would also like to create folds manually, you can get both by putting this in your vimrc:

augroup vimrc
  au BufReadPre * setlocal foldmethod=indent
  au BufWinEnter * if &fdm == 'indent' | setlocal foldmethod=manual | endif
augroup END

The first autocommand sets 'indent' as the fold method before a file is loaded, so that indent-based folds will be defined. The second one allows you to manually create folds while editing. It's executed after the modeline is read, so it won't change the fold method if the modeline set the fold method to something else like 'marker' or 'syntax'.

Folding by expressionEdit

This is the most complicated, but also the most powerful fold method. You can use it to fold in pretty much any way you desire. For example, you could fold away text not matching a regular expression. See :help 'foldexpr' for details.

Folding with markersEdit

Setting foldmethod to "marker" is similar to manual folding, because you can use zf and zd to add/remove folds, and all folds are defined manually. However, it works by adding special markers to your buffer text so that the same folds can be loaded by anyone opening the file in Vim. The markers are defined by the 'foldmarker' option, which defaults to three consecutive open curly braces to start a fold and three consecutive closed curly braces to end a fold. This method is mostly useful when the other options don't give satisfactory results, either because a syntax file does not define folding, you want to break up a file into logical portions instead of syntactical constructs, or you are folding plain text in some way.

If you change the default 'foldmarker' setting, be sure to communicate the correct setting to other people in some way. An especially effective method for this would be to use a modeline, so that most Vim users will get your intended settings by default when they edit the file.

Diff foldingEdit

This foldmethod should never be set manually without very good reason. It is the default fold method when using Vim in diff mode. Simply running any of the commands to put Vim in diff mode will set this option for you. It works by folding away lines that do not differ between the buffers in the diff, so that you can focus on the lines with differences. Note that you can tweak the number of lines to leave unfolded, using the 'diffopt' option.

If you want folding in diff/patch files, see Folding for diff files instead.

Opening and closing foldsEdit

The command zc will close a fold (if the cursor is in an open fold), and zo will open a fold (if the cursor is in a closed fold). It's easier to just use za which will toggle the current fold (close it if it was open, or open it if it was closed).

The commands zc (close), zo (open), and za (toggle) operate on one level of folding, at the cursor. The commands zC, zO and zA are similar, but operate on all folding levels (for example, the cursor line may be in an open fold, which is inside another open fold; typing zC would close all folds at the cursor).

The command zr reduces folding by opening one more level of folds throughout the whole buffer (the cursor position is not relevant). Use zR to open all folds.

The command zm gives more folding by closing one more level of folds throughout the whole buffer. Use zM to close all folds.

Mappings to toggle foldsEdit

With the following in your vimrc, you can toggle folds open/closed by pressing F9. In addition, if you have :set foldmethod=manual, you can visually select some lines, then press F9 to create a fold.

inoremap <F9> <C-O>za
nnoremap <F9> za
onoremap <F9> <C-C>za
vnoremap <F9> zf

Here is an alternative procedure: In normal mode, press Space to toggle the current fold open/closed. However, if the cursor is not in a fold, move to the right (the default behavior). In addition, with the manual fold method, you can create a fold by visually selecting some lines, then pressing Space.

nnoremap <silent> <Space> @=(foldlevel('.')?'za':"\<Space>")<CR>
vnoremap <Space> zf

In the first mapping for Space, @= refers to the expression register (:help @=). The following expression is evaluated when Enter is pressed (<CR>). The value of foldlevel('.') is determined (the fold level at the current line, or zero if the current line is not in a fold). If the result is nonzero (true), the result is 'za' (toggle fold); otherwise it is "\<Space>", which evaluates back to the default behaviour of the <Space> key (move forward by one character). :help expr1

Saving folds before closing vimEdit

Vim provides a good mechanism called view. You can use it to save a fold. See Make views automatic. You may also want to use plugin restore_view.vim.

Commands over foldsEdit

Folds can be created using one of the methods described above. Then, all the folds can be closed using zM. Now, commands can be executed on each line that is folded, using :folddoc <command>. Reopen the folds using zR to see the results.

Todo: Explain how a command stored in a register can be executed this way. Ctrl-r, followed by the register name does not appear to execute the set of keystrokes for each line that is folded?

See alsoEdit



Around Wikia's network

Random Wiki