tmux¶

Introduction ¶

I appreciate tmux (a terminal multiplexer) for its window management features. For terminal based activities, it can be an alternative to using a tiling window manager.

Installation ¶

On a Debian GNU/Linux system, install tmux (as root) with:

apt-get install tmux # As root.

You can launch tmux with command tmux. I usually use tmux in an xterm and launch both with a single xterm tmux command.

You may need the tmux-resurrect plugin. You can install it that way (as an unprivileged user):

mkdir -p ~/.tmux/plugins
cd ~/.tmux/plugins
git clone https://github.com/tmux-plugins/tmux-resurrect resurrect

At the time of this writing (2022-04-17), current version of tmux-resurrect is 4.0.0. I have experienced som issues with session restoration with version 4.0.0 so I’m sticking with version 3.0.0 for now:

cd ~/.tmux/plugins/resurrect
git checkout v3.0.0

The default key bindings for tmux-resurrect are prefix Ctrl-s (save session) and prefix Ctrl-r (restore session).

Configuration ¶

My .tmux.conf ¶

You can download my ~/.tmux.conf.

I had a little bit of a hard time defining the status-right option (the right hand side of the status line). It causes the right hand side of the status line to show:

A Caps lock mode indicator (a yellow “Caps lock on” when Caps lock is on, nothing visible otherwise).
A Num lock mode indicator (a yellow “Num lock off” when Caps lock is off, nothing visible otherwise).
A power supply indicator (“CHG” if the machine is plugged in, “BAT” if the machine is running on the battery, nothing visible if the information is not found).
The remaining capacity of charge in the battery in percent (yellow if lower than 20% and machine not plugged in, nothing visible if the information is not found).
Time and date, with the day of the week.

The time / date part was easy enough, the format specification is passed through strftime(3). The sole time / date part could be obtained with set -g status-right "%H:%M %Y-%m-%d(%a)".

I could obtain the other parts using shell commands. The shell commands must be enclosed in a #() construct. So my status-right option “line” now is something like set -g status-right "#(<shell commands>) %H:%M %Y-%m-%d(%a)".

When multiple and/or long shell commands are needed, one solution is to write them in a separate script file and just call the script file in the #() construct. Another solution is to use line continuation. Lines can be continuated by adding \ at the end. That’s the route I went, and my status-right option “line” now is more like:

set -g status-right "#(\
<shell \
commands>\
) %H:%M %Y-%m-%d(%a)"

The shell commands actually ended up being a sequence of calls to printf in if ... else ... fi; constructs. Text coloring in the tmux status line is controlled using strings like #[fg=colour184]. Example:

set -g status-right "#(printf '#[fg=colour184]yellow#[fg=colour0] black') %a"

(Note that I don’t use text coloring any more in my ~/.tmux.conf because I now use base16-tmux (see Base16 color schemes).)

The Caps lock mode indicator is build from the content of a file like /sys/class/leds/input5::capslock/brightness. But there might be multiple files like this one (if you have multiple keyboards plugged in to your machine). You can cat only one of them with a command like (from my experience, they all have the same content at a given time):

cat $(find /sys/class/leds -name "*capslock"|head -1)/brightness

Similarly, for Num lock mode:

cat $(find /sys/class/leds -name "*numlock"|head -1)/brightness

The power supply indicator is build from the content of the /sys/class/power_supply/AC/online if it exists (from my experience, and on a Debian system, it exists on a laptop computer but not on a desktop computer).

Finally, the remaining capacity of charge in the battery is taken in file /sys/class/power_supply/BAT/capacity if it exists. It exists on my Debian laptop. On other systems, the file may be /sys/class/power_supply/BAT0/capacity instead. And some laptop have two batteries. My status-right option displays the remaining capacity for only one battery.

Determining whether the remaining capacity is lower than 20% or not is achieved by piping the remaining capacity to a grep '$^\|[0-1]$.$' command. If the output is non empty, then the remaining capacity is lower than 20%. Note that in the ~/.tmux.conf the backslashes must be escaped: grep '\$^\\|[0-1]\$.$').

Note also the format string in the printf command for the remaining capacity. The percent sign must be tripled (printf '% 3d%%%' $(cat /sys/class/power_supply/BAT/capacity);).

I’ve set the refresh rate of the status line to 3 seconds:

set -g status-interval 3

And I also had to specify the status-right-length option, without that the status line is truncated:

set -g status-right-length 56

Reloading configuration ¶

After changing your ~/.tmux.conf, you can reload it with:

tmux source-file ~/.tmux.conf

Disabling control flow ¶

You should probably disable control flow by adding this line to your ~/.bashrc:

stty -ixon

You can find more details about that in Tom Ryder’s “Terminal annoyances” blog post.

Colors ¶

The following command shows the colors that can be used in a tmux configuration (source: https://superuser.com/a/1104214):

for i in {0..255}; \
  do printf "\x1b[38;5;${i}mcolour%-5i\x1b[0m" $i; \
  if ! (( ($i + 1 ) % 8 )); then echo; fi; \
done

Vim configuration ¶

Enable the use of the mouse in terminal Vim by adding this line to your ~/.vimrc:

set mouse=a

Listing / killing tmux sessions ¶

List your opened tmux sessions with:

tmux ls

Kill all the opened tmux sessions and the tmux server with:

tmux kill-server
tmux confirm-before kill-server # Prompts the user for confirmation in
                                # tmux status bar.

If you’re in a tmux session and want to kill all the other sessions, use:

tmux kill-session -a

To kill a specific session, read session ID from tmux ls and do:

tmux kill-session -t <session_id>

I usually have only one tmux session and I close it with prefix s (which brings you to a “session list” screen), and then x to require to stop the current session and y to confirm.

Detaching client / attaching session ¶

Detach the current client with prefix d or:

tmux detach

Reattach with one of:

tmux attach
tmux a
tmux attach -d -t <session_id> # To attach to a specific session.
                               # -d causes any other clients attached to the
                               # session to be detached.

Managing windows and panes ¶

Create a new window with prefix c.

Rename the current window with prefix ,.

Close the current window with prefix &.

Split pane vertically with prefix %.

Split pane horizontally with prefix ".

Resize pane with prefix + left/down/up/right arrow. See also this article by Michael Lee.

To swap two windows, enter command mode with prefix : and type a command like swap-window -s 3 -t 1. This command swaps numbering of windows 3 and 1.

Zooming a window to fit it to full terminal size ¶

Just use prefix z. This does also unzoom the window.

Doing this I sometimes accidentally hit Ctrl-z, which suspends the tmux process. The solution in this case is to grab another terminal, to find the PID of the tmux process and to send a SIGCONT signal to it:

kill -cont <PID>

Other resources ¶

tmux cheatsheet