Self-contained, pretty and versatile .tmux.conf
configuration file.
Requirements:
>= 2.3
(soon >= 2.4
) running inside Linux, Mac, OpenBSD, Cygwin
or WSL$TERM
must be set to xterm-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/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.
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 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.
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 for
tmux_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 default C-b
prefix<prefix> +
<prefix> m
reattach-to-user-namespace
if availablereattach-to-user-namespace
on macOS, xsel
or xclip
on Linux)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 + cThis configuration uses the following bindings:
<prefix> e
opens ~/.tmux.conf.local
with the editor defined by the
$EDITOR
environment variable (defaults to vim
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> h
, <prefix> j
, <prefix> k
and <prefix> l
let you navigate
panes ala Vim
<prefix> H
, <prefix> J
, <prefix> K
, <prefix> L
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
Additionally, copy-mode-vi
matches my own Vim configuration
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 operationWhile 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:
PowerlineSymbols.otf
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'
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:
#{battery_bar}
: horizontal battery charge bar#{battery_percentage}
: battery percentage#{battery_status}
: is battery charging or discharging?#{battery_vbar}
: vertical battery charge bar#{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/MoshBeside 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
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. 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
.
This configuration now comes with built-in TPM support:
set -g @plugin ...
syntax to enable a pluginstatus-left
or
status-right
, you can use it in tmux_conf_theme_status_left
and
tmux_conf_theme_status_right
variables, see instructions above 👆set -g @plugin 'tmux-plugins/tpm'
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 configurationSee ~/.tmux.conf.local
for instructions.
< 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.
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.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。