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.
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 , 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.
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/), 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.
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).
Remove plugin directory to uninstall the plugin permanently or use
plugin blacklist plugin-name command in your
vifmrc to disable it temporarily.
At the moment configuration is limited to environment variables (via
let) and running plugin-provided :commands after forcing loading them in
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
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 , 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
- custom columns
- dynamic format of status line
- file previewers written in Lua
- handling editing request to accommodate your favourite editor