created 2008 · complexity basic · author JeremyBarton · version 7.0
This tip is a tutorial on the use of the file filetype.vim
which is used to determine the "type" of a file. For example, while editing example.py
the command :set ft?
should display filetype=python
if :filetype indent plugin on
has been used. The file type determines whether any plugins for scripts, indenting rules, or syntax highlighting are loaded. See file type plugins for an overview.
File structure[]
Custom filetype.vim
files should always have the following structure:
if exists("did_load_filetypes") finish endif augroup filetypedetect " au! commands to set the filetype go here augroup END
Files that are being used as fallbacks (in the after
directories) should use a form such as
if exists("did_load_filetypes_userafter") finish endif let did_load_filetypes_userafter = 1 augroup filetypedetect " au! commands to set the filetype go here augroup END
because did_load_filetypes
will be set before the after
files are used. Using the suffixes _userafter
and _systemafter
as appropriate will prevent one from interfering with the other.
File contents[]
Between augroup filetypedetect
and augroup END
there will be one or more autocmd
statements that may assign a filetype when the BufNewFile
and BufRead
events occur (that is, when a new file is created, or when an existing file is read).
Following are some examples to illustrate common scenarios.
Assign the dosbatch
filetype to any file with name ending in .bat
or .sys
:
au! BufNewFile,BufRead *.bat,*.sys setf dosbatch
If the first line of a .cmd
file begins with /*
then assign the filetype rexx
, otherwise assign the filetype dosbatch
:
au! BufNewFile,BufRead *.cmd if getline(1) =~ '^/\*' | setf rexx | else | setf dosbatch | endif
If the first line of a .bat
file contains "--*-Perl-*--
" then assign the filetype perl
, otherwise do nothing and continue processing rules (see tip):
au! BufRead,BufNewFile *.bat if getline(1) =~ '--\*-Perl-\*--' | setf perl | endif
When reading a .btm
file, if the variable g:dosbatch_syntax_for_btm
is defined and non-zero then assign the dosbatch
filetype, otherwise assign the btm
filetype.
au! BufNewFile,BufRead *.btm call s:FTbtm() function! s:FTbtm() if exists("g:dosbatch_syntax_for_btm") && g:dosbatch_syntax_for_btm setf dosbatch else setf btm endif endfunction
File locations[]
The file filetype.vim
is read from directories in the runtime path. The first match which executes :setf
will set the filetype for the file Vim is creating or reading. If no rules execute :setf
then additional filetype.vim
files will be read.
The file locations (in the order that the files are processed) are:
- User-specific primary definitions
- Rules for the current user that should be attempted before any other rule.
$HOME/.vim/filetype.vim
(Unix-based systems)$HOME\vimfiles\filetype.vim
(Windows systems)- System primary definitions
- Rules for all users on a system (usually requires administrative rights to edit).
$VIM/vimfiles/filetype.vim
(all systems)- Vim default ruleset
- Rules that are part of the Vim install (do not edit this file).
$VIMRUNTIME/filetype.vim
(all systems)- System fallback definitions
- Rules for all users if no other rule has matched so far. Useful for a rule that you would want to stop using if a future version of Vim defined a better match.
$VIM/vimfiles/after/filetype.vim
(all systems)- User-specific fallback definitions
- Rules for the current user if no other rule has matched so far.
$HOME/.vim/after/filetype.vim
(Unix-based systems)$HOME\vimfiles\after\filetype.vim
(Windows systems)
In Vim, use commands like the following to check these locations:
:echo $HOME :echo $VIM :echo $VIMRUNTIME
On Windows systems, $HOME
is set from the environment variable HOME
, if defined; or is set by joining variables HOMEDRIVE
and HOMEPATH
, if they are defined. At command prompt (not in Vim), enter set H
to display the environment variables that begin with 'H
'.
Example[]
When using our CSV tip, it is necessary to specify that *.csv
files have the csv
file type. To do this, edit the following file:
$HOME/.vim/filetype.vim
(Unix based systems)$HOME/vimfiles/filetype.vim
(Windows systems – can use forward slash or backslash in Vim)
Check that $HOME
has been defined, and that the $HOME/.vim
directory (Unix) or $HOME/vimfiles
directory (Windows) exists, and you may need to create the filetype.vim
file in that directory.
Contents of user filetype.vim
(which may include other rules):
if exists("did_load_filetypes") finish endif augroup filetypedetect au! BufNewFile,BufRead *.csv setf csv augroup END
As well as configuring filetype.vim
, you may need the following commands (which would normally be in your vimrc) to enable all the features available for a particular file type.
:set nocompatible :filetype indent plugin on :syntax on
References[]
Comments[]
- Possibly mention the "ftdetect" directory. :help ftdetect