Self-contained, pretty and versatile .tmux.conf
configuration file.
Requirements:
- tmux
>= 2.1
(soon>= 2.4
) running inside Linux, Mac, OpenBSD, Cygwin or WSL - awk, perl and sed
- outside of tmux,
$TERM
must be set toxterm-256color
To install, run the following from your terminal: (you may want to backup your
existing ~/.tmux.conf
first)
$ cd
$ git clone https://github.com/barimehdi77/.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/barimehdi77/.tmux.git
$ 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.
-
I'm running tmux
HEAD
and 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_CTYPE
to use anUTF-8
locale. 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 > 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. -
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.otf
font. Then make sure your~/.tmux.conf.local
copy uses the right code points fortmux_conf_theme_left_separator_XXX
values. -
I'm using Bash On Windows (WSL), colors and 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
~/.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.
C-a
acts as secondary prefix, while keeping defaultC-b
prefix- 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
- automatic usage of
reattach-to-user-namespace
if available - laptop battery status line information
- uptime status line information
- optional highlight of focused pane (tmux
>= 2.1
) - configurable new windows and panes behavior (optionally retain current path)
- SSH/Mosh aware split pane (reconnects to remote server)
- copy to OS clipboard (needs
reattach-to-user-namespace
on macOS,xsel
orxclip
on Linux) - support for 4-digit hexadecimal Unicode characters (requires
perl
or Bash >= 4.1.2) - Facebook PathPicker integration if available
- 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> 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:
-
<prefix> e
opens~/.tmux.conf.local
with the editor defined by the$EDITOR
environment variable (defaults tovim
when empty) -
<prefix> r
reloads the configuration -
C-l
clears both the screen and the tmux history -
<prefix> C-c
creates a new session -
<prefix> C-f
lets you switch to another session by name -
<prefix> C-h
and<prefix> C-l
let you navigate windows (default<prefix> n
and<prefix> p
are unbound) -
<prefix> Tab
brings you to the last active window -
<prefix> -
splits the current pane vertically -
<prefix> |
splits the current pane horizontally -
<prefix> right-arrow
,<prefix> left-arrow
,<prefix> up-arrow
and<prefix> down-arrow
let you navigate panes ala Vim -
<prefix> alt+right-arrow
,<prefix> alt+left-arrow
,<prefix> alt+up-arrow
,<prefix> alt+down-arrow
let you resize panes -
<prefix> <
and<prefix> >
let you swap panes -
<prefix> +
maximizes the current pane to a new window -
<prefix> m
toggles mouse mode on or off -
<prefix> U
launches Urlview (if available) -
<prefix> F
launches Facebook PathPicker (if available) -
<prefix> Enter
enters copy-mode -
<prefix> b
lists the paste-buffers -
<prefix> p
pastes from the top paste-buffer -
<prefix> P
lets you choose the paste-buffer to paste from
Bindings for copy-mode-vi
:
v
begins selection / visual modeC-v
toggles between blockwise visual mode and visual modeH
jumps to the start of lineL
jumps to the end of liney
copies the selection to the top paste-bufferEscape
cancels the current operation
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).
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
Credit: Gregory Pakosz