Self-contained, pretty and versatile .tmux.conf configuration file.
Requirements:
- tmux
>= 2.6running inside Linux, Mac, OpenBSD, Cygwin or WSL - awk, perl and sed
- outside of tmux,
$TERMmust be set toxterm-256color
You can install Oh my tmux! at any of the following locations:
~$XDG_CONFIG_HOME/tmux~/.config/tmux
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"
$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 2: Productive Mouse-Free Development by @bphogan.
Now proceed to adjust your .local customization file copy.
-
I'm running tmux
HEADand things don't work properly. What should I do?Please open an issue describing what doesn't work with upcoming tmux. I'll do my best to address it.
-
Status line is broken and/or gets duplicated at the bottom of the screen. What gives?
This particularly happens on Linux when the distribution provides a version of glib that received Unicode 9.0 upgrades (glib
>= 2.50.1) while providing a version of glibc that didn't (glibc< 2.26). You may also configureLC_CTYPEto use anUTF-8locale. Typically VTE based terminal emulators rely on glib'sg_unichar_iswide()function while tmux relies on glibc'swcwidth()function. When these two functions disagree, display gets messed up.This can also happen on macOS when using iTerm2 and "Use Unicode version 9 character widths" is enabled in
Preferences... > Profiles > TextFor that reason, the default sample
.localcustomization file stopped using Unicode characters for which width changed in between Unicode 8.0 and 9.0 standards, as well as Emojis. -
I installed Powerline and/or (patched) fonts but can't see Powerline symbols.
First, you don't need to install Powerline. You only need fonts patched with Powerline symbols or the standalone
PowerlineSymbols.otffont. Then make sure your.localcustomization file copy uses the Powerline code points fortmux_conf_theme_left_separator_XXXvalues. -
I'm using Bash On Windows (WSL), colors and the Powerline look are broken.
There is currently a bug in the new console powering Bash On Windows preventing text attributes (bold, underscore, ...) to combine properly with colors. The workaround is to search your
.localcustomization file copy and replace attributes with'none'.Also, until Window's console replaces its GDI based render with a DirectWrite one, Powerline symbols will be broken.
The alternative is to use the Mintty terminal for WSL.
C-aacts as secondary prefix, while keeping defaultC-bprefix- visual theme inspired by Powerline
- maximize any pane to a new window with
<prefix> + - SSH/Mosh aware username and hostname status line information
- mouse mode toggle with
<prefix> m - laptop battery status line information
- uptime status line information
- optional highlight of focused pane
- configurable new windows and panes behavior (optionally retain current path)
- SSH/Mosh aware split pane (reconnects to remote server)
- copy to OS clipboard (needs
xsel,xclip, orwl-copyon Linux) - support for 4-digit hexadecimal Unicode characters
- Facebook PathPicker integration if available
- Urlscan (preferred) or Urlview integration if available
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.
Mouse mode allows you to set the active window, set the active pane, resize panes and automatically switches to copy-mode to select text.
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:
<prefix>means you have to either hit Ctrl + a or Ctrl + b<prefix> cmeans you have to hit Ctrl + a or Ctrl + b followed by c<prefix> C-cmeans you have to hit Ctrl + a or Ctrl + b followed by Ctrl + c
This configuration uses the following bindings:
-
<prefix> eopens the.localcustomization file copy with the editor defined by the$EDITORenvironment variable (defaults tovimwhen empty) -
<prefix> rreloads the configuration -
C-lclears both the screen and the tmux history -
<prefix> C-ccreates a new session -
<prefix> C-flets you switch to another session by name -
<prefix> C-hand<prefix> C-llet you navigate windows (default<prefix> nand<prefix> pare unbound) -
<prefix> Tabbrings you to the last active window -
<prefix> -splits the current pane vertically -
<prefix> _splits the current pane horizontally -
<prefix> h,<prefix> j,<prefix> kand<prefix> llet you navigate panes ala Vim -
<prefix> H,<prefix> J,<prefix> K,<prefix> Llet you resize panes -
<prefix> <and<prefix> >let you swap panes -
<prefix> +maximizes the current pane to a new window -
<prefix> mtoggles mouse mode on or off -
<prefix> Ulaunches Urlscan (preferred) or Urlview, if available -
<prefix> Flaunches Facebook PathPicker, if available -
<prefix> Enterenters copy-mode -
<prefix> blists the paste-buffers -
<prefix> ppastes from the top paste-buffer -
<prefix> Plets you choose the paste-buffer to paste from
Additionally, copy-mode-vi matches my own Vim configuration
Bindings for copy-mode-vi:
vbegins selection / visual modeC-vtoggles between blockwise visual mode and visual modeHjumps to the start of lineLjumps to the end of lineycopies the selection to the top paste-bufferEscapecancels the current operation
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).
Powerline originated as a status-line plugin for Vim. Its popular eye-catching
look is based on the use of special symbols: 
To make use of these symbols, there are several options:
- use a font that already bundles those: this is e.g. the case of the 2.030R-ro/1.050R-it version of the Source Code Pro font
- use a pre-patched font
- use your preferred font along with the Powerline font (that
only contains the Powerline symbols): this highly depends on your operating
system and your terminal emulator, for instance here's a
screenshot of iTerm2 configured to use
PowerlineSymbols.otf
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.
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:
#{battery_bar}: horizontal battery charge bar#{battery_hbar}: 1 character wide, horizontal battery charge bar#{battery_vbar}: 1 character wide, vertical battery charge bar#{battery_percentage}: battery percentage#{battery_status}: is battery charging or discharging?#{circled_session_name}: circled session number, up to 20#{hostname}: SSH/Mosh aware hostname information#{hostname_ssh}: SSH/Mosh aware hostname information, blank when not connected to a remote server through SSH/Mosh#{loadavg}: load average#{pairing}: is session attached to more than one client?#{prefix}: is prefix being depressed?#{root}: is current user root?#{synchronized}: are the panes synchronized?#{uptime_y}: uptime years#{uptime_d}: uptime days, modulo 365 when#{uptime_y}is used#{uptime_h}: uptime hours#{uptime_m}: uptime minutes#{uptime_s}: uptime seconds#{username}: SSH/Mosh aware username information#{username_ssh}: SSH aware username information, blank when not connected to a remote server through SSH/Mosh
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.
💡 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.
This configuration now comes with built-in TPM support:
- use the
set -g @plugin ...syntax to enable a plugin - whenever a plugin introduces a variable to be used in
status-leftorstatus-right, you can use it intmux_conf_theme_status_leftandtmux_conf_theme_status_rightvariables, see instructions above 👆 ⚠️ do not addset -g @plugin 'tmux-plugins/tpm'to any configuration file- ⛔️ do not add
run '~/.tmux/plugins/tpm/tpm'to any configuration file
- installing plugins:
<prefix> + I - uninstalling plugins:
<prefix> + Alt + u - updating plugins:
<prefix> + u
See the sample .local customization file for instructions.
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.
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:
- color emojis are only available through DirectWrite starting with Windows 8.1
- display of double width symbols, like the battery discharging symbol indicator (U+1F50B) is buggy
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
