1*usr_28.txt* For Vim version 7.3. Last change: 2008 Jun 14 2 3 VIM USER MANUAL - by Bram Moolenaar 4 5 Folding 6 7 8Structured text can be separated in sections. And sections in sub-sections. 9Folding allows you to display a section as one line, providing an overview. 10This chapter explains the different ways this can be done. 11 12|28.1| What is folding? 13|28.2| Manual folding 14|28.3| Working with folds 15|28.4| Saving and restoring folds 16|28.5| Folding by indent 17|28.6| Folding with markers 18|28.7| Folding by syntax 19|28.8| Folding by expression 20|28.9| Folding unchanged lines 21|28.10| Which fold method to use? 22 23 Next chapter: |usr_29.txt| Moving through programs 24 Previous chapter: |usr_27.txt| Search commands and patterns 25Table of contents: |usr_toc.txt| 26 27============================================================================== 28*28.1* What is folding? 29 30Folding is used to show a range of lines in the buffer as a single line on the 31screen. Like a piece of paper which is folded to make it shorter: 32 33 +------------------------+ 34 | line 1 | 35 | line 2 | 36 | line 3 | 37 |_______________________ | 38 \ \ 39 \________________________\ 40 / folded lines / 41 /________________________/ 42 | line 12 | 43 | line 13 | 44 | line 14 | 45 +------------------------+ 46 47The text is still in the buffer, unchanged. Only the way lines are displayed 48is affected by folding. 49 50The advantage of folding is that you can get a better overview of the 51structure of text, by folding lines of a section and replacing it with a line 52that indicates that there is a section. 53 54============================================================================== 55*28.2* Manual folding 56 57Try it out: Position the cursor in a paragraph and type: > 58 59 zfap 60 61You will see that the paragraph is replaced by a highlighted line. You have 62created a fold. |zf| is an operator and |ap| a text object selection. You 63can use the |zf| operator with any movement command to create a fold for the 64text that it moved over. |zf| also works in Visual mode. 65 66To view the text again, open the fold by typing: > 67 68 zo 69 70And you can close the fold again with: > 71 72 zc 73 74All the folding commands start with "z". With some fantasy, this looks like a 75folded piece of paper, seen from the side. The letter after the "z" has a 76mnemonic meaning to make it easier to remember the commands: 77 78 zf F-old creation 79 zo O-pen a fold 80 zc C-lose a fold 81 82Folds can be nested: A region of text that contains folds can be folded 83again. For example, you can fold each paragraph in this section, and then 84fold all the sections in this chapter. Try it out. You will notice that 85opening the fold for the whole chapter will restore the nested folds as they 86were, some may be open and some may be closed. 87 88Suppose you have created several folds, and now want to view all the text. 89You could go to each fold and type "zo". To do this faster, use this command: > 90 91 zr 92 93This will R-educe the folding. The opposite is: > 94 95 zm 96 97This folds M-ore. You can repeat "zr" and "zm" to open and close nested folds 98of several levels. 99 100If you have nested several levels deep, you can open all of them with: > 101 102 zR 103 104This R-educes folds until there are none left. And you can close all folds 105with: > 106 107 zM 108 109This folds M-ore and M-ore. 110 111You can quickly disable the folding with the |zn| command. Then |zN| brings 112back the folding as it was. |zi| toggles between the two. This is a useful 113way of working: 114- create folds to get overview on your file 115- move around to where you want to do your work 116- do |zi| to look at the text and edit it 117- do |zi| again to go back to moving around 118 119More about manual folding in the reference manual: |fold-manual| 120 121============================================================================== 122*28.3* Working with folds 123 124When some folds are closed, movement commands like "j" and "k" move over a 125fold like it was a single, empty line. This allows you to quickly move around 126over folded text. 127 128You can yank, delete and put folds as if it was a single line. This is very 129useful if you want to reorder functions in a program. First make sure that 130each fold contains a whole function (or a bit less) by selecting the right 131'foldmethod'. Then delete the function with "dd", move the cursor and put it 132with "p". If some lines of the function are above or below the fold, you can 133use Visual selection: 134- put the cursor on the first line to be moved 135- hit "V" to start Visual mode 136- put the cursor on the last line to be moved 137- hit "d" to delete the selected lines. 138- move the cursor to the new position and "p"ut the lines there. 139 140It is sometimes difficult to see or remember where a fold is located, thus 141where a |zo| command would actually work. To see the defined folds: > 142 143 :set foldcolumn=4 144 145This will show a small column on the left of the window to indicate folds. 146A "+" is shown for a closed fold. A "-" is shown at the start of each open 147fold and "|" at following lines of the fold. 148 149You can use the mouse to open a fold by clicking on the "+" in the foldcolumn. 150Clicking on the "-" or a "|" below it will close an open fold. 151 152To open all folds at the cursor line use |zO|. 153To close all folds at the cursor line use |zC|. 154To delete a fold at the cursor line use |zd|. 155To delete all folds at the cursor line use |zD|. 156 157When in Insert mode, the fold at the cursor line is never closed. That allows 158you to see what you type! 159 160Folds are opened automatically when jumping around or moving the cursor left 161or right. For example, the "0" command opens the fold under the cursor 162(if 'foldopen' contains "hor", which is the default). The 'foldopen' option 163can be changed to open folds for specific commands. If you want the line 164under the cursor always to be open, do this: > 165 166 :set foldopen=all 167 168Warning: You won't be able to move onto a closed fold then. You might want to 169use this only temporarily and then set it back to the default: > 170 171 :set foldopen& 172 173You can make folds close automatically when you move out of it: > 174 175 :set foldclose=all 176 177This will re-apply 'foldlevel' to all folds that don't contain the cursor. 178You have to try it out if you like how this feels. Use |zm| to fold more and 179|zr| to fold less (reduce folds). 180 181The folding is local to the window. This allows you to open two windows on 182the same buffer, one with folds and one without folds. Or one with all folds 183closed and one with all folds open. 184 185============================================================================== 186*28.4* Saving and restoring folds 187 188When you abandon a file (starting to edit another one), the state of the folds 189is lost. If you come back to the same file later, all manually opened and 190closed folds are back to their default. When folds have been created 191manually, all folds are gone! To save the folds use the |:mkview| command: > 192 193 :mkview 194 195This will store the settings and other things that influence the view on the 196file. You can change what is stored with the 'viewoptions' option. 197When you come back to the same file later, you can load the view again: > 198 199 :loadview 200 201You can store up to ten views on one file. For example, to save the current 202setup as the third view and load the second view: > 203 204 :mkview 3 205 :loadview 2 206 207Note that when you insert or delete lines the views might become invalid. 208Also check out the 'viewdir' option, which specifies where the views are 209stored. You might want to delete old views now and then. 210 211============================================================================== 212*28.5* Folding by indent 213 214Defining folds with |zf| is a lot of work. If your text is structured by 215giving lower level items a larger indent, you can use the indent folding 216method. This will create folds for every sequence of lines with the same 217indent. Lines with a larger indent will become nested folds. This works well 218with many programming languages. 219 220Try this by setting the 'foldmethod' option: > 221 222 :set foldmethod=indent 223 224Then you can use the |zm| and |zr| commands to fold more and reduce folding. 225It's easy to see on this example text: 226 227This line is not indented 228 This line is indented once 229 This line is indented twice 230 This line is indented twice 231 This line is indented once 232This line is not indented 233 This line is indented once 234 This line is indented once 235 236Note that the relation between the amount of indent and the fold depth depends 237on the 'shiftwidth' option. Each 'shiftwidth' worth of indent adds one to the 238depth of the fold. This is called a fold level. 239 240When you use the |zr| and |zm| commands you actually increase or decrease the 241'foldlevel' option. You could also set it directly: > 242 243 :set foldlevel=3 244 245This means that all folds with three times a 'shiftwidth' indent or more will 246be closed. The lower the foldlevel, the more folds will be closed. When 247'foldlevel' is zero, all folds are closed. |zM| does set 'foldlevel' to zero. 248The opposite command |zR| sets 'foldlevel' to the deepest fold level that is 249present in the file. 250 251Thus there are two ways to open and close the folds: 252(A) By setting the fold level. 253 This gives a very quick way of "zooming out" to view the structure of the 254 text, move the cursor, and "zoom in" on the text again. 255 256(B) By using |zo| and |zc| commands to open or close specific folds. 257 This allows opening only those folds that you want to be open, while other 258 folds remain closed. 259 260This can be combined: You can first close most folds by using |zm| a few times 261and then open a specific fold with |zo|. Or open all folds with |zR| and 262then close specific folds with |zc|. 263 264But you cannot manually define folds when 'foldmethod' is "indent", as that 265would conflict with the relation between the indent and the fold level. 266 267More about folding by indent in the reference manual: |fold-indent| 268 269============================================================================== 270*28.6* Folding with markers 271 272Markers in the text are used to specify the start and end of a fold region. 273This gives precise control over which lines are included in a fold. The 274disadvantage is that the text needs to be modified. 275 276Try it: > 277 278 :set foldmethod=marker 279 280Example text, as it could appear in a C program: 281 282 /* foobar () {{{ */ 283 int foobar() 284 { 285 /* return a value {{{ */ 286 return 42; 287 /* }}} */ 288 } 289 /* }}} */ 290 291Notice that the folded line will display the text before the marker. This is 292very useful to tell what the fold contains. 293 294It's quite annoying when the markers don't pair up correctly after moving some 295lines around. This can be avoided by using numbered markers. Example: 296 297 /* global variables {{{1 */ 298 int varA, varB; 299 300 /* functions {{{1 */ 301 /* funcA() {{{2 */ 302 void funcA() {} 303 304 /* funcB() {{{2 */ 305 void funcB() {} 306 /* }}}1 */ 307 308At every numbered marker a fold at the specified level begins. This will make 309any fold at a higher level stop here. You can just use numbered start markers 310to define all folds. Only when you want to explicitly stop a fold before 311another starts you need to add an end marker. 312 313More about folding with markers in the reference manual: |fold-marker| 314 315============================================================================== 316*28.7* Folding by syntax 317 318For each language Vim uses a different syntax file. This defines the colors 319for various items in the file. If you are reading this in Vim, in a terminal 320that supports colors, the colors you see are made with the "help" syntax file. 321 In the syntax files it is possible to add syntax items that have the "fold" 322argument. These define a fold region. This requires writing a syntax file 323and adding these items in it. That's not so easy to do. But once it's done, 324all folding happens automatically. 325 Here we'll assume you are using an existing syntax file. Then there is 326nothing more to explain. You can open and close folds as explained above. 327The folds will be created and deleted automatically when you edit the file. 328 329More about folding by syntax in the reference manual: |fold-syntax| 330 331============================================================================== 332*28.8* Folding by expression 333 334This is similar to folding by indent, but instead of using the indent of a 335line a user function is called to compute the fold level of a line. You can 336use this for text where something in the text indicates which lines belong 337together. An example is an e-mail message where the quoted text is indicated 338by a ">" before the line. To fold these quotes use this: > 339 340 :set foldmethod=expr 341 :set foldexpr=strlen(substitute(substitute(getline(v:lnum),'\\s','',\"g\"),'[^>].*','','')) 342 343You can try it out on this text: 344 345> quoted text he wrote 346> quoted text he wrote 347> > double quoted text I wrote 348> > double quoted text I wrote 349 350Explanation for the 'foldexpr' used in the example (inside out): 351 getline(v:lnum) gets the current line 352 substitute(...,'\\s','','g') removes all white space from the line 353 substitute(...,'[^>].*','','') removes everything after leading '>'s 354 strlen(...) counts the length of the string, which 355 is the number of '>'s found 356 357Note that a backslash must be inserted before every space, double quote and 358backslash for the ":set" command. If this confuses you, do > 359 360 :set foldexpr 361 362to check the actual resulting value. To correct a complicated expression, use 363the command-line completion: > 364 365 :set foldexpr=<Tab> 366 367Where <Tab> is a real Tab. Vim will fill in the previous value, which you can 368then edit. 369 370When the expression gets more complicated you should put it in a function and 371set 'foldexpr' to call that function. 372 373More about folding by expression in the reference manual: |fold-expr| 374 375============================================================================== 376*28.9* Folding unchanged lines 377 378This is useful when you set the 'diff' option in the same window. The 379|vimdiff| command does this for you. Example: > 380 381 :setlocal diff foldmethod=diff scrollbind nowrap foldlevel=1 382 383Do this in every window that shows a different version of the same file. You 384will clearly see the differences between the files, while the text that didn't 385change is folded. 386 387For more details see |fold-diff|. 388 389============================================================================== 390*28.10* Which fold method to use? 391 392All these possibilities make you wonder which method you should choose. 393Unfortunately, there is no golden rule. Here are some hints. 394 395If there is a syntax file with folding for the language you are editing, that 396is probably the best choice. If there isn't one, you might try to write it. 397This requires a good knowledge of search patterns. It's not easy, but when 398it's working you will not have to define folds manually. 399 400Typing commands to manually fold regions can be used for unstructured text. 401Then use the |:mkview| command to save and restore your folds. 402 403The marker method requires you to change the file. If you are sharing the 404files with other people or you have to meet company standards, you might not 405be allowed to add them. 406 The main advantage of markers is that you can put them exactly where you 407want them. That avoids that a few lines are missed when you cut and paste 408folds. And you can add a comment about what is contained in the fold. 409 410Folding by indent is something that works in many files, but not always very 411well. Use it when you can't use one of the other methods. However, it is 412very useful for outlining. Then you specifically use one 'shiftwidth' for 413each nesting level. 414 415Folding with expressions can make folds in almost any structured text. It is 416quite simple to specify, especially if the start and end of a fold can easily 417be recognized. 418 If you use the "expr" method to define folds, but they are not exactly how 419you want them, you could switch to the "manual" method. This will not remove 420the defined folds. Then you can delete or add folds manually. 421 422============================================================================== 423 424Next chapter: |usr_29.txt| Moving through programs 425 426Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: 427