tmux

tmux is a terminal multiplexer, similar to GNU screen but with window management. It serves two needs:

  • Enabling any number of terminals to be accessed from a single terminal.
  • Allowing the user to detach from a session, which will continue to run in the background, and can later be resumed.

Concepts

  • Sessions are made up of one or more windows. tmux exits when there are no longer any running sessions.
  • Windows host one or more panes. Only one window may be visible at any given time.
  • Panes can host pseudo terminals. Panes may be navigated within a window.
  • Pseudo terminals are managed as child processes of the tmux server.
  • The Status line shows the active and available windows, and can show additional information about the machine tmux is running on.
  • The Prefix key precedes a tmux command.

Commands

  • ls lists sessions.
  • new-session [-d] [-n WINDOW_NAME] [-s SESSION_NAME] creates a new session.
  • new-window [-a] [-t TARGET] [-n WINDOW_NAME] creates a new session.
  • attach [-t TARGET] attaches to a session.
  • kill-session [-t TARGET] kills a session.
  • kill-server kills the server.

Modes

Each pane pane has a mode:

  • Direct terminal access is the default. Keys are sent directly to the pseudo terminal.
  • Copy mode (entered with copy-mode) allows copying a selection of the pane's history to a paste buffer.
  • View mode behaves like copy mode, but can only be entered by running a command that produces output.
  • Choose mode allows picking items from a list, and can be entered only from the choose-* commands.

Key bindings

Key bindings execute commands. For consistency with the documentation key bindings are denoted in emacs syntax. They're triggered with the prefix key (C-b by default) followed by a command key:

  • C-b passes the prefix key sequence to the terminal.
  • ? shows the key bindings.
  • : enters a command.
  • r forces the client to redraw.
  • ~ shows messages from the tmux server.
  • d detaches the current client.
  • D selects a client to detach from the server.
  • L switch the attached client back to the last session.

Pane navigation

  • Cursor keys navigate between panes.
  • q briefly shows pane numbers.
  • o navigates to the next pane in the window.
  • ; returns to the previously active pane.
  • { swaps the current pane with the previous pane.
  • } swaps the current pane with the next pane.
  • M-n jumps to the next window with a bell/activity marker.
  • M-p jumps to the previous window with a bell/activity marker.

Pane management

These commands operate within the current pane:

  • t shows the time.
  • % splits vertically.
  • " splits horizontally.
  • z toggles the pane's zoom (full screen) state (note *Z in the status line).
  • ! moves the pane to a new window.
  • x kills the pane.

Pane arrangement

  • M-1 through M-5 arrange panes in a preset layout:
    • even-horizontal
    • even-vertical
    • main-horizontal
    • main-vertical
    • tiled
  • Space arranges windows in the next layout.
  • C-Up, C-Down, C-Left, and C-Right resize the current pane in one cell steps.
  • M-Up, M-Down, M-Left, M-Right resize the current pane in five cell steps.

Window navigation

  • 0 through 9 switch to the specified window.
  • ' prompts for a window to switch to.
  • w changes window interactively.
  • f searches for text in open windows.
  • l moves to the previously selected window.
  • n moves to the next window.
  • p moves to the previous window.

Window management

These commands operate on the current window:

  • c creates a new window.
  • i shows some information about the window.
  • , renames the window.
  • & kills the window.
  • . moves the window.

Session navigation

  • s interactively selects a new session for the client to attach to.
  • ( selects the previous session.
  • ) selects the next session.

Session management

  • $ renames the session.

Copy/paste

  • [ enters copy mode, also allowing scrollback through history.
    • PgUp enters copy mode and scrolls one page up.
  • ] pastes.
  • = interactively selects the buffer to paste.
  • # lists all paste buffers.
  • - deletes the most recently copied buffer.

Implementation

Terminals run in a server, to which the client connects. The server exits when there are no longer any active sessions.

Configuration

Configuration is stored in ~/.tmux.conf, and can execute any commands.

Some interesting options:

  • set-option -g mouse on enables mouse support for pane navigation and resizing.
  • set-option -g pane-border-status top shows the pane title and number above each pane.
    • set-option -g pane-border-format " [ (#P) #T ] " shows the pane index and title enclosed in square brackets.
  • bind-key C-k "send-keys -R C-l; clear-history clears the screen and tmux scrollback buffer in one go.
  • bind-key -n C-a send-prefix allows hitting C-a in the root tmux session to pass the prefix key to a nested session.

References


Children
  1. Tmuxinator
  2. tmuxp