Tmux configuration

This page documents some commands I use most frequently.

Documentation

keybindings	https://man.archlinux.org/man/community/tmux/tmux.1.en#KEY_BINDINGS
mouse	https://man.archlinux.org/man/community/tmux/tmux.1.en#MOUSE_SUPPORT

Locations

~/.tmux.conf

config

Example

Sample Window/Pane setup script

generate_rps1() {
    # .zshrc: `test -n "${OVERRIDE_RPS1}" && RPS1="${OVERRIDE_RPS1}"`
    echo '[%F{165}'"$1"']'
}


create_integration_panes() {
    # Creates Tmux Panes for repos
    #    |       A           |         B          |
    # ---+-------------------+--------------------+
    #  1 | repo1-logs        |  repo1-console     |
    # ---+-------------------+--------------------+
    #  2 | repo2-logs        |  repo2-console     |
    # ---+-------------------+--------------------+
    #  3 | repo3-logs        |  repo3-console     |
    # ---+-------------------+--------------------+
    #  4 | repo4-logs        |  repo4-console     |
    # ---+-------------------+--------------------+

    # A-1
    tmux respawn-pane -k  \
        -c "~/src/repo1" \
        -e OVERRIDE_RPS1="$(generate_rps1 repo1-logs)"

    # B-1
    tmux split-window -h \
        -c "~/src/repo1" \
        -e OVERRIDE_RPS1="$(generate_rps1 repo1-console)"

    # A-3
    tmux select-pane -L
    tmux split-window \
        -c "~/src/repo3" \
        -e OVERRIDE_RPS1="$(generate_rps1 repo3-logs)"

    # A-2
    tmux select-pane -U
    tmux split-window \
        -c "~/src/repo2" \
        -e OVERRIDE_RPS1="$(generate_rps1 repo2-logs)"

    # A-4
    tmux select-pane -D
    tmux split-window \
        -c "~/src/repo4" \
        -e OVERRIDE_RPS1="$(generate_rps1 repo4-logs)"

    # B-3
    tmux select-pane -R
    tmux split-window \
        -c "~/src/repo3" \
        -e OVERRIDE_RPS1="$(generate_rps1 repo3-console)"

    # B-2
    tmux select-pane -U
    tmux split-window \
        -c "~/src/repo2" \
        -e OVERRIDE_RPS1="$(generate_rps1 repo2-console)"

    # B-4
    tmux select-pane -D
    tmux split-window \
        -c "~/src/repo4" \
        -e OVERRIDE_RPS1="$(generate_rps1 repo4-console)"
}


create_dev_panes() {
    # Creates Tmux Panes for wiki
    # +-------------------+
    # | dev-vim           |
    # +-------------------+
    # | dev-console       |
    # +-------------------+
    tmux new-window \
        -c "~/src/dev" \
        -e OVERRIDE_RPS1="$(generate_rps1 dev-vim)"

    tmux split-window \
        -c "~/src/dev" \
        -e OVERRIDE_RPS1="$(generate_rps1 dev-console)"
}


create_integration_panes
create_dev_panes

Syntax

Conditionals

Tmux supports conditionals in configuration.
For example here I bind clipboard operations if we're running an xorg server.

if-shell -b 'test -n ${DISPLAY}' {
    # selection automatically copied to selection-clipboard
    bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe "xclip -i"

    # yank copies to selection-clipboard
    bind y run-shell -b "tmux show-buffer | xclip -selection c -f > /dev/null && tmux show-buffer | xclip -i > /dev/null"
}

Format Variables

Format variables may control command output, or can be referred to within commands.
These format variables can be nested.
See format variables for details.

# sample use in command output

# sample use in keybinding
bind-key 'Y' new-window -c '#{pane_current_path}'

Commands

current config

tmux show-options -g  # list current configuration

scrollback history

set -g history-limit 10000

notifications

set -g display-time 5000                     # message display duration
display-message -c /dev/pts/0 'hello world'  # show a message

terminal

set -g default-terminal "screen-256color"  # desired $TERM value
set -g visual-bell off
set -g visual-activity off
set -g bell-action current

mouse

set -g mouse on

statusbar

set -g pane-base-index 1
set -g status-position top
setw -g clock-mode-style 2

source-file

source-file ${FILE}  # import file

keybindings

See KEYBINDINGS section in man page.

Keys are bound within tables. by default, they are bound to the prefix table (active following tmux-prefix keyseq).
Keys executed without a prefix are defined in the root table.
bind and bind-key can be used interchangeably.

tmux bind-key \
  [-n] `# bind w/o prefix (root table)` \
  [-r] `# repeatable` \
  [-N ${NOTE}] \
  [-T ${KEY_TABLE}] \
  ${KEY} \
  ${TMUX_COMMAND} ${ARGUMENTS[@]}

bind-key     F1   set-option status off   # bind key-sequence (after prefix)
bind-key -n  M-0  select-window -t 10    # bind key-sequence to root table (w/o prefix)

unbind C-b                               # unbind key-sequence

tmux prefix

set -g prefix 'M-a'                      # set (additional) alternative tmux-prefix

enable vi mode

set -g mode-keys vi
set -g status-keys vi

pane config

You can configure/display pane names.

<M-:> select-pane -T ${NAME}  # name pane

# configure tmux to show pane titles
set -g pane-border-status-top
set -g pane-border-format " [ ###P #T ] "

https://stackoverflow.com/questions/40234553/how-do-i-rename-a-pane-in-tmux