usr_43.txt ForVim version 9.2. Last change: 2026 Feb 14 VIM USER MANUALbyBramMoolenaar UsingfiletypesWhen you are editinga file ofa certain type, for exampleaC program orashell script, you often use the same option settings and mappings. Youquickly get tired of manually setting these each time. This chapter explainshow todoit automatically.43.1 Plugins forafiletype43.2 Addingafiletype Next chapter:usr_44.txt Your ownsyntax highlighted Previous chapter:usr_42.txt Add newmenusTable of contents:usr_toc.txt==============================================================================43.1 Plugins forafiletypefiletype-pluginHow to start usingfiletype plugins has already been discussed here:add-filetype-plugin. But you probably are not satisfied with the defaultsettings, because they have been kept minimal. Suppose that forC files youwant to set the'softtabstop' option to 4 and defineamapping toinsertathree-line comment. Youdo this with only two steps:your-runtime-dir1. Create your own runtime directory. OnUnix this usuallyis "~/.vim". In this directory create the "ftplugin" directory:mkdir ~/.vimmkdir ~/.vim/ftplugin When you are not on Unix, check the value of the'runtimepath' option to see where Vim will look for the "ftplugin" directory:set runtimepath You would normally use the first directory name (before the first comma). You might want to prependa directory name to the'runtimepath' option in yourvimrc file if you don't like the default value.2. Create the file "~/.vim/ftplugin/c.vim", with the contents:setlocal softtabstop=4noremap <buffer> <LocalLeader>c o/**************<CR><CR>/<Esc>let b:undo_ftplugin = "setl softtabstop< | unmap <buffer> <LocalLeader>c"Try editingaC file. You should notice that the'softtabstop' optionis setto 4. But when you edit another file it's reset to the default zero. Thatisbecause the ":setlocal" command was used. This sets the'softtabstop' optiononly locally to the buffer. As soonas you edit another buffer,it will beset to the value set for that buffer. Fora new bufferit will get thedefault value or the value from the last ":set" command.Likewise, themapping for "\c" will disappear when editing another buffer.The ":map<buffer>" command createsamapping thatis local to the currentbuffer. This works with anymapping command: ":map!", ":vmap", etc. The<LocalLeader> in themappingis replaced with the value of the"maplocalleader" variable.The line to set b:undo_ftpluginis for when thefiletypeis set to anothervalue. In thatcase you will want toundo your preferences. Theb:undo_ftplugin variableis executedasa command. Watch out for characterswitha special meaning insidea string, suchasa backslash.You can find examples forfiletype plugins in this directory:$VIMRUNTIME/ftplugin/More details aboutwritingafiletypeplugin can be found here:write-plugin.==============================================================================43.2 AddingafiletypeIf you are usinga type of file thatis not recognized by Vim, thisis how togetit recognized. You needa runtime directory of your own. Seeyour-runtime-dir above.Createa file "filetype.vim" which contains anautocommand for your filetype.(Autocommands were explained insection40.3.) Example:augroup filetypedetectau BufNewFile,BufRead *.xyzsetf xyzaugroup ENDThis will recognize all files thatend in ".xyz"as the "xyz" filetype. The":augroup" commandsput thisautocommand in the "filetypedetect" group. Thisallows removing allautocommands forfiletype detection when doing ":filetypeoff". The "setf" command will set the'filetype' option to its argument,unlessit was set already. This will make sure that'filetype' isn't settwice.You can use many different patterns to match the name of your file. Directorynames can also be included. Seeautocmd-patterns. For example, the filesunder "/usr/share/scripts/" are all "ruby" files, but don't have the expectedfile name extension. Adding this to the example above:augroup filetypedetectau BufNewFile,BufRead *.xyzsetf xyzau BufNewFile,BufRead /usr/share/scripts/*setf rubyaugroup ENDHowever, if you now edita file /usr/share/scripts/README.txt, thisis notaruby file. The danger ofapattern ending in "*"is thatit quickly matchestoo many files. To avoid trouble with this,put the filetype.vim file inanother directory, one thatisat theend of'runtimepath'. ForUnix forexample, you could use "~/.vim/after/filetype.vim". You nowput the detection of text files in ~/.vim/filetype.vim:augroup filetypedetectau BufNewFile,BufRead *.txtsetf textaugroup ENDThat fileis found in'runtimepath' first. Then use this in~/.vim/after/filetype.vim, whichis found last:augroup filetypedetectau BufNewFile,BufRead /usr/share/scripts/*setf rubyaugroup ENDWhat will happen nowis that Vim searches for "filetype.vim" files in eachdirectory in'runtimepath'. First ~/.vim/filetype.vimis found. Theautocommand to catch *.txt filesis defined there. Then Vim finds thefiletype.vim file in $VIMRUNTIME, whichis halfway'runtimepath'. Finally~/.vim/after/filetype.vimis found and theautocommand for detectingrubyfiles in /usr/share/scriptsis added. When you now edit /usr/share/scripts/README.txt, theautocommands arechecked in the order in which they were defined. The *.txtpattern matches,thus "setf text"is executed to set thefiletype to "text". Thepattern forruby matches too, and the "setfruby"is executed. But since'filetype' wasalready set to "text", nothing happens here. When you edit the file /usr/share/scripts/foobar the sameautocommands arechecked. Only the one forruby matches and "setfruby" sets'filetype' toruby.RECOGNIZING BY CONTENTSIf your file cannot be recognized by its file name, you might be able torecognizeit by its contents. For example, manyscript files start withaline like:#!/bin/xyzTo recognize thisscript createa file "scripts.vim" in your runtime directory(same place where filetype.vim goes). It might look like this:if did_filetype() finishendifif getline(1) =~ '^#!.*[/\\]xyz\>' setf xyzendifThe first check withdid_filetype()is to avoid that you will check thecontents of files for which thefiletype was already detected by the filename. That avoids wasting time on checking the file when the "setf" commandwon'tdo anything. The scripts.vim fileis sourced by anautocommand in the defaultfiletype.vim file. Therefore, the order of checks is:1. filetype.vim files before$VIMRUNTIME in'runtimepath'2. first part of $VIMRUNTIME/filetype.vim3. all scripts.vim files in'runtimepath'4. remainder of $VIMRUNTIME/filetype.vim5. filetype.vim files after$VIMRUNTIME in'runtimepath'If thisis not sufficient for you, add anautocommand that matches all filesand sourcesascript or executesa function to check the contents of the file.==============================================================================Next chapter:usr_44.txt Your ownsyntax highlightedCopyright: seemanual-copyright vim:tw=78:ts=8:noet:ft=help:norl: