====== Tmux Terminal Multiplexing ======

[[https://github.com/tmux/tmux/wiki|Tmux]] is a terminal multiplexer that lets you have multiple virtual terminals and also split windows and have multiple panes and tabs. Another nice feature is if you are connecting over SSH and using Tmux, Tmux can keep your session going even if you disconnect and re-connect later. An alternative to Tmux is [[https://www.gnu.org/software/screen/|GNU Screen]].

===== Installing =====

In Debian, you can simple use the system package manager to install:

<code bash>
sudo apt install tmux
tmux -V  # Check version
</code>

To build from source, download sources from the [[https://github.com/tmux/tmux/releases|Tmux GitHub Releases]]. Building is pretty simple, it has few dependencies and compiles quickly.

<code bash>
# Install buidl dependencies
sudo apt install libevent-dev ncurses-dev build-essential bison pkg-config

wget https://github.com/tmux/tmux/releases/download/3.1c/tmux-3.1c.tar.gz
tar -zxf tmux-3.1c.tar.gz
cd tmux-3.1c/

# Identify the options you want
./configure --help | less
./configure
make
./tmux -V
sudo make install  # Optional
</code>

===== Basic Usage =====

To initialize a tmux session, simply invoke ''tmux''.

<code bash>
tmux
</code>

To get help information and a list of commands, use:

<code bash>
man tmux
tmux --help
tmux list-keys
tmux list-commands
# Within tmux press ''CTRL-b ?''
</code>

===== Enabling mouse =====

With mouse enabled, you can click between split windows and use the mouse to resize. You can also right click on panes and in the bottom left corner to switch windows and manage processes. It adds a lot of really nice functionality.

You must specify ''setw -g mouse on'' in a tmux conf file. For example:

<code - .tmux.conf>
# ~/.tmux.conf

# Enable mouse
set -g mouse on
</code>

<code bash>
# Then run tmux as normal
tmux
# OR to be explicit
tmux source-file ~/.tmux.conf
</code>

===== Sessions =====

When you start tmux, you are creating a "session". You can have multiple sessions and they are identified by a number or a name.

<code bash>
# List active sessions
tmux ls

# Connect to last active session
tmux attach

# Connect to a session by its numeric ID
tmux attach -t 0

# Create a new named session
tmux new -s mysession

# Create a new named session + run vim in detached mode
tmux new -s mysession -d "vim"

# Connect to a session by name
tmux attach -t mysession
</code>

Once you are in a session and you want to disconnect, 

<code bash>
# Use the shell command
tmux detach

# Or use the keybinds
CTRL-b d
</code>

To kill a session, simply exit the shell like normal with ''exit'' or ''CTRL-d'', or you can send a tmux command to kill the session.

<code bash>
# End a session by name
tmux kill-session -t myapp
</code>

===== Windows =====

The top level object is a session. A session contains windows, and a window contains panes. Here are commands related to windows. Like most things in tmux, you can use the shell command, or the keybind.

<code bash>
tmux new-window
tmux list-windows
tmux select-window -t 1
tmux rename-window # Renames current window

tmux split-window
tmux split-window -h

tmux swap-pane -\[UDLR\]
</code>

Most of these keybinds must be preceeded with the ''CTRL-b'' chord.

  * Create a new window - ''c''
  * List window - ''w''
  * Select a window - (the number of the window)
  * Rename windows - '',''
  * Kill window - ''&''
  * Next window - ''n''
  * Previous window - ''p''
  * Last window - ''l''
  * Split window horizontally in two panes - ''"''
  * Split window vertically in to two panes - ''%''
  * Set even split horizontally - ''ALT-1''
  * Set even split vertically - ''ALT-2''


===== Panes =====

A pane is the lowest level of hierarchy in screen organizing. The top level is the session, then the session has windows, and a window is made up of panes.

Most of these need to be preceeded by ''CTRL-b'' followed by one of the following keybinds:

  * Switch active pane - ''up/down/left/right arrow''
  * Next pane - ''o''
  * Previous pane - '';''
  * Kill pane - ''x''
  * Break out pane in to window - ''!''
  * Resize pane 1 unit - ''CTRL'' plus ''left/right/up/down arrow''
  * Resize pane 5 units - ''ALT'' plus ''left/right/up/down arrow''
  * Swap pane up/down - ''{'' or ''}''
  * Rotate pane up/down - ''CTRL-o'' or ''ALT-o''



===== Send keystrokes to a session =====

You can use ''tmux send-keys'' to send keystrokes to a specific session.

All keys including functions, alt, home, page up, arrow keys, and even mouse actions can all be emulated. Here is a full list of keys from the source code of tmux:
[[https://github.com/tmux/tmux/blob/ec7f5305b1a6e5548f0769f988e76b01ec293dcc/key-string.c#L33-L100]]

<code bash>
# Send some vim commands to a session
tmux send-keys -t mysession "i" "hello" Enter Escape ":w! test.txt" Enter
</code>


===== Other common tasks =====

Every command is assumed to begin with the chord, which by default is ''CTRL-b''. Press ''CTRL-b'' and then release before pressing the next action key.


  * Toggle scrolling with ''CTRL-b [''
  * Switch to next pre-defined layout: ''CTRL-b SPACE''