Repository files navigation

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

Requirements:

• tmux>= 2.3 (soon>= 2.4) running inside Linux, Mac, OpenBSD, Cygwinor 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 yourexisting~/.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 theproper~/.tmux.conf symlink and you copy the.tmux.conf.local sample file inyour 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 tocustomize your~/.tmux.conf.local copy.

If you're a Vim user, setting the$EDITOR environment variable tovim willenable and further customize the vi-style key bindings (see tmux manual).

If you're new to tmux, I recommend you readtmux 2: Productive Mouse-FreeDevelopment by@bphogan.

• I'm running tmuxHEAD and things don't work properly. What should I do?

  Please open an issue describing what doesn't work with upcoming tmux. I'll domy 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 versionof glib that received Unicode 9.0 upgrades (glib>= 2.50.1) while providinga version of glibc that didn't (glibc< 2.26). You may also configureLC_CTYPE to use anUTF-8 locale. Typically VTE based terminal emulatorsrely on glib'sg_unichar_iswide() function while tmux relies on glibc'swcwidth() function. When these two functions disagree, display gets messedup.

  This can also happen on macOS when using iTerm2 and "Use Unicode version 9character widths" is enabled inPreferences... > Profiles > Text

  For that reason, the default~/.tmux.conf.local file stopped using Unicodecharacters 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 Powerlinesymbols.

  First, you don't need to install Powerline. You only need fonts patched withPowerline symbols or the standalonePowerlineSymbols.otf font. Then makesure 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 abug in the new console powering Bash On Windowspreventing text attributes (bold, underscore, ...) to combine properly withcolors. The workaround is to search your~/.tmux.conf.local copy andreplace attributes with'none'.

  Also, until Window's console replaces its GDI based render with a DirectWriteone, Powerline symbols will be broken.

  The alternative is to use theMintty terminal for WSL.

• C-a acts as secondary prefix, while keeping defaultC-b prefix
• visual theme inspired byPowerline
• 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 ofreattach-to-user-namespaceif available
• laptop battery status line information
• uptime status line information
• optional highlight of focused pane
• configurable new windows and panes behavior (optionally retain current path)
• SSH/Mosh aware split pane (reconnects to remote server)
• copy to OS clipboard (needsreattach-to-user-namespaceon macOS,xsel orxclip on Linux)
• support for 4-digit hexadecimal Unicode characters
• Facebook PathPicker integration if available
• Urlview integration if available

The "maximize any pane to a new window with<prefix> +" feature is differentfrom builtinresize-pane -Z as it allows you to further split a maximizedpane. It's also more flexible by allowing you to maximize a pane to a newwindow, then change window, then go back and the pane is still in maximizedstate 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, resizepanes and automatically switches to copy-mode to select text.

tmux may be controlled from an attached client by using a key combination of aprefix key, followed by a command key. This configuration usesC-a as asecondary prefix while keepingC-b as the default prefix. In the followinglist of key bindings:

• <prefix> means you have to either hitCtrl +a orCtrl +b
• <prefix> c means you have to hitCtrl +a orCtrl +b followed byc
• <prefix> C-c means you have to hitCtrl +a orCtrl +b followed byCtrl +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> h,<prefix> j,<prefix> k and<prefix> l let you navigatepanes 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 matchesmy own Vim configuration

Bindings forcopy-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

While this configuration tries to bring sane default settings, you may want tocustomize it further to your needs. Instead of altering the~/.tmux.conf fileand diverging from upstream, the proper way is to edit the~/.tmux.conf.localfile.

Please refer to the sample.tmux.conf.local file to know more about variablesyou can adjust to alter different behaviors. Pressing<prefix> e will open~/.tmux.conf.local with the editor defined by the$EDITOR environmentvariable (defaults tovim when empty).

Powerline originated as a status-line plugin for Vim. Its popular eye-catchinglook 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 the2.030R-ro/1.050R-it version of the Source Code Pro font
• use apre-patched font
• use your preferred font along with thePowerline font (thatonly contains the Powerline symbols):this highly depends on your operatingsystem and your terminal emulator, for instance here's ascreenshot of iTerm2 configured to usePowerlineSymbols.otf

Please see thePowerline manual for further details.

Then edit your~/.tmux.conf.local copy (with<prefix> e) and adjust thefollowing 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 totalcontrol on the content and order ofstatus-left andstatus-right.

Edit your~/.tmux.conf.local copy (<prefix> e) and adjust thetmux_conf_theme_status_left andtmux_conf_theme_status_right variables toyour 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 notconnected 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 connectedto a remote server through SSH/Mosh

Beside custom variables mentioned above, thetmux_conf_theme_status_left andtmux_conf_theme_status_right variables support usual tmux syntax, e.g. using#() to call an external command that inserts weather information provided bywttr.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} '

Thesleep 900 call makes sure the network request is issued at most every 15minutes whatever the value ofstatus-interval.

💡 You can also define your own custom variables. See the sample.tmux.conf.local file for instructions.

Finally, remembertmux_conf_theme_status_left andtmux_conf_theme_status_right end up being given to tmux asstatus-left andstatus-right which means they're passed throughstrftime(). 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)'

Seeman 3 strftime.

This configuration now comes with built-inTPM support:

• use theset -g @plugin ... syntax to enable a plugin
• whenever a plugin introduces a variable to be used instatus-left orstatus-right, you can use it intmux_conf_theme_status_left andtmux_conf_theme_status_right variables, see instructions above 👆
• ⚠️ do not addset -g @plugin 'tmux-plugins/tpm'
• ⚠️ do not addrun '~/.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

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

Chris Johnsen created thereattach-to-user-namespaceutility that makespbcopy andpbpaste workagain within tmux.

To installreattach-to-user-namespace, use eitherMacPorts orHomebrew:

$ 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. Forkingunder Cygwin is extremely slow and this configuration issues a lot ofrun-shell commands under the hood. As such, you will experience high CPUusage. As an alternative consider usingMintty terminal for WSL.

It is possible to use this configuration under Cygwin within Mintty, howeversupport for Unicode symbols and emojis lacks behind Mac and Linux.

Particularly, Mintty's text rendering is implemented with GDI which haslimitations:

• color emojis are only available through DirectWrite starting with Windows 8.1
• display of double width symbols, like the battery discharging symbol indicator(U+1F50B) is buggy

To get Unicode symbols displayed properly, you have to usefont linking.Openregedit.exe then navigate to the registry key atHKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\FontLink\SystemLinkand add a new entry for you preferred font to link it with the Segoe UI Symbolfont.