.tmux/README.md

   1 .tmux
   2 =====
   3
   4 Self-contained, pretty and versatile `.tmux.conf` configuration file.
   5
   6 ![Screenshot](https://cloud.githubusercontent.com/assets/553208/19740585/85596a5a-9bbf-11e6-8aa1-7c8d9829c008.gif)
   7
   8 Installation
   9 ------------
  10
  11 Requirements:
  12
  13   - tmux **`>= 2.1`** (soon `>= 2.4`) running inside Linux, Mac, OpenBSD, Cygwin
  14     or WSL
  15   - awk, perl and sed
  16   - outside of tmux, `$TERM` must be set to `xterm-256color`
  17
  18 To install, run the following from your terminal: (you may want to backup your
  19 existing `~/.tmux.conf` first)
  20
  21 ```
  22 $ cd
  23 $ git clone https://github.com/gpakosz/.tmux.git
  24 $ ln -s -f .tmux/.tmux.conf
  25 $ cp .tmux/.tmux.conf.local .
  26 ```
  27
  28 Then proceed to [customize] your `~/.tmux.conf.local` copy.
  29
  30 [customize]: #enabling-the-powerline-look
  31
  32 If you're a Vim user, setting the `$EDITOR` environment variable to `vim` will
  33 enable and further customize the vi-style key bindings (see tmux manual).
  34
  35 If you're new to tmux, I recommend you read [tmux 2: Productive Mouse-Free
  36 Development][bhtmux2] by [@bphogan].
  37
  38 [bhtmux2]: https://pragprog.com/book/bhtmux2/tmux-2
  39 [@bphogan]: https://twitter.com/bphogan
  40
  41 Troubleshooting
  42 ---------------
  43
  44  - **I'm running tmux `HEAD` and things don't work properly. What should I do?**
  45
  46    Please open an issue describing what doesn't work with upcoming tmux. I'll do
  47    my best to address it.
  48
  49  - **Status line is broken and/or gets duplicated at the bottom of the screen.
  50    What gives?**
  51
  52    This particularly happens on Linux when the distribution provides a version
  53    of glib that received Unicode 9.0 upgrades (glib `>= 2.50.1`) while providing
  54    a version of glibc that didn't (glibc `< 2.26`). You may also configure
  55    `LC_CTYPE` to use an `UTF-8` locale. Typically VTE based terminal emulators
  56    rely on glib's `g_unichar_iswide()` function while tmux relies on glibc's
  57    `wcwidth()` function. When these two functions disagree, display gets messed
  58    up.
  59
  60    This can also happen on macOS when using iTerm2 and "Use Unicode version 9
  61    character widths" is enabled in `Preferences... > Profiles > Text`
  62
  63    For that reason, the default `~/.tmux.conf.local` file stopped using Unicode
  64    characters for which width changed in between Unicode 8.0 and 9.0 standards,
  65    as well as Emojis.
  66
  67  - **I installed Powerline and/or (patched) fonts but can't see Powerline
  68    symbols.**
  69
  70    First, you don't need to install Powerline. You only need fonts patched with
  71    Powerline symbols or the standalone `PowerlineSymbols.otf` font. Then make
  72    sure your `~/.tmux.conf.local` copy uses the right code points for
  73    `tmux_conf_theme_left_separator_XXX` values.
  74
  75  - **I'm using Bash On Windows (WSL), colors and Powerline look are broken.**
  76
  77    There is currently a [bug][1681] in the new console powering Bash On Windows
  78    preventing text attributes (bold, underscore, ...) to combine properly with
  79    colors. The workaround is to search your `~/.tmux.conf.local` copy and
  80    replace attributes with `'none'`.
  81
  82    Also, until Window's console replaces its GDI based render with a DirectWrite
  83    one, Powerline symbols will be broken.
  84
  85    The alternative is to use the [Mintty terminal for WSL][wsltty].
  86
  87 [1681]: https://github.com/Microsoft/BashOnWindows/issues/1681
  88 [wsltty]: https://github.com/mintty/wsltty
  89
  90 Features
  91 --------
  92
  93  - `C-a` acts as secondary prefix, while keeping default `C-b` prefix
  94  - visual theme inspired by [Powerline][]
  95  - [maximize any pane to a new window with `<prefix> +`][maximize-pane]
  96  - SSH/Mosh aware username and hostname status line information
  97  - mouse mode toggle with `<prefix> m`
  98  - automatic usage of [`reattach-to-user-namespace`][reattach-to-user-namespace]
  99    if available
 100  - laptop battery status line information
 101  - uptime status line information
 102  - optional highlight of focused pane (tmux `>= 2.1`)
 103  - configurable new windows and panes behavior (optionally retain current path)
 104  - SSH/Mosh aware split pane (reconnects to remote server)
 105  - copy to OS clipboard (needs [`reattach-to-user-namespace`][reattach-to-user-namespace]
 106    on macOS, `xsel` or `xclip` on Linux)
 107  - support for 4-digit hexadecimal Unicode characters (requires `perl` or Bash >= 4.1.2)
 108  - [Facebook PathPicker][] integration if available
 109  - [Urlview][] integration if available
 110
 111 [Powerline]: https://github.com/Lokaltog/powerline
 112 [maximize-pane]: http://pempek.net/articles/2013/04/14/maximizing-tmux-pane-new-window/
 113 [reattach-to-user-namespace]: https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard
 114 [Facebook PathPicker]: https://facebook.github.io/PathPicker/
 115 [Urlview]: https://packages.debian.org/stable/misc/urlview
 116
 117 The "maximize any pane to a new window with `<prefix> +`" feature is different
 118 from builtin `resize-pane -Z` as it allows you to further split a maximized
 119 pane. It's also more flexible by allowing you to maximize a pane to a new
 120 window, then change window, then go back and the pane is still in maximized
 121 state in its own window. You can then minimize a pane by using `<prefix> +`
 122 either from the source window or the maximized window.
 123
 124 ![Maximize pane](https://cloud.githubusercontent.com/assets/553208/9890858/ee3c0ca6-5c02-11e5-890e-05d825a46c92.gif)
 125
 126 Mouse mode allows you to set the active window, set the active pane, resize
 127 panes and automatically switches to copy-mode to select text.
 128
 129 ![Mouse mode](https://cloud.githubusercontent.com/assets/553208/9890797/8dffe542-5c02-11e5-9c06-a25b452e6fcc.gif)
 130
 131 Bindings
 132 --------
 133
 134 tmux may be controlled from an attached client by using a key combination of a
 135 prefix key, followed by a command key. This configuration uses `C-a` as a
 136 secondary prefix while keeping `C-b` as the default prefix. In the following
 137 list of key bindings:
 138   - `<prefix>` means you have to either hit <kbd>Ctrl</kbd> + <kbd>a</kbd> or <kbd>Ctrl</kbd> + <kbd>b</kbd>
 139   - `<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>
 140   - `<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>
 141
 142 This configuration uses the following bindings:
 143
 144  - `<prefix> e` opens `~/.tmux.conf.local` with the editor defined by the
 145    `$EDITOR` environment variable (defaults to `vim` when empty)
 146  - `<prefix> r` reloads the configuration
 147  - `C-l` clears both the screen and the tmux history
 148
 149  - `<prefix> C-c` creates a new session
 150  - `<prefix> C-f` lets you switch to another session by name
 151
 152  - `<prefix> C-h` and `<prefix> C-l` let you navigate windows (default
 153    `<prefix> n` and `<prefix> p` are unbound)
 154  - `<prefix> Tab` brings you to the last active window
 155
 156  - `<prefix> -` splits the current pane vertically
 157  - `<prefix> _` splits the current pane horizontally
 158  - `<prefix> h`, `<prefix> j`, `<prefix> k` and `<prefix> l` let you navigate
 159    panes ala Vim
 160  - `<prefix> H`, `<prefix> J`, `<prefix> K`, `<prefix> L` let you resize panes
 161  - `<prefix> <` and `<prefix> >` let you swap panes
 162  - `<prefix> +` maximizes the current pane to a new window
 163
 164  - `<prefix> m` toggles mouse mode on or off
 165
 166  - `<prefix> U` launches Urlview (if available)
 167  - `<prefix> F` launches Facebook PathPicker (if available)
 168
 169  - `<prefix> Enter` enters copy-mode
 170  - `<prefix> b` lists the paste-buffers
 171  - `<prefix> p` pastes from the top paste-buffer
 172  - `<prefix> P` lets you choose the paste-buffer to paste from
 173
 174 Additionally, `copy-mode-vi` matches [my own Vim configuration][]
 175
 176 [my own Vim configuration]: https://github.com/gpakosz/.vim.git
 177
 178 Bindings for `copy-mode-vi`:
 179
 180 - `v` begins selection / visual mode
 181 - `C-v` toggles between blockwise visual mode and visual mode
 182 - `H` jumps to the start of line
 183 - `L` jumps to the end of line
 184 - `y` copies the selection to the top paste-buffer
 185 - `Escape` cancels the current operation
 186
 187 Configuration
 188 -------------
 189
 190 While this configuration tries to bring sane default settings, you may want to
 191 customize it further to your needs. Instead of altering the `~/.tmux.conf` file
 192 and diverging from upstream, the proper way is to edit the `~/.tmux.conf.local`
 193 file.
 194
 195 Please refer to the default `~/.tmux.conf.local` file to know more about
 196 variables you can adjust to alter different behaviors. Pressing `<prefix> e`
 197 will open `~/.tmux.conf.local` with the editor defined by the `$EDITOR`
 198 environment variable (defaults to `vim` when empty).
 199
 200 ### Enabling the Powerline look
 201
 202 Powerline originated as a status-line plugin for Vim. Its popular eye-catching
 203 look is based on the use of special symbols: <img width="80" alt="Powerline Symbols" style="vertical-align: middle;" src="https://cloud.githubusercontent.com/assets/553208/10687156/1b76dda6-796b-11e5-83a1-1634337c4571.png" />
 204
 205 To make use of these symbols, there are several options:
 206
 207 - use a font that already bundles those: this is e.g. the case of the
 208   [2.030R-ro/1.050R-it version][source code pro] of the Source Code Pro font
 209 - use a [pre-patched font][powerline patched fonts]
 210 - use your preferred font along with the [Powerline font][powerline font] (that
 211   only contains the Powerline symbols): [this highly depends on your operating
 212   system and your terminal emulator][terminal support], for instance here's a
 213   screenshot of iTerm2 configured to use `PowerlineSymbols.otf`
 214   ![iTerm2 + Powerline font](https://user-images.githubusercontent.com/553208/62243890-8232f500-b3de-11e9-9b8c-51a5d38bdaa8.png)
 215
 216 [source code pro]: https://github.com/adobe-fonts/source-code-pro/releases/tag/2.030R-ro/1.050R-it
 217 [powerline patched fonts]: https://github.com/powerline/fonts
 218 [powerline font]: https://github.com/powerline/powerline/raw/develop/font/PowerlineSymbols.otf
 219 [terminal support]: http://powerline.readthedocs.io/en/master/usage.html#usage-terminal-emulators
 220 [Powerline manual]: http://powerline.readthedocs.org/en/latest/installation.html#fonts-installation
 221
 222 Please see the [Powerline manual] for further details.
 223
 224 Then edit the `~/.tmux.conf.local` file (`<prefix> e`) and adjust the following
 225 variables:
 226
 227 ```
 228 tmux_conf_theme_left_separator_main='\uE0B0'
 229 tmux_conf_theme_left_separator_sub='\uE0B1'
 230 tmux_conf_theme_right_separator_main='\uE0B2'
 231 tmux_conf_theme_right_separator_sub='\uE0B3'
 232 ```
 233 ### Configuring the status line
 234
 235 Contrary to the first iterations of this configuration, by now you have total
 236 control on the content and order of `status-left` and `status-right`.
 237
 238 Edit the `~/.tmux.conf.local` file (`<prefix> e`) and adjust the
 239 `tmux_conf_theme_status_left` and `tmux_conf_theme_status_right` variables to
 240 your own preferences.
 241
 242 This configuration supports the following builtin variables:
 243
 244  - `#{battery_bar}`: horizontal battery charge bar
 245  - `#{battery_percentage}`: battery percentage
 246  - `#{battery_status}`: is battery charging or discharging?
 247  - `#{battery_vbar}`: vertical battery charge bar
 248  - `#{circled_session_name}`: circled session number, up to 20
 249  - `#{hostname}`: SSH/Mosh aware hostname information
 250  - `#{hostname_ssh}`: SSH/Mosh aware hostname information, blank when not
 251    connected to a remote server through SSH/Mosh
 252  - `#{loadavg}`: load average
 253  - `#{pairing}`: is session attached to more than one client?
 254  - `#{prefix}`: is prefix being depressed?
 255  - `#{root}`: is current user root?
 256  - `#{synchronized}`: are the panes synchronized?
 257  - `#{uptime_y}`: uptime years
 258  - `#{uptime_d}`: uptime days, modulo 365 when `#{uptime_y}` is used
 259  - `#{uptime_h}`: uptime hours
 260  - `#{uptime_m}`: uptime minutes
 261  - `#{uptime_s}`: uptime seconds
 262  - `#{username}`: SSH/Mosh aware username information
 263  - `#{username_ssh}`: SSH aware username information, blank when not connected
 264    to a remote server through SSH/Mosh
 265
 266 Beside custom variables mentioned above, the `tmux_conf_theme_status_left` and
 267 `tmux_conf_theme_status_right` variables support usual tmux syntax, e.g. using
 268 `#()` to call an external command that inserts weather information provided by
 269 [wttr.in]:
 270 ```
 271 tmux_conf_theme_status_right='#{prefix}#{pairing}#{synchronized} #(curl wttr.in?format=3) , %R , %d %b | #{username}#{root} | #{hostname} '
 272 ```
 273
 274 ![Weather information from wttr.in](https://user-images.githubusercontent.com/553208/52175490-07797c00-27a5-11e9-9fb6-42eec4fe4188.png)
 275
 276 [wttr.in]: https://github.com/chubin/wttr.in#one-line-output
 277
 278 ### Accessing the macOS clipboard from within tmux sessions
 279
 280 [Chris Johnsen created the `reattach-to-user-namespace`
 281 utility][reattach-to-user-namespace] that makes `pbcopy` and `pbpaste` work
 282 again within tmux.
 283
 284 To install `reattach-to-user-namespace`, use either [MacPorts][] or
 285 [Homebrew][]:
 286
 287     $ port install tmux-pasteboard
 288
 289 or
 290
 291     $ brew install reattach-to-user-namespace
 292
 293 Once installed, `reattach-to-usernamespace` will be automatically detected.
 294
 295 [MacPorts]: http://www.macports.org/
 296 [Homebrew]: http://brew.sh/
 297
 298 ### Using the configuration under Cygwin within Mintty
 299
 300 **I don't recommend running this configuration with Cygwin anymore. Forking
 301 under Cygwin is extremely slow and this configuration issues a lot of
 302 `run-shell` commands under the hood. As such, you will experience high CPU
 303 usage. As an alternative consider using [Mintty terminal for WSL][wsltty].**
 304
 305 ![cygwin](https://cloud.githubusercontent.com/assets/553208/19741789/67a3f3d8-9bc2-11e6-9ecc-499fc0228ee6.png)
 306
 307 It is possible to use this configuration under Cygwin within Mintty, however
 308 support for Unicode symbols and emojis lacks behind Mac and Linux.
 309
 310 Particularly, Mintty's text rendering is implemented with GDI which has
 311 limitations:
 312
 313 - color emojis are only available through DirectWrite starting with Windows 8.1
 314 - display of double width symbols, like the battery discharging symbol indicator
 315   (U+1F50B) is buggy
 316
 317 To get Unicode symbols displayed properly, you have to use [font linking].
 318 Open `regedit.exe` then navigate to the registry key at
 319 `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\FontLink\SystemLink`
 320 and add a new entry for you preferred font to link it with the Segoe UI Symbol
 321 font.
 322
 323 ![regedit](https://cloud.githubusercontent.com/assets/553208/19741304/71a2f3ae-9bc0-11e6-96aa-4c09a812c313.png)
 324
 325 [font linking]: https://msdn.microsoft.com/en-us/goglobal/bb688134.aspx