vim.filetype

Get a line range from the buffer.

Get a single line from the buffer.

Check whether a string matches any of the given Lua patterns.

Get the next non-whitespace line in the buffer.

Gets a best-effort set of all "known" filetypes, discovered by:

• getcompletion()
• vim.filetype internal registry

Check whether the given string matches the Vim regex pattern.

Add new filetype mappings.

Filetype mappings can be added either by extension or by filename (either the "tail" or the full file path). The full file path is checked first, followed by the file name. If a match is not found using the filename, then the filename is matched against the list of |lua-pattern|s (sorted by priority) until a match is found. Lastly, if pattern matching does not find a filetype, then the file extension is used. Extension mappings match only the text after the final dot in the filename.

The filetype can be either a string (in which case it is used as the filetype directly) or a function. If a function, it takes the full path and buffer number of the file as arguments (along with captures from the matched pattern, if any) and should return a string that will be used as the buffer's filetype. Optionally, the function can return a second function value which, when called, modifies the state of the buffer. This can be used to, for example, set filetype-specific buffer variables. This function will be called by Nvim before setting the buffer's filetype.

Filename patterns can specify an optional priority to resolve cases when a file path matches multiple patterns. Higher priorities are matched first. When omitted, the priority defaults to 0. A pattern can contain environment variables of the form "${SOME_VAR}" that will be automatically expanded. If the environment variable is not set, the pattern won't be matched.

See $VIMRUNTIME/lua/vim/filetype.lua for more examples.

Example:

vim.filetype.add({
  extension = {
    foo = 'fooscript',
    bar = function(path, bufnr)
      if some_condition() then
        return 'barscript', function(bufnr)
          -- Set a buffer variable
          vim.b[bufnr].barscript_version = 2
        end
      end
      return 'bar'
    end,
  },
  filename = {
    ['.foorc'] = 'toml',
    ['/etc/foo/config'] = 'toml',
  },
  pattern = {
    ['.*/etc/foo/.*'] = 'fooscript',
    -- Using an optional priority
    ['.*/etc/foo/.*%.conf'] = { 'dosini', { priority = 10 } },
    -- A pattern containing an environment variable
    ['${XDG_CONFIG_HOME}/foo/git'] = 'git',
    ['.*README.(%a+)'] = function(path, bufnr, ext)
      if ext == 'md' then
        return 'markdown'
      elseif ext == 'rst' then
        return 'rst'
      end
    end,
  },
})

To add a fallback match on contents, use

vim.filetype.add {
  pattern = {
    ['.*'] = {
      function(path, bufnr)
        local content = vim.api.nvim_buf_get_lines(bufnr, 0, 1, false)[1] or ''
        if vim.regex([[^#!.*\\<mine\\>]]):match_str(content) ~= nil then
          return 'mine'
        elseif vim.regex([[\\<drawing\\>]]):match_str(content) ~= nil then
          return 'drawing'
        end
      end,
      { priority = -math.huge },
    },
  },
}

Perform filetype detection.

The filetype can be detected using one of three methods:

1. Using an existing buffer
2. Using only a file name
3. Using only file contents

Of these, option 1 provides the most accurate result as it uses both the buffer's filename and (optionally) the buffer contents. Options 2 and 3 can be used without an existing buffer, but may not always provide a match in cases where the filename (or contents) cannot unambiguously determine the filetype.

Each of the three options is specified using a key to the single argument of this function. Example:

-- Using a buffer number
vim.filetype.match({ buf = 42 })

-- Override the filename of the given buffer
vim.filetype.match({ buf = 42, filename = 'foo.c' })

-- Using a filename without a buffer
vim.filetype.match({ filename = 'main.lua' })

-- Using file contents
vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })

Get the default option value for a {filetype}.

The returned value is what would be set in a new buffer after 'filetype' is set, meaning it should respect all FileType autocmds and ftplugin files.

Example:

vim.filetype.get_option('vim', 'commentstring')

Note: this uses |nvimgetoption_value()| but caches the result. This means |ftplugin| and |FileType| autocommands are only triggered once and may not reflect later changes.

Inspect the current state of the filetype registry.

Returns a copy of the internal tables used for filetype detection by extension, filename, or pattern. Note: Due to the dynamic nature of filetype detection, this is only useful for checking whether a certain extension, filename, or pattern has been registered so far. In addition, the pattern table is in an internal format optimized for fast lookup. Prefer |vim.filetype.match()| for checking the detected filetype for a given pattern.