fzf added to the bashrc
[dotfiles/.git] / .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