Filetype.vim

Filetype.vim is the name of the file that is used by the filetype plugin (Category:Filetype).

File Structure

Custom filetype.vim files should always have the following structure:

if exists("did_load_filetypes")
  finish
endif
augroup filetypedetect
  " local filetype changes 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
  " local filetype changes go here
augroup END

because did_load_filetypes will be set before execution gets to the after files. Using the suffixes _userafter and _machineafter as appropriate will prevent one from interfering with the other.

File Contents

Between augroup filetypedetect and augroup END you will have one or more au[tocmd] directives, registered against the BufNewFile and BufRead events, to assign the filetype.

Common rule formats

The following examples are primarily taken from the Vim default ruleset on Vim 7.1.

Always match a specified file extension

au BufNewFile,BufRead *.bat,*.sys 	setf dosbatch

Always assigns the dosbatch filetype to any file ending in .bat or .sys.

Match conditionally on a file extension (simple)

au BufNewFile,BufRead *.cmd 	if getline(1) =~ '^/\*' | setf rexx | else | setf dosbatch | endif

If the first line of a .cmd file begins with /* then assign the filetype rexx, otherwise assign the filetype dosbatch.

Match conditionally on a file extension for override (simple)

au! BufRead,BufNewFile *.bat 	if getline(1) =~ '--\*-Perl-\*--' | setf perl | endif

If the first line of a .bat file begins with --*-Perl-*-- then assign the filetype perl, otherwise do nothing and continue processing rules. (Referenced from Editing ActiveState Perl batch files.)

Match conditionally on a file extension (complex)

au BufNewFile,BufRead *.btm 	call s:FTbtm()

func! s:FTbtm()
  if exists("g:dosbatch_syntax_for_btm") && g:dosbatch_syntax_for_btm
    setf dosbatch
  else
    setf btm
  endif
endfunc

When reading a .btm file, if g:dosbatch_syntax_for_btm is defined and non-zero then assign the dosbatch filetype, otherwise assign the btm filetype.

File Locations

The plugin will load filetype.vim file(s) from the runtime path. The first match which calls setf will be the resulting filetype for the affected file. If no rules match, or the rule fails to eventually call setf then rules from successive files will be attempted.

• User-specific primary definitions
  • Contains rules for the current user that should be attempted before any other rule. If your rule is conditional and does not call setf then later rules will still be attempted.
    • Unix: $HOME/.vim/filetype.vim
    • Win32: %USERPROFILE%\vimfiles\filetype.vim
• Machine-local primary definitions
  • Contains rules that should apply to all users on a machine. This file usually requires some sort of administrative rights to edit.
    • $VIM/vimfiles/filetype.vim
• Vim default ruleset
  • Contains rules that are part of the Vim install. DO NOT edit this file.
    • $VIMRUNTIME/filetype.vim
• Machine-local fallback definitions
  • Contains rules that should apply to all users on a machine only if no other rule has matched so far. This is useful when you have a rule that you would want to stop using if a future version of Vim defined a better match.
    • $VIM/vimfiles/after/filetype.vim
• User-specific fallback definitions
  • Contains rules for the current user that should only be attempted if no other rule has matched so far.
    • Unix: $HOME/.vim/after/filetype.vim
    • Win32: %USERPROFILE%\vimfiles\after\filetype.vim

See also

• :help filetype
• :help new-filetype
• :help ft
• :help setf
• :help augroup
• :help autocmd
• :help BufNewFile
• :help BufRead
• :help getline
• :help user-functions
• :help runtimepath
• :help $VIM
• :help $VIMRUNTIME

Comments

Maybe we should mention the "ftdetect" directory. :help ftdetect

Also, on Windows, %HOMEDRIVE%%HOMEPATH% is used before %USERPROFILE% for the location of $HOME. I'm not sure how much of the stuff in :help todo.txt regarding the setting of $HOME in Windows is implemented, but I do know that my Windows installation picks up %HOMEDRIVE%%HOMEPATH% and not %USERPROFILE%.

Looks like you're right. Vim71 uses %HOMEDRIVE%%HOMEPATH%, which is arguably broken (as it has been, neither runas or (presumably) roaming profiles work right), but current implementations don't use %USERPROFILE% at all. I guess it can just be $HOME as a wiki link and in that page a Win32 section explains it. Not sure if I'm more disappointed in Windows or Vim on this one. --JeremyBarton 16:49, 30 September 2008 (UTC)