Editing Folding

{{TipImported
|id=108
|previous=107
|next=111
|created=2001
|complexity=basic
|author=
|version=6.0
|rating=90/41
|category1=Folding
|category2=
}}
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 methods==
To activate folding in your text, you will need to set the 'foldmethod' option.

The <code>'foldmethod'</code> option (abbreviated to <code>'fdm'</code>) is local to each window. It determines what kind of folding applies in the current window. Possible values are:
*<code>manual</code> – folds must be defined by entering commands (such as {{help|prefix=no|zf}})
*<code>indent</code> – groups of lines with the same indent form a fold
*<code>syntax</code> – folds are defined by syntax highlighting
*<code>expr</code>   – folds are defined by a user-defined expression
*<code>marker</code> – special characters can be manually or automatically added to your text to flag the start and end of folds
*<code>diff</code> – used to fold unchanged text when viewing differences (automatically set in diff mode)

===Manual folding===
Normally it is best to use an automatic folding method, but manual folding is simple and can be useful for dealing with small folds.

When <code>foldmethod</code> is set to <code>manual</code> (or <code>marker</code>), a fold can be '''created''' in ''Normal mode'' by typing <code>zf{motion}</code>.  For example, <code>zf'a</code> will fold from the current line to wherever the mark a has been set, or <code>zf3j</code> folds the current line along with the following 3 lines.  If you want to create folds in a text file that uses curly braces to delimit code blocks (<code>{...}</code>), you can use the command <code>zfa}</code> to create a fold for the current code block.

Alternatively, an arbitrary group of lines can be folded by selecting them to enter ''Visual mode'' and pressing <code>zf</code>. This allows you to preview the section you've selected before you fold it.  The above example of folding the current code block could also be accomplished by first selecting the code block delimited by the curly braces (<code>va}</code>) and then creating the fold (<code>zf</code>). Putting this together gives <code>va}zf</code>.

Manual folds can also be created in ''Command mode'' <code>:{range}fo[ld]</code>, e.g., the current line along with the following three lines (as in the example above) can be folded by running <code>:,+3fo</code>.

Use <code>zd</code> to '''delete''' the fold at the cursor (no text is deleted, just the fold markers); <code>zD</code> is used to ''recursively'' delete folds at the cursor.

===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 <code>foldmethod=syntax</code>. Many syntax files define folding based on the language syntax, although you may need to enable it by [[VimTip1534|setting syntax file options]]. If a specific syntax file doesn't define folding, you can [[Syntax folding of Vim scripts|define your own]].

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

===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]]:
<pre>
augroup vimrc
  au BufReadPre * setlocal foldmethod=indent
  au BufWinEnter * if &fdm == 'indent' | setlocal foldmethod=manual | endif
augroup END
</pre>

The first autocommand sets <code>'indent'</code> 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 <code>'marker'</code> or <code>'syntax'</code>.

===Folding by expression===
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 [[Folding with Regular Expression|fold away text not matching a regular expression]]. See {{help|'foldexpr'}} for details.

===Folding with markers===
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. 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.

===Diff folding===
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 {{help|prefix=no|'diffopt'}} option.

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

The commands <code>zc</code> (close), <code>zo</code> (open), and <code>za</code> (toggle) operate on one level of folding, at the cursor. The commands <code>zC</code>, <code>zO</code> and <code>zA</code> 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 <code>zC</code> would close all folds at the cursor).

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

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

===Mappings to toggle folds===
With the following in your [[vimrc]], you can toggle folds open/closed by pressing F9. In addition, if you have <code>:set&nbsp;foldmethod=manual</code>, you can visually select some lines, then press F9 to create a fold.
<pre>
inoremap <F9> <C-O>za
nnoremap <F9> za
onoremap <F9> <C-C>za
vnoremap <F9> zf
</pre>

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 <code>manual</code> fold method, you can create a fold by visually selecting some lines, then pressing Space.
<pre>
nnoremap <silent> <Space> @=(foldlevel('.')?'za':"\<Space>")<CR>
vnoremap <Space> zf
</pre>

In the first mapping for Space, <code>@=</code> refers to the expression register ({{help|1=@=}}). The following expression is evaluated when Enter is pressed (<code><CR></code>). The value of <code>foldlevel('.')</code> 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 <code>'za'</code> (toggle fold); otherwise it is <code>"\<Space>"</code>, which evaluates back to the default behaviour of the <Space> key (move forward by one character). {{help|expr1}}

==Saving folds before closing the vim==
Vim provides a good mechanism called <code>view</code>.  You can use it to saving a fold. See [[VimTip991|Make views automatic]].  You may also want to use plugin {{script|id=4021|text=restore_view.vim}}.

==Commands over folds==
Folds can be created using one of the methods described above. Then, all the folds can be closed using <code>zM</code>. Now, commands can be executed on each line that is folded, using <code>:folddoc <command></code>. Reopen the folds using <code>zR</code> 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 [[:Category:VimL|Vim script]] language
*[[Auto-fold Perl subs]] discusses folding for the [[:Category:Perl|Perl]] language
*[[Dosini_files#Folding_sections|Dosini files]] includes information about folding in DOS-style <code>.ini</code> files

==References==
*{{help|folding}}
*{{help|zc}}
*{{help|zo}}
*{{help|za}}
*{{help|zf}}
*{{help|:syn-fold}}

==Comments==
@@ Line 38: / Line 38: @@
 ===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.
-As noted above, with 'foldmethod' set to indent, lines with the same level of indentation will be folded together. Note this means text like this:
-<pre>
-Line one
-  Line two
-  Line three
-Line four
-</pre>
-will be folded as follows, which may not be expected:
-<pre>
-Line one
-+ Line two and three
-Line four
-</pre>
-Since folding by indent may not be as clear as you like, the foldcolumn is especially useful for this method. Setting foldcolumn to at least the level of folds you want displayed will show a sidebar, in which you can see which lines in the file can be folded, or are already folded, with a '+' (closed) or '-' (open) indicator.
 ===Syntax folding===
-Try <code>:setlocal foldmethod=syntax</code>. Many syntax files define folding based on the language syntax, although you may need to enable it by [[VimTip1534|setting syntax file options]]. If a specific syntax file doesn't define folding, you can [[Syntax folding of Vim scripts|define your own]].
+Try setting <code>foldmethod=syntax</code>. Many syntax files define folding based on the language syntax, although you may need to enable it by [[VimTip1534|setting syntax file options]]. If a specific syntax file doesn't define folding, you can [[Syntax folding of Vim scripts|define your own]].
 Note that this particular fold method especially may define too many folds for your liking. You can change this using the {{help|prefix=no|'foldnestmax'}} option, by setting it to a value low enough for your liking.
@@ Line 77: / Line 60: @@
 ===Folding with markers===
-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 {{help|prefix=no|'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.
+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. 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 magic|modeline]], so that most Vim users will get your intended settings by default when they edit the file.
 ===Diff folding===
 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 {{help|prefix=no|'diffopt'}} option.
-If you want folding in diff/patch files, see [[Folding for diff files]] instead.
 ==Opening and closing folds==
@@ Line 112: / Line 91: @@
 In the first mapping for Space, <code>@=</code> refers to the expression register ({{help|1=@=}}). The following expression is evaluated when Enter is pressed (<code><CR></code>). The value of <code>foldlevel('.')</code> 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 <code>'za'</code> (toggle fold); otherwise it is <code>"\<Space>"</code>, which evaluates back to the default behaviour of the <Space> key (move forward by one character). {{help|expr1}}
-==Saving folds before closing vim==
+==Saving folds before closing the vim==
-Vim provides a good mechanism called <code>view</code>.  You can use it to save a fold. See [[VimTip991|Make views automatic]].  You may also want to use plugin {{script|id=4021|text=restore_view.vim}}.
+Vim provides a good mechanism called <code>view</code>.  You can use it to saving a fold. See [[VimTip991|Make views automatic]].  You may also want to use plugin {{script|id=4021|text=restore_view.vim}}.
 ==Commands over folds==