X-Git-Url: https://git.josue.xyz/?p=dotfilesold%2F.git;a=blobdiff_plain;f=.tmux%2FREADME.md;fp=.tmux%2FREADME.md;h=470007d976f7a9c0bc308a21eacbe99fc54dce39;hp=0000000000000000000000000000000000000000;hb=53a831e99cb3bc5a1903665f74198026c25f788f;hpb=56b426ab888bd14c2b7875f8352f06c40f7aec6d diff --git a/.tmux/README.md b/.tmux/README.md new file mode 100644 index 0000000..470007d --- /dev/null +++ b/.tmux/README.md @@ -0,0 +1,325 @@ +.tmux +===== + +Self-contained, pretty and versatile `.tmux.conf` configuration file. + +![Screenshot](https://cloud.githubusercontent.com/assets/553208/19740585/85596a5a-9bbf-11e6-8aa1-7c8d9829c008.gif) + +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/gpakosz/.tmux.git +$ ln -s -f .tmux/.tmux.conf +$ cp .tmux/.tmux.conf.local . +``` + +Then proceed to [customize] your `~/.tmux.conf.local` copy. + +[customize]: #enabling-the-powerline-look + +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][bhtmux2] by [@bphogan]. + +[bhtmux2]: https://pragprog.com/book/bhtmux2/tmux-2 +[@bphogan]: https://twitter.com/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][1681] 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][wsltty]. + +[1681]: https://github.com/Microsoft/BashOnWindows/issues/1681 +[wsltty]: https://github.com/mintty/wsltty + +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 ` +`][maximize-pane] + - SSH/Mosh aware username and hostname status line information + - mouse mode toggle with ` m` + - automatic usage of [`reattach-to-user-namespace`][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`][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 + +[Powerline]: https://github.com/Lokaltog/powerline +[maximize-pane]: http://pempek.net/articles/2013/04/14/maximizing-tmux-pane-new-window/ +[reattach-to-user-namespace]: https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard +[Facebook PathPicker]: https://facebook.github.io/PathPicker/ +[Urlview]: https://packages.debian.org/stable/misc/urlview + +The "maximize any pane to a new window with ` +`" 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 ` +` +either from the source window or the maximized window. + +![Maximize pane](https://cloud.githubusercontent.com/assets/553208/9890858/ee3c0ca6-5c02-11e5-890e-05d825a46c92.gif) + +Mouse mode allows you to set the active window, set the active pane, resize +panes and automatically switches to copy-mode to select text. + +![Mouse mode](https://cloud.githubusercontent.com/assets/553208/9890797/8dffe542-5c02-11e5-9c06-a25b452e6fcc.gif) + +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: + - `` means you have to either hit Ctrl + a or Ctrl + b + - ` c` means you have to hit Ctrl + a or Ctrl + b followed by c + - ` C-c` means you have to hit Ctrl + a or Ctrl + b followed by Ctrl + c + +This configuration uses the following bindings: + + - ` e` opens `~/.tmux.conf.local` with the editor defined by the + `$EDITOR` environment variable (defaults to `vim` when empty) + - ` r` reloads the configuration + - `C-l` clears both the screen and the tmux history + + - ` C-c` creates a new session + - ` C-f` lets you switch to another session by name + + - ` C-h` and ` C-l` let you navigate windows (default + ` n` and ` p` are unbound) + - ` Tab` brings you to the last active window + + - ` -` splits the current pane vertically + - ` _` splits the current pane horizontally + - ` h`, ` j`, ` k` and ` l` let you navigate + panes ala Vim + - ` H`, ` J`, ` K`, ` L` let you resize panes + - ` <` and ` >` let you swap panes + - ` +` maximizes the current pane to a new window + + - ` m` toggles mouse mode on or off + + - ` U` launches Urlview (if available) + - ` F` launches Facebook PathPicker (if available) + + - ` Enter` enters copy-mode + - ` b` lists the paste-buffers + - ` p` pastes from the top paste-buffer + - ` P` lets you choose the paste-buffer to paste from + +Additionally, `copy-mode-vi` matches [my own Vim configuration][] + +[my own Vim configuration]: https://github.com/gpakosz/.vim.git + +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 default `~/.tmux.conf.local` file to know more about +variables you can adjust to alter different behaviors. Pressing ` 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: Powerline 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][source code pro] of the Source Code Pro font +- use a [pre-patched font][powerline patched fonts] +- use your preferred font along with the [Powerline font][powerline font] (that + only contains the Powerline symbols): [this highly depends on your operating + system and your terminal emulator][terminal support], for instance here's a + screenshot of iTerm2 configured to use `PowerlineSymbols.otf` + ![iTerm2 + Powerline font](https://user-images.githubusercontent.com/553208/62243890-8232f500-b3de-11e9-9b8c-51a5d38bdaa8.png) + +[source code pro]: https://github.com/adobe-fonts/source-code-pro/releases/tag/2.030R-ro/1.050R-it +[powerline patched fonts]: https://github.com/powerline/fonts +[powerline font]: https://github.com/powerline/powerline/raw/develop/font/PowerlineSymbols.otf +[terminal support]: http://powerline.readthedocs.io/en/master/usage.html#usage-terminal-emulators +[Powerline manual]: http://powerline.readthedocs.org/en/latest/installation.html#fonts-installation + +Please see the [Powerline manual] for further details. + +Then edit the `~/.tmux.conf.local` file (` e`) and adjust the following +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' +``` +### Configuring the status line + +Contrary to the first iterations of this configuration, by now you have total +control on the content and order of `status-left` and `status-right`. + +Edit the `~/.tmux.conf.local` file (` e`) and adjust the +`tmux_conf_theme_status_left` and `tmux_conf_theme_status_right` variables to +your 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 not + connected 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 connected + to a remote server through SSH/Mosh + +Beside custom variables mentioned above, the `tmux_conf_theme_status_left` and +`tmux_conf_theme_status_right` variables support usual tmux syntax, e.g. using +`#()` to call an external command that inserts weather information provided by +[wttr.in]: +``` +tmux_conf_theme_status_right='#{prefix}#{pairing}#{synchronized} #(curl wttr.in?format=3) , %R , %d %b | #{username}#{root} | #{hostname} ' +``` + +![Weather information from wttr.in](https://user-images.githubusercontent.com/553208/52175490-07797c00-27a5-11e9-9fb6-42eec4fe4188.png) + +[wttr.in]: https://github.com/chubin/wttr.in#one-line-output + +### Accessing the macOS clipboard from within tmux sessions + +[Chris Johnsen created the `reattach-to-user-namespace` +utility][reattach-to-user-namespace] that makes `pbcopy` and `pbpaste` work +again within tmux. + +To install `reattach-to-user-namespace`, use either [MacPorts][] or +[Homebrew][]: + + $ port install tmux-pasteboard + +or + + $ brew install reattach-to-user-namespace + +Once installed, `reattach-to-usernamespace` will be automatically detected. + +[MacPorts]: http://www.macports.org/ +[Homebrew]: http://brew.sh/ + +### Using the configuration under Cygwin within Mintty + +**I don't recommend running this configuration with Cygwin anymore. Forking +under Cygwin is extremely slow and this configuration issues a lot of +`run-shell` commands under the hood. As such, you will experience high CPU +usage. As an alternative consider using [Mintty terminal for WSL][wsltty].** + +![cygwin](https://cloud.githubusercontent.com/assets/553208/19741789/67a3f3d8-9bc2-11e6-9ecc-499fc0228ee6.png) + +It is possible to use this configuration under Cygwin within Mintty, however +support for Unicode symbols and emojis lacks behind Mac and Linux. + +Particularly, Mintty's text rendering is implemented with GDI which has +limitations: + +- 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 use [font linking]. +Open `regedit.exe` then navigate to the registry key at +`HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\FontLink\SystemLink` +and add a new entry for you preferred font to link it with the Segoe UI Symbol +font. + +![regedit](https://cloud.githubusercontent.com/assets/553208/19741304/71a2f3ae-9bc0-11e6-96aa-4c09a812c313.png) + +[font linking]: https://msdn.microsoft.com/en-us/goglobal/bb688134.aspx