.tmux

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

Installation

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 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/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.

Troubleshooting

• 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.

Features

• C-a acts as secondary prefix, while keeping default C-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 or xclip 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.

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:

• <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> 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 mode
• C-v toggles between blockwise visual mode and visual mode
• H jumps to the start of line
• L jumps to the end of line
• y copies the selection to the top paste-buffer
• Escape cancels the current operation

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:

• 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