tmux HOTWO

tmux_howto.md

tmux HOWTO

tmux is a terminal multiplexer that lets you switch easily between several programs in one terminal, detach them (they keep running in the background) and reattach them to a different terminal, and a lot more.

• The tmux manpage (man tmux) or the printed copy of the tmux book near the team's library are great resources on using tmux.
  This HOWTO just lists the most useful commands.
• Despite tmux being a very powerful tool, the default configuration of tmux is not the most user friendly.
  I am maintaining a tmux configuration file that makes life a bit easier here:
  https://github.com/kmhofmann/dotfiles
  The HOWTO is written assuming this configuration file (or one with similar mappings) is installed.

tmux concepts

• A user can run multiple tmux sessions, which can optionally be named.
• Each session can contain multiple terminal windows. These are displayed in the bottom statusbar, can easily be switched to, and renamed.
• Each window can contain multiple panes (through horizontal or vertical splits, or a combination thereof).

The tmux command line

• tmux new-session [-s <name>] (short: tmux new)

  Start a new tmux session with the specified name (specifying a name is optional). This can be shortened to the command tmux, if specifying a name is not important.

• tmux attach [-t <name>] (short: tmux a)

  Attach to the specified session. If no session is specified, attach to the last detached session.

• tmux list-sessions (short: tmux ls)

  List all active sessions.

Inside tmux

All tmux commands are given with a preceding prefix key (notation: <Prefix>), which in Michael's configuration file is <Ctrl-A> (the default is <Ctrl-B>, but that's harder to type). In order to send an actual <Ctrl-A>, one needs to send the combination twice: <Ctrl-A><Ctrl-A>.

Session management

• <Prefix>d

  Detach the current session. It will continue running in the background and can be reattached with tmux attach from the command line (see above).

• <Prefix>( / <Prefix>)

  Go to previous/next session.

• <Prefix>$

  Rename current session.

• <Prefix>s

  List all sessions (also to select current session).

• <Prefix>:new <cr>

  Create new session

Window management

• <Prefix>c or <Prefix>n

  Create a new window in the current session.

• <Prefix>x

  Kill (close) a pane. If the pane is the only one contained in the window, the respective window will be closed.

• <Prefix>,

  Rename a window. Giving a window a descriptive name can help keeping them apart.

• <Prefix>1, ..., <Prefix>9

  Go to the n-th window.

• <Prefix><Ctrl-h> or <Shift><Left>

  Go one window to the left.

• <Prefix><Ctrl-l> or <Shift><Right>

  Go one window to the right.

• <Ctrl-Shift><Left>

  Move the current window one to the left.

• <Ctrl-Shift><Right>

  Move the current window one to the right.

Pane management

• <Prefix>- (or: original binding <Prefix>")

  Open a new pane, using a horizontal split.
  <Prefix>- will open the new pane using the directory of the current pane, while <Prefix>" will use the directory session working directory.

• <Prefix>| (or: original binding <Prefix>%)

  Open a new pane, using a vertical split.
  <Prefix>| will open the new pane using the directory of the current pane, while <Prefix>% will use the directory session working directory.

• <Prefix>h / <Prefix>j / <Prefix>k / <Prefix>l or <Alt><Left> / <Alt><Down> / <Alt><Up> / <Alt><Right>

  Move to pane one left/down/up/right.

• <Prefix>H / <Prefix>J / <Prefix>K / <Prefix>L or <Alt-Shift><Left> / <Alt-Shift><Down> / <Alt-Shift><Up> / <Alt-Shift><Right>

  Resize a pane in the respective direction.

• <Prefix>{/<Prefix>}

  Move pane to previous/next position.

• <Prefix><Ctrl-O>/<Prefix><Alt-O>

  Rotate all panes.

• <Prefix>z

  Zoom/unzoom pane (zoom == full screen).

• <Prefix>!

  Move current pane into a new window.

• <Prefix>q

  Show pane numbers.

Copy mode

• <Prefix><Esc> or <Prefix>[

  Enter copy mode. In this mode, one can easily scroll up and down the terminal buffer, and copy/paste (albeit into/from tmux internal buffers). This mode is configured to use vim bindings.

Miscellaneous

• <Prefix>:

  Open command prompt.

• <Prefix>?

  List key bindings.

• <Prefix>t

  Display big clock.

Useful commands

Specifying windows/panes

• For use in commands, windows are specified in the format session:window. Panes are specified in the format session:window.pane.

• Example: sess:3:1 points to pane 1 in window 3 of session sess.

Moving windows/panes

• break-pane [-dP] [-F format] [-n window-name] [-s src-pane] [-t dst-window]

  (alias: breakp) (man page)

  Break src-pane off from its containing window to make it the only pane in dst-window. If -d is given, the new window does not become the current window. The -P option prints information about the new window after it has been created. By default, it uses the format ‘#{session_name}:#{window_index}’ but a different format may be specified with -F.

• join-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]

  (alias: joinp) (man page)

  Split dst-pane and move src-pane into the space. This can be used to reverse break-pane. The -b option causes src-pane to be joined to left of or above dst-pane. If -s is omitted and a marked pane is present (see select-pane -m), the marked pane is used rather than the current pane.

• move-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]

  (alias: movep) (man page)

  Like join-pane, but src-pane and dst-pane may belong to the same window.

• move-window [-ardk] [-s src-window] [-t dst-window]

  (alias: movew) (man page)

  The window at src-window is moved to dst-window. With -r, all windows in the session are renumbered in sequential order, respecting the base-index option.

Other resources

• tmux web site: https://tmux.github.io/
• tmux man page: http://man.openbsd.org/OpenBSD-current/man1/tmux.1
• tmux book: https://pragprog.com/book/bhtmux2/tmux-2