filetype.txt (44553B)
1 *filetype.txt* For Vim version 9.2. Last change: 2026 Oct 01 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 Filetypes *filetype* *file-type* 8 9 1. Filetypes |filetypes| 10 2. Filetype plugin |filetype-plugins| 11 3. Docs for the default filetype plugins. |ftplugin-docs| 12 13 Also see |autocmd.txt|. 14 15 16 ============================================================================== 17 1. Filetypes *filetypes* *file-types* 18 19 Vim can detect the type of file that is edited. This is done by checking the 20 file name and sometimes by inspecting the contents of the file for specific 21 text. 22 23 *:filetype* *:filet* 24 To enable file type detection, use this command in your vimrc: > 25 :filetype on 26 Each time a new or existing file is edited, Vim will try to recognize the type 27 of the file and set the 'filetype' option. This will trigger the FileType 28 event, which can be used to set the syntax highlighting, set options, etc. 29 30 NOTE: Filetypes and 'compatible' don't work together well, since being Vi 31 compatible means options are global. Resetting 'compatible' is recommended, 32 if you didn't do that already. 33 34 Detail: The ":filetype on" command will load one of these files: 35 Amiga $VIMRUNTIME/filetype.vim 36 Mac $VIMRUNTIME:filetype.vim 37 MS-Windows $VIMRUNTIME\filetype.vim 38 Unix $VIMRUNTIME/filetype.vim 39 VMS $VIMRUNTIME/filetype.vim 40 This file is a Vim script that defines autocommands for the 41 BufNewFile and BufRead events. If the file type is not found by the 42 name, the file $VIMRUNTIME/scripts.vim is used to detect it from the 43 contents of the file. 44 When the GUI is running or will start soon, the |menu.vim| script is 45 also sourced. See |'go-M'| about avoiding that. 46 47 To add your own file types, see |new-filetype| below. To search for help on a 48 filetype prepend "ft-" and optionally append "-syntax", "-indent" or 49 "-plugin". For example: > 50 :help ft-vim-indent 51 :help ft-vim-syntax 52 :help ft-man-plugin 53 54 If the file type is not detected automatically, or it finds the wrong type, 55 you can either set the 'filetype' option manually, or add a modeline to your 56 file. Example, for an IDL file use the command: > 57 :set filetype=idl 58 59 or add this |modeline| to the file: 60 /* vim: set filetype=idl : */ ~ 61 62 *:filetype-plugin-on* 63 You can enable loading the plugin files for specific file types with: > 64 :filetype plugin on 65 If filetype detection was not switched on yet, it will be as well. 66 This actually loads the file "ftplugin.vim" in 'runtimepath'. 67 The result is that when a file is edited its plugin file is loaded (if there 68 is one for the detected filetype). |filetype-plugin| 69 70 *:filetype-plugin-off* 71 You can disable it again with: > 72 :filetype plugin off 73 The filetype detection is not switched off then. But if you do switch off 74 filetype detection, the plugins will not be loaded either. 75 This actually loads the file "ftplugof.vim" in 'runtimepath'. 76 77 *:filetype-indent-on* 78 You can enable loading the indent file for specific file types with: > 79 :filetype indent on 80 If filetype detection was not switched on yet, it will be as well. 81 This actually loads the file "indent.vim" in 'runtimepath'. 82 The result is that when a file is edited its indent file is loaded (if there 83 is one for the detected filetype). |indent-expression| 84 85 *:filetype-indent-off* 86 You can disable it again with: > 87 :filetype indent off 88 The filetype detection is not switched off then. But if you do switch off 89 filetype detection, the indent files will not be loaded either. 90 This actually loads the file "indoff.vim" in 'runtimepath'. 91 This disables auto-indenting for files you will open. It will keep working in 92 already opened files. Reset 'autoindent', 'cindent', 'smartindent' and/or 93 'indentexpr' to disable indenting in an opened file. 94 95 *:filetype-off* 96 To disable file type detection, use this command: > 97 :filetype off 98 This will keep the flags for "plugin" and "indent", but since no file types 99 are being detected, they won't work until the next ":filetype on". 100 101 102 Overview: *:filetype-overview* 103 104 command detection plugin indent ~ 105 :filetype on on unchanged unchanged 106 :filetype off off unchanged unchanged 107 :filetype plugin on on on unchanged 108 :filetype plugin off unchanged off unchanged 109 :filetype indent on on unchanged on 110 :filetype indent off unchanged unchanged off 111 :filetype plugin indent on on on on 112 :filetype plugin indent off unchanged off off 113 114 To see the current status, type: > 115 :filetype 116 The output looks something like this: > 117 filetype detection:ON plugin:ON indent:OFF 118 119 The file types are also used for syntax highlighting. If the ":syntax on" 120 command is used, the file type detection is installed too. There is no need 121 to do ":filetype on" after ":syntax on". 122 123 To disable one of the file types, add a line in your filetype file, see 124 |remove-filetype|. 125 126 *filetype-detect* 127 To detect the file type again: > 128 :filetype detect 129 Use this if you started with an empty file and typed text that makes it 130 possible to detect the file type. For example, when you entered this in a 131 shell script: "#!/bin/csh". 132 When filetype detection was off, it will be enabled first, like the "on" 133 argument was used. 134 135 *filetype-overrule* 136 When the same extension is used for multiple filetypes, Vim tries to guess 137 what kind of file it is. This doesn't always work. A number of global 138 variables can be used to overrule the filetype used for certain extensions: 139 140 file name variable ~ 141 *.al g:filetype_al 142 *.app g:filetype_app 143 *.as g:filetype_as 144 *.asa g:filetype_asa |ft-aspperl-syntax| 145 |ft-aspvbs-syntax| 146 *.asm g:asmsyntax |ft-asm-syntax| 147 *.asp g:filetype_asp |ft-aspperl-syntax| 148 |ft-aspvbs-syntax| 149 *.bas g:filetype_bas |ft-basic-syntax| 150 *.cfg g:filetype_cfg 151 *.cls g:filetype_cls 152 *.csh g:filetype_csh |ft-csh-syntax| 153 *.dat g:filetype_dat 154 *.def g:filetype_def 155 *.dsp g:filetype_dsp 156 *.f g:filetype_f |ft-forth-syntax| 157 *.frm g:filetype_frm |ft-form-syntax| 158 *.fs g:filetype_fs |ft-forth-syntax| 159 *.h g:c_syntax_for_h |ft-c-syntax| (deprecated) 160 *.h g:ch_syntax_for_h |ft-ch-syntax| (deprecated) 161 *.h g:filetype_h |ft-c-syntax| 162 |ft-ch-syntax| 163 |ft-cpp-syntax| 164 *.i g:filetype_i |ft-progress-syntax| 165 *.inc g:filetype_inc 166 *.int g:filetype_int 167 *.lsl g:filetype_lsl 168 *.m g:filetype_m |ft-mathematica-syntax| 169 *.mm g:filetype_mm 170 *.mac g:filetype_mac 171 *[mM]makefile,*.mk,*.mak,[mM]akefile* 172 g:make_flavor |ft-make-syntax| 173 *.markdown,*.mdown,*.mkd,*.mkdn,*.mdwn,*.md 174 g:filetype_md |ft-pandoc-syntax| 175 *.mod g:filetype_mod 176 *.p g:filetype_p |ft-pascal-syntax| 177 *.pl g:filetype_pl 178 *.pp g:filetype_pp |ft-pascal-syntax| 179 *.prg g:filetype_prg 180 *.r g:filetype_r 181 *.sig g:filetype_sig 182 *.sql g:filetype_sql |ft-sql-syntax| 183 *.src g:filetype_src 184 *.sys g:filetype_sys 185 *.sh g:bash_is_sh |ft-sh-syntax| 186 *.tex g:tex_flavor |ft-tex-plugin| 187 *.tf g:filetype_tf 188 *.typ g:filetype_typ 189 *.v g:filetype_v 190 *.w g:filetype_w |ft-cweb-syntax| 191 192 For a few filetypes the global variable is used only when the filetype could 193 not be detected: 194 *.r g:filetype_r |ft-rexx-syntax| 195 196 *filetype-ignore* 197 To avoid that certain files are being inspected, the g:ft_ignore_pat variable 198 is used. The default value is set like this: > 199 :let g:ft_ignore_pat = '\.\(Z\|gz\|bz2\|zip\|tgz\)$' 200 This means that the contents of compressed files are not inspected. 201 202 *new-filetype* 203 If a file type that you want to use is not detected yet, there are four ways 204 to add it. In any way, it's better not to modify the $VIMRUNTIME/filetype.vim 205 file. It will be overwritten when installing a new version of Vim. 206 207 A. If you want to overrule all default file type checks. 208 This works by writing one file for each filetype. The disadvantage is that 209 there can be many files. The advantage is that you can simply drop this 210 file in the right directory to make it work. 211 *ftdetect* 212 1. Create your user runtime directory. You would normally use the first 213 item of the 'runtimepath' option. Then create the directory "ftdetect" 214 inside it. Example for Unix: > 215 :!mkdir ~/.vim 216 :!mkdir ~/.vim/ftdetect 217 < 218 2. Create a file that contains an autocommand to detect the file type. 219 Example: > 220 au BufRead,BufNewFile *.mine set filetype=mine 221 < Note that there is no "augroup" command, this has already been done 222 when sourcing your file. You could also use the pattern "*" and then 223 check the contents of the file to recognize it. 224 Write this file as "mine.vim" in the "ftdetect" directory in your user 225 runtime directory. For example, for Unix: > 226 :w ~/.vim/ftdetect/mine.vim 227 228 < 3. To use the new filetype detection you must restart Vim. 229 230 The files in the "ftdetect" directory are used after all the default 231 checks, thus they can overrule a previously detected file type. But you 232 can also use |:setfiletype| to keep a previously detected filetype. 233 234 B. If you want to detect your file after the default file type checks. 235 236 This works like A above, but instead of setting 'filetype' unconditionally 237 use ":setfiletype". This will only set 'filetype' if no file type was 238 detected yet. Example: > 239 au BufRead,BufNewFile *.txt setfiletype text 240 < 241 You can also use the already detected file type in your command. For 242 example, to use the file type "mypascal" when "pascal" has been detected: > 243 au BufRead,BufNewFile * if &ft == 'pascal' | set ft=mypascal 244 | endif 245 246 C. If your file type can be detected by the file name. 247 1. Create your user runtime directory. You would normally use the first 248 item of the 'runtimepath' option. Example for Unix: > 249 :!mkdir ~/.vim 250 < 251 2. Create a file that contains autocommands to detect the file type. 252 Example: > 253 " my filetype file 254 if exists("did_load_filetypes") 255 finish 256 endif 257 augroup filetypedetect 258 au! BufRead,BufNewFile *.mine setfiletype mine 259 au! BufRead,BufNewFile *.xyz setfiletype drawing 260 augroup END 261 < Write this file as "filetype.vim" in your user runtime directory. For 262 example, for Unix: > 263 :w ~/.vim/filetype.vim 264 265 < 3. To use the new filetype detection you must restart Vim. 266 267 Your filetype.vim will be sourced before the default FileType autocommands 268 have been installed. Your autocommands will match first, and the 269 ":setfiletype" command will make sure that no other autocommands will set 270 'filetype' after this. 271 *new-filetype-scripts* 272 D. If your filetype can only be detected by inspecting the contents of the 273 file. 274 275 1. Create your user runtime directory. You would normally use the first 276 item of the 'runtimepath' option. Example for Unix: > 277 :!mkdir ~/.vim 278 < 279 2. Create a Vim script file for doing this. Example: > 280 if did_filetype() " filetype already set.. 281 finish " ..don't do these checks 282 endif 283 if getline(1) =~ '^#!.*\<mine\>' 284 setfiletype mine 285 elseif getline(1) =~? '\<drawing\>' 286 setfiletype drawing 287 endif 288 < See $VIMRUNTIME/scripts.vim for more examples. 289 Write this file as "scripts.vim" in your user runtime directory. For 290 example, for Unix: > 291 :w ~/.vim/scripts.vim 292 < 293 3. The detection will work right away, no need to restart Vim. 294 295 Your scripts.vim is loaded before the default checks for file types, which 296 means that your rules override the default rules in 297 $VIMRUNTIME/scripts.vim. 298 299 *remove-filetype* 300 If a file type is detected that is wrong for you, install a filetype.vim or 301 scripts.vim to catch it (see above). You can set 'filetype' to a non-existing 302 name to avoid that it will be set later anyway: > 303 :set filetype=ignored 304 305 If you are setting up a system with many users, and you don't want each user 306 to add/remove the same filetypes, consider writing the filetype.vim and 307 scripts.vim files in a runtime directory that is used for everybody. Check 308 the 'runtimepath' for a directory to use. If there isn't one, set 309 'runtimepath' in the |system-vimrc|. Be careful to keep the default 310 directories! 311 312 313 *autocmd-osfiletypes* 314 NOTE: this code is currently disabled, as the RISC OS implementation was 315 removed. In the future this will use the 'filetype' option. 316 317 On operating systems which support storing a file type with the file, you can 318 specify that an autocommand should only be executed if the file is of a 319 certain type. 320 321 The actual type checking depends on which platform you are running Vim 322 on; see your system's documentation for details. 323 324 To use osfiletype checking in an autocommand you should put a list of types to 325 match in angle brackets in place of a pattern, like this: > 326 327 :au BufRead *.html,<&faf;HTML> runtime! syntax/html.vim 328 329 This will match: 330 331 - Any file whose name ends in ".html" 332 - Any file whose type is "&faf" or "HTML", where the meaning of these types 333 depends on which version of Vim you are using. 334 Unknown types are considered NOT to match. 335 336 You can also specify a type and a pattern at the same time (in which case they 337 must both match): > 338 339 :au BufRead <&fff>diff* 340 341 This will match files of type "&fff" whose names start with "diff". 342 343 344 *plugin-details* 345 The "plugin" directory can be in any of the directories in the 'runtimepath' 346 option. All of these directories will be searched for plugins and they are 347 all loaded. For example, if this command: > 348 349 set runtimepath 350 351 produces this output: 352 353 runtimepath=/etc/vim,~/.vim,/usr/local/share/vim/vim82 ~ 354 355 then Vim will load all plugins in these directories and below: 356 357 /etc/vim/plugin/ ~ 358 ~/.vim/plugin/ ~ 359 /usr/local/share/vim/vim82/plugin/ ~ 360 361 Note that the last one is the value of $VIMRUNTIME which has been expanded. 362 363 Note that when using a plugin manager or |packages| many directories will be 364 added to 'runtimepath'. These plugins each require their own directory, don't 365 put them directly in ~/.vim/plugin. 366 367 What if it looks like your plugin is not being loaded? You can find out what 368 happens when Vim starts up by using the |-V| argument: > 369 370 vim -V2 371 372 You will see a lot of messages, in between them is a remark about loading the 373 plugins. It starts with: 374 375 Searching for "plugin/**/*.vim" in ~ 376 377 There you can see where Vim looks for your plugin scripts. 378 379 ============================================================================== 380 2. Filetype plugin *filetype-plugins* 381 382 When loading filetype plugins has been enabled |:filetype-plugin-on|, options 383 will be set and mappings defined. These are all local to the buffer, they 384 will not be used for other files. 385 386 Defining mappings for a filetype may get in the way of the mappings you 387 define yourself. There are a few ways to avoid this: 388 1. Set the "maplocalleader" variable to the key sequence you want the mappings 389 to start with. Example: > 390 :let maplocalleader = "," 391 < All mappings will then start with a comma instead of the default, which 392 is a backslash. Also see |<LocalLeader>|. 393 394 2. Define your own mapping. Example: > 395 :map ,p <Plug>MailQuote 396 < You need to check the description of the plugin file below for the 397 functionality it offers and the string to map to. 398 You need to define your own mapping before the plugin is loaded (before 399 editing a file of that type). The plugin will then skip installing the 400 default mapping. 401 *no_mail_maps* *g:no_mail_maps* 402 3. Disable defining mappings for a specific filetype by setting a variable, 403 which contains the name of the filetype. For the "mail" filetype this 404 would be: > 405 :let no_mail_maps = 1 406 < *no_plugin_maps* *g:no_plugin_maps* 407 4. Disable defining mappings for all filetypes by setting a variable: > 408 :let no_plugin_maps = 1 409 < 410 411 *ftplugin-overrule* 412 If a global filetype plugin does not do exactly what you want, there are three 413 ways to change this: 414 415 1. Add a few settings. 416 You must create a new filetype plugin in a directory early in 417 'runtimepath'. For Unix, for example you could use this file: > 418 vim ~/.vim/ftplugin/fortran.vim 419 < You can set those settings and mappings that you would like to add. Note 420 that the global plugin will be loaded after this, it may overrule the 421 settings that you do here. If this is the case, you need to use one of the 422 following two methods. 423 424 2. Make a copy of the plugin and change it. 425 You must put the copy in a directory early in 'runtimepath'. For Unix, for 426 example, you could do this: > 427 cp $VIMRUNTIME/ftplugin/fortran.vim ~/.vim/ftplugin/fortran.vim 428 < Then you can edit the copied file to your liking. Since the b:did_ftplugin 429 variable will be set, the global plugin will not be loaded. 430 A disadvantage of this method is that when the distributed plugin gets 431 improved, you will have to copy and modify it again. 432 433 3. Overrule the settings after loading the global plugin. 434 You must create a new filetype plugin in a directory from the end of 435 'runtimepath'. For Unix, for example, you could use this file: > 436 vim ~/.vim/after/ftplugin/fortran.vim 437 < In this file you can change just those settings that you want to change. 438 439 ============================================================================== 440 3. Docs for the default filetype plugins. *ftplugin-docs* 441 442 443 *plugin_exec* *g:plugin_exec* 444 Enable executing of external commands. This was done historically for e.g. 445 the perl filetype plugin (and a few others) to set the search path. 446 Disabled by default for security reasons: > 447 :let g:plugin_exec = 1 448 It is also possible to enable this only for certain filetypes: > 449 :let g:<filetype>_exec = 1 450 So to enable this only for ruby, set the following variable: > 451 :let g:ruby_exec = 1 452 453 If both, the global `plugin_exec` and the `<filetype>_exec` specific variable 454 are set, the filetype specific variable should have precedent. 455 456 457 ASCIIDOC *ft-asciidoc-plugin* 458 459 To enable |folding| use this: > 460 let g:asciidoc_folding = 1 461 462 To disable nesting of folded headers use this: > 463 let g:asciidoc_foldnested = 0 464 465 To disable folding everything under the title use this: > 466 let asciidoc_fold_under_title = 0 467 468 469 ARDUINO *ft-arduino-plugin* 470 471 By default the following options are set, in accordance with the default 472 settings of Arduino IDE: > 473 474 setlocal expandtab tabstop=2 softtabstop=2 shiftwidth=2 475 476 To disable this behavior, set the following variable in your vimrc: > 477 478 let g:arduino_recommended_style = 0 479 480 481 AWK *ft-awk-plugin* 482 483 Support for features specific to GNU Awk, like @include, can be enabled by 484 setting: > 485 :let g:awk_is_gawk = 1 486 487 BEANCOUNT *ft-beancount-plugin* 488 489 Beancount omni-completion |compl-omni| is provided by beancountcomplete.vim, 490 if enabled with g:beancount_completion_enable. 491 492 To enable completion of account names, set: > 493 let g:beancount_completion_enable = 1 494 < 495 Note: Enabling this may cause beancount to load additional plugin files. Only 496 enable for code you trust. 497 498 Variables: 499 g:beancount_account_completion 500 Specify the completion pattern format for the account 501 name. Can be either "default" or "chunks". 502 Default value: "default" 503 504 g:beancount_completion_enable 505 Enable omni-completion |compl-omni| for accounts. 506 Default value: 0 507 508 g:beancount_detailed_first 509 If non-zero, accounts higher down the hierarchy will 510 be listed first as completions. 511 Default value: 0 512 513 g:beancount_separator_col 514 The column that the decimal separator is aligned to. 515 Default value: 50 516 517 b:beancount_root 518 Set the root Beancount file. This is used to gather 519 values for the completion. 520 If not set (default), the current file will be used. 521 522 523 Commands: 524 :AlignCommodity Adds spaces between an account and commodity so that 525 the decimal points of the commodities all occur in the 526 column given by g:beancount_separator_col. If an 527 amount has no decimal point, the imaginary decimal 528 point to the right of the least significant digit will 529 align. 530 531 The command acts on a range, with the default being 532 the current line. If the cursor happens to be inside 533 that range and to the right of the account name, the 534 cursor will be pushed to the right the appropriate 535 amount, so that it remains on the same character. 536 537 The script assumes the use of spaces for alignment. 538 It does not understand tabs. 539 540 :GetContext Uses bean-doctor context to display the context of the 541 current line. 542 543 CHANGELOG *ft-changelog-plugin* 544 545 Allows for easy entrance of Changelog entries in Changelog files. There are 546 some commands, mappings, and variables worth exploring: 547 548 Options: 549 'comments' is made empty to not mess up formatting. 550 'textwidth' is set to 78, which is standard. 551 'formatoptions' the 't' flag is added to wrap when inserting text. 552 553 Commands: 554 NewChangelogEntry Adds a new Changelog entry in an intelligent fashion 555 (see below). 556 557 Local mappings: 558 <Leader>o Starts a new Changelog entry in an equally intelligent 559 fashion (see below). 560 561 Global mappings: 562 NOTE: The global mappings are accessed by sourcing the 563 ftplugin/changelog.vim file first, e.g. with > 564 runtime ftplugin/changelog.vim 565 < in your |.vimrc|. 566 <Leader>o Switches to the ChangeLog buffer opened for the 567 current directory, or opens it in a new buffer if it 568 exists in the current directory. Then it does the 569 same as the local <Leader>o described above. 570 571 Variables: 572 g:changelog_timeformat Deprecated; use g:changelog_dateformat instead. 573 g:changelog_dateformat The date (and time) format used in ChangeLog entries. 574 The format accepted is the same as for the 575 |strftime()| function. 576 The default is "%Y-%m-%d" which is the standard format 577 for many ChangeLog layouts. 578 g:changelog_username The name and email address of the user. 579 The default is deduced from environment variables and 580 system files. It searches /etc/passwd for the comment 581 part of the current user, which informally contains 582 the real name of the user up to the first separating 583 comma. then it checks the $NAME environment variable 584 and finally runs `whoami` and `hostname` to build an 585 email address. The final form is > 586 Full Name <user@host> 587 < 588 g:changelog_new_date_format 589 The format to use when creating a new date-entry. 590 The following table describes special tokens in the 591 string: 592 %% insert a single '%' character 593 %d insert the date from above 594 %u insert the user from above 595 %p insert result of 596 b:changelog_entry_prefix 597 %c where to position cursor when done 598 The default is "%d %u\n\n\t* %p%c\n\n", which 599 produces something like (| is where cursor will be, 600 unless at the start of the line where it denotes the 601 beginning of the line) > 602 |2003-01-14 Full Name <user@host> 603 | 604 | * prefix| 605 < 606 g:changelog_new_entry_format 607 The format used when creating a new entry. 608 The following table describes special tokens in the 609 string: 610 %p insert result of 611 b:changelog_entry_prefix 612 %c where to position cursor when done 613 The default is "\t*%c", which produces something 614 similar to > 615 | * prefix| 616 < 617 g:changelog_date_entry_search 618 The search pattern to use when searching for a 619 date-entry. 620 The same tokens that can be used for 621 g:changelog_new_date_format can be used here as well. 622 The default is '^\s*%d\_s*%u' which finds lines 623 matching the form > 624 |2003-01-14 Full Name <user@host> 625 < and some similar formats. 626 627 g:changelog_date_end_entry_search 628 The search pattern to use when searching for the end 629 of a date-entry. 630 The same tokens that can be used for 631 g:changelog_new_date_format can be used here as well. 632 The default is '^\s*$' which finds lines that contain 633 only whitespace or are completely empty. 634 635 b:changelog_name *b:changelog_name* 636 Name of the ChangeLog file to look for. 637 The default is 'ChangeLog'. 638 639 b:changelog_path 640 Path of the ChangeLog to use for the current buffer. 641 The default is empty, thus looking for a file named 642 |b:changelog_name| in the same directory as the 643 current buffer. If not found, the parent directory of 644 the current buffer is searched. This continues 645 recursively until a file is found or there are no more 646 parent directories to search. 647 648 b:changelog_entry_prefix 649 Name of a function to call to generate a prefix to a 650 new entry. This function takes no arguments and 651 should return a string containing the prefix. 652 Returning an empty prefix is fine. 653 The default generates the shortest path between the 654 ChangeLog's pathname and the current buffers pathname. 655 In the future, it will also be possible to use other 656 variable contexts for this variable, for example, g:. 657 658 The Changelog entries are inserted where they add the least amount of text. 659 After figuring out the current date and user, the file is searched for an 660 entry beginning with the current date and user and if found adds another item 661 under it. If not found, a new entry and item is prepended to the beginning of 662 the Changelog. 663 664 665 FORTRAN *ft-fortran-plugin* 666 667 Options: 668 'expandtab' is switched on to avoid tabs as required by the Fortran 669 standards unless the user has set fortran_have_tabs in .vimrc. 670 'textwidth' is set to 80 for fixed source format whereas it is set to 132 671 for free source format. Setting the 672 fortran_extended_line_length variable increases the width to 673 132 for fixed source format. 674 'formatoptions' is set to break code and comment lines and to preserve long 675 lines. You can format comments with |gq|. 676 For further discussion of fortran_have_tabs and the method used for the 677 detection of source format see |ft-fortran-syntax|. 678 679 680 FREEBASIC *ft-freebasic-plugin* 681 682 This plugin aims to treat the four FreeBASIC dialects, "fb", "qb", "fblite" 683 and "deprecated", as distinct languages. 684 685 The dialect will be set to the first name found in g:freebasic_forcelang, any 686 #lang directive or $lang metacommand in the file being edited, or finally 687 g:freebasic_lang. These global variables conceptually map to the fbc options 688 -forcelang and -lang. If no dialect is explicitly specified "fb" will be 689 used. 690 691 For example, to set the dialect to a default of "fblite" but still allow for 692 any #lang directive overrides, use the following command: > 693 694 let g:freebasic_lang = "fblite" 695 696 697 GDSCRIPT *ft-gdscript-plugin* 698 699 By default the following options are set, based on Godot official docs: > 700 701 setlocal noexpandtab softtabstop=0 shiftwidth=0 702 703 To disable this behavior, set the following variable in your vimrc: > 704 705 let g:gdscript_recommended_style = 0 706 707 708 GIT COMMIT *ft-gitcommit-plugin* 709 710 One command, :DiffGitCached, is provided to show a diff of the current commit 711 in the preview window. It is equivalent to calling "git diff --cached" plus 712 any arguments given to the command. 713 714 The length of the first line of the commit message used for 715 syntax highlighting can be configured via `g:gitcommit_summary_length`. 716 The default is 50. Example: > 717 718 let g:gitcommit_summary_length = 70 719 720 GIT REBASE *ft-gitrebase-plugin* 721 722 The gitrebase filetype defines the following buffer-local commands, to help 723 with interactive `git rebase`: > 724 725 :Drop " to discard this commit 726 :Edit " to stop for editing this commit 727 :Fixup " to squash (but discard the message) into the previous one 728 :Pick " to pick this commit (the cursor is on) 729 :Reword " to pick this commit, but change the commit message 730 :Squash " to squash this commit into the previous one 731 732 In addition, the following command can be used to cycle between the different 733 possibilities: > 734 735 :Cycle " to cycle between the previous commands 736 < 737 The `:Cycle` command is also mapped to the CTRL-A and CTRL-X keys. 738 For details, see `git-rebase --help`. 739 740 GLEAM *ft-gleam-plugin* 741 742 By default the following options are set for the recommended gleam style: > 743 744 setlocal expandtab shiftwidth=2 softtabstop=2 745 746 To disable this behavior, set the following variable in your vimrc: > 747 748 let g:gleam_recommended_style = 0 749 750 GO *ft-go-plugin* 751 752 By default the following options are set, based on Golang official docs: > 753 754 setlocal noexpandtab softtabstop=0 shiftwidth=0 755 756 To disable this behavior, set the following variable in your vimrc: > 757 758 let g:go_recommended_style = 0 759 760 761 GPROF *ft-gprof-plugin* 762 763 The gprof filetype plugin defines a mapping <C-]> to jump from a function 764 entry in the gprof flat profile or from a function entry in the call graph 765 to the details of that function in the call graph. 766 767 The mapping can be disabled with: > 768 let g:no_gprof_maps = 1 769 770 771 HARE *ft-hare* 772 773 Since the text for this plugin is rather long it has been put in a separate 774 file: |ft_hare.txt|. 775 776 HTML *ft-html-plugin* 777 778 Tag folding poses a few difficulties. Many elements, e.g. `blockquote`, are 779 always delimited by start and end tags; end tags for some elements, e.g. `p`, 780 can be omitted in certain contexts; void elements, e.g. `hr`, have no end tag. 781 Although the rules for supporting omissible end tags are ad-hoc and involved 782 [0], they apply to elements in scope. Assuming syntactical wellformedness, an 783 end tag can be associated with its nearest matching start tag discoverable in 784 scope [1] and towards the beginning of a file, whereas all unbalanced tags and 785 inlined tags can be disregarded. Having syntax highlighting in effect, tag 786 folding using the |fold-expr| method can be enabled with: > 787 let g:html_expr_folding = 1 788 < 789 By default, tag folding will be redone from scratch after each occurrence of 790 a |TextChanged| or an |InsertLeave| event. Such frequency may not be desired, 791 especially for large files, and this recomputation can be disabled with: > 792 let g:html_expr_folding_without_recomputation = 1 793 doautocmd FileType 794 < 795 To force another recomputation, do: > 796 unlet! b:foldsmap 797 normal zx 798 < 799 [0] https://html.spec.whatwg.org/multipage/syntax.html#optional-tags 800 [1] https://en.wikipedia.org/wiki/Dangling_else 801 802 ICALENDAR *ft-icalendar-plugin* *g:icalendar_folding* 803 804 You can enable folding of iCalendar components (BEGIN: and END: pairs) 805 using |fold-expr| by: > 806 807 let g:icalendar_folding = 1 808 < 809 Nested components, such as a VALARM inside a VEVENT, produce nested folds. 810 811 IDRIS2 *ft-idris2-plugin* 812 813 By default the following options are set: > 814 815 setlocal shiftwidth=2 tabstop=2 expandtab 816 setlocal comments=s1:{-,mb:-,ex:-},:\|\|\|,:-- 817 setlocal commentstring=--\ %s 818 setlocal wildignore+=*.ibc 819 820 To use tabs instead of spaces for indentation, set the following variable 821 in your vimrc: > 822 823 let g:idris2#allow_tabchar = 1 824 825 JAVA *ft-java-plugin* 826 827 Whenever the variable "g:ftplugin_java_source_path" is defined and its value 828 is a filename whose extension is either ".jar" or ".zip", e.g.: > 829 let g:ftplugin_java_source_path = '/path/to/src.jar' 830 let g:ftplugin_java_source_path = '/path/to/src.zip' 831 < 832 and the |zip| plugin has already been sourced, the |gf| command can be used to 833 open the archive and the |n| command can be used to look for the selected type 834 and the <Return> key can be used to load a listed file. 835 836 Note that the effect of using the "gf" command WITHIN a buffer loaded with the 837 Zip plugin depends on the version of the Zip plugin. For the Zip plugin 838 versions that do not support Jar type archives, consider creating symbolic 839 links with the ".zip" extension for each Jar archive of interest and assigning 840 any such file to the variable from now on. 841 842 Otherwise, for the defined variable "g:ftplugin_java_source_path", the local 843 value of the 'path' option will be further modified by prefixing the value of 844 the variable, e.g.: > 845 let g:ftplugin_java_source_path = $JDK_SRC_PATH 846 let &l:path = g:ftplugin_java_source_path .. ',' .. &l:path 847 < 848 and the "gf" command can be used on a fully-qualified type to look for a file 849 in the "path" and to try to load it. 850 851 Remember to manually trigger the |FileType| event from a buffer with a Java 852 file loaded in it each time after assigning a new value to the variable: > 853 doautocmd FileType 854 < 855 Markdown documentation comments may contain common runs of vertical leading 856 whitespace following the comment marks (`///`) for aesthetic reasons; however, 857 some horizontal runs of leading whitespace are significant in Markdown because 858 they denote code blocks etc. For convenience, a 'formatexpr' function is 859 provided for the |gq| operator. As long as neither "g:java_ignore_javadoc" 860 nor "g:java_ignore_markdown" is defined, the reformatting of Markdown comments 861 can be enabled on demand with: > 862 setlocal formatexpr=g:javaformat#RemoveCommonMarkdownWhitespace() 863 < 864 Or for Vim versions less than `7.4.265`, with: > 865 setlocal formatexpr=javaformat#RemoveCommonMarkdownWhitespace() 866 < 867 This function accepts a range of lines, removes a common run of vertical 868 leading whitespace, and rewrites the lines of the range. Depending on the 869 author's layout style and the comment contents, which lines to select for 870 reformatting can vary from the whole comment to only some portion of it. 871 872 To enable the recognition of Markdown comments each time after removing 873 "g:java_ignore_markdown" or "g:java_ignore_javadoc", remember to manually 874 re-source "javaformat.vim" for Vim versions greater than `8.2.1397`: > 875 runtime autoload/javaformat.vim 876 < 877 JSON-FORMAT *ft-json-plugin* 878 879 JSON filetype can be extended to use 'formatexpr' and "json.FormatExpr()" 880 function for json formatting (using |gq|). 881 882 Add following lines to $HOME/.vim/ftplugin/json.vim: > 883 884 vim9script 885 import autoload 'dist/json.vim' 886 setl formatexpr=json.FormatExpr() 887 888 LUA *ft-lua-plugin* *g:lua_folding* 889 890 You can enable folding of Lua functions using |fold-expr| by: > 891 892 let g:lua_folding = 1 893 < *g:lua_version* *g:lua_subversion* 894 Lua filetype's 'includeexpr' and |ft-lua-syntax| highlighting use the global 895 variables "g:lua_version" and "g:lua_subversion" to determine the version of 896 Lua to use (5.3 is the default) 897 898 For example, to use Lua 5.1, set the variables like this: > 899 900 let g:lua_version = 5 901 let g:lua_subversion = 1 902 < 903 LUAU *ft-luau-plugin* *g:luau_folding* 904 905 You can enable folding of Luau block constructs using |fold-expr| by: > 906 907 let g:luau_folding = 1 908 < 909 MAIL *ft-mail-plugin* 910 911 Options: 912 'modeline' is switched off to avoid the danger of trojan horses, and to 913 avoid that a Subject line with "Vim:" in it will cause an 914 error message. 915 'textwidth' is set to 72. This is often recommended for e-mail. 916 'formatoptions' is set to break text lines and to repeat the comment leader 917 in new lines, so that a leading ">" for quotes is repeated. 918 You can also format quoted text with |gq|. 919 920 Local mappings: 921 <LocalLeader>q or \MailQuote 922 Quotes the text selected in Visual mode, or from the cursor position 923 to the end of the file in Normal mode. This means "> " is inserted in 924 each line. 925 926 MAN *ft-man-plugin* *:Man* *:ManReload* *man.vim* 927 928 This plugin displays a manual page in a nice way. See |find-manpage| in the 929 user manual for more information. 930 931 To start using the |:Man| command before any manual page has been loaded, 932 source this script from your startup |vimrc| file: > 933 runtime ftplugin/man.vim 934 935 Options: 936 'iskeyword' The '.' character is added to support the use of CTRL-] on the 937 manual page name. 938 939 Commands: 940 Man {name} Display the manual page for {name} in a window. 941 Man {number} {name} 942 Display the manual page for {name} in a section {number}. 943 ManReload Reload the cache of available man pages used for |:Man| argument 944 completion. 945 946 Global mapping: 947 <Leader>K Displays the manual page for the word under the cursor. 948 <Plug>ManPreGetPage 949 idem, allows for using a mapping: > 950 nmap <F1> <Plug>ManPreGetPage 951 952 Local mappings: 953 <Plug>ManBS 954 <LocalLeader>h Clear backspace <BS> characters from the buffer. 955 CTRL-] Jump to the manual page for the word under the cursor. 956 CTRL-T Jump back to the previous manual page. 957 958 The mappings can be disabled with: > 959 let g:no_man_maps = 1 960 961 To use a vertical split instead of horizontal: > 962 let g:ft_man_open_mode = 'vert' 963 To use a new tab: > 964 let g:ft_man_open_mode = 'tab' 965 966 To enable |folding|, use this: > 967 let g:ft_man_folding_enable = 1 968 If you do not like the default folding, use an |autocommand| to add your 969 desired folding style instead. For example: > 970 autocmd FileType man setlocal foldmethod=indent foldenable 971 972 If you would like :Man {number} {name} to behave like man {number} {name} by 973 not running man {name} if no page is found, then use this: > 974 let g:ft_man_no_sect_fallback = 1 975 < 976 *g:ft_man_implementation* 977 The completion for the :Man command tries to guess which implementation of man 978 the system has. If it guesses wrong, you can set g:ft_man_implementation to 979 one of these values: 980 'man-db' https://man-db.nongnu.org/ 981 '' Unknown, fall back to completing shell commands 982 instead of man pages. 983 984 You may also want to set 'keywordprg' to make the |K| command open a manual 985 page in a Vim window: > 986 set keywordprg=:Man 987 988 989 MANPAGER *manpager.vim* 990 991 The |:Man| command allows you to turn Vim into a manpager (that syntax 992 highlights manpages and follows linked manpages on hitting CTRL-]). 993 994 For bash,zsh,ksh or dash, add to the config file (.bashrc,.zshrc, ...) 995 996 export MANPAGER="vim +MANPAGER --not-a-term -" 997 998 For (t)csh, add to the config file 999 1000 setenv MANPAGER "vim +MANPAGER --not-a-term -" 1001 1002 For fish, add to the config file 1003 1004 set -x MANPAGER "vim +MANPAGER --not-a-term -" 1005 1006 NOTE: Some man implementations pass a temporary file path to the pager as an 1007 argument instead. This includes mandoc's frontend, which is the default on 1008 OpenBSD, Alpine Linux and Void Linux for example. 1009 1010 In that case adjust the above lines to set the MANPAGER environment variable 1011 to "vim +MANPAGER --not-a-term" instead, dropping the final hyphen argument. 1012 1013 A way to support both behaviors is to create the following wrapper script: 1014 >sh 1015 #!/bin/sh 1016 vim +MANPAGER --not-a-term "${1:--}" 1017 < 1018 You can set the MANPAGER environment variable to the script name to enable it 1019 (if it's not on the PATH you can use the absolute path). Make sure the 1020 executable permission bit is set. 1021 1022 MARKDOWN *ft-markdown-plugin* 1023 1024 To enable folding use this: > 1025 let g:markdown_folding = 1 1026 1027 'expandtab' will be set by default. If you do not want that use this: > 1028 let g:markdown_recommended_style = 0 1029 1030 1031 ORG *ft-org-plugin* 1032 1033 To enable folding use this: > 1034 let g:org_folding = 1 1035 < 1036 1037 PDF *ft-pdf-plugin* 1038 1039 Two maps, <C-]> and <C-T>, are provided to simulate a tag stack for navigating 1040 the PDF. The following are treated as tags: 1041 1042 - The byte offset after "startxref" to the xref table 1043 - The byte offset after the /Prev key in the trailer to an earlier xref table 1044 - A line of the form "0123456789 00000 n" in the xref table 1045 - An object reference like "1 0 R" anywhere in the PDF 1046 1047 These maps can be disabled with > 1048 :let g:no_pdf_maps = 1 1049 1050 PLSQL *ft-plsql-plugin* 1051 1052 To enable syntax folding in PL/SQL filetypes, set the following variable: > 1053 1054 :let g:plsql_fold = 1 1055 < 1056 1057 PYTHON *ft-python-plugin* *PEP8* 1058 1059 By default the following options are set, in accordance with PEP8: > 1060 1061 setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=8 1062 1063 To disable this behavior, set the following variable in your vimrc: > 1064 1065 let g:python_recommended_style = 0 1066 < 1067 Python omni-completion |compl-omni| is provided by python3complete.vim (or 1068 pythoncomplete.vim) for Vim builds with the |+python|/|+python3| interpreter. 1069 By default it does not inspect the import / from statements found in the 1070 buffer. This means completion of names defined in the buffer itself (classes, 1071 functions, variables) works, but completion of members of imported modules is 1072 not offered. 1073 1074 To enable completion of imported module members, set: > 1075 let g:pythoncomplete_allow_import = 1 1076 < 1077 WARNING: enabling this causes omni-completion to execute the import statements 1078 found in the buffer through Python's import machinery, which runs the imported 1079 modules' top-level code. Only enable this for code you trust. 1080 1081 QF QUICKFIX *qf.vim* *ft-qf-plugin* 1082 1083 The "qf" filetype is used for the quickfix window, see |quickfix-window|. 1084 1085 The quickfix filetype plugin includes configuration for displaying the command 1086 that produced the quickfix list in the |status-line|. To disable this setting, 1087 configure as follows: > 1088 :let g:qf_disable_statusline = 1 1089 1090 1091 R MARKDOWN *ft-rmd-plugin* 1092 1093 By default ftplugin/html.vim is not sourced. If you want it sourced, add to 1094 your |vimrc|: > 1095 let rmd_include_html = 1 1096 1097 The 'formatexpr' option is set dynamically with different values for R code 1098 and for Markdown code. If you prefer that 'formatexpr' is not set, add to 1099 your |vimrc|: > 1100 let rmd_dynamic_comments = 0 1101 1102 1103 R RESTRUCTURED TEXT *ft-rrst-plugin* 1104 1105 The 'formatexpr' option is set dynamically with different values for R code 1106 and for ReStructured text. If you prefer that 'formatexpr' is not set, add to 1107 your |vimrc|: > 1108 let rrst_dynamic_comments = 0 1109 1110 1111 RESTRUCTUREDTEXT *ft-rst-plugin* 1112 1113 The following formatting setting are optionally available: > 1114 setlocal expandtab shiftwidth=3 softtabstop=3 tabstop=8 1115 1116 To enable this behavior, set the following variable in your vimrc: > 1117 let g:rst_style = 1 1118 1119 1120 RNOWEB *ft-rnoweb-plugin* 1121 1122 The 'formatexpr' option is set dynamically with different values for R code 1123 and for LaTeX code. If you prefer that 'formatexpr' is not set, add to your 1124 |vimrc|: > 1125 let rnw_dynamic_comments = 0 1126 1127 1128 RPM SPEC *ft-spec-plugin* 1129 1130 Since the text for this plugin is rather long it has been put in a separate 1131 file: |pi_spec.txt|. 1132 1133 1134 RUST *ft-rust* 1135 1136 Since the text for this plugin is rather long it has been put in a separate 1137 file: |ft_rust.txt|. 1138 1139 1140 SQL *ft-sql* 1141 1142 Since the text for this plugin is rather long it has been put in a separate 1143 file: |ft_sql.txt|. 1144 1145 1146 TEX *ft-tex-plugin* *g:tex_flavor* 1147 1148 If the first line of a *.tex file has the form > 1149 %&<format> 1150 then this determined the file type: plaintex (for plain TeX), context (for 1151 ConTeXt), or tex (for LaTeX). Otherwise, the file is searched for keywords to 1152 choose context or tex. If no keywords are found, it defaults to plaintex. 1153 You can change the default by defining the variable g:tex_flavor to the format 1154 (not the file type) you use most. Use one of these: > 1155 let g:tex_flavor = "plain" 1156 let g:tex_flavor = "context" 1157 let g:tex_flavor = "latex" 1158 Currently no other formats are recognized. 1159 1160 TYPST *ft-typst-plugin* 1161 1162 *g:typst_recommended_style* 1163 By default, the Typst filetype plugin enables the following options: > 1164 setlocal expandtab shiftwidth=2 softtabstop=2 1165 1166 To disable this, set the following variable: > 1167 let g:typst_recommended_style = 0 1168 < 1169 *g:typst_conceal* 1170 When |TRUE| the Typst filetype plugin will set the 'conceallevel' option to 2. 1171 1172 *g:typst_folding* 1173 When |TRUE| the Typst filetype plugin will fold headings. (default: |FALSE|) 1174 1175 To enable: > 1176 let g:typst_folding = 1 1177 < 1178 *g:typst_foldnested* 1179 When |TRUE| the Typst filetype plugin will fold nested heading under their 1180 parents. (default: |TRUE|) 1181 1182 To disable: > 1183 let g:typst_foldnested = 0 1184 < 1185 VIM *ft-vim-plugin* 1186 1187 The Vim filetype plugin defines the following mappings: 1188 1189 [[ move to the start of the previous function 1190 ]] move to the start of the next function 1191 ][ move to the end of the previous function 1192 [] move to the end of the next function 1193 ]" move to the next (legacy) comment 1194 [" move to the previous (legacy) comment 1195 gf edit the file under the cursor 1196 CTRL-W gf edit the file under the cursor in a new tab page 1197 CTRL-W f edit the file under the cursor in a new window 1198 1199 1200 The mappings can be disabled with: > 1201 let g:no_vim_maps = 1 1202 1203 YAML *ft-yaml-plugin* 1204 By default, the YAML filetype plugin enables the following options: > 1205 setlocal shiftwidth=2 softtabstop=2 1206 1207 To disable this, set the following variable: > 1208 let g:yaml_recommended_style = 0 1209 1210 1211 ZIG *ft-zig-plugin* 1212 1213 *g:zig_recommended_style* 1214 By default the following indentation options are set, in accordance with Zig's 1215 recommended style (https://ziglang.org/documentation/master/): > 1216 1217 setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=8 1218 < 1219 To disable this behavior, set |g:zig_recommended_style| to 0: > 1220 1221 let g:zig_recommended_style = 0 1222 < 1223 *g:zig_std_dir* 1224 The path to the Zig standard library. The Zig |ftplugin| reads |g:zig_std_dir| 1225 and appends it to the 'path' for Zig files. Where the Zig standard library 1226 is located is system and installation method dependent. 1227 1228 One can automatically set |g:zig_std_dir| using `zig env`: > 1229 1230 let g:zig_std_dir = json_decode(system('zig env'))['std_dir'] 1231 < 1232 This can, for example, be put in a FileType |:autocmd| or user |ftplugin| to 1233 only load when a Zig file is opened. 1234 1235 1236 ZIMBU *ft-zimbu-plugin* 1237 1238 The Zimbu filetype plugin defines mappings to move to the start and end of 1239 functions with [[ and ]]. 1240 1241 The mappings can be disabled with: > 1242 let g:no_zimbu_maps = 1 1243 < 1244 1245 1246 vim:tw=78:ts=8:noet:ft=help:norl: