Barbarian Meets Coding
barbarianmeetscoding

WebDev, UX & a Pinch of Fantasy

8 minutes readtmux

Tmux - Productive Mouse Free Development

Oftentimes when doing software development you’ll run into the need of having lots of terminals open running different tasks: development web servers, editors, git, building, linting, remote servers, etc… If you haven’t put much thought/energy into it you’re likely to use tabs or different terminal windows which you create on demand and arrange every now and then with your mouse. This is typically slow and will require you to redo the whole setup any time you restart your computer. Tmux is a tool (a terminal multiplexer if we want to speak with property) that helps you level up your terminal wizardry. To put it in a succint way, tmux is the vim of terminal management. It:

  • eases the creation and management of terminal windows and panes with a few keyboard shortcuts
  • lets you setup working/developing environments that you can pause and resume at will
  • is entirely customizable and can be made to work perfectly in tandem with vim
  • lets you pair program remotely with your colleagues

In this wiki you’ll learn how to setup tmux to improve your development workflow and it’s up to you to train your muscle memory to take the most advantage of tmux.

Setting up tmux

If you’re using a mac you can intall tmux using homebrew:

$ brew install tmux

Otherwise use the favorite package manager of your OS for choice and you should be able to find it. When in doubt take a look at tmux’s website.

You can check whether it works by running the following:

$ man tmux

Which should show you tmux manual or:

tmux

Which should start a tmux session. A tmux session?

Tmux Sessions, Windows and Panes

You can think of a tmux session as a workspace or project work environment. A session can have multiple windows (which behave like text-based virtual desktops) and multiple panes which let you divide the screen horizontally and vertical within the sample window.

When you start tmux like this:

$ tmux

You create an anonymous session with 1 window and 1 pane. Each pane has its own isolated terminal running within it.

Within a session you can create new windows and panes at will. When you want to communicate with tmux (as opposed to the terminal within the active pane) you use a special key combination that tells tmux to handle whatever comes next. The special key combination is typically called prefix and it defaults to C-b (as in keep CTRL pressed and b).

For instance, you can type prefix + % to split a window vertically (creating an additional pane to the right), and you can type prefix + " to split a window horitzontally (creating an additional pane below). These are shortcuts for tmux commands which can be accessed by typing prefix :. The equivalent commands for the shortcuts above are prefix :split-window -h and prefix :split-window -v (for some reason I haven’t been able to comprehend yet tmux considers a horizontal split what the rest of the world considers a vertical one).

// TODO: continue writing about windows, dettaching sessions, named sessions, etc

Great Tmux Shortcuts

  • prefix ? to get help and see the different commands available
  • prefix t to get the time

Working with Sessions

  • prefix d to detach from a session
  • prefix w to jump between sessions (this one is really cool)
  • prefix ( and prefix ) lets you switch between sessions

Working with Panes from a session

  • prefix x to close a pane

Copying Stuff

  • C-b [ to enter scroll mode where you can copy
  • Enter press enter to copy something (and get out of scroll mode)
  • C-b ] to paste

Basic Configuration

An awesome thing about tmux is that is completely configurable. If you’re a vim user you’ll be more comfortable creating vim-like bindings for tmux. For instance, you can change the prefix to C-j instead of C-b, that will put the CTRL key beside your left pinkie finger and j below your index finger nice and cozy in the home row.

Tmux configuration resides in ~/.tmux.conf. You will need to create that file and type the following:

# remap prefix from 'C-b' to 'C-j'
unbind C-b
set-option -g prefix C-j
bind-key C-j send-prefix

This basically says that you no longer want to use C-b and insist in using C-j which is much better.

You can then continue customizing stuff using mnemonics the vim way. Splitting a window in panes is much easier to remember if you use | for vertical splits and - for horizontal splits:

 # panes: window splitting
 unbind %
 bind | split-window -h
 unbind '"'
 bind - split-window -v

// TODO: more basic configuration

Setting up 24 bit True Color

If you want to have great color support within tmux you’ll need to enabled 24 bit true color. If you’re using iTerm2 on your Mac this is how you do it. Add the following to your tmux configuration:

# use the following terminals for pretty colors.
# This enables same colors from iTerm2 within tmux.
# This is also recommended in neovim :healthcheck
set -g default-terminal "screen-256color"
set -ga terminal-overrides ",xterm-256color:Tc"

Creating Reusable Configurations

Another great feature of tmux is the ability to define reusable development environments. You tell tmux… I’m going to have a development environment for this project, where I’m going to have open a window with the editor and a terminal, another window with a terminal for the server, yet another one with source control, etc, and then tmux just spins up the development environment for you whenever you need it.

Tmux offers an API to create reusable sessions in which you basically run tmux commands to create a session, windows and panes, and run diverse commands in them. (add more info about this)

There are, however, some simpler alternatives out there that allow you to create reusable configurations in a faster and easier way: Tmuxinator and tmuxp. Both of these are tools that let you create a development environment within tmux by specifying it declaratively in YAML.

Let’s take a look at tmuxp for instance. You install it using the python package manager:

$ pip3 install --user tmuxp

Make sure that you pip user directory is in your path and now you can use the tmuxp command to spin up development environments to you heart’s content. With tmuxp you can create the following configuration for a blogging dev environment called blog.yaml inside the .tmuxp directory:

session_name: blog
windows:
  - window_name: blog
    layout: main-vertical
    shell_command_before:
      - cd github/barbarianmeetscoding
    panes:
      - nvim .
      - git status

And then you can just run the following command:

$ tmuxp load blog

That will tell tmuxp to create all the windows and panes for you and execute the commands that you specify.

Some Useful tmux plugins

TPM Tmux Plugin Manager

TPM helps you install, uninstall and update your tmux plugins. Here’s how it works:

###########################
# Plugins
###########################
# To install plugins:
#   1) Add plugin down here
#   2) Prefix + I to install plugin
# To update plugins:
#   1) Prefix + U
# To remove plugins:
#   1) Remove line down here
#   2) Prefix + ALT + U

# List of plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
# Add more plugins below this line

# Run Tmux Plugin Manager
run '~/.tmux/plugins/tpm/tpm'

You can find more info on GitHub.

If you’re using iTerm2 on a Mac you may need to go to your Profiles, then keys and select that the option key should be treated as Esc+ in order for the Prefix + ALT + U combination to work.

Tmux resurrect

Tmux resurrect. Persists tmux sessions across system restarts. Install it by following these instructions and then just before you’re abuot to restart your computer:

  • Use prefix + CTRL-S to save all the sessions

And just after you’ve rebooted your computer.

  1. Open a tmux session with tmux
  2. Use prefix + CTRL-R to restore all the sessions

Type tmux list or tmux ls and there they should be.

References

Jaime González García

Written by Jaime González García , dad, husband, software engineer, ux designer, amateur pixel artist, tinkerer and master of the arcane arts. You can also find him on Twitter jabbering about random stuff.Jaime González García