Title: Binding Keys in tmux
Tags: tmux
To list all current key bindings, including any custom bindings you've added and bindings added by plugins:
* Ctrl + b ?
* `tmux list-keys` or `tmux lsk` in a shell inside tmux
* `list-keys` or `lsk` at tmux's command prompt (Ctrl + b :)
The `bind-key` and `unbind-key` commands (aliases `bind` and `unbind`) change key bindings in tmux. Like all tmux commands a `bind` or `unbind` command can be
entered in three different ways:
1. By running `tmux bind ...` in a shell inside tmux
2. By hitting Ctrl + b : in tmux and then entering `bind ...` into tmux's command prompt
3. By adding a `bind ...` line to your `~/.tmux.conf` file to bind the key at startup
For example:
bind C-t new-window
Now Ctrl + b Ctrl + t will open a new window.
To remove the key binding:
unbind C-t
The `C-` stands for Control. There's also `S-` for Shift and `M-` for Alt, e.g. `bind M-t new-window`, `bind -n M-S-Left swap-window -t +1`. There are several special key names for use in
`bind` commands, including: `Up`, `Down`, `Left`, `Right`, `BSpace`, `Delete`, `End`, `Enter`, `Escape`, `F1` ... `F12`, `Home`, `Insert`, `PageDown` or `PgDn`,
`PageUp` or `PgUp`, `Space` and `Tab`.
`S-` doesn't work with keys that send a different character when Shift'ed.
`bind S-n ...`, `bind S-1 ...`, etc don't work.
Use `bind N ...`, `bind ! ...`, etc instead.
But if you want to bind Alt + Shift + ←, for example, then it _is_ `bind M-S-Left ...`.
Shift'd keys also don't work with Ctrl because Ctrl-modified keys are case-insensitive in terminals.
So while you can do `bind C-N ...` the binding will be triggered by either Ctrl + Shift + n
or just Ctrl + n.
There are various other modifier key limitations as well, see [Modifier Keys](https://github.com/tmux/tmux/wiki/Modifier-Keys)
on the tmux wiki.
Every keybinding lives in a **key table**. There are three built-in key tables:
1. `prefix`: Keys in this table must be pressed after the prefix Ctrl + b to trigger the binding. This is the table that the
`bind` command uses by default. Example: `bind C-t new-window`
2. `root`: Keys in this table can just be pressed, without any prefix. Use `-n` (a shortcut for `-T root`) to bind keys in this table.
Example: `bind -n C-t new-window`
3. `copy-mode` or `copy-mode-vi` for when in copy mode, depending on whether you're using emacs- or vi-style key bindings mode
(add `set-window-option -g mode-keys vi` to your `~/.tmux.conf` file to force vi-style). Use `-T copy-mode-vi` to bind keys in this table.
Example: `bind -T copy-mode-vi C-t new-window`
## Repeatable prefix key bindings
For key bindings in the `prefix` table the `-r` option can be used to make them repeatable.
For example with `tmux bind -r t new-window` Ctrl + b t is needed to open a first new window, then you can
keep hitting t to open more without having to hit Ctrl + b each time. The `repeat-time` setting decides how much time
you have to repeat the key before the prefix times out (default: 500 milliseconds).
## Binding a key to run multiple commands at once
You can use `\;` to separate multiple commands in a single key binding:
bind t new-window \; display-message "new window opened"
If using the `tmux bind` shell command you may need to quote the commands instead:
tmux bind t 'new-window; display-message "new window opened"'
A multiline format is also possible by ending each line with \ or (if the line is part of the command) \; \. Example:
```
bind -n DoubleClick1Pane \
select-pane \; \
copy-mode -M \; \
send-keys -X select-word \; \
send-keys -X copy-pipe-no-clear "xsel -i"
```
## Binding a sequence of keys: custom key tables
You can bind keys in custom named key tables and use the `switch-client` command to move between key tables. This enables sequences of keys to be bound.
For example to make `abc` in quick succession open a new window:
bind -T root a switch-client -T my_table_1
bind -T my_table_1 b switch-client -T my_table_2
bind -T my_table_2 c new-window
## Binding `"` and `'`
To bind `"` or `'` you need to put them in quotes:
bind '"' split-window
bind "'" new-window
## Binding mouse events
If tmux's mouse support is enabled (`set -g mouse on`) then `bind` can also bind mouse events. For example to make clicking the Left Mouse Button on a
pane open a new window:
bind -n MouseDown1Pane new-window
The mouse events are `MouseDown1`, `MouseUp1`, `MouseDrag1`, `MouseDragEnd1`, `DoubleClick1`, `TripleClick1`, `MouseDown2`, `MouseUp2`, `MouseDrag2`,
`MouseDragEnd2`, `DoubleClick2`, `TripleClick2`, `MouseDown3`, `MouseUp3`, `MouseDrag3`, `MouseDragEnd3`, `DoubleClick3`, `TripleClick3`, `WheelUp`, `WheelDown`.
Each event always needs to be suffixed with one of the target locations `Pane`, `Border`, `Status` (the window list in the status line), `StatusLeft`,
`StatusRight` or `StatusDefault` (any other part of the status line that isn't the window list or left or right parts).
Mouse button 2 (`MouseDown2`, `MouseUp2`, ...) is the middle mouse button and 3 (`MouseDown3`, `MouseUp3`, ...) is the right button.
The special token `{mouse}` or `=` in a mouse event `bind` command resolves to the target-window or target-pane that was clicked on, for when you need the target window
or pane in the bound command.
For example `bind -n MouseDown1Pane select-pane -t {mouse}` makes clicking on a pane select that pane.
`bind -n MouseDown1Status select-window -t =` makes clicking on a window in the status line select that window.