tpm/HOW_TO_PLUGIN.md

109 lines
3.0 KiB
Markdown
Raw Normal View History

2014-05-21 06:29:20 -04:00
# How to create Tmux plugins
Creating a new plugin is easy.
For demonstration purposes we'll create a simple plugin that lists all
installed TPM plugins. Yes, a plugin that lists plugins :) We'll bind that to
`prefix + T`.
2015-07-06 20:17:58 -04:00
The source code for this example plugin can be found
[here](https://github.com/tmux-plugins/tmux-example-plugin).
2014-05-21 06:29:20 -04:00
### 1. create a new git project
TPM depends on git for downloading and updating plugins.
To create a new git project:
$ mkdir tmux_my_plugin
$ cd tmux_my_plugin
$ git init
### 2. create a `*.tmux` plugin run file
When it sources a plugin, TPM executes all `*.tmux` files in your plugins'
directory. That's how plugins are run.
Create a plugin run file in plugin directory:
$ touch my_plugin.tmux
$ chmod +x my_plugin.tmux
2015-07-06 20:03:05 -04:00
You can have more than one `*.tmux` file, and all will get executed. However, usually
you'll need just one.
2014-05-21 06:29:20 -04:00
### 3. create a plugin key binding
We want the behavior of the plugin to trigger when a user hits `prefix + T`.
2014-05-21 06:52:54 -04:00
Key `T` is chosen because:
- it's "kind of" a mnemonic for `TPM`
2014-05-21 06:29:20 -04:00
- the key is not used by Tmux natively. Tmux man page, KEY BINDINGS section
2015-07-06 20:03:05 -04:00
contains a list of all the bindings Tmux uses. There's plenty of unused keys
and we don't want to override any Tmux default binding,
2014-05-21 06:29:20 -04:00
Open the plugin run file in your favorite text editor:
$ vim my_plugin.tmux
# or
$ subl my_plugin.tmux
Put the following content in the file:
2014-05-21 06:52:54 -04:00
#!/usr/bin/env bash
2014-05-21 06:29:20 -04:00
CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
tmux bind-key T run-shell "$CURRENT_DIR/scripts/tmux_list_plugins.sh"
As you can see, plugin run file is a simple bash script that sets up binding.
2015-07-06 20:03:05 -04:00
When pressed, `prefix + T` will execute another shell script:
2014-05-21 06:29:20 -04:00
`tmux_list_plugins.sh`. That script should be in `scripts/` directory -
relative to the plugin run file.
2014-05-21 06:52:54 -04:00
### 4. listing plugins
2014-05-21 06:29:20 -04:00
2015-07-06 20:03:05 -04:00
Now that we have the binding, let's create a script that's invoked with
2014-05-21 06:29:20 -04:00
`prefix + T`.
$ mkdir scripts
$ touch scripts/tmux_list_plugins.sh
$ chmod +x scripts/tmux_list_plugins.sh
And here's the script content:
2014-05-21 06:52:54 -04:00
#!/usr/bin/env bash
2014-05-21 06:29:20 -04:00
2015-07-06 20:03:05 -04:00
# fetching the directory where plugins are installed
plugin_path="$(tmux show-env -g TMUX_PLUGIN_MANAGER_PATH | cut -f2 -d=)"
2014-05-21 06:29:20 -04:00
2015-07-06 20:03:05 -04:00
# listing installed plugins
ls -1 "$plugin_path"
2014-05-21 06:29:20 -04:00
### 5. try it out
2015-07-06 20:03:05 -04:00
To see if this works, execute the plugin run file:
2014-05-21 06:29:20 -04:00
$ ./my_plugin.tmux
That should set up the key binding. Now hit `prefix + T` and see if it works.
### 6. publish the plugin
2015-07-06 20:03:05 -04:00
When everything is ready, push the plugin to an online git repository,
preferably Github.
2014-05-21 06:29:20 -04:00
Other users can install your plugin by just adding plugin git URL to the
2015-07-06 20:03:05 -04:00
`@plugin` list in their `.tmux.conf`.
2014-05-21 06:29:20 -04:00
If the plugin is on Github, your users will be able to use the shorthand of
`github_username/repository`.
### Conclusion
Hopefully, that was easy. As you can see, it's mostly shell scripting.
2015-07-06 20:03:05 -04:00
You can use other scripting languages (ruby, phyton etc) but plain old shell
is preferred because of portability.