Home

Awesome

.tmux

Self-contained, pretty and versatile .tmux.conf configuration file.

Screenshot

Installation

Requirements:

⚠️ Before installing, you may want to backup your existing configuration.

You can install Oh my tmux! at any of the following locations:

Installing in ~:

$ cd
$ git clone https://github.com/gpakosz/.tmux.git
$ ln -s -f .tmux/.tmux.conf
$ cp .tmux/.tmux.conf.local .

Installing in $XDG_CONFIG_HOME/tmux:

$ git clone https://github.com/gpakosz/.tmux.git "/path/to/oh-my-tmux"
$ mkdir -p "$XDG_CONFIG_HOME/tmux"
$ ln -s "/path/to/oh-my-tmux/.tmux.conf" "$XDG_CONFIG_HOME/tmux/tmux.conf"
$ cp "/path/to/oh-my-tmux/.tmux.conf.local" "$XDG_CONFIG_HOME/tmux/tmux.conf.local"

Installing in ~/.config/tmux:

$ git clone https://github.com/gpakosz/.tmux.git "/path/to/oh-my-tmux"
$ mkdir -p "~/.config/tmux"
$ ln -s "/path/to/oh-my-tmux/.tmux.conf" "~/.config/tmux/tmux.conf"
$ cp "/path/to/oh-my-tmux/.tmux.conf.local" "~/.config/tmux/tmux.conf.local"

⚠️ When installing $XDG_CONFIG_HOME/tmux or ~/.config/tmux, the configuration file names don't have a leading . character.

❗️ You should never alter the main .tmux.conf or tmux.conf file. If you do, you're on your own. Instead, every customization should happen in your .tmux.conf.local or tmux.conf.local customization file copy.

If you're a Vim user, setting the $EDITOR environment variable to vim will enable and further customize the vi-style key bindings (see tmux manual).

If you're new to tmux, I recommend you to read tmux 3: Productive Mouse-Free Development by @bphogan.

Now proceed to adjust your .local customization file copy.

Troubleshooting

Features

The "maximize any pane to a new window with <prefix> +" feature is different from builtin resize-pane -Z as it allows you to further split a maximized pane. It's also more flexible by allowing you to maximize a pane to a new window, then change window, then go back and the pane is still in maximized state in its own window. You can then minimize a pane by using <prefix> + either from the source window or the maximized window.

Maximize pane

Mouse mode allows you to set the active window, set the active pane, resize panes and automatically switches to copy-mode to select text.

Mouse mode

Bindings

tmux may be controlled from an attached client by using a key combination of a prefix key, followed by a command key. This configuration uses C-a as a secondary prefix while keeping C-b as the default prefix. In the following list of key bindings:

This configuration uses the following bindings:

Additionally, copy-mode-vi matches my own Vim configuration

Bindings for copy-mode-vi:

Configuration

While this configuration tries to bring sane default settings, you may want to customize it further to your needs.

❗️ Again, you should never alter the main .tmux.conf or tmux.conf file. If you do, you're on your own.

Please refer to the sample .local customization file to know more about the variables that allow you to alter different behaviors. Upon successful installation, pressing <prefix> e will open your .local customization file copy with the editor defined by the $EDITOR environment variable (defaults to vim when empty).

Enabling the Powerline look

Powerline originated as a status-line plugin for Vim. Its popular eye-catching look is based on the use of special symbols: <img width="80" alt="Powerline Symbols" style="vertical-align: middle;" src="https://cloud.githubusercontent.com/assets/553208/10687156/1b76dda6-796b-11e5-83a1-1634337c4571.png" />

To make use of these symbols, there are several options:

Then edit your .local customization file copy (with <prefix> e) and adjust the following variables:

tmux_conf_theme_left_separator_main='\uE0B0'
tmux_conf_theme_left_separator_sub='\uE0B1'
tmux_conf_theme_right_separator_main='\uE0B2'
tmux_conf_theme_right_separator_sub='\uE0B3'

The Powerline manual contains further details on how to install fonts containing the Powerline symbols. You don't need to install Powerline itself though.

Configuring the status line

Edit your .local customization file copy (<prefix> e) and adjust the tmux_conf_theme_status_left and tmux_conf_theme_status_right variables to your own preferences.

This configuration supports the following builtin variables:

Beside the variables mentioned above, the tmux_conf_theme_status_left and tmux_conf_theme_status_right variables support usual tmux syntax, e.g. using #() to call an external command that inserts weather information provided by wttr.in:

tmux_conf_theme_status_right='#{prefix}#{pairing}#{synchronized} #(curl -m 1 wttr.in?format=3 2>/dev/null; sleep 900) , %R , %d %b | #{username}#{root} | #{hostname} '

The sleep 900 call makes sure the network request is issued at most every 15 minutes whatever the value of status-interval.

Weather information from wttr.in

💡 You can also define your own custom variables by writing special functions, see the sample .local customization file for instructions.

Finally, remember tmux_conf_theme_status_left and tmux_conf_theme_status_right end up being given to tmux as status-left and status-right which means they're passed through strftime(). As such, the % character has a special meaning and needs to be escaped by doubling it, e.g.

tmux_conf_theme_status_right='#(echo foo %% bar)'

See also man 3 strftime.

Using TPM plugins

This configuration now comes with built-in TPM support:

⚠️ The TPM bindings differ slightly from upstream:

See the sample .local customization file for instructions.

Using the configuration under Cygwin within Mintty

I don't recommend running this configuration with Cygwin anymore. Forking under Cygwin is extremely slow and this configuration issues a lot of run-shell commands under the hood. As such, you will experience high CPU usage. As an alternative consider using Mintty terminal for WSL.

cygwin

It is possible to use this configuration under Cygwin within Mintty, however support for Unicode symbols and emojis lacks behind Mac and Linux.

Particularly, Mintty's text rendering is implemented with GDI which has limitations:

To get Unicode symbols displayed properly, you have to use font linking. Open regedit.exe then navigate to the registry key at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\FontLink\SystemLink and add a new entry for you preferred font to link it with the Segoe UI Symbol font.

regedit