1*filetype.txt* For Vim version 7.3. Last change: 2008 Jul 15 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Filetypes *filetype* *file-type* 8 91. Filetypes |filetypes| 102. Filetype plugin |filetype-plugins| 113. Docs for the default filetype plugins. |ftplugin-docs| 12 13Also see |autocmd.txt|. 14 15{Vi does not have any of these commands} 16 17============================================================================== 181. Filetypes *filetypes* *file-types* 19 20Vim can detect the type of file that is edited. This is done by checking the 21file name and sometimes by inspecting the contents of the file for specific 22text. 23 24 *:filetype* *:filet* 25To enable file type detection, use this command in your vimrc: > 26 :filetype on 27Each time a new or existing file is edited, Vim will try to recognize the type 28of the file and set the 'filetype' option. This will trigger the FileType 29event, which can be used to set the syntax highlighting, set options, etc. 30 31NOTE: Filetypes and 'compatible' don't work together well, since being Vi 32compatible means options are global. Resetting 'compatible' is recommended, 33if you didn't do that already. 34 35Detail: The ":filetype on" command will load one of these files: 36 Amiga $VIMRUNTIME/filetype.vim 37 Mac $VIMRUNTIME:filetype.vim 38 MS-DOS $VIMRUNTIME\filetype.vim 39 RiscOS Vim:Filetype 40 Unix $VIMRUNTIME/filetype.vim 41 VMS $VIMRUNTIME/filetype.vim 42 This file is a Vim script that defines autocommands for the 43 BufNewFile and BufRead events. If the file type is not found by the 44 name, the file $VIMRUNTIME/scripts.vim is used to detect it from the 45 contents of the file. 46 When the GUI is running or will start soon, the menu.vim script is 47 also sourced. See |'go-M'| about avoiding that. 48 49To add your own file types, see |new-filetype| below. To search for help on a 50filetype prepend "ft-" and optionally append "-syntax", "-indent" or 51"-plugin". For example: > 52 :help ft-vim-indent 53 :help ft-vim-syntax 54 :help ft-man-plugin 55 56If the file type is not detected automatically, or it finds the wrong type, 57you can either set the 'filetype' option manually, or add a modeline to your 58file. Example, for an IDL file use the command: > 59 :set filetype=idl 60 61or add this |modeline| to the file: 62 /* vim: set filetype=idl : */ ~ 63 64 *:filetype-plugin-on* 65You can enable loading the plugin files for specific file types with: > 66 :filetype plugin on 67If filetype detection was not switched on yet, it will be as well. 68This actually loads the file "ftplugin.vim" in 'runtimepath'. 69The result is that when a file is edited its plugin file is loaded (if there 70is one for the detected filetype). |filetype-plugin| 71 72 *:filetype-plugin-off* 73You can disable it again with: > 74 :filetype plugin off 75The filetype detection is not switched off then. But if you do switch off 76filetype detection, the plugins will not be loaded either. 77This actually loads the file "ftplugof.vim" in 'runtimepath'. 78 79 *:filetype-indent-on* 80You can enable loading the indent file for specific file types with: > 81 :filetype indent on 82If filetype detection was not switched on yet, it will be as well. 83This actually loads the file "indent.vim" in 'runtimepath'. 84The result is that when a file is edited its indent file is loaded (if there 85is one for the detected filetype). |indent-expression| 86 87 *:filetype-indent-off* 88You can disable it again with: > 89 :filetype indent off 90The filetype detection is not switched off then. But if you do switch off 91filetype detection, the indent files will not be loaded either. 92This actually loads the file "indoff.vim" in 'runtimepath'. 93This disables auto-indenting for files you will open. It will keep working in 94already opened files. Reset 'autoindent', 'cindent', 'smartindent' and/or 95'indentexpr' to disable indenting in an opened file. 96 97 *:filetype-off* 98To disable file type detection, use this command: > 99 :filetype off 100This will keep the flags for "plugin" and "indent", but since no file types 101are being detected, they won't work until the next ":filetype on". 102 103 104Overview: *:filetype-overview* 105 106command detection plugin indent ~ 107:filetype on on unchanged unchanged 108:filetype off off unchanged unchanged 109:filetype plugin on on on unchanged 110:filetype plugin off unchanged off unchanged 111:filetype indent on on unchanged on 112:filetype indent off unchanged unchanged off 113:filetype plugin indent on on on on 114:filetype plugin indent off unchanged off off 115 116To see the current status, type: > 117 :filetype 118The output looks something like this: > 119 filetype detection:ON plugin:ON indent:OFF 120 121The file types are also used for syntax highlighting. If the ":syntax on" 122command is used, the file type detection is installed too. There is no need 123to do ":filetype on" after ":syntax on". 124 125To disable one of the file types, add a line in your filetype file, see 126|remove-filetype|. 127 128 *filetype-detect* 129To detect the file type again: > 130 :filetype detect 131Use this if you started with an empty file and typed text that makes it 132possible to detect the file type. For example, when you entered this in a 133shell script: "#!/bin/csh". 134 When filetype detection was off, it will be enabled first, like the "on" 135argument was used. 136 137 *filetype-overrule* 138When the same extension is used for two filetypes, Vim tries to guess what 139kind of file it is. This doesn't always work. A number of global variables 140can be used to overrule the filetype used for certain extensions: 141 142 file name variable ~ 143 *.asa g:filetype_asa |ft-aspvbs-syntax| |ft-aspperl-syntax| 144 *.asp g:filetype_asp |ft-aspvbs-syntax| |ft-aspperl-syntax| 145 *.asm g:asmsyntax |ft-asm-syntax| 146 *.prg g:filetype_prg 147 *.pl g:filetype_pl 148 *.inc g:filetype_inc 149 *.w g:filetype_w |ft-cweb-syntax| 150 *.i g:filetype_i |ft-progress-syntax| 151 *.p g:filetype_p |ft-pascal-syntax| 152 *.sh g:bash_is_sh |ft-sh-syntax| 153 *.tex g:tex_flavor |ft-tex-plugin| 154 155 *filetype-ignore* 156To avoid that certain files are being inspected, the g:ft_ignore_pat variable 157is used. The default value is set like this: > 158 :let g:ft_ignore_pat = '\.\(Z\|gz\|bz2\|zip\|tgz\)$' 159This means that the contents of compressed files are not inspected. 160 161 *new-filetype* 162If a file type that you want to use is not detected yet, there are four ways 163to add it. In any way, it's better not to modify the $VIMRUNTIME/filetype.vim 164file. It will be overwritten when installing a new version of Vim. 165 166A. If you want to overrule all default file type checks. 167 This works by writing one file for each filetype. The disadvantage is that 168 means there can be many files. The advantage is that you can simply drop 169 this file in the right directory to make it work. 170 *ftdetect* 171 1. Create your user runtime directory. You would normally use the first 172 item of the 'runtimepath' option. Then create the directory "ftdetect" 173 inside it. Example for Unix: > 174 :!mkdir ~/.vim 175 :!mkdir ~/.vim/ftdetect 176< 177 2. Create a file that contains an autocommand to detect the file type. 178 Example: > 179 au BufRead,BufNewFile *.mine set filetype=mine 180< Note that there is no "augroup" command, this has already been done 181 when sourcing your file. You could also use the pattern "*" and then 182 check the contents of the file to recognize it. 183 Write this file as "mine.vim" in the "ftdetect" directory in your user 184 runtime directory. For example, for Unix: > 185 :w ~/.vim/ftdetect/mine.vim 186 187< 3. To use the new filetype detection you must restart Vim. 188 189 The files in the "ftdetect" directory are used after all the default 190 checks, thus they can overrule a previously detected file type. But you 191 can also use |:setfiletype| to keep a previously detected filetype. 192 193B. If you want to detect your file after the default file type checks. 194 195 This works like A above, but instead of setting 'filetype' unconditionally 196 use ":setfiletype". This will only set 'filetype' if no file type was 197 detected yet. Example: > 198 au BufRead,BufNewFile *.txt setfiletype text 199< 200 You can also use the already detected file type in your command. For 201 example, to use the file type "mypascal" when "pascal" has been detected: > 202 au BufRead,BufNewFile * if &ft == 'pascal' | set ft=mypascal 203 | endif 204 205C. If your file type can be detected by the file name. 206 1. Create your user runtime directory. You would normally use the first 207 item of the 'runtimepath' option. Example for Unix: > 208 :!mkdir ~/.vim 209< 210 2. Create a file that contains autocommands to detect the file type. 211 Example: > 212 " my filetype file 213 if exists("did_load_filetypes") 214 finish 215 endif 216 augroup filetypedetect 217 au! BufRead,BufNewFile *.mine setfiletype mine 218 au! BufRead,BufNewFile *.xyz setfiletype drawing 219 augroup END 220< Write this file as "filetype.vim" in your user runtime directory. For 221 example, for Unix: > 222 :w ~/.vim/filetype.vim 223 224< 3. To use the new filetype detection you must restart Vim. 225 226 Your filetype.vim will be sourced before the default FileType autocommands 227 have been installed. Your autocommands will match first, and the 228 ":setfiletype" command will make sure that no other autocommands will set 229 'filetype' after this. 230 *new-filetype-scripts* 231D. If your filetype can only be detected by inspecting the contents of the 232 file. 233 234 1. Create your user runtime directory. You would normally use the first 235 item of the 'runtimepath' option. Example for Unix: > 236 :!mkdir ~/.vim 237< 238 2. Create a vim script file for doing this. Example: > 239 if did_filetype() " filetype already set.. 240 finish " ..don't do these checks 241 endif 242 if getline(1) =~ '^#!.*\<mine\>' 243 setfiletype mine 244 elseif getline(1) =~? '\<drawing\>' 245 setfiletype drawing 246 endif 247< See $VIMRUNTIME/scripts.vim for more examples. 248 Write this file as "scripts.vim" in your user runtime directory. For 249 example, for Unix: > 250 :w ~/.vim/scripts.vim 251< 252 3. The detection will work right away, no need to restart Vim. 253 254 Your scripts.vim is loaded before the default checks for file types, which 255 means that your rules override the default rules in 256 $VIMRUNTIME/scripts.vim. 257 258 *remove-filetype* 259If a file type is detected that is wrong for you, install a filetype.vim or 260scripts.vim to catch it (see above). You can set 'filetype' to a non-existing 261name to avoid that it will be set later anyway: > 262 :set filetype=ignored 263 264If you are setting up a system with many users, and you don't want each user 265to add/remove the same filetypes, consider writing the filetype.vim and 266scripts.vim files in a runtime directory that is used for everybody. Check 267the 'runtimepath' for a directory to use. If there isn't one, set 268'runtimepath' in the |system-vimrc|. Be careful to keep the default 269directories! 270 271 272 *autocmd-osfiletypes* 273On operating systems which support storing a file type with the file, you can 274specify that an autocommand should only be executed if the file is of a 275certain type. 276 277The actual type checking depends on which platform you are running Vim 278on; see your system's documentation for details. 279 280To use osfiletype checking in an autocommand you should put a list of types to 281match in angle brackets in place of a pattern, like this: > 282 283 :au BufRead *.html,<&faf;HTML> runtime! syntax/html.vim 284 285This will match: 286 287- Any file whose name ends in ".html" 288- Any file whose type is "&faf" or "HTML", where the meaning of these types 289 depends on which version of Vim you are using. 290 Unknown types are considered NOT to match. 291 292You can also specify a type and a pattern at the same time (in which case they 293must both match): > 294 295 :au BufRead <&fff>diff* 296 297This will match files of type "&fff" whose names start with "diff". 298 299Note that osfiletype checking is skipped if Vim is compiled without the 300|+osfiletype| feature. 301 302 *plugin-details* 303The "plugin" directory can be in any of the directories in the 'runtimepath' 304option. All of these directories will be searched for plugins and they are 305all loaded. For example, if this command: > 306 307 set runtimepath 308 309produces this output: 310 311 runtimepath=/etc/vim,~/.vim,/usr/local/share/vim/vim60 ~ 312 313then Vim will load all plugins in these directories and below: 314 315 /etc/vim/plugin/ ~ 316 ~/.vim/plugin/ ~ 317 /usr/local/share/vim/vim60/plugin/ ~ 318 319Note that the last one is the value of $VIMRUNTIME which has been expanded. 320 321What if it looks like your plugin is not being loaded? You can find out what 322happens when Vim starts up by using the |-V| argument: > 323 324 vim -V2 325 326You will see a lot of messages, in between them is a remark about loading the 327plugins. It starts with: 328 329 Searching for "plugin/**/*.vim" in ~ 330 331There you can see where Vim looks for your plugin scripts. 332 333============================================================================== 3342. Filetype plugin *filetype-plugins* 335 336When loading filetype plugins has been enabled |:filetype-plugin-on|, options 337will be set and mappings defined. These are all local to the buffer, they 338will not be used for other files. 339 340Defining mappings for a filetype may get in the way of the mappings you 341define yourself. There are a few ways to avoid this: 3421. Set the "maplocalleader" variable to the key sequence you want the mappings 343 to start with. Example: > 344 :let maplocalleader = "," 345< All mappings will then start with a comma instead of the default, which 346 is a backslash. Also see |<LocalLeader>|. 347 3482. Define your own mapping. Example: > 349 :map ,p <Plug>MailQuote 350< You need to check the description of the plugin file below for the 351 functionality it offers and the string to map to. 352 You need to define your own mapping before the plugin is loaded (before 353 editing a file of that type). The plugin will then skip installing the 354 default mapping. 355 3563. Disable defining mappings for a specific filetype by setting a variable, 357 which contains the name of the filetype. For the "mail" filetype this 358 would be: > 359 :let no_mail_maps = 1 360 3614. Disable defining mappings for all filetypes by setting a variable: > 362 :let no_plugin_maps = 1 363< 364 365 *ftplugin-overrule* 366If a global filetype plugin does not do exactly what you want, there are three 367ways to change this: 368 3691. Add a few settings. 370 You must create a new filetype plugin in a directory early in 371 'runtimepath'. For Unix, for example you could use this file: > 372 vim ~/.vim/ftplugin/fortran.vim 373< You can set those settings and mappings that you would like to add. Note 374 that the global plugin will be loaded after this, it may overrule the 375 settings that you do here. If this is the case, you need to use one of the 376 following two methods. 377 3782. Make a copy of the plugin and change it. 379 You must put the copy in a directory early in 'runtimepath'. For Unix, for 380 example, you could do this: > 381 cp $VIMRUNTIME/ftplugin/fortran.vim ~/.vim/ftplugin/fortran.vim 382< Then you can edit the copied file to your liking. Since the b:did_ftplugin 383 variable will be set, the global plugin will not be loaded. 384 A disadvantage of this method is that when the distributed plugin gets 385 improved, you will have to copy and modify it again. 386 3873. Overrule the settings after loading the global plugin. 388 You must create a new filetype plugin in a directory from the end of 389 'runtimepath'. For Unix, for example, you could use this file: > 390 vim ~/.vim/after/ftplugin/fortran.vim 391< In this file you can change just those settings that you want to change. 392 393============================================================================== 3943. Docs for the default filetype plugins. *ftplugin-docs* 395 396 397CHANGELOG *ft-changelog-plugin* 398 399Allows for easy entrance of Changelog entries in Changelog files. There are 400some commands, mappings, and variables worth exploring: 401 402Options: 403'comments' is made empty to not mess up formatting. 404'textwidth' is set to 78, which is standard. 405'formatoptions' the 't' flag is added to wrap when inserting text. 406 407Commands: 408NewChangelogEntry Adds a new Changelog entry in an intelligent fashion 409 (see below). 410 411Local mappings: 412<Leader>o Starts a new Changelog entry in an equally intelligent 413 fashion (see below). 414 415Global mappings: 416 NOTE: The global mappings are accessed by sourcing the 417 ftplugin/changelog.vim file first, e.g. with > 418 runtime ftplugin/changelog.vim 419< in your |.vimrc|. 420<Leader>o Switches to the ChangeLog buffer opened for the 421 current directory, or opens it in a new buffer if it 422 exists in the current directory. Then it does the 423 same as the local <Leader>o described above. 424 425Variables: 426g:changelog_timeformat Deprecated; use g:changelog_dateformat instead. 427g:changelog_dateformat The date (and time) format used in ChangeLog entries. 428 The format accepted is the same as for the 429 |strftime()| function. 430 The default is "%Y-%m-%d" which is the standard format 431 for many ChangeLog layouts. 432g:changelog_username The name and email address of the user. 433 The default is deduced from environment variables and 434 system files. It searches /etc/passwd for the comment 435 part of the current user, which informally contains 436 the real name of the user up to the first separating 437 comma. then it checks the $NAME environment variable 438 and finally runs `whoami` and `hostname` to build an 439 email address. The final form is > 440 Full Name <user@host> 441< 442g:changelog_new_date_format 443 The format to use when creating a new date-entry. 444 The following table describes special tokens in the 445 string: 446 %% insert a single '%' character 447 %d insert the date from above 448 %u insert the user from above 449 %c where to position cursor when done 450 The default is "%d %u\n\n\t* %c\n\n", which produces 451 something like (| is where cursor will be, unless at 452 the start of the line where it denotes the beginning 453 of the line) > 454 |2003-01-14 Full Name <user@host> 455 | 456 | * | 457< 458g:changelog_new_entry_format 459 The format used when creating a new entry. 460 The following table describes special tokens in the 461 string: 462 %c where to position cursor when done 463 The default is "\t*%c", which produces something 464 similar to > 465 | * | 466< 467g:changelog_date_entry_search 468 The search pattern to use when searching for a 469 date-entry. 470 The same tokens that can be used for 471 g:changelog_new_date_format can be used here as well. 472 The default is '^\s*%d\_s*%u' which finds lines 473 matching the form > 474 |2003-01-14 Full Name <user@host> 475< and some similar formats. 476 477g:changelog_date_end_entry_search 478 The search pattern to use when searching for the end 479 of a date-entry. 480 The same tokens that can be used for 481 g:changelog_new_date_format can be used here as well. 482 The default is '^\s*$' which finds lines that contain 483 only whitespace or are completely empty. 484 485b:changelog_name *b:changelog_name* 486 Name of the ChangeLog file to look for. 487 The default is 'ChangeLog'. 488 489b:changelog_path 490 Path of the ChangeLog to use for the current buffer. 491 The default is empty, thus looking for a file named 492 |b:changelog_name| in the same directory as the 493 current buffer. If not found, the parent directory of 494 the current buffer is searched. This continues 495 recursively until a file is found or there are no more 496 parent directories to search. 497 498b:changelog_entry_prefix 499 Name of a function to call to generate a prefix to a 500 new entry. This function takes no arguments and 501 should return a string containing the prefix. 502 Returning an empty prefix is fine. 503 The default generates the shortest path between the 504 ChangeLog's pathname and the current buffers pathname. 505 In the future, it will also be possible to use other 506 variable contexts for this variable, for example, g:. 507 508The Changelog entries are inserted where they add the least amount of text. 509After figuring out the current date and user, the file is searched for an 510entry beginning with the current date and user and if found adds another item 511under it. If not found, a new entry and item is prepended to the beginning of 512the Changelog. 513 514 515FORTRAN *ft-fortran-plugin* 516 517Options: 518'expandtab' is switched on to avoid tabs as required by the Fortran 519 standards unless the user has set fortran_have_tabs in .vimrc. 520'textwidth' is set to 72 for fixed source format as required by the 521 Fortran standards and to 80 for free source format. 522'formatoptions' is set to break code and comment lines and to preserve long 523 lines. You can format comments with |gq|. 524For further discussion of fortran_have_tabs and the method used for the 525detection of source format see |ft-fortran-syntax|. 526 527 528GIT COMMIT *ft-gitcommit-plugin* 529 530One command, :DiffGitCached, is provided to show a diff of the current commit 531in the preview window. It is equivalent to calling "git diff --cached" plus 532any arguments given to the command. 533 534 535MAIL *ft-mail-plugin* 536 537Options: 538'modeline' is switched off to avoid the danger of trojan horses, and to 539 avoid that a Subject line with "Vim:" in it will cause an 540 error message. 541'textwidth' is set to 72. This is often recommended for e-mail. 542'formatoptions' is set to break text lines and to repeat the comment leader 543 in new lines, so that a leading ">" for quotes is repeated. 544 You can also format quoted text with |gq|. 545 546Local mappings: 547<LocalLeader>q or \\MailQuote 548 Quotes the text selected in Visual mode, or from the cursor position 549 to the end of the file in Normal mode. This means "> " is inserted in 550 each line. 551 552MAN *ft-man-plugin* *:Man* 553 554Displays a manual page in a nice way. Also see the user manual 555|find-manpage|. 556 557To start using the ":Man" command before any manual page was loaded, source 558this script from your startup vimrc file: > 559 560 runtime ftplugin/man.vim 561 562Options: 563'iskeyword' the '.' character is added to be able to use CTRL-] on the 564 manual page name. 565 566Commands: 567Man {name} Display the manual page for {name} in a window. 568Man {number} {name} 569 Display the manual page for {name} in a section {number}. 570 571Global mapping: 572<Leader>K Displays the manual page for the word under the cursor. 573 574Local mappings: 575CTRL-] Jump to the manual page for the word under the cursor. 576CTRL-T Jump back to the previous manual page. 577 578 579PDF *ft-pdf-plugin* 580 581Two maps, <C-]> and <C-T>, are provided to simulate a tag stack for navigating 582the PDF. The following are treated as tags: 583 584- The byte offset after "startxref" to the xref table 585- The byte offset after the /Prev key in the trailer to an earlier xref table 586- A line of the form "0123456789 00000 n" in the xref table 587- An object reference like "1 0 R" anywhere in the PDF 588 589These maps can be disabled with > 590 :let g:no_pdf_maps = 1 591< 592 593RPM SPEC *ft-spec-plugin* 594 595Since the text for this plugin is rather long it has been put in a separate 596file: |pi_spec.txt|. 597 598 599SQL *ft-sql* 600 601Since the text for this plugin is rather long it has been put in a separate 602file: |ft_sql.txt|. 603 604 605TEX *ft-tex-plugin* 606 607If the first line of a *.tex file has the form > 608 %&<format> 609then this determined the file type: plaintex (for plain TeX), context (for 610ConTeXt), or tex (for LaTeX). Otherwise, the file is searched for keywords to 611choose context or tex. If no keywords are found, it defaults to plaintex. 612You can change the default by defining the variable g:tex_flavor to the format 613(not the file type) you use most. Use one of these: > 614 let g:tex_flavor = "plain" 615 let g:tex_flavor = "context" 616 let g:tex_flavor = "latex" 617Currently no other formats are recognized. 618 619 620 vim:tw=78:ts=8:ft=help:norl: 621