Update readme.md with topics 'Copy mode and scroll behavior' and

readme.md

@@ -1,6 +1,6 @@
 Tmux Configuration
 =====================
-Tmux configuration, that supercharges your [tmux](https://tmux.github.io/) to build cozy and cool terminal environment.
+Tmux configuration, that supercharges your [tmux](https://tmux.github.io/) and builds cozy and cool terminal environment.
 
 ![intro](https://user-images.githubusercontent.com/768858/33152741-ec5f1270-cfe6-11e7-9570-6d17330a83aa.gif)
 
@@ -13,6 +13,8 @@ Table of contents
 1. [Key bindings](#key-bindings)
 1. [Status line](#status-line)
 1. [Nested tmux sessions](#nested-tmux-sessions)
+1. [Copy mode](#copy-mode)
+1. [Clipboard integration](#clipboard-integration)
 1. [Themes and customization](#themes-and-customization)
 1. [iTerm2 and tmux integration](#iterm2-and-tmux-integration)
 
@@ -21,43 +23,59 @@ Features
 
 - "C-a" prefix instead of "C-b" (screen like)
 - support for nested tmux sessions
-- configurable visual theme/colors, with some elements borrowed from [Powerline](https://github.com/powerline/powerline)
-- can apply different configuration whether your session is on local or remote machine
-- supercharged and cozy status line
-- status line: CPU, memory usage, system load average metrics
-- status line: username and hostname, current date time
-- status line: battery information in status line
-- status line: visual indicator when you press `prefix`
-- status line: visual indicator when pane is zoomed
-- status line: online/offline visual indicator
-- toggle visibility of status line
-- monitor windows for activity/silence
+- local vs remote specific session configuration
 - scroll and copy mode improvements
+- integration with OSX or Linux clipboard (works for local, remote, and local+remote nested session scenario)
+- supercharged status line
+- renew tmux and shell environment (SSH_AUTH_SOCK, DISPLAY, SSH_TTY) when reattaching back to old session
 - prompt to rename window right after it's created
+- newly created windows and panes retain current working directory
+- monitor windows for activity/silence
 - highlight focused pane
 - merge current session with existing one (move all windows)
+- configurable visual theme/colors, with some elements borrowed from [Powerline](https://github.com/powerline/powerline)
 - integration with 3rd party plugins: [tmux-sidebar](https://github.com/tmux-plugins/tmux-sidebar), [tmux-copycat](https://github.com/tmux-plugins/tmux-copycat), [tmux-open](https://github.com/tmux-plugins/tmux-open), [tmux-plugin-sysstat](https://github.com/samoshkin/tmux-plugin-sysstat)
 
-**TBD**:
-- [ ] retain current path when new pane is created
-- [ ] integration with clipboard
-- [ ] fix installation script to properly install TPM
+**Status line widgets**:
+
+- CPU, memory usage, system load average metrics
+- username and hostname, current date time
+- battery information in status line
+- visual indicator when you press `prefix`
+- visual indicator when you're in `Copy` mode
+- visual indicator when pane is zoomed
+- online/offline visual indicator
+- toggle visibility of status line
 
 
 Installation
 -------------
-The prerequisite is installed tmux >= "2.4" and [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm)
+Prerequisites:
+- tmux >= "v2.4"
+- OSX, Linux (tested on Ubuntu 14 and CentOS7)
+
+Personally, I use it on OSX 10.11.5 El Capitan through iTerm2.
+
+On OSX you can install latest 2.6 version with `brew install tmux`. On Linux it's better to install from source, because official repositories usually contain outdated version. For example, CentOS7 - v1.8 from base repo, Ubuntu 14 - v1.8 from trusty/main. For how to install from source, see this [gist](https://gist.github.com/P7h/91e14096374075f5316e) or just google it.
 
+
+To install tmux-config:
 ```
 $ git clone https://github.com/samoshkin/tmux-config.git
 $ ./tmux-config/install.sh
 ```
 
-Installation script will copy files to `~/.tmux` directory, symlink main `~/.tmux` config file. If you already have existing `~/tmux.conf`, backup will be created.
+`install.sh` script does following:
+- copies files to `~/.tmux` directory
+- symlink tmux config file at `~/.tmux.conf`, existing `~/.tmux.conf` will be backed up
+- [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm) will be installed at default location `~/.tmux/plugins/tpm`, unless already presemt
+- required tmux plugins will be installed
 
-Note, that after you launch tmux, plugins needs to be installed. Hit `C-a Shift-i` keybinding to install all tmux plugins.
+Finally, you can jump into a new tmux session:
 
-- [ ] **TODO:** automate TPM and tmux plugin installation
+```
+$ tmux new
+```
 
 
 General settings
@@ -327,6 +345,65 @@ Remote session is detected by existence of `$SSH_CLIENT` variable. When session
 You can apply remote-specific settings by extending `~/.tmux/.tmux.remote.conf` file.
 
 
+Copy mode
+----------------------
+There are some tweaks to copy mode and scrolling behavior, you should be aware of.
+
+There is a root keybinding to enter Copy mode: `M-Up`. Once in copy mode, you have several scroll controls:
+
+- scroll by line: `M-Up`, `M-down`
+- scroll by half screen: `M-PageUp`, `M-PageDown`
+- scroll by whole screen: `PageUp`, `PageDown`
+- scroll by mouse wheel, scroll step is changed from `5` lines to `2`
+
+`Space` starts selection, `Enter` copies selection and exits copy mode. List all items in copy buffer using `prefix C-p`, and paste most recent item from buffer using `prexix p`.
+
+You can also use `y` which is equivalent to `Enter`, and `Y` will copy text, exit copy mode and immediately paste buffer to you command line.
+
+You can also select text using mouse. Default behavior is to copy text and immediately cancel copy mode on `MouseDragEnd` event. This is annoying, because sometimes I select text just to highlight it, but tmux drops me out of copy mode and reset scroll by the end. I've changed this behavior, so `MouseDragEnd` does not execute `copy-selection-and-cancel` action. You can then copy text just by left mouse click, and continue working in copy-mode.
+
+![copy and scroll](https://user-images.githubusercontent.com/768858/33231146-e390afc8-d1f8-11e7-80ad-6977fc3a5df7.gif)
+
+Clipboard integration
+----------------------
+
+When you copy text inside tmux, it's stored in private tmux buffer, and not shared with system clipboard. Same is true when you SSH onto remote machine, and attach to tmux session there. Copied text will be stored in remote's session buffer, and not shared/transported to your local system clipboard. And sure, if you start local tmux session, then jump into nested remote session, copied text will not land in your system clipboard either.
+
+This is one of the major limitations of tmux, that you might just decide to give up using it. Let's explore possible solutions:
+
+- share text with OSX clipboard using **"pbcopy"**
+- share text with OSX clipboard using [reattach-to-user-namespace](https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard) wrapper to access "pbcopy" from tmux environment (seems on OSX 10.11.5 ElCapitan this is not needed, since I can still access pbcopy without this wrapper).
+- share text with X selection using **"xclip"** or **"xsel"** (store text in primary and clipboard selections). Works on Linux when DISPLAY variable is set.
+
+All solutions above are suitable for sharing tmux buffer with system clipboard for local machine scenario. They still does not address remote session scenarios. What we need is some way to transport buffer from remote machine to the clipboard on the local machine, bypassing remote system clipboard.
+
+There are 2 workarounds to address remote scenarios.
+
+Use **[ANSI OSC 52](https://en.wikipedia.org/wiki/ANSI_escape_code#Escape_sequences)** escape [sequence](https://blog.vucica.net/2017/07/what-are-osc-terminal-control-sequences-escape-codes.html) to talk to controlling/parent terminal and pass buffer on local machine. Terminal should properly undestand and handle OSC 52. Currently, only iTerm2 and XTerm support it. OSX Terminal, Gnome Terminal, Terminator do not.
+
+Second workaround is really involved and consists of [local network listener and SSH remote tunneling](https://apple.stackexchange.com/a/258168):
+
+- SSH onto target machine with remote tunneling on
+ ```
+ ssh -R 2222:localhost:3333 [email protected]
+ ```
+- When text is copied inside tmux (by mouse, by keyboard by whatever configured shortcut), pipe text to network socket on remote machine
+ ```
+ echo "buffer" | nc localhost 2222
+ ```
+- Buffer will be sent thru SSH remote tunnel from port `2222` on remote machine to port `3333` on local machine.
+- Setup a service on local machine (systemd service unit with socket activation), which listens on network socket on port `3333`, and pipes any input to `pbcopy` command (or `xsel`, `xclip`).
+
+This tmux-config does its best to integrate with system clipboard, trying all solutions above in order, and falling back to OSC 52 ANSI escape sequences in case of failure. 
+
+On OSX you might need to install `reattach-to-user-namespace` wrapper: `brew install reattach-to-user-namespace`, and make sure OSC 52 sequence handling is turned on in iTerm. (Preferences -> General -> Applications in Terminal may access clipboard).
+
+On Linux, make sure `xclip` or `xsel` is installed. For remote scenarios, you would still need to setup network listener and use SSH remote tunneling, unless you terminal emulators supports OSC 52 sequences.
+
+
+
+
+
 Themes and customization
 ------------------------
 
@@ -351,11 +428,6 @@ color_window_off_status_current_bg="colour254"
 
 Note, that variables are not extracted to dedicated file, as it should be, because for some reasons, tmux does not see variable values after sourcing `theme.conf` file. Don't know why.
 
-create several panes, windows
-move between them
-zoom window
-open nested tmux session
-scroll and copy
 
 iTerm2 and tmux integration
 ---------------------------