codekingpro/portable-devtools

1*usr_28.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		     VIM USER MANUAL	by Bram Moolenaar5 6 7				   Folding8 9 10Structured text can be separated in sections.  And sections in sub-sections.11Folding allows you to display a section as one line, providing an overview.12This chapter explains the different ways this can be done.13 14|28.1|	What is folding?15|28.2|	Manual folding16|28.3|	Working with folds17|28.4|	Saving and restoring folds18|28.5|	Folding by indent19|28.6|	Folding with markers20|28.7|	Folding by syntax21|28.8|	Folding by expression22|28.9|	Folding unchanged lines23|28.10|	Which fold method to use?24 25     Next chapter: |usr_29.txt|  Moving through programs26 Previous chapter: |usr_27.txt|  Search commands and patterns27Table of contents: |usr_toc.txt|28 29==============================================================================30*28.1*	What is folding?31 32Folding is used to show a range of lines in the buffer as a single line on the33screen.  Like a piece of paper which is folded to make it shorter:34 35	+------------------------+36	| line 1		 |37	| line 2		 |38	| line 3		 |39	|_______________________ |40	\			 \41	 \________________________\42	 / folded lines		  /43	/________________________/44	| line 12		 |45	| line 13		 |46	| line 14		 |47	+------------------------+48 49The text is still in the buffer, unchanged.  Only the way lines are displayed50is affected by folding.51 52The advantage of folding is that you can get a better overview of the53structure of text, by folding lines of a section and replacing it with a line54that indicates that there is a section.55 56==============================================================================57*28.2*	Manual folding58 59Try it out: Position the cursor in a paragraph and type: >60 61	zfap62 63You will see that the paragraph is replaced by a highlighted line.  You have64created a fold.  |zf| is an operator and |ap| a text object selection.  You65can use the |zf| operator with any movement command to create a fold for the66text that it moved over.  |zf| also works in Visual mode.67 68To view the text again, open the fold by typing: >69 70	zo71 72And you can close the fold again with: >73 74	zc75 76All the folding commands start with "z".  With some fantasy, this looks like a77folded piece of paper, seen from the side.  The letter after the "z" has a78mnemonic meaning to make it easier to remember the commands:79 80	zf	F-old creation81	zo	O-pen a fold82	zc	C-lose a fold83 84Folds can be nested: A region of text that contains folds can be folded85again.  For example, you can fold each paragraph in this section, and then86fold all the sections in this chapter.  Try it out.  You will notice that87opening the fold for the whole chapter will restore the nested folds as they88were, some may be open and some may be closed.89 90Suppose you have created several folds, and now want to view all the text.91You could go to each fold and type "zo".  To do this faster, use this command: >92 93	zr94 95This will R-educe the folding.  The opposite is: >96 97	zm98 99This folds M-ore.  You can repeat "zr" and "zm" to open and close nested folds100of several levels.101 102If you have nested several levels deep, you can open all of them with: >103 104	zR105 106This R-educes folds until there are none left.  And you can close all folds107with: >108 109	zM110 111This folds M-ore and M-ore.112 113You can quickly disable the folding with the |zn| command.  Then |zN| brings114back the folding as it was.  |zi| toggles between the two.  This is a useful115way of working:116- create folds to get overview on your file117- move around to where you want to do your work118- do |zi| to look at the text and edit it119- do |zi| again to go back to moving around120 121More about manual folding in the reference manual: |fold-manual|122 123==============================================================================124*28.3*	Working with folds125 126When some folds are closed, movement commands like "j" and "k" move over a127fold like it was a single, empty line.  This allows you to quickly move around128over folded text.129 130You can yank, delete and put folds as if it was a single line.  This is very131useful if you want to reorder functions in a program.  First make sure that132each fold contains a whole function (or a bit less) by selecting the right133'foldmethod'.  Then delete the function with "dd", move the cursor and put it134with "p".  If some lines of the function are above or below the fold, you can135use Visual selection:136- put the cursor on the first line to be moved137- hit "V" to start Visual mode138- put the cursor on the last line to be moved139- hit "d" to delete the selected lines.140- move the cursor to the new position and "p"ut the lines there.141 142It is sometimes difficult to see or remember where a fold is located, thus143where a |zo| command would actually work.  To see the defined folds: >144 145	:set foldcolumn=4146 147This will show a small column on the left of the window to indicate folds.148A "+" is shown for a closed fold.  A "-" is shown at the start of each open149fold and "|" at following lines of the fold.150 151You can use the mouse to open a fold by clicking on the "+" in the foldcolumn.152Clicking on the "-" or a "|" below it will close an open fold.153 154To open all folds at the cursor line use |zO|.155To close all folds at the cursor line use |zC|.156To delete a fold at the cursor line use |zd|.157To delete all folds at the cursor line use |zD|.158 159When in Insert mode, the fold at the cursor line is never closed.  That allows160you to see what you type!161 162Folds are opened automatically when jumping around or moving the cursor left163or right.  For example, the "0" command opens the fold under the cursor164(if 'foldopen' contains "hor", which is the default).  The 'foldopen' option165can be changed to open folds for specific commands.  If you want the line166under the cursor always to be open, do this: >167 168	:set foldopen=all169 170Warning: You won't be able to move onto a closed fold then.  You might want to171use this only temporarily and then set it back to the default: >172 173	:set foldopen&174 175You can make folds close automatically when you move out of it: >176 177	:set foldclose=all178 179This will re-apply 'foldlevel' to all folds that don't contain the cursor.180You have to try it out if you like how this feels.  Use |zm| to fold more and181|zr| to fold less (reduce folds).182 183The folding is local to the window.  This allows you to open two windows on184the same buffer, one with folds and one without folds.  Or one with all folds185closed and one with all folds open.186 187==============================================================================188*28.4*	Saving and restoring folds189 190When you abandon a file (starting to edit another one), the state of the folds191is lost.  If you come back to the same file later, all manually opened and192closed folds are back to their default.  When folds have been created193manually, all folds are gone!  To save the folds use the |:mkview| command: >194 195	:mkview196 197This will store the settings and other things that influence the view on the198file.  You can change what is stored with the 'viewoptions' option.199When you come back to the same file later, you can load the view again: >200 201	:loadview202 203You can store up to ten views on one file.  For example, to save the current204setup as the third view and load the second view: >205 206	:mkview 3207	:loadview 2208 209Note that when you insert or delete lines the views might become invalid.210Also check out the 'viewdir' option, which specifies where the views are211stored.  You might want to delete old views now and then.212 213==============================================================================214*28.5*	Folding by indent215 216Defining folds with |zf| is a lot of work.  If your text is structured by217giving lower level items a larger indent, you can use the indent folding218method.  This will create folds for every sequence of lines with the same219indent.  Lines with a larger indent will become nested folds.  This works well220with many programming languages.221 222Try this by setting the 'foldmethod' option: >223 224	:set foldmethod=indent225 226Then you can use the |zm| and |zr| commands to fold more and reduce folding.227It's easy to see on this example text:228 229This line is not indented230	This line is indented once231		This line is indented twice232		This line is indented twice233	This line is indented once234This line is not indented235	This line is indented once236	This line is indented once237 238Note that the relation between the amount of indent and the fold depth depends239on the 'shiftwidth' option.  Each 'shiftwidth' worth of indent adds one to the240depth of the fold.  This is called a fold level.241 242When you use the |zr| and |zm| commands you actually increase or decrease the243'foldlevel' option.  You could also set it directly: >244 245	:set foldlevel=3246 247This means that all folds with three times a 'shiftwidth' indent or more will248be closed.  The lower the foldlevel, the more folds will be closed.  When249'foldlevel' is zero, all folds are closed.  |zM| does set 'foldlevel' to zero.250The opposite command |zR| sets 'foldlevel' to the deepest fold level that is251present in the file.252 253Thus there are two ways to open and close the folds:254(A) By setting the fold level.255    This gives a very quick way of "zooming out" to view the structure of the256    text, move the cursor, and "zoom in" on the text again.257 258(B) By using |zo| and |zc| commands to open or close specific folds.259    This allows opening only those folds that you want to be open, while other260    folds remain closed.261 262This can be combined: You can first close most folds by using |zm| a few times263and then open a specific fold with |zo|.  Or open all folds with |zR| and264then close specific folds with |zc|.265 266But you cannot manually define folds when 'foldmethod' is "indent", as that267would conflict with the relation between the indent and the fold level.268 269More about folding by indent in the reference manual: |fold-indent|270 271==============================================================================272*28.6*	Folding with markers273 274Markers in the text are used to specify the start and end of a fold region.275This gives precise control over which lines are included in a fold.  The276disadvantage is that the text needs to be modified.277 278Try it: >279 280	:set foldmethod=marker281 282Example text, as it could appear in a C program:283 284	/* foobar () {{{ */285	int foobar()286	{287		/* return a value {{{ */288		return 42;289		/* }}} */290	}291	/* }}} */292 293Notice that the folded line will display the text before the marker.  This is294very useful to tell what the fold contains.295 296It's quite annoying when the markers don't pair up correctly after moving some297lines around.  This can be avoided by using numbered markers.  Example:298 299	/* global variables {{{1 */300	int varA, varB;301 302	/* functions {{{1 */303	/* funcA() {{{2 */304	void funcA() {}305 306	/* funcB() {{{2 */307	void funcB() {}308	/* }}}1 */309 310At every numbered marker a fold at the specified level begins.  This will make311any fold at a higher level stop here.  You can just use numbered start markers312to define all folds.  Only when you want to explicitly stop a fold before313another starts you need to add an end marker.314 315More about folding with markers in the reference manual: |fold-marker|316 317==============================================================================318*28.7*	Folding by syntax319 320For each language Vim uses a different syntax file.  This defines the colors321for various items in the file.  If you are reading this in Vim, in a terminal322that supports colors, the colors you see are made with the "help" syntax file.323   In the syntax files it is possible to add syntax items that have the "fold"324argument.  These define a fold region.  This requires writing a syntax file325and adding these items in it.  That's not so easy to do.  But once it's done,326all folding happens automatically.327   Here we'll assume you are using an existing syntax file.  Then there is328nothing more to explain.  You can open and close folds as explained above.329The folds will be created and deleted automatically when you edit the file.330 331More about folding by syntax in the reference manual: |fold-syntax|332 333==============================================================================334*28.8*	Folding by expression335 336This is similar to folding by indent, but instead of using the indent of a337line a user function is called to compute the fold level of a line.  You can338use this for text where something in the text indicates which lines belong339together.  An example is an e-mail message where the quoted text is indicated340by a ">" before the line.  To fold these quotes use this: >341 342	:set foldmethod=expr343	:set foldexpr=strlen(substitute(substitute(getline(v:lnum),'\\s','',\"g\"),'[^>].*','',''))344 345You can try it out on this text:346 347> quoted text he wrote348> quoted text he wrote349> > double quoted text I wrote350> > double quoted text I wrote351 352Explanation for the 'foldexpr' used in the example (inside out):353   getline(v:lnum)			gets the current line354   substitute(...,'\\s','','g')		removes all white space from the line355   substitute(...,'[^>].*','','')	removes everything after leading '>'s356   strlen(...)				counts the length of the string, which357					is the number of '>'s found358 359Note that a backslash must be inserted before every space, double quote and360backslash for the ":set" command.  If this confuses you, do >361 362	:set foldexpr363 364to check the actual resulting value.  To correct a complicated expression, use365the command-line completion: >366 367	:set foldexpr=<Tab>368 369Where <Tab> is a real Tab.  Vim will fill in the previous value, which you can370then edit.371 372When the expression gets more complicated you should put it in a function and373set 'foldexpr' to call that function.374 375More about folding by expression in the reference manual: |fold-expr|376 377==============================================================================378*28.9*	Folding unchanged lines379 380This is useful when you set the 'diff' option in the same window.  The381|vimdiff| command does this for you.  Example: >382 383	:setlocal diff foldmethod=diff scrollbind nowrap foldlevel=1384 385Do this in every window that shows a different version of the same file.  You386will clearly see the differences between the files, while the text that didn't387change is folded.388 389For more details see |fold-diff|.390 391==============================================================================392*28.10* Which fold method to use?393 394All these possibilities make you wonder which method you should choose.395Unfortunately, there is no golden rule.  Here are some hints.396 397If there is a syntax file with folding for the language you are editing, that398is probably the best choice.  If there isn't one, you might try to write it.399This requires a good knowledge of search patterns.  It's not easy, but when400it's working you will not have to define folds manually.401 402Typing commands to manually fold regions can be used for unstructured text.403Then use the |:mkview| command to save and restore your folds.404 405The marker method requires you to change the file.  If you are sharing the406files with other people or you have to meet company standards, you might not407be allowed to add them.408   The main advantage of markers is that you can put them exactly where you409want them.  That avoids that a few lines are missed when you cut and paste410folds.  And you can add a comment about what is contained in the fold.411 412Folding by indent is something that works in many files, but not always very413well.  Use it when you can't use one of the other methods.  However, it is414very useful for outlining.  Then you specifically use one 'shiftwidth' for415each nesting level.416 417Folding with expressions can make folds in almost any structured text.  It is418quite simple to specify, especially if the start and end of a fold can easily419be recognized.420   If you use the "expr" method to define folds, but they are not exactly how421you want them, you could switch to the "manual" method.  This will not remove422the defined folds.  Then you can delete or add folds manually.423 424==============================================================================425 426Next chapter: |usr_29.txt|  Moving through programs427 428Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl:429