DOCSEARCHbyAlgolia
Submit Docs

Tmux Plugin Manager (TPM)

repository·master·Indexed 12 days ago

https://github.com/tmux-plugins/tpm

A tool for installing and loading tmux plugins by automating the cloning of git repositories and sourcing them within the tmux environment. Supports plugin management via key bindings (prefix + I, prefix + U) or CLI scripts for installation, updating, and cleaning. Requires tmux version 1.9 or higher, git, and bash.

Tokens
3.2K
Snippets
14
Records
19
Agent score
91%

What's inside TPM

  1. How to create a Tmux plugin

    master

    Tmux plugins are essentially shell scripts that TPM (Tmux Plugin Manager) executes when the plugin is sourced. To create a plugin, you need a git repository containing one or more *.tmux files. TPM automatically executes all *.tmux files found in the plugin's directory.

    Plugin Structure

    A standard plugin structure typically includes:

    • A *.tmux file in the root directory (the plugin run file).
    • A scripts/ directory containing the actual logic/shell scripts.

    Implementation Steps

    1. Initialize a Git project: TPM requires plugins to be git repositories.
    2. Create a plugin run file: Create a file ending in .tmux (e.g., my_plugin.tmux) and make it executable (chmod u+x). This file is responsible for setting up the plugin's environment, such as key bindings.
    3. Define logic: Use the plugin run file to bind tmux keys to shell scripts located within your plugin directory.
    4. Publish: Push your code to a git provider (like GitHub). Users can then install it using the @plugin syntax in their .tmux.conf.
    # Example plugin run file (my_plugin.tmux)
#!/usr/bin/env bash

CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
tmux bind-key T run-shell "$CURRENT_DIR/scripts/tmux_list_plugins.sh"

  2. Update plugins via the command line

    master

    You can update your plugins using the update_plugins script. You can either update every installed plugin at once or target a specific plugin by name.

    # Update all installed plugins
~/.tmux/plugins/tpm/bin/update_plugins all

# Update a single specific plugin
~/.tmux/plugins/tpm/bin/update_plugins tmux-sensible

  3. Automatically install TPM and plugins on a new machine

    master

    To ensure tpm and your plugins are automatically installed when starting tmux (useful when cloning dotfiles to a new machine), add a conditional check to your .tmux.conf. This snippet checks if the ~/.tmux/plugins/tpm directory exists; if it does not, it clones the tpm repository and immediately runs the plugin installation script.

    Important: This snippet must be placed in .tmux.conf before the line that initializes TPM (run '~/.tmux/plugins/tpm/tpm').

    if "test ! -d ~/.tmux/plugins/tpm" \
   "run 'git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm && ~/.tmux/plugins/tpm/bin/install_plugins'"

  4. Install and Update plugins

    master

    Once you have added a plugin to your ~/.tmux.conf, use the following key bindings to manage them:

    To Install New Plugins:

    1. Add the set -g @plugin '...' line to your config.
    2. Press prefix + I (capital i). This fetches the plugin and clones it to ~/.tmux/plugins/.

    To Update Plugins:

    • Press prefix + U (capital u).

  5. Change the TPM plugins installation directory

    master

    By default, TPM installs plugins into a plugins/ subfolder located within $XDG_CONFIG_HOME/tmux/ (if a tmux.conf is present there) or ~/.tmux/.

    To use a custom directory for plugin installation, set the TMUX_PLUGIN_MANAGER_PATH environment variable in your .tmux.conf. You must also update the TPM initialization run command to point to the new location of the tpm script.

    # 1. Set the custom installation path for plugins
set-environment -g TMUX_PLUGIN_MANAGER_PATH '/some/other/path/'

# 2. Initialize TPM from its new location
# Ensure this line is at the very bottom of your .tmux.conf
run '/some/other/path/tpm/tpm'

  7. Install Tmux Plugin Manager (TPM)

    master

    To install TPM, clone the repository into your tmux plugins directory and configure your tmux configuration file.

    Requirements:

    • tmux version 1.9 or higher
    • git
    • bash

    Steps:

    1. Clone the repository:
      git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
    2. Add the initialization line to the very bottom of your ~/.tmux.conf (or $XDG_CONFIG_HOME/tmux/tmux.conf).
    3. Reload your tmux environment to source TPM.
    # 1. Clone TPM
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# 2. Reload tmux (if already running)
tmux source ~/.tmux.conf

  9. Uninstall plugins

    master

    To remove plugins, follow these steps:

    1. Remove or comment out the set -g @plugin '...' line from your ~/.tmux.conf.
    2. Press prefix + alt + u (lowercase u). This removes plugins that are no longer present in your configuration list.

    Alternatively, you can manually delete the plugin directory from ~/.tmux/plugins/.

  10. Configure plugins in ~/.tmux.conf

    master

    Plugins are managed by adding set -g @plugin commands to your ~/.tmux.conf. You must also include the TPM initialization line at the end of the file.

    Plugin Syntax Examples:

    • Standard GitHub plugin: set -g @plugin 'github_username/plugin_name'
    • Specific branch: set -g @plugin 'github_username/plugin_name#branch'
    • Git SSH: set -g @plugin 'git@github.com:user/plugin'
    • Bitbucket: set -g @plugin 'git@bitbucket.com:user/plugin'
    # List of plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'

# Other examples:
# set -g @plugin 'github_username/plugin_name'
# set -g @plugin 'github_username/plugin_name#branch'
# set -g @plugin 'git@github.com:user/plugin'
# set -g @plugin 'git@bitbucket.com:user/plugin'

# Initialize TMUX plugin manager (keep this line at the very bottom of tmux.conf)
run '~/.tmux/plugins/tpm/tpm'

  11. Fix 'returned 2' error on Windows/Cygwin (Line Endings)

    master

    If tpm returns error code 2, it is likely due to Windows line endings (CRLF) being introduced by git's core.autocrlf setting. You must convert the files in your .tmux directory to Unix newline characters (LF).

    find ~/.tmux -type d -name '.git*' -prune -o -type f -print0 | xargs -0 dos2unix

  12. Fix TPM not working with custom tmux config files

    master

    If you use the tmux -f /path/to/my_tmux.conf flag to start tmux, tpm may fail to load plugins. To resolve this, switch from the standard set -g @plugin syntax to the @tpm_plugins list syntax.

    1. Remove all set -g @plugin lines from your configuration.
    2. Define your plugins using the set -g @tpm_plugins command.
    3. Ensure the tpm initialization line is at the very bottom of your file.
    4. Reload your environment using tmux source /path/to/my_tmux.conf.
    # List of plugins
set -g @tpm_plugins '          \
  tmux-plugins/tpm             \
  tmux-plugins/tmux-sensible   \
  tmux-plugins/tmux-resurrect  \
'

# Initialize TMUX plugin manager (keep this line at the very bottom of tmux.conf)
run '~/.tmux/plugins/tpm/tpm'