A Tmux Crash Course

I’ve been using Tmux for about six months now and it has become just as essential to my workflow as vim. Pane and window management, copy-mode for navigating output, and session management make it a no-brainer for those who live in the terminal (and especially vim). I’ve compiled a list of tmux commands I use daily to help me work more efficiently.

If a tmux command I mention is bound to a keyboard shortcut by default, I’ll note that in parenthesis.

Session Management

Sessions are useful for completely separating work environments. I have a ‘Work’ session and a ‘Play’ session; in ‘Work’, I keep everything open that I need during my day-to-day development, while in ‘Play’, I keep open current open-source gems or other work I hack on at home.

tmux new -s session_name

creates a new tmux session named session_name

tmux attach -t session_name

attaches to an existing tmux session named session_name

tmux switch -t session_name

switches to an existing session named session_name

tmux list-sessions

lists existing tmux sessions

tmux detach (prefix + d)

detach the currently attached session

Windows

Tmux has a tabbed interface, but it calls its tabs “Windows”. To stay organized, I rename all the windows I use; if I’m hacking on a gem, I’ll name the window that gem’s name. The same thing goes for client applications. That way, I can recognize windows by context and not what application it’s running.

tmux new-window (prefix + c)

create a new window

tmux select-window -t :0-9 (prefix + 0-9)

move to the window based on index

tmux rename-window (prefix + ,)

rename the current window

Panes

Panes take my development time from bland to awesome. They’re the reason I was able to uninstall MacVim and develop solely in iTerm2. I don’t have to switch applications to switch contexts (editing, reading logs, IRB, etc.) - everything I do, I do in a terminal now. People argue that OS X’s Cmd+Tab is just as fast, but I don’t think so.

tmux split-window (prefix + ")

splits the window into two vertical panes

tmux split-window -h (prefix + %)

splits the window into two horizontal panes

tmux swap-pane -[UDLR] (prefix + { or })

swaps pane with another in the specified direction

tmux select-pane -[UDLR]

selects the next pane in the specified direction

tmux select-pane -t :.+

selects the next pane in numerical order

Helpful Tmux commands

tmux list-keys

lists out every bound key and the tmux command it runs

tmux list-commands

lists out every tmux command and its arguments

tmux info

lists out every session, window, pane, its pid, etc.

tmux source-file ~/.tmux.conf

reloads the current tmux configuration (based on a default tmux config)

Must-haves

These are some of my must-haves in my tmux config:

# remap prefix to Control + a
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# force a reload of the config file
unbind r
bind r source-file ~/.tmux.conf

# quick pane cycling
unbind ^A
bind ^A select-pane -t :.+

Workflow

During the day, I’ll work on one or two Rails apps, work on my dotfiles, run irssi, and maybe run vim in another window to take notes for myself. As I mentioned, I run all of this inside one tmux session (named work) and switch between the different windows throughout the day.

When I’m working on any Ruby work specifically, I’ll have a 75%/25% vertical split for vim and a terminal so I can run tests, interact with git, and code. If I run tests or ‘git diff’ and want to see more output than the 25% allots me, I’ll use tmux to swap the panes and then move into copy mode to see whatever I need to see.

Finally, I run iTerm2 in full-screen mode. Switching between OS X apps for an editor and a terminal is for chumps!

Love, hate, & tmux

It seems like everywhere I turn lately, I run into tmux.

Nick, Josh, Harold, and Goose are running their editor+shell combos inside of tmux on a daily basis. When I wanted to know more about remote pair programming with ssh, vim, and GNU screen, Stephen Caudill’s awesome article suggested tmux was superior to screen. Then, Bryan Liles recorded a tmux screencast.

I’m always down for a ride on a bandwagon, so I’m giving tmux a shot. I’ve rarely used GNU screen so this is not a comparison between two similar tools. I’m evaluating a tool many of my peers are using.

These are the questions I’ve had so far.

Why should I care?

“[Terminal tabs]: that’s not awesome.” - Bryan Liles.

I like the idea of having one shell for my whole development environment that I fly around inside like a Tasmanian devil.

I want speed and focus.

How do I get started?

I went with Bryan’s suggestion and downloaded iTerm 2. While I’m still on the fence about tmux, iTerm 2 is definitely an improvement and I recommend it without reservation.

Then I installed tmux, read the documentation, and fired it up.

brew install tmux
man tmux
tmux -u

Can I make the environment look good?

In my opinion, no. Anti-aliasing and 256 colors is the state of the art here. If I wanted a beautiful-looking editor, I’d still be using Textmate. I’m willing to trade off looks for speed. I know people who are very fast in other editors. I feel my ceiling for speed is higher in vim.

Josh tells me you can make some good-looking vim schemes with Palette that will be automatically converted to 256 colors. We’ll see.

How can I scroll up to see my backtraces?

This was non-obvious to me. You enter “copy mode” using prefix+[, then use vim bindings to move up (Ctrl+b, j, k, etc.).

Why is vim so slow?

There’s a noticeable delay in the editor that doesn’t exist in MacVim. I haven’t figured out why yet. I suspect it might actually be iTerm 2.

How can I copy text?

Enter “copy mode” using prefix+[, use vim bindings to move, select with space, copy with enter. This will let you copy and paste within tmux.

The bigger issue is copying text from within tmux and pasting it elsewhere. The very latest Homebrew formula has a patch to fix a pboard problem with copying in Mac OS X. It mostly works.

What are people doing to their ~/.tmux.conf?

Most common amongst thoughtbot folks and blog posts is to make tmux act more like vim and GNU screen.

# act like vim
setw -g mode-keys vi
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R
bind-key -r C-h select-window -t :-
bind-key -r C-l select-window -t :+

# act like GNU screen
unbind C-b
set -g prefix C-a

# look good
set -g default-terminal "screen-256color"

How do I name sessions?

One day I might work on Hoptoad. Another day, a client project. I’d like to name my tmux sessions so I can leave one, drop into another, and go back to the original with all my state maintained (files still open in my editor, console/logs I want open, etc.).

tmux new -s hoptoad
# hack, leave, do something else
tmux attach -t hoptoad

This is my favorite feature so far.

How do I split and move about panes and windows?

This is a big selling point of tmux but I’m not convinced. Contrast the following with Command+Tab or using your mouse to move and click. In terms of speed, it’s probably six or one half dozen.

Using vim and GNU screen bindings:

Ctrl+a c # create a new window
Ctrl+a , # name the window (test, vim, console, log, etc.)
Ctrl+a " # split pane horizontally
Ctrl+a % # split pane vertically
Ctrl+a j (or k) # move up or down a pane
Ctrl+a h (or l) # move left or right a pane
Ctrl+a x # kill a pane or window

I believe in the philosophy of setting my mouse free but the reality is takes time for muscle memory to make this fast and the savings might not really be significant.

Give it a shot

I’ve had a love-hate relationship with tmux in my first week using it, but the brief moments of flow I’ve experienced so far are enough to keep trying it.

Give tmux a shot and if you have any other tips, I’d love to hear them.