title: Tmux Basics
tags: tmux

Useful site: https://tmuxcheatsheet.com/ (credit: most of what you find here is ripped from that -- one day I'll read the actual tmux docs.)  Also see the TMux wiki at: https://github.com/tmux/tmux/wiki

Use `Ctrl-B` to control TMux. Use `Ctrl-B :` to get into command mode.

## Cheat Sheet
### Command line
You can do `Ctrl-B : command` or from the command line, e.g.
```bash
$ tmux new-window
```

### Keys
Key combos involve pressing `Ctrl-B` followed by something.

### Commands
`Ctrl-B :` enters command mode. In command mode there is tab-completion.

Use `Ctrl-B` followed by:
```
: attach -d -- detach all other clients
```

### Session
Keybindings:
`Ctrl-B` followed by
```
$ -- rename session
d -- detach from session
( -- previous session
) -- next session
s -- list sessions
```
and commands
```
:ls, :list-sessions              -- list sessions
:new                             -- new session
:new -s session_name             -- new session with name session_name
:kill-ses                        -- short for :kill-session
:kill-session -t session_name    -- kill session with name session_name
:kill-session -a -t session_name -- kill all sessions but session_name
:attach-session -t session_name  -- attach to session with name session_name
:a -t, :at -t, :attach -t        -- shorthands for :attach-session 
:attach -c /path/to/new/default  -- change the default path in which new windows start
```

### Window
Keybindings:
`Ctrl-B` followed by
```
c -- create window
, -- rename window
& -- close window
n -- next window
p -- previous window
0..9 -- change to window number 0..9
```
and commands
```
:swap-window -t -1     -- move current window left by one position
:swap-window -t n      -- swap current window with window at position n
:swap-window -t n -s m -- swap window n with window m
```

### Windows to/from Panes
Commands
```
:move-pane -t <window number>:<split number>
:join-pane -s <src window number> -t <target window number> # one above t'other
:join-pane -s <src> -t <tgt> -h # side by side
:break-pane # break out current pane as separate window
```

### Panes
`Ctrl-B` followed by
```
; -- toggle last active pane
% -- split vertically (side by side)
" -- split horizontally (one above the other)
{ -- move current pane left
} -- move current pane right
arrow -- move to pane in direction of arrow (e.g. left arrow switches to pane to left)
q -- show pane numbers (and sizes)
q 0..9 -- switch to numbered pane (you have about a second to press the number)
z -- toggle pane zoom (make pane fill entire window / revert )
! -- convert pane to window
x -- close pane
Ctrl-arrow -- resize pane (one row/col at a time)
```

Alternative for resizing: hold `Ctrl-B` and press
```
arrow -- to resize pane (e.g. with right pane selected, Ctrl-b-leftarrow enlarges right pane by moving divider to the left) this is preferable
```

Commands
```
:setw synchronize-panes  -- toggle synchronize panes (keys to to all panes)
```

### Referring to windows and panes
For panes, use e.g. `%21`. For windows, use e.g. `@42`. To see identifiers, use
```
list-panes
list-windows
```
and then e.g.
```
:join-pane -s %21 -t @42
```

### Copy mode
Keybindings: `Ctrl-B` followed by
```
[     -- enter copy mode
Pgup  -- enter copy mode and scroll one page up
q     -- quit copy mode
g     -- go to top line
G     -- go to bottom line
Up    -- scroll up
Down  -- scroll down
h     -- move cursor left
j     -- move cursor down
k     -- move cursor up
l     -- move cursor right
w     -- move cursor forward one word
b     -- move cursor back one word
/     -- search forward
?     -- search backward
n     -- next keyword occurrence
N     -- previous keyword occurrence
Space -- start selection
Esc   -- clear selection
Enter -- copy selection
]     -- paste contents of buffer_0
```

Commands:
```
:setw -g mode-keys vi  -- use vi keys in buffer
:capture-pane          -- copy entire visible contents of pane to buffer_0
:list-buffers          -- show all buffers
:choose-buffer         -- show all buffers and paste selected
:save-buffer buf.txt   -- save buffer contents to buf.txt
:delete-buffer -b 1    -- delete buffer_1
```
(similarly we can use `-b n` with most buffer commands)

### Shorthand scripts
I use these two scripts, which I call `tm` and `tmx` respectively
```bash
#!/bin/bash

# usage: tm <session> # to start new session named <session>
#        tm           # as shorthand for tmux
if [ -z "$1" ]; then
  tmux
else
  S="$1"
  shift
  tmux new -s "$S" "$@"
fi
```
```bash
#!/bin/bash

# usage: tmx <session> # to attach to session,
#        tmx           # to list sessions
# like screen -x -r "$@"

if [ -z "$1" ]; then
  tmux ls
else
  S="$1"
  shift
  tmux attach -t "$S" "$@"
fi
```

### Launching scripts in new sessions
```bash
tmux new-session -s "session-name" "command"
tmux new-session -d -s "session-name" "command" # start detached
```
or use the shorter
```bash
tmux new -s "session-name" "command"
```

#### The `tmux.sh` Pattern
Often I'll create a subdirectory somewhere, and in it put a `tmux.sh`
script (possibly `hh_tmux.sh` or something). This script then creates
the various windows and starts programs so that in executing 
```
tmux new-session -s "mysession" -c "/path/to/project" bash tmux.sh
```
the whole session is initialised with a single command.

### Current Working Directory
Within tmux
```
Ctrl-B : attach -c /path/to
```
When starting
```bash
tmux new -s session_name -c path/to/start/in
````
When attaching, this will change the default directory for new windows
```bash
tmux attach -s session_name -c path/to/start/in
```

## Config
This goes in `.tmux.conf`.
```
set-option -g display-time 4000
```

## Attaching and Detaching
Detaching other sessions: `Ctrl-B D`

## Cloning a Session
To have two distinct sessions with the same windows:
```bash
tmux new-session -s new_session_name -t existing_session_name
```