Filetype.vim

Tip 1606 Printable Monobook Previous Next

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

• :help filetype
• :help new-filetype
• :help 'filetype'
• :help :setf
• :help 'runtimepath'

Comments

• Possibly mention the "ftdetect" directory. :help ftdetect