Folding

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.

Opening and closing folds

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.

中文译本： zm命令可以对Buff中所存在的所有折叠执行收起折叠的操作，zM可以展开Buff中所存在的所有折叠。

Mappings to toggle folds

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':'l')<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 'l' (move right). :help expr1

Folding methods

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
• indent – groups of lines with the same indent form a fold
• syntax – folds are defined by syntax highlighting
• expr – folds are defined by an expression

In addition, 'foldmethod' may have values:

• expr – an expression to calculate the fold level can be entered
• 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

Manual folding

Normally it's best to use syntax folding, but manual folding is simple and useful for dealing with small folds. It's 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 folding

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 folding

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.

Indent folding with manual folds

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'.

Commands over folds

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 also

• Syntax folding of Vim scripts discusses folding for files in the Vim script language
• Auto-fold Perl subs discusses folding for the Perl language
• Dosini files includes information about folding in DOS-style .ini files

References

• :help folding
• :help zc
• :help zo
• :help za
• :help zf
• :help :syn-fold