codekingpro/portable-devtools

1*fold.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		  VIM REFERENCE MANUAL	  by Bram Moolenaar5 6 7Folding						*Folding* *folding* *folds*8 9You can find an introduction on folding in chapter 28 of the user manual.10|usr_28.txt|11 121. Fold methods		|fold-methods|132. Fold commands	|fold-commands|143. Fold options		|fold-options|154. Behavior of folds	|fold-behavior|16 17{not available when compiled without the |+folding| feature}18 19==============================================================================201. Fold methods					*fold-methods*21 22The folding method can be set with the 'foldmethod' option.23 24When setting 'foldmethod' to a value other than "manual", all folds are25deleted and new ones created.  Switching to the "manual" method doesn't remove26the existing folds.  This can be used to first define the folds automatically27and then change them manually.28 29There are six methods to select folds:30	manual		manually define folds31	indent		more indent means a higher fold level32	expr		specify an expression to define folds33	syntax		folds defined by syntax highlighting34	diff		folds for unchanged text35	marker		folds defined by markers in the text36 37 38MANUAL						*fold-manual*39 40Use commands to manually define the fold regions.  This can also be used by a41script that parses text to find folds.42 43The level of a fold is only defined by its nesting.  To increase the fold44level of a fold for a range of lines, define a fold inside it that has the45same lines.46 47The manual folds are lost when you abandon the file.  To save the folds use48the |:mkview| command.  The view can be restored later with |:loadview|.49 50 51INDENT						*fold-indent*52 53The folds are automatically defined by the indent of the lines.54 55The foldlevel is computed from the indent of the line, divided by the56'shiftwidth' (rounded down).  A sequence of lines with the same or higher fold57level form a fold, with the lines with a higher level forming a nested fold.58 59The nesting of folds is limited with 'foldnestmax'.60 61Some lines are ignored and get the fold level of the line above or below it,62whichever is lower.  These are empty or white lines and lines starting63with a character in 'foldignore'.  White space is skipped before checking for64characters in 'foldignore'.  For C use "#" to ignore preprocessor lines.65 66When you want to ignore lines in another way, use the "expr" method.  The67|indent()| function can be used in 'foldexpr' to get the indent of a line.68 69 70EXPR						*fold-expr*71 72The folds are automatically defined by their foldlevel, like with the "indent"73method.  The value of the 'foldexpr' option is evaluated to get the foldlevel74of a line.  Examples:75This will create a fold for all consecutive lines that start with a tab: >76	:set foldexpr=getline(v:lnum)[0]==\"\\t\"77This will make a fold out of paragraphs separated by blank lines: >78	:set foldexpr=getline(v:lnum)=~'^\\s*$'&&getline(v:lnum+1)=~'\\S'?'<1':179This does the same: >80	:set foldexpr=getline(v:lnum-1)=~'^\\s*$'&&getline(v:lnum)=~'\\S'?'>1':181 82Note that backslashes must be used to escape characters that ":set" handles83differently (space, backslash, double quote, etc., see |option-backslash|).84 85The most efficient is to call a compiled function without arguments: >86	:set foldexpr=MyFoldLevel()87The function must use v:lnum.  See |expr-option-function|.88 89These are the conditions with which the expression is evaluated:90 91- The current buffer and window are set for the line.92- The variable "v:lnum" is set to the line number.93 94The result of foldexpr then determines the fold level as follows:95  value			meaning ~96  0			the line is not in a fold97  1, 2, ..		the line is in a fold with this level98  -1			the fold level is undefined, use the fold level of a99			line before or after this line, whichever is the100			lowest.101  "="			use fold level from the previous line102  "a1", "a2", ..	add one, two, .. to the fold level of the previous103			line, use the result for the current line104  "s1", "s2", ..	subtract one, two, .. from the fold level of the105			previous line, use the result for the next line106  "<1", "<2", ..	a fold with this level ends at this line107  ">1", ">2", ..	a fold with this level starts at this line108 109The result values "=", "s" and "a" are more expensive, please see110|fold-expr-slow|.111 112It is not required to mark the start (end) of a fold with ">1" ("<1"), a fold113will also start (end) when the fold level is higher (lower) than the fold114level of the previous line.115 116There must be no side effects from the expression.  The text in the buffer,117cursor position, the search patterns, options etc. must not be changed.118You can change and restore them if you are careful.119 120If there is some error in the expression, or the resulting value isn't121recognized, there is no error message and the fold level will be zero.122For debugging the 'debug' option can be set to "msg", the error messages will123be visible then.124 125If the 'foldexpr' expression starts with s: or |<SID>|, then it is replaced126with the script ID (|local-function|).  Examples: >127		set foldexpr=s:MyFoldExpr()128		set foldexpr=<SID>SomeFoldExpr()129<130An example of using "a1" and "s1": For a multi-line C comment, a line131containing "/*" would return "a1" to start a fold, and a line containing "*/"132would return "s1" to end the fold after that line: >133  if match(thisline, '/\*') >= 0134    return 'a1'135  elseif match(thisline, '\*/') >= 0136    return 's1'137  else138    return '='139  endif140However, this won't work for single line comments, strings, etc.141 142|foldlevel()| can be useful to compute a fold level relative to a previous143fold level.  But note that foldlevel() may return -1 if the level is not known144yet.  And it returns the level at the start of the line, while a fold might145end in that line.146 147It may happen that folds are not updated properly.  You can use |zx| or |zX|148to force updating folds.149 150MINIMIZING COMPUTATIONAL COST				*fold-expr-slow*151 152Due to its computational cost, this fold method can make Vim unresponsive,153especially when the fold level of all lines have to be initially computed.154Afterwards, after each change, Vim restricts the computation of foldlevels155to those lines whose fold level was affected by it (and reuses the known156foldlevels of all the others).157 158The fold expression should therefore strive to minimize the number of159dependent lines needed for the computation of a given line: For example, try160to avoid the "=", "a" and "s" return values, because these will require the161evaluation of the fold levels on previous lines until an independent fold162level is found.163 164If this proves difficult, the next best thing could be to cache all fold165levels in a buffer-local variable (b:foldlevels) that is only updated on166|b:changedtick|:167>168  vim9script169  def MyFoldFunc(): number170    if b:lasttick == b:changedtick171      return b:foldlevels[v:lnum - 1]172    endif173    b:lasttick = b:changedtick174    b:foldlevels = []175    # compute foldlevels ...176    return b:foldlevels[v:lnum - 1]177  enddef178  set foldexpr=s:MyFoldFunc()179<180In above example further speedup was gained by using a precompiled Vim9 script181function without arguments (that must still use v:lnum).  See182|expr-option-function|.183 184SYNTAX						*fold-syntax*185 186A fold is defined by syntax items that have the "fold" argument. |:syn-fold|187 188The fold level is defined by nesting folds.  The nesting of folds is limited189with 'foldnestmax'.190 191Be careful to specify proper syntax syncing.  If this is not done right, folds192may differ from the displayed highlighting.  This is especially relevant when193using patterns that match more than one line.  In case of doubt, try using194brute-force syncing: >195	:syn sync fromstart196 197 198DIFF						*fold-diff*199 200The folds are automatically defined for text that is not part of a change or201close to a change.202 203This method only works properly when the 'diff' option is set for the current204window and changes are being displayed.  Otherwise the whole buffer will be205one big fold.206 207The 'diffopt' option can be used to specify the context.  That is, the number208of lines between the fold and a change that are not included in the fold.  For209example, to use a context of 8 lines: >210	:set diffopt=filler,context:8211The default context is six lines.212 213When 'scrollbind' is also set, Vim will attempt to keep the same folds open in214other diff windows, so that the same text is visible.215 216 217MARKER						*fold-marker*218 219Markers in the text tell where folds start and end.  This allows you to220precisely specify the folds.  This will allow deleting and putting a fold,221without the risk of including the wrong lines.  The 'foldtext' option is222normally set such that the text before the marker shows up in the folded line.223This makes it possible to give a name to the fold.224 225Markers can have a level included, or can use matching pairs.  Including a226level is easier, you don't have to add end markers and avoid problems with227non-matching marker pairs.  Example: >228	/* global variables {{{1 */229	int varA, varB;230 231	/* functions {{{1 */232	/* funcA() {{{2 */233	void funcA() {}234 235	/* funcB() {{{2 */236	void funcB() {}237<							*{{{* *}}}*238A fold starts at a "{{{" marker.  The following number specifies the fold239level.  What happens depends on the difference between the current fold level240and the level given by the marker:2411. If a marker with the same fold level is encountered, the previous fold242   ends and another fold with the same level starts.2432. If a marker with a higher fold level is found, a nested fold is started.2443. If a marker with a lower fold level is found, all folds up to and including245   this level end and a fold with the specified level starts.246 247The number indicates the fold level.  A zero cannot be used (a marker with248level zero is ignored).  You can use "}}}" with a digit to indicate the level249of the fold that ends.  The fold level of the following line will be one less250than the indicated level.  Note that Vim doesn't look back to the level of the251matching marker (that would take too much time).  Example: >252 253	{{{1254	fold level here is 1255	{{{3256	fold level here is 3257	}}}3258	fold level here is 2259 260You can also use matching pairs of "{{{" and "}}}" markers to define folds.261Each "{{{" increases the fold level by one, each "}}}" decreases the fold262level by one.  Be careful to keep the markers matching!  Example: >263 264	{{{265	fold level here is 1266	{{{267	fold level here is 2268	}}}269	fold level here is 1270 271You can mix using markers with a number and without a number.  A useful way of272doing this is to use numbered markers for large folds, and unnumbered markers273locally in a function.  For example use level one folds for the sections of274your file like "structure definitions", "local variables" and "functions".275Use level 2 markers for each definition and function,  Use unnumbered markers276inside functions.  When you make changes in a function to split up folds, you277don't have to renumber the markers.278 279The markers can be set with the 'foldmarker' option.  It is recommended to280keep this at the default value of "{{{,}}}", so that files can be exchanged281between Vim users.  Only change it when it is required for the file (e.g., it282contains markers from another folding editor, or the default markers cause283trouble for the language of the file).284 285							*fold-create-marker*286"zf" can be used to create a fold defined by markers.  Vim will insert the287markers for you.  Vim will append the start and end marker, as specified with288'foldmarker'.  The markers are appended to the end of the line.289'commentstring' is used if it isn't empty.290This does not work properly when:291- The line already contains a marker with a level number.  Vim then doesn't292  know what to do.293- Folds nearby use a level number in their marker which gets in the way.294- The line is inside a comment, 'commentstring' isn't empty and nested295  comments don't work.  For example with C: adding /* {{{ */ inside a comment296  will truncate the existing comment.  Either put the marker before or after297  the comment, or add the marker manually.298Generally it's not a good idea to let Vim create markers when you already have299markers with a level number.300 301							*fold-delete-marker*302"zd" can be used to delete a fold defined by markers.  Vim will delete the303markers for you.  Vim will search for the start and end markers, as specified304with 'foldmarker', at the start and end of the fold.  When the text around the305marker matches with 'commentstring', that text is deleted as well.306This does not work properly when:307- A line contains more than one marker and one of them specifies a level.308  Only the first one is removed, without checking if this will have the309  desired effect of deleting the fold.310- The marker contains a level number and is used to start or end several folds311  at the same time.312 313==============================================================================3142. Fold commands				*fold-commands* *E490*315 316All folding commands start with "z".  Hint: the "z" looks like a folded piece317of paper, if you look at it from the side.318 319 320CREATING AND DELETING FOLDS ~321							*zf* *E350*322zf{motion}  or323{Visual}zf	Operator to create a fold.324		This only works when 'foldmethod' is "manual" or "marker".325		The new fold will be closed for the "manual" method.326		'foldenable' will be set.327		Also see |fold-create-marker|.328 329							*zF*330zF		Create a fold for [count] lines.  Works like "zf".331 332:{range}fo[ld]						*:fold* *:fo*333		Create a fold for the lines in {range}.  Works like "zf".334 335							*zd* *E351*336zd		Delete one fold at the cursor.  When the cursor is on a folded337		line, that fold is deleted.  Nested folds are moved one level338		up.  In Visual mode one level of all folds (partially) in the339		selected area are deleted.340		Careful: This easily deletes more folds than you expect and341		there is no undo for manual folding.342		This only works when 'foldmethod' is "manual" or "marker".343		Also see |fold-delete-marker|.344 345							*zD*346zD		Delete folds recursively at the cursor.  In Visual mode all347		folds (partially) in the selected area and all nested folds in348		them are deleted.349		This only works when 'foldmethod' is "manual" or "marker".350		Also see |fold-delete-marker|.351 352							*zE* *E352*353zE		Eliminate all folds in the window.354		This only works when 'foldmethod' is "manual" or "marker".355		Also see |fold-delete-marker|.356 357 358OPENING AND CLOSING FOLDS ~359 360A fold smaller than 'foldminlines' will always be displayed like it was open.361Therefore the commands below may work differently on small folds.362 363							*zo*364zo		Open one fold under the cursor.  When a count is given, that365		many folds deep will be opened.  In Visual mode one level of366		folds is opened for all lines in the selected area.367 368							*zO*369zO		Open all folds under the cursor recursively.  Folds that don't370		contain the cursor line are unchanged.371		In Visual mode it opens all folds that are in the selected372		area, also those that are only partly selected.373 374							*zc*375zc		Close one fold under the cursor.  When a count is given, that376		many folds deep are closed.  In Visual mode one level of folds377		is closed for all lines in the selected area.378		'foldenable' will be set.379 380							*zC*381zC		Close all folds under the cursor recursively.  Folds that382		don't contain the cursor line are unchanged.383		In Visual mode it closes all folds that are in the selected384		area, also those that are only partly selected.385		'foldenable' will be set.386 387							*za*388za		Summary: Toggle the fold under the cursor.389		When on a closed fold: open it.  When folds are nested, you390		may have to use "za" several times.  When a count is given,391		that many closed folds are opened.392		When on an open fold: close it and set 'foldenable'.  This393		will only close one level, since using "za" again will open394		the fold.  When a count is given that many folds will be395		closed (that's not the same as repeating "za" that many396		times).397 398							*zA*399zA		When on a closed fold: open it recursively.400		When on an open fold: close it recursively and set401		'foldenable'.402 403							*zv*404zv		View cursor line: Open just enough folds to make the line in405		which the cursor is located not folded.406 407							*zx*408zx		Update folds: Undo manually opened and closed folds: re-apply409		'foldlevel', then do "zv": View cursor line.410		Also forces recomputing folds.  This is useful when using411		'foldexpr' and the buffer is changed in a way that results in412		folds not to be updated properly.413 414							*zX*415zX		Undo manually opened and closed folds: re-apply 'foldlevel'.416		Also forces recomputing folds, like |zx|.417 418							*zm*419zm		Fold more: Subtract |v:count1| from 'foldlevel'.  If420		'foldlevel' was already zero nothing happens.421		'foldenable' will be set.422 423							*zM*424zM		Close all folds: set 'foldlevel' to 0.425		'foldenable' will be set.426 427							*zr*428zr		Reduce folding: Add |v:count1| to 'foldlevel'.429 430							*zR*431zR		Open all folds.  This sets 'foldlevel' to highest fold level.432 433							*:foldo* *:foldopen*434:{range}foldo[pen][!]435		Open folds in {range}.  When [!] is added all folds are436		opened.  Useful to see all the text in {range}.  Without [!]437		one level of folds is opened.438 439							*:foldc* *:foldclose*440:{range}foldc[lose][!]441		Close folds in {range}.  When [!] is added all folds are442		closed.  Useful to hide all the text in {range}.  Without [!]443		one level of folds is closed.444 445							*zn*446zn		Fold none: reset 'foldenable'.  All folds will be open.447 448							*zN*449zN		Fold normal: set 'foldenable'.  All folds will be as they450		were before.451 452							*zi*453zi		Invert 'foldenable'.454 455 456MOVING OVER FOLDS ~457							*[z*458[z		Move to the start of the current open fold.  If already at the459		start, move to the start of the fold that contains it.  If460		there is no containing fold, the command fails.461		When a count is used, repeats the command [count] times.462 463							*]z*464]z		Move to the end of the current open fold.  If already at the465		end, move to the end of the fold that contains it.  If there466		is no containing fold, the command fails.467		When a count is used, repeats the command [count] times.468 469							*zj*470zj		Move downwards to the start of the next fold.  A closed fold471		is counted as one fold.472		When a count is used, repeats the command [count] times.473		This command can be used after an |operator|.474 475							*zk*476zk		Move upwards to the end of the previous fold.  A closed fold477		is counted as one fold.478		When a count is used, repeats the command [count] times.479		This command can be used after an |operator|.480 481 482EXECUTING COMMANDS ON FOLDS ~483 484:[range]foldd[oopen] {cmd}		*:foldd* *:folddo* *:folddoopen*485		Execute {cmd} on all lines that are not in a closed fold.486		When [range] is given, only these lines are used.487		Each time {cmd} is executed the cursor is positioned on the488		line it is executed for.489		This works like the ":global" command: First all lines that490		are not in a closed fold are marked.  Then the {cmd} is491		executed for all marked lines.  Thus when {cmd} changes the492		folds, this has no influence on where it is executed (except493		when lines are deleted, of course).494		Example: >495			:folddoopen s/end/loop_end/ge496<		Note the use of the "e" flag to avoid getting an error message497		where "end" doesn't match.498 499:[range]folddoc[losed] {cmd}			*:folddoc* *:folddoclosed*500		Execute {cmd} on all lines that are in a closed fold.501		Otherwise like ":folddoopen".502 503==============================================================================5043. Fold options					*fold-options*505 506COLORS							*fold-colors*507 508The colors of a closed fold are set with the Folded group |hl-Folded|.  The509colors of the fold column are set with the FoldColumn group |hl-FoldColumn|.510Example to set the colors: >511 512	:highlight Folded guibg=grey guifg=blue513	:highlight FoldColumn guibg=darkgrey guifg=white514 515 516FOLDLEVEL						*fold-foldlevel*517 518'foldlevel' is a number option: The higher the more folded regions are open.519When 'foldlevel' is 0, all folds are closed.520When 'foldlevel' is positive, some folds are closed.521When 'foldlevel' is very high, all folds are open.522'foldlevel' is applied when it is changed.  After that manually folds can be523opened and closed.524When increased, folds above the new level are opened.  No manually opened525folds will be closed.526When decreased, folds above the new level are closed.  No manually closed527folds will be opened.528 529 530FOLDTEXT						*fold-foldtext*531 532'foldtext' is a string option that specifies an expression.  This expression533is evaluated to obtain the text displayed for a closed fold.  Example: >534 535    :set foldtext=v:folddashes.substitute(getline(v:foldstart),'/\\*\\\|\\*/\\\|{{{\\d\\=','','g')536 537This shows the first line of the fold, with "/*", "*/" and "{{{" removed.538Note the use of backslashes to avoid some characters to be interpreted by the539":set" command.  It is much simpler to define a function and call it: >540 541    :set foldtext=MyFoldText()542    :function MyFoldText()543    :  let line = getline(v:foldstart)544    :  let sub = substitute(line, '/\*\|\*/\|{{{\d\=', '', 'g')545    :  return v:folddashes .. sub546    :endfunction547 548The advantage of using a function call without arguments is that it is faster,549see |expr-option-function|.550 551Evaluating 'foldtext' is done in the |sandbox|.  The current window is set to552the window that displays the line.  The context is set to the script where the553option was last set.554 555Errors are ignored.  For debugging set the 'debug' option to "throw".556 557The default value is |foldtext()|.  This returns a reasonable text for most558types of folding.  If you don't like it, you can specify your own 'foldtext'559expression.  It can use these special Vim variables:560	v:foldstart	line number of first line in the fold561	v:foldend	line number of last line in the fold562	v:folddashes	a string that contains dashes to represent the563			foldlevel.564	v:foldlevel	the foldlevel of the fold565 566In the result a TAB is replaced with a space and unprintable characters are567made into printable characters.568 569The resulting line is truncated to fit in the window, it never wraps.570When there is room after the text, it is filled with the character specified571by 'fillchars'.572 573If the 'foldtext' expression starts with s: or |<SID>|, then it is replaced574with the script ID (|local-function|).  Examples: >575		set foldtext=s:MyFoldText()576		set foldtext=<SID>SomeFoldText()577<578Note that backslashes need to be used for characters that the ":set" command579handles differently: Space, backslash and double-quote. |option-backslash|580 581 582FOLDCOLUMN						*fold-foldcolumn*583 584'foldcolumn' is a number, which sets the width for a column on the side of the585window to indicate folds.  When it is zero, there is no foldcolumn.  A normal586value is 4 or 5.  The minimal useful value is 2, although 1 still provides587some information.  The maximum is 12.588 589An open fold is indicated with a column that has a '-' at the top and '|'590characters below it.  This column stops where the open fold stops.  When folds591nest, the nested fold is one character right of the fold it's contained in.592 593A closed fold is indicated with a '+'.594 595These characters can be changed with the 'fillchars' option.596 597Where the fold column is too narrow to display all nested folds, digits are598shown to indicate the nesting level.  To override this behavior you can use599the "foldinner" character of the 'fillchars' option.600 601The mouse can also be used to open and close folds by clicking in the602fold column:603- Click on a '+' to open the closed fold at this row.604- Click on any other non-blank character to close the open fold at this row.605 606 607OTHER OPTIONS608 609'foldenable'  'fen':	Open all folds while not set.610'foldexpr'    'fde':	Expression used for "expr" folding.611'foldignore'  'fdi':	Characters used for "indent" folding.612'foldmarker'  'fmr':	Defined markers used for "marker" folding.613'foldmethod'  'fdm':	Name of the current folding method.614'foldminlines' 'fml':	Minimum number of screen lines for a fold to be615			displayed closed.616'foldnestmax' 'fdn':	Maximum nesting for "indent" and "syntax" folding.617'foldopen'    'fdo':	Which kinds of commands open closed folds.618'foldclose'   'fcl':	When the folds not under the cursor are closed.619 620==============================================================================6214. Behavior of folds					*fold-behavior*622 623When moving the cursor upwards or downwards and when scrolling, the cursor624will move to the first line of a sequence of folded lines.  When the cursor is625already on a folded line, it moves to the next unfolded line or the next626closed fold.627 628While the cursor is on folded lines, the cursor is always displayed in the629first column.  The ruler does show the actual cursor position, but since the630line is folded, it cannot be displayed there.631 632Many movement commands handle a sequence of folded lines like an empty line.633For example, the "w" command stops once in the first column.634 635When starting a search in a closed fold it will not find a match in the636current fold.  It's like a forward search always starts from the end of the637closed fold, while a backwards search starts from the start of the closed638fold.639 640When in Insert mode, the cursor line is never folded.  That allows you to see641what you type!642 643When using an operator, a closed fold is included as a whole.  Thus "dl"644deletes the whole closed fold under the cursor.645 646For Ex commands that operate on buffer lines, the range is adjusted to always647start at the first line of a closed fold and end at the last line of a closed648fold.  Thus, this command: >649	:s/foo/bar/g650when used with the cursor on a closed fold, will replace "foo" with "bar" in651all lines of the fold.652This does not happen for |:folddoopen| and |:folddoclosed|.653 654Note that for some Ex commands like |:source| the range is only adjusted when655using a two line specifiers [range].656 657When editing a buffer that has been edited before, the last used folding658settings are used again.  For manual folding the defined folds are restored.659For all folding methods the manually opened and closed folds are restored.660If this buffer has been edited in this window, the values from back then are661used.  Otherwise the values from the window where the buffer was edited last662are used.663 664==============================================================================665 vim:tw=78:ts=8:noet:ft=help:norl:666