gpakosz

.tmux

🇫🇷 Oh my tmux! My self-contained, pretty & versatile tmux configuration made with ❤️
Under Other
By gpakosz

dotfiles shell tmux powerline tmux-conf tmux-configuration tmux-config cli configuration terminal customization conf console screen wsl tmux-theme tmux-plugins plugins theme tpm

.tmux

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



Installation

Requirements:



To install, run the following from your terminal: (you may want to backup your
existing ~/.tmux.conf first)


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


💡 You can clone the repository anywhere you want, provided you create the
proper ~/.tmux.conf symlink and you copy the .tmux.conf.local sample file in
your home directory:


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


Then proceed to customize your ~/.tmux.conf.local 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 read tmux 2: Productive Mouse-Free
Development by @bphogan.


Troubleshooting

Please open an issue describing what doesn't work with upcoming tmux. I'll do
my best to address it.



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 configure
LC_CTYPE to use an UTF-8 locale. Typically VTE based terminal emulators
rely on glib's g_unichar_iswide() function while tmux relies on glibc's
wcwidth() 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 > Text


For that reason, the default ~/.tmux.conf.local file stopped using Unicode
characters for which width changed in between Unicode 8.0 and 9.0 standards,
as well as Emojis.



First, you don't need to install Powerline. You only need fonts patched with
Powerline symbols or the standalone PowerlineSymbols.otf font. Then make
sure your ~/.tmux.conf.local copy uses the right code points for
tmux_conf_theme_left_separator_XXX values.



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 ~/.tmux.conf.local 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.


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.



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



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:
- <prefix> means you have to either hit Ctrl + a or Ctrl + b
- <prefix> c means you have to hit Ctrl + a or Ctrl + b followed by c
- <prefix> C-c means you have to hit Ctrl + a or Ctrl + b followed by Ctrl + c


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. Instead of altering the ~/.tmux.conf file
and diverging from upstream, the proper way is to edit the ~/.tmux.conf.local
file.


Please refer to the sample .tmux.conf.local file to know more about variables
you can adjust to alter different behaviors. Pressing <prefix> e will open
~/.tmux.conf.local 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:


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



Please see the Powerline manual for further details.


Then edit your ~/.tmux.conf.local 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'


Configuring the status line

Contrary to the first iterations of this configuration, by now you have total
control on the content and order of status-left and status-right.


Edit your ~/.tmux.conf.local 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 custom 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


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 900call 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. See the sample
.tmux.conf.local 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 man 3 strftime.


Using TPM plugins

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-left or
status-right, you can use it in tmux_conf_theme_status_left and
tmux_conf_theme_status_right variables, see instructions above 👆
- ⚠ do not add set -g @plugin 'tmux-plugins/tpm'
- ⚠ do not add run '~/.tmux/plugins/tpm/tpm' to ~/.tmux.conf or your
- ~/.tmux.conf.local copy ← people who are used to alter
.tmux.conf to add TPM support will have to adapt their configuration


⚠ The TPM bindings differ slightly from upstream:
- installing plugins: <prefix> + I
- uninstalling plugins: <prefix> + Alt + u
- updating plugins: <prefix> + u


See ~/.tmux.conf.local for instructions.


Accessing the macOS clipboard from within tmux sessions (tmux < 2.6)

Chris Johnsen created the reattach-to-user-namespace
utility that makes pbcopy and pbpaste work
again within tmux.


To install reattach-to-user-namespace, use either MacPorts or
Homebrew:


$ port install tmux-pasteboard

or


$ brew install reattach-to-user-namespace

Once installed, reattach-to-usernamespace will be automatically detected.


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.



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.