Using Lua plugins

This page is meant to provide quick overview about plugins to help one start using them. Keep in mind that Lua plugins feature is experimental until v1.0.

Reference Documentation

If you have a version with support for plugins installed, you have the documentation. If 'vimhelp' option is set, you can access it by running :help vifm-lua.txt command. Otherwise, you might need to open the file manually with vim /usr/share/vifm/vim-doc/doc/vifm-lua.txt or equivalent.

The latest version can be found at [1], but keep in mind that it's better to use local documentation as it should match your local version of the application.

Motivation and Design

The documentation linked above starts with explanation of status, motivation and design. You can find details there, but the basics are below.

Overview

Vifm bundles Lua 5.4.* which is used to execute plugins. There are no new dependencies and the Lua version is fixed across platforms and future releases.

Plugins are just directories inside $VIFM/plugins/ (think ~/.config/vifm/plugins/ or ~/.vifm/plugins/), which should have init.lua file that returns a table to be recognized as a valid plugin. They are handled similar to regular Lua modules elsewhere and can consist of multiple Lua-files.

Installation

Copying a plugin directory under $VIFM/plugins/ is all there is, very similar how you install plugins in Vim when they have separate directories. Plugins are reloaded by :restart command, so you don't need to restart Vifm instance to pick up a newly installed plugin or changes to an already installed one.

If a plugin is a single file, just saving its contents as $VIFM/plugins/pickaname/init.lua is enough (at least as of v0.12.1, some metadata might be required later).

Uninstallation

Remove plugin directory to uninstall the plugin permanently or use plugin blacklist plugin-name command in your vifmrc to disable it temporarily.

Configuration

At the moment configuration is limited to environment variables (via let) and running plugin-provided :commands after forcing loading them in vifmrc via plugin load. In some cases it might be useful to check Lua handler's presence via if has('#plugin#handler'). Example:

plugin load

if has('#sbar#fmt')
    set statusline=#sbar#fmt

    " current session, if any
    sbar left $session
    " file name
    sbar left %t
    " file attributes
    sbar right %A
    " human readable cumulative file size
    sbar right %5E
    " file modification date and time
    sbar right %d
endif

Available Plugins

This is still early in development, so you won't find much. That said, the API developed in response to real-world use cases where other solutions don't fit and some plugins are written to test things out or demonstrate API usage. Latest version of these sample plugins is in [2], but it might be better to use corresponding directory of the release that matches to your application's version to avoid compatibility issues.

When Plugins are Useful

The API is far from being comprehensive at the moment, but there are already some things which plugins do better or that only plugins can do. Use cases include:

• Builtin-like :commands and keys
  • keys handing counts, registers and selectors
  • new selectors
  • custom commands with completion

• Better integration with other tools
  • choosing files based on some computational criteria and running an external command on them
  • running external commands and handling their results
  • integrate external apps by keeping track of their state in a plugin

• Customizations
  • custom columns
  • dynamic format of status line
  • file previewers written in Lua
  • handling editing request to accommodate your favourite editor