˗ˏˋ ★ ˎˊ˗ My self-contained, pretty and versatile tmux configuration, made with ❤️ ˗ˏˋ ★ ˎˊ˗

Installation

Requirements:

tmux >= 2.6 running on Linux, macOS, OpenBSD, Windows (WSL or Cygwin)
awk, perl (with Time::HiRes support), grep, and sed
Outside of tmux, the TERM environment variable must be set to xterm-256color

⚠️ Before installing, you may want to backup your existing configuration.

You can install Oh my tmux! at any of the following locations:

~
$XDG_CONFIG_HOME/tmux
~/.config/tmux

Automatic installation

Copy the following command and paste it in your terminal.

curl -fsSL "https://github.com/gpakosz/.tmux/raw/refs/heads/master/install.sh#$(date +%s)" | bash

Manual installation in ~

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

Manual installation in $XDG_CONFIG_HOME/tmux

$ git clone --single-branch 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"

Manual installation ~/.config/tmux

$ git clone --single-branch 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

⚠️ When installing $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 VIUAL or 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 the tmux getting started guide, as well as the tmux 3: Productive Mouse-Free Development book by @bphogan.

Now proceed to adjust your .local customization file copy.

Troubleshooting

I believe something's not quite right

Please, try make sure no tmux client or server process is currently running.

Then launch tmux with:
```
$ tmux -f /dev/null -L test
```
Which launches a new tmux client/server pair without loading any configuration.

If the issue is still reproducing, please reach out to the tmux project for support.

Otherwise, please open an issue describing what doesn't work and I'll do my best to address it.
I tried to used set, bind and unbind in my .local customization file, but Oh my tmux! overwrites my preferences

When that happens append #!important to the line:
```
bind c new-window -c '#{pane_current_path}' #!important
```
```
set -g default-terminal "screen-256color" #!important
```
Status line is broken and/or gets duplicated at the bottom of the screen

This could happen 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 sample .local customization 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 I can't see the Powerline symbols

🤯 Please realize that 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 .local customization file copy uses the Powerline code points for the tmux_conf_theme_left_separator_main, tmux_conf_theme_left_separator_sub, tmux_conf_theme_right_separator_main and tmux_conf_theme_right_separator_sub variables.

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> +
Mouse mode toggle with <prefix> m
Laptop battery status line information
Uptime status line information
Optional highlight of focused pane
Configurable new sessions, windows and panes behavior (to optionally retain the current path)
SSH/Mosh aware username and hostname status line information
SSH/Mosh aware pane splitting (with automatic reconnection to the remote server)
Copy to OS clipboard (needs xsel, xclip, or wl-copy on Linux)
Support for 4-digit hexadecimal Unicode characters
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 the builtin resize-pane -Z command, 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 <kbd>Ctrl</kbd> + <kbd>a</kbd> or <kbd>Ctrl</kbd> + <kbd>b</kbd>
<prefix> c means you have to hit <kbd>Ctrl</kbd> + <kbd>a</kbd> or <kbd>Ctrl</kbd> + <kbd>b</kbd> followed by <kbd>c</kbd>
<prefix> C-c means you have to hit <kbd>Ctrl</kbd> + <kbd>a</kbd> or <kbd>Ctrl</kbd> + <kbd>b</kbd> followed by <kbd>Ctrl</kbd> + <kbd>c</kbd>

This configuration uses the following bindings:

<prefix> e opens the .local customization file copy with the editor defined by the VISUAL or 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 is unbound and <prefix> p is repurposed)
<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

.tmux

Install / Use

README

Installation

Troubleshooting

Features

Bindings