stonevil / tmux-fzf

Use fzf to manage your tmux work environment!

Features

• Manage sessions (attach, detach*, rename, kill*).
• Manage windows (switch, link, move, swap, rename, kill*).
• Manage panes (switch, break, join*, swap, layout, kill*, resize).
• Multiple selection (support for actions marked by *).
• Search commands and append to command prompt.
• Search key bindings and execute.
• User menu.
• Popup window support.

Installation

Requirements

• GNU bash
• GNU sed
• junegunn/fzf

Note: Please use this command to check whether tmux is able to find fzf #1: tmux run-shell -b 'command -v fzf'

Install via TPM

Add this line to your ~/.tmux.conf

set -g @plugin 'sainnhe/tmux-fzf'

Reload configuration, then press prefix + I.

Usage

To launch tmux-fzf, press prefix + F (Shift+F).

This plugin supports multiple selection for some actions, you can press TAB and Shift-TAB to mark multiple items.

You can bind a key to preselect an action. See #6 for more information.

Most actions don't need to be explained, but there are some actions that might need to be explained here.

link & move window

You can use link action to link a window from another session to current session.

launch tmux-fzf -> window -> link -> select a window in another session

And you can use kill action to unlink or kill current window.

kill actually use tmux unlink-window -k instead of tmux kill-window. The main difference between unlink-window -k and kill-window is that kill-window will kill current window and all other windows linked to it, while unlink-window -k will only kill current window.

The logic of the unlink -k action is a bit like hard link in unix/linux. If the current window only exists in one session, then kill; if the current window exists in multiple sessions, then unlink.

Btw, if you want to bind a key to kill current window, I would recommend unlink-window -k instead of kill.

move action is similar to link, except the window at source window is moved to destination.

break & join pane

break action will break source pane off from its containing window to make it the only pane in destination window.

launch tmux-fzf -> pane -> break -> select source pane

join action is like split-window, but instead of splitting destination pane and creating a new pane, it will split it and move source pane to the current window. This can be used to reverse break-pane.

launch tmux-fzf -> pane -> join -> select source pane(s)

user menu

You can add a custom menu to quickly execute some commands.

This feature is not enabled by default. To enable it, add something like this to ~/.tmux.conf

TMUX_FZF_MENU=\
"foo\necho 'Hello!'\n"\
"bar\nls ~\n"\
"sh\nsh ~/test.sh\n"

When you launch tmux-fzf, an extra item named menu will appear. Selecting this item will produce this.

There will be 3 items to select from: foo, bar and sh.

When you select foo, tmux will execute echo 'Hello!'.

When you select bar, tmux will execute ls ~.

When you select sh, tmux will execute sh ~/test.sh.

Note:

• foo and echo 'hello' are separated by \n in TMUX_FZF_MENU, and you need to add another \n after echo 'hello'.
• DO NOT add additional white spaces/tabs at the beginning of each line.
• Commands are executed using tmux -c, so please make sure tmux -c "your command" makes sense.

popup window

To enable popup window, you'll need to compile and install the latest development version from tmux/tmux.

For arch linux users, there is a package available in AUR: tmux-git

This feature is automatically enabled in the version >= 3.2, but you can disable it by adding TMUX_FZF_POPUP=0 to your ~/.tmux.conf.

If your tmux version < 3.2 but you're pretty sure that your tmux supports popup window, you can force enabling it by adding TMUX_FZF_POPUP=1 to your ~/.tmux.conf

Customization

key binding

For example, to use prefix + C-f (Ctrl+F), add this line to your ~/.tmux.conf

set -g @tmux-fzf-launch-key 'C-f'

fzf behavior

This plugin will read fzf environment variables, so you can customize the behavior of fzf such as prompt and color by setting those variables.

For more information, check official page of fzf.

In addition, this plugin supports options of fzf-tmux command which is provided by fzf, you can customize them by adding something like this to ~/.tmux.conf

TMUX_FZF_OPTIONS="-d 35%"

To list all available fzf-tmux options, execute fzf-tmux --help in your shell.

popup window

To adjust the width and height of popup window, add something like this to your ~/.tmux.conf:

TMUX_FZF_POPUP_HEIGHT="38%"
TMUX_FZF_POPUP_WIDTH="62%"

order

To customize the order of the items, add something like this to your ~/.tmux.conf:

TMUX_FZF_ORDER="session|window|pane|command|keybinding"

format

For some reasons, you may want to customize format of panes, windows, sessions listed in fzf. There are three variables to complete this work:

TMUX_FZF_PANE_FORMAT TMUX_FZF_WINDOW_FORMAT TMUX_FZF_SESSION_FORMAT

For example, tmux list-panes -a doesn't show running program and window name by default. If you want to show running program and window name, add something like this to ~/.tmux.conf

TMUX_FZF_PANE_FORMAT="[#{window_name}] #{pane_current_command}  [#{pane_width}x#{pane_height}] [history #{history_size}/#{history_limit}, #{history_bytes} bytes] #{?pane_active,[active],[inactive]}"

Similarly, TMUX_FZF_WINDOW_FORMAT and TMUX_FZF_SESSION_FORMAT can also be handled in this way.

For more information, check "FORMATS" section in tmux manual.

FAQ

• Q: What's your status line configuration?
• A: See this article.
• Q: What's the color scheme used in the screenshot?
• A: Gruvbox Material

More plugins

• sainnhe/tmux-translator: A translation plugin powered by popup window.

License

MIT && Anti-996