| blob | 4b5ac9e2c52cecacc1e10c7372bb261410f50396 |
1 *filetype.txt* For Vim version 7.2c. Last change: 2008 Jul 15
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Filetypes *filetype* *file-type*
9 1. Filetypes |filetypes|
10 2. Filetype plugin |filetype-plugins|
11 3. Docs for the default filetype plugins. |ftplugin-docs|
13 Also see |autocmd.txt|.
15 {Vi does not have any of these commands}
17 ==============================================================================
18 1. Filetypes *filetypes* *file-types*
20 Vim can detect the type of file that is edited. This is done by checking the
21 file name and sometimes by inspecting the contents of the file for specific
22 text.
24 *:filetype* *:filet*
25 To enable file type detection, use this command in your vimrc: >
26 :filetype on
27 Each time a new or existing file is edited, Vim will try to recognize the type
28 of the file and set the 'filetype' option. This will trigger the FileType
29 event, which can be used to set the syntax highlighting, set options, etc.
31 NOTE: Filetypes and 'compatible' don't work together well, since being Vi
32 compatible means options are global. Resetting 'compatible' is recommended,
33 if you didn't do that already.
35 Detail: 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.
49 To add your own file types, see |new-filetype| below. To search for help on a
50 filetype 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
56 If the file type is not detected automatically, or it finds the wrong type,
57 you can either set the 'filetype' option manually, or add a modeline to your
58 file. Example, for an IDL file use the command: >
59 :set filetype=idl
61 or add this |modeline| to the file:
62 /* vim: set filetype=idl : */ ~
64 *:filetype-plugin-on*
65 You can enable loading the plugin files for specific file types with: >
66 :filetype plugin on
67 If filetype detection was not switched on yet, it will be as well.
68 This actually loads the file "ftplugin.vim" in 'runtimepath'.
69 The result is that when a file is edited its plugin file is loaded (if there
70 is one for the detected filetype). |filetype-plugin|
72 *:filetype-plugin-off*
73 You can disable it again with: >
74 :filetype plugin off
75 The filetype detection is not switched off then. But if you do switch off
76 filetype detection, the plugins will not be loaded either.
77 This actually loads the file "ftplugof.vim" in 'runtimepath'.
79 *:filetype-indent-on*
80 You can enable loading the indent file for specific file types with: >
81 :filetype indent on
82 If filetype detection was not switched on yet, it will be as well.
83 This actually loads the file "indent.vim" in 'runtimepath'.
84 The result is that when a file is edited its indent file is loaded (if there
85 is one for the detected filetype). |indent-expression|
87 *:filetype-indent-off*
88 You can disable it again with: >
89 :filetype indent off
90 The filetype detection is not switched off then. But if you do switch off
91 filetype detection, the indent files will not be loaded either.
92 This actually loads the file "indoff.vim" in 'runtimepath'.
93 This disables auto-indenting for files you will open. It will keep working in
94 already opened files. Reset 'autoindent', 'cindent', 'smartindent' and/or
95 'indentexpr' to disable indenting in an opened file.
97 *:filetype-off*
98 To disable file type detection, use this command: >
99 :filetype off
100 This will keep the flags for "plugin" and "indent", but since no file types
101 are being detected, they won't work until the next ":filetype on".
104 Overview: *:filetype-overview*
106 command 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
116 To see the current status, type: >
117 :filetype
118 The output looks something like this: >
119 filetype detection:ON plugin:ON indent:OFF
121 The file types are also used for syntax highlighting. If the ":syntax on"
122 command is used, the file type detection is installed too. There is no need
123 to do ":filetype on" after ":syntax on".
125 To disable one of the file types, add a line in your filetype file, see
126 |remove-filetype|.
128 *filetype-detect*
129 To detect the file type again: >
130 :filetype detect
131 Use this if you started with an empty file and typed text that makes it
132 possible to detect the file type. For example, when you entered this in a
133 shell script: "#!/bin/csh".
134 When filetype detection was off, it will be enabled first, like the "on"
135 argument was used.
137 *filetype-overrule*
138 When the same extension is used for two filetypes, Vim tries to guess what
139 kind of file it is. This doesn't always work. A number of global variables
140 can be used to overrule the filetype used for certain extensions:
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|
155 *filetype-ignore*
156 To avoid that certain files are being inspected, the g:ft_ignore_pat variable
157 is used. The default value is set like this: >
158 :let g:ft_ignore_pat = '\.\(Z\|gz\|bz2\|zip\|tgz\)$'
159 This means that the contents of compressed files are not inspected.
161 *new-filetype*
162 If a file type that you want to use is not detected yet, there are four ways
163 to add it. In any way, it's better not to modify the $VIMRUNTIME/filetype.vim
164 file. It will be overwritten when installing a new version of Vim.
166 A. 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
187 < 3. To use the new filetype detection you must restart Vim.
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.
193 B. If you want to detect your file after the default file type checks.
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
205 C. 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
224 < 3. To use the new filetype detection you must restart Vim.
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*
231 D. If your filetype can only be detected by inspecting the contents of the
232 file.
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.
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.
258 *remove-filetype*
259 If a file type is detected that is wrong for you, install a filetype.vim or
260 scripts.vim to catch it (see above). You can set 'filetype' to a non-existing
261 name to avoid that it will be set later anyway: >
262 :set filetype=ignored
264 If you are setting up a system with many users, and you don't want each user
265 to add/remove the same filetypes, consider writing the filetype.vim and
266 scripts.vim files in a runtime directory that is used for everybody. Check
267 the 'runtimepath' for a directory to use. If there isn't one, set
268 'runtimepath' in the |system-vimrc|. Be careful to keep the default
269 directories!
272 *autocmd-osfiletypes*
273 On operating systems which support storing a file type with the file, you can
274 specify that an autocommand should only be executed if the file is of a
275 certain type.
277 The actual type checking depends on which platform you are running Vim
278 on; see your system's documentation for details.
280 To use osfiletype checking in an autocommand you should put a list of types to
281 match in angle brackets in place of a pattern, like this: >
283 :au BufRead *.html,<&faf;HTML> runtime! syntax/html.vim
285 This will match:
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.
292 You can also specify a type and a pattern at the same time (in which case they
293 must both match): >
295 :au BufRead <&fff>diff*
297 This will match files of type "&fff" whose names start with "diff".
299 Note that osfiletype checking is skipped if Vim is compiled without the
300 |+osfiletype| feature.
302 *plugin-details*
303 The "plugin" directory can be in any of the directories in the 'runtimepath'
304 option. All of these directories will be searched for plugins and they are
305 all loaded. For example, if this command: >
307 set runtimepath
309 produces this output:
311 runtimepath=/etc/vim,~/.vim,/usr/local/share/vim/vim60 ~
313 then Vim will load all plugins in these directories and below:
315 /etc/vim/plugin/ ~
316 ~/.vim/plugin/ ~
317 /usr/local/share/vim/vim60/plugin/ ~
319 Note that the last one is the value of $VIMRUNTIME which has been expanded.
321 What if it looks like your plugin is not being loaded? You can find out what
322 happens when Vim starts up by using the |-V| argument: >
324 vim -V2
326 You will see a lot of messages, in between them is a remark about loading the
327 plugins. It starts with:
329 Searching for "plugin/**/*.vim" in ~
331 There you can see where Vim looks for your plugin scripts.
333 ==============================================================================
334 2. Filetype plugin *filetype-plugins*
336 When loading filetype plugins has been enabled |:filetype-plugin-on|, options
337 will be set and mappings defined. These are all local to the buffer, they
338 will not be used for other files.
340 Defining mappings for a filetype may get in the way of the mappings you
341 define yourself. There are a few ways to avoid this:
342 1. 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>|.
348 2. 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.
356 3. 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
361 4. Disable defining mappings for all filetypes by setting a variable: >
362 :let no_plugin_maps = 1
363 <
365 *ftplugin-overrule*
366 If a global filetype plugin does not do exactly what you want, there are three
367 ways to change this:
369 1. 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.
378 2. 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.
387 3. 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.
393 ==============================================================================
394 3. Docs for the default filetype plugins. *ftplugin-docs*
397 CHANGELOG *ft-changelog-plugin*
399 Allows for easy entrance of Changelog entries in Changelog files. There are
400 some commands, mappings, and variables worth exploring:
402 Options:
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.
407 Commands:
408 NewChangelogEntry Adds a new Changelog entry in an intelligent fashion
409 (see below).
411 Local mappings:
412 <Leader>o Starts a new Changelog entry in an equally intelligent
413 fashion (see below).
415 Global 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.
425 Variables:
426 g:changelog_timeformat Deprecated; use g:changelog_dateformat instead.
427 g: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.
432 g: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 <
442 g: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 <
458 g: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 <
467 g: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.
477 g: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.
485 b:changelog_name *b:changelog_name*
486 Name of the ChangeLog file to look for.
487 The default is 'ChangeLog'.
489 b: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.
498 b: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:.
508 The Changelog entries are inserted where they add the least amount of text.
509 After figuring out the current date and user, the file is searched for an
510 entry beginning with the current date and user and if found adds another item
511 under it. If not found, a new entry and item is prepended to the beginning of
512 the Changelog.
515 FORTRAN *ft-fortran-plugin*
517 Options:
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|.
524 For further discussion of fortran_have_tabs and the method used for the
525 detection of source format see |ft-fortran-syntax|.
528 GIT COMMIT *ft-gitcommit-plugin*
530 One command, :DiffGitCached, is provided to show a diff of the current commit
531 in the preview window. It is equivalent to calling "git diff --cached" plus
532 any arguments given to the command.
535 MAIL *ft-mail-plugin*
537 Options:
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|.
546 Local 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.
552 MAN *ft-man-plugin* *:Man*
554 Displays a manual page in a nice way. Also see the user manual
555 |find-manpage|.
557 To start using the ":Man" command before any manual page was loaded, source
558 this script from your startup vimrc file: >
560 runtime ftplugin/man.vim
562 Options:
563 'iskeyword' the '.' character is added to be able to use CTRL-] on the
564 manual page name.
566 Commands:
567 Man {name} Display the manual page for {name} in a window.
568 Man {number} {name}
569 Display the manual page for {name} in a section {number}.
571 Global mapping:
572 <Leader>K Displays the manual page for the word under the cursor.
574 Local mappings:
575 CTRL-] Jump to the manual page for the word under the cursor.
576 CTRL-T Jump back to the previous manual page.
579 PDF *ft-pdf-plugin*
581 Two maps, <C-]> and <C-T>, are provided to simulate a tag stack for navigating
582 the PDF. The following are treated as tags:
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
589 These maps can be disabled with >
590 :let g:no_pdf_maps = 1
591 <
593 RPM SPEC *ft-spec-plugin*
595 Since the text for this plugin is rather long it has been put in a separate
596 file: |pi_spec.txt|.
599 SQL *ft-sql*
601 Since the text for this plugin is rather long it has been put in a separate
602 file: |ft_sql.txt|.
605 TEX *ft-tex-plugin*
607 If the first line of a *.tex file has the form >
608 %&<format>
609 then this determined the file type: plaintex (for plain TeX), context (for
610 ConTeXt), or tex (for LaTeX). Otherwise, the file is searched for keywords to
611 choose context or tex. If no keywords are found, it defaults to plaintex.
612 You 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"
617 Currently no other formats are recognized.
620 vim:tw=78:ts=8:ft=help:norl: