Using Lua plugins - Revision history

Xaizek: /* Reference Documentation */ Link to vifm.info for Lua API docs

2025-05-14T09:29:02Z

Reference Documentation: Link to vifm.info for Lua API docs

Xaizek: /* Available Plugins */ Add shellfzf plugin

2025-03-04T14:31:13Z

Available Plugins: Add shellfzf plugin

Xaizek: /* Installation */ Mention that handlers depend on plugin name.

2025-01-20T22:32:56Z

Installation: Mention that handlers depend on plugin name.

Xaizek: /* Available Plugins */ Add list of known other plugins

2024-12-27T14:49:13Z

Available Plugins: Add list of known other plugins

Xaizek: /* Installation */ Describe how to check the plugin was loaded

2024-03-04T09:00:41Z

Installation: Describe how to check the plugin was loaded

Xaizek: /* Installation */ Specify how to use single-file plugins.

2022-10-06T11:35:04Z

Installation: Specify how to use single-file plugins.

Xaizek: Mainly improve structure

2022-09-18T21:56:19Z

Mainly improve structure

Xaizek: Add more details

2022-09-17T11:43:04Z

Add more details

Xaizek: Provide minimal information about plugins

2022-09-17T11:03:43Z

Provide minimal information about plugins

New page

This page is meant to provide quick overview about plugins to help with starting using it. 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 <code>'vimhelp'</code> option is set, you can access it by running <code>:help vifm-lua.txt</code> command. Otherwise, you might need to open the file manually with <code>vim /usr/share/vifm/vim-doc/doc/vifm-lua.txt</code> or equivalent.

The latest version can be found at [https://github.com/vifm/vifm/blob/master/data/vim/doc/app/vifm-lua.txt], 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 <code>$VIFM/plugins/</code> (think <code>~/.config/vifm/plugins/</code> or <code>~/.vifm/plugins/</code>), which should have <code>init.lua</code> 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 <code>$VIFM/plugins/</code> is all there is. Plugins are reloaded by <code>:restart</code> command, so you don't need to restart Vifm instance to pick up newly installed plugin or changes to an already installed one.

=== Uninstallation ===

Remove plugin directory to uninstall the plugin permanently or use <code>plugin blacklist plugin-name</code> command in your <code>vifmrc</code> to disable it temporary.

== 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 and some plugins are written to test things out or demonstrate API usage. Latest version of these sample plugins is in [https://github.com/vifm/vifm/tree/master/data/plugins], but it might be better to use corresponding directory of the release that corresponds to your application's version to avoid compatibility issues.

[[Category:Manual]]

@@ Line 62: / Line 62: @@
 * https://github.com/haolian9/cd.vifm
 * https://github.com/haolian9/reveal.nvim/tree/master/lua/reveal/vifm/reveal
 == When Plugins are Useful ==

@@ Line 21: / Line 21: @@
 Copying a plugin directory under <code>$VIFM/plugins/</code> is all there is, very similar how you install plugins in Vim when they have separate directories.  Plugins are reloaded by <code>:restart</code> 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 <code>$VIFM/plugins/pickaname/init.lua</code> is enough (at least as of v0.12.1, some metadata might be required later).
+If a plugin is a single file, just saving its contents as <code>$VIFM/plugins/pickaname/init.lua</code> is enough (at least as of v0.12.1, some metadata might be required later).  Note, however, that handlers include plugin name as a prefix (e.g., <code>#pluginname#handlername</code>) which needs to be taken into account when invoking them in <code>:filetype</code> or <code>:fileviewer</code> commands.
 ==== Verification ====

← Older revision		Revision as of 14:49, 27 December 2024
Line 57:		Line 57:

	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 [https://github.com/vifm/vifm/tree/master/data/plugins], but it might be better to use corresponding directory of the release that matches to your application's version to avoid compatibility issues.		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 [https://github.com/vifm/vifm/tree/master/data/plugins], but it might be better to use corresponding directory of the release that matches to your application's version to avoid compatibility issues.
		+
		+	Some other plugins:
		+	* https://github.com/psxvoid/vifm-git-mv
		+	* https://github.com/haolian9/cd.vifm
		+	* https://github.com/haolian9/reveal.nvim/tree/master/lua/reveal/vifm/reveal

	== When Plugins are Useful ==		== When Plugins are Useful ==

← Older revision		Revision as of 09:00, 4 March 2024
Line 22:		Line 22:

	If a plugin is a single file, just saving its contents as <code>$VIFM/plugins/pickaname/init.lua</code> is enough (at least as of v0.12.1, some metadata might be required later).		If a plugin is a single file, just saving its contents as <code>$VIFM/plugins/pickaname/init.lua</code> is enough (at least as of v0.12.1, some metadata might be required later).
		+
		+	==== Verification ====
		+
		+	Use [https://vifm.info/vimdoc.shtml#vifm-%3Aplugins :plugins menu] to verify that the plugin was discovered and loaded without errors.

	=== Uninstallation ===		=== Uninstallation ===

← Older revision		Revision as of 11:35, 6 October 2022
Line 20:		Line 20:

	Copying a plugin directory under <code>$VIFM/plugins/</code> is all there is, very similar how you install plugins in Vim when they have separate directories. Plugins are reloaded by <code>:restart</code> command, so you don't need to restart Vifm instance to pick up a newly installed plugin or changes to an already installed one.		Copying a plugin directory under <code>$VIFM/plugins/</code> is all there is, very similar how you install plugins in Vim when they have separate directories. Plugins are reloaded by <code>:restart</code> 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 <code>$VIFM/plugins/pickaname/init.lua</code> is enough (at least as of v0.12.1, some metadata might be required later).

	=== Uninstallation ===		=== Uninstallation ===

@@ Line 5: / Line 5: @@
 If you have a version with support for plugins installed, you have the documentation. If <code>'vimhelp'</code> option is set, you can access it by running <code>:help vifm-lua.txt</code> command. Otherwise, you might need to open the file manually with <code>vim /usr/share/vifm/vim-doc/doc/vifm-lua.txt</code> or equivalent.
-The latest version can be found at [https://github.com/vifm/vifm/blob/master/data/vim/doc/app/vifm-lua.txt], but keep in mind that it's better to use local documentation as it should match your local version of the application.
+The version for the latest release (as well as for other releases) can be found [https://vifm.info/docs/vifm-lua.txt here], 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 ==

@@ Line 1: / Line 1: @@
-This page is meant to provide quick overview about plugins to help with starting using it. Keep in mind that Lua plugins feature is experimental until v1.0.
+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 ==
@@ Line 11: / Line 11: @@
 The documentation linked above starts with explanation of status, motivation and design. You can find details there, but the basics are below.
-=== Overview ===
+== 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.
@@ Line 19: / Line 19: @@
 === Installation ===
-Copying a plugin directory under <code>$VIFM/plugins/</code> is all there is.  Plugins are reloaded by <code>:restart</code> command, so you don't need to restart Vifm instance to pick up newly installed plugin or changes to an already installed one.
+Copying a plugin directory under <code>$VIFM/plugins/</code> is all there is, very similar how you install plugins in Vim when they have separate directories.  Plugins are reloaded by <code>:restart</code> command, so you don't need to restart Vifm instance to pick up a newly installed plugin or changes to an already installed one.
 === Uninstallation ===
 Remove plugin directory to uninstall the plugin permanently or use <code>plugin blacklist plugin-name</code> command in your <code>vifmrc</code> to disable it temporarily.
 == 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 and some plugins are written to test things out or demonstrate API usage. Latest version of these sample plugins is in [https://github.com/vifm/vifm/tree/master/data/plugins], but it might be better to use corresponding directory of the release that corresponds to your application's version to avoid compatibility issues.
+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 [https://github.com/vifm/vifm/tree/master/data/plugins], but it might be better to use corresponding directory of the release that matches to your application's version to avoid compatibility issues.
-At the moment configuration is limited to environment variables (via <code>let</code>) and running plugin-provided :commands after forcing loading them in <code>vifmrc</code> via <code>plugin load</code>.
+== When Plugins are Useful ==
-== When to Write a Plugin ==
+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:
-The plugins are meant to be extensions and are not an alternative way of doing configuration in your <code>vifmrc</code> file (although there are use cases for doing configuration via plugins).
+* Builtin-like :commands and keys
-They are meant to make external helper scripts obsolete, provide ways to interact with external applications or do some non-trivial processing.
+* Better integration with other tools
-Resort to plugins when they can offer you something regular extension mechanisms lack.  There are already number of things which plugins do better or that only plugins can do (processing output of external apps, interacting with them, implementing custom file selectors, columns) and the list should only grow, but the configuration and :commands will remain there.
+* Customizations
 [[Category:Manual]]