{"id":13475310,"url":"https://github.com/samoshkin/tmux-config","last_synced_at":"2025-05-15T10:01:53.547Z","repository":{"id":39541592,"uuid":"111244808","full_name":"samoshkin/tmux-config","owner":"samoshkin","description":"Tmux configuration, that supercharges your tmux to build cozy and cool terminal environment","archived":false,"fork":false,"pushed_at":"2024-07-10T12:42:51.000Z","size":72,"stargazers_count":2206,"open_issues_count":47,"forks_count":512,"subscribers_count":41,"default_branch":"master","last_synced_at":"2025-04-11T19:58:06.964Z","etag":null,"topics":["dotfiles","tmux","tmux-config","tmux-configs","tmux-configuration"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samoshkin.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-18T22:34:27.000Z","updated_at":"2025-04-10T20:13:30.000Z","dependencies_parsed_at":"2024-12-26T06:16:42.704Z","dependency_job_id":null,"html_url":"https://github.com/samoshkin/tmux-config","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Ftmux-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Ftmux-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Ftmux-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Ftmux-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samoshkin","download_url":"https://codeload.github.com/samoshkin/tmux-config/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319715,"owners_count":22051072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dotfiles","tmux","tmux-config","tmux-configs","tmux-configuration"],"created_at":"2024-07-31T16:01:19.282Z","updated_at":"2025-05-15T10:01:52.360Z","avatar_url":"https://github.com/samoshkin.png","language":"Shell","funding_links":[],"categories":["Shell","User configuraions","tmux"],"sub_categories":[],"readme":"Tmux Configuration\n=====================\nTmux configuration, that supercharges your [tmux](https://tmux.github.io/) and builds cozy and cool terminal environment.\n\n![intro](https://user-images.githubusercontent.com/768858/33152741-ec5f1270-cfe6-11e7-9570-6d17330a83aa.gif)\n\nTable of contents\n-----------------\n\n1. [Features](#features)\n1. [Installation](#installation)\n1. [General settings](#general-settings)\n1. [Key bindings](#key-bindings)\n1. [Status line](#status-line)\n1. [Nested tmux sessions](#nested-tmux-sessions)\n1. [Copy mode](#copy-mode)\n1. [Clipboard integration](#clipboard-integration)\n1. [Themes and customization](#themes-and-customization)\n1. [iTerm2 and tmux integration](#iterm2-and-tmux-integration)\n\nFeatures\n---------\n\n- \"C-a\" prefix instead of \"C-b\" (screen like)\n- support for nested tmux sessions\n- local vs remote specific session configuration\n- scroll and copy mode improvements\n- integration with OSX or Linux clipboard (works for local, remote, and local+remote nested session scenario)\n- supercharged status line\n- renew tmux and shell environment (SSH_AUTH_SOCK, DISPLAY, SSH_TTY) when reattaching back to old session\n- prompt to rename window right after it's created\n- newly created windows and panes retain current working directory\n- monitor windows for activity/silence\n- highlight focused pane\n- merge current session with existing one (move all windows)\n- configurable visual theme/colors, with some elements borrowed from [Powerline](https://github.com/powerline/powerline)\n- 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)\n\n**Status line widgets**:\n\n- CPU, memory usage, system load average metrics\n- username and hostname, current date time\n- battery information in status line\n- visual indicator when you press `prefix`\n- visual indicator when you're in `Copy` mode\n- visual indicator when pane is zoomed\n- online/offline visual indicator\n- toggle visibility of status line\n\n\nInstallation\n-------------\nPrerequisites:\n- tmux \u003e= \"v2.4\"\n- OSX, Linux (tested on Ubuntu 14 and CentOS7), FreeBSD (tested on 11.1)\n\nPersonally, I use it on OSX 10.11.5 El Capitan through iTerm2.\n\nOn 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.\n\n\nTo install tmux-config:\n```\n$ git clone https://github.com/samoshkin/tmux-config.git\n$ ./tmux-config/install.sh\n```\n\n`install.sh` script does following:\n- copies files to `~/.tmux` directory\n- symlink tmux config file at `~/.tmux.conf`, existing `~/.tmux.conf` will be backed up\n- [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm) will be installed at default location `~/.tmux/plugins/tpm`, unless already presemt\n- required tmux plugins will be installed\n\nFinally, you can jump into a new tmux session:\n\n```\n$ tmux new\n```\n\n\nGeneral settings\n----------------\nWindows and pane indexing starts from `1` rather than `0`. Scrollback history limit is set to `20000`. Automatic window renameing is turned off. Aggresive resizing is on. Message line display timeout is `1.5s`. Mouse support in `on`.\n\n256 color palette support is turned on, make sure that your parent terminal is configured propertly. See [here](https://unix.stackexchange.com/questions/1045/getting-256-colors-to-work-in-tmux) and [there](https://github.com/tmux/tmux/wiki/FAQ)\n\n```\n# parent terminal\n$ echo $TERM\nxterm-256color\n\n# jump into a tmux session\n$ tmux new\n$ echo $TERM\nscreen-256color\n```\n\nKey bindings\n-----------\nSo `~/.tmux.conf` overrides default key bindings for many action, to make them more reasonable, easy to recall and comforable to type.\n\nLet's go through them. \n\nIf you are an iTerm2 user, third column describes the keybinding of similar  \"action\" in iTerm2. It's possible to reuse very same keys you already get used to and tell iTerm2 to execute analogous tmux actions. See [iTerm2 and tmux integration](#iterm2-and-tmux-integration) section below.\n\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003ctd nowrap\u003e\u003cb\u003etmux key\u003c/b\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003cb\u003eDescription\u003c/b\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003cb\u003eiTerm2 key\u003c/b\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd nowrap\u003e\u003ccode\u003eC-a\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eDefault prefix, used instead of \"C-b\". Same prefix is used in screen program, and it's easy to type. The only drawback of \"C-a\" is that underlying shell does not receive the keystroke to move to the beginning of the line.\n        \u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd nowrap\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; C-e\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eOpen ~/.tmux.conf file in your $EDITOR\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; C-r\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eReload tmux configuration from ~/.tmux.conf file\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; r\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eRename current window\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; R\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eRename current session\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; _\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSplit new pane horizontally\u003c/td\u003e\n        \u003ctd\u003e⌘⇧D\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; |\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSplit new pane vertically\u003c/td\u003e\n        \u003ctd\u003e⌘D\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; \u0026lt;\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSelect next pane\u003c/td\u003e\n        \u003ctd\u003e⌘[\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; \u0026gt;\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSelect previous pane\u003c/td\u003e\n        \u003ctd\u003e⌘]\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; ←\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSelect pane on the left\u003c/td\u003e\n        \u003ctd\u003e⌘⌥←\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; →\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSelect pane on the right\u003c/td\u003e\n        \u003ctd\u003e⌘⌥→\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; ↑\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSelect pane on the top\u003c/td\u003e\n        \u003ctd\u003e⌘⌥↑\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; ↓\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSelect pane on the bottom\u003c/td\u003e\n        \u003ctd\u003e⌘⌥↓\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; C-←\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eResize pane to the left\u003c/td\u003e\n        \u003ctd\u003e^⌘←\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; C-→\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eResize pane to the right\u003c/td\u003e\n        \u003ctd\u003e^⌘→\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; C-↑\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eResize pane to the top\u003c/td\u003e\n        \u003ctd\u003e^⌘↑\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; C-↓\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eResize pane to the bottom\u003c/td\u003e\n        \u003ctd\u003e^⌘↓\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; \u0026gt;\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eMove to next window\u003c/td\u003e\n        \u003ctd\u003e⌘⇧]\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; \u0026lt;\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eMove to previous window\u003c/td\u003e\n        \u003ctd\u003e⌘⇧[\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; Tab\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSwitch to most recently used window\u003c/td\u003e\n        \u003ctd\u003e^Tab\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; L\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eLink window from another session by entering target session and window reference\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; \\\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSwap panes back and forth with 1st pane. When in main-horizontal or main-vertical layout, the main panel is always at index 1. This keybinding let you swap secondary pane with main one, and do the opposite.\u003c/td\u003e\n        \u003ctd\u003e⌘\\\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; C-o\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSwap current active pane with next one\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; +\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eToggle zoom for current pane\u003c/td\u003e\n        \u003ctd\u003e⌘⇧Enter\u003c/td\u003e\n    \u003c/td\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; x\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eKill current pane\u003c/td\u003e\n        \u003ctd\u003e⌘W\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; X\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eKill current window\u003c/td\u003e\n        \u003ctd\u003e⌘⌥W\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; C-x\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eKill other windows but current one (with confirmation)\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; Q\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eKill current session (with confirmation)\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; C-u\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eMerge current session with another. Essentially, this moves all windows from current session to another one\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; d\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eDetach from session\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; D\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eDetach other clients except current one from session\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; C-s\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eToggle status bar visibility\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; m\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eMonitor current window for activity\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; M\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eMonitor current window for silence by entering silence period\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ccode\u003e\u0026lt;prefix\u0026gt; F12\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSwitch off all key binding and prefix hanling in current window. See \"Nested sessions\" paragraph for more info\u003c/td\u003e\n        \u003ctd\u003e-\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n\nStatus line\n-----------\n\nI've started with Powerline as a status line, but then realized it's too fat for my Macbook 15'' display, it hardly can fit all those fancy arrows, widgets and separators, so that I can only see one window \"tab\".\n\nSo I decide to make my feet wet, with the idea to keep it dense, and include essential widgets. Sometimes it tries to replicate OSX topbar (battery, date time).\n\nLeft part:\n![status line left](https://user-images.githubusercontent.com/768858/33151594-59db6a8e-cfe1-11e7-8a36-476fe0b416b3.png)\n\nRight part:\n![status line right](https://user-images.githubusercontent.com/768858/33151608-6978de72-cfe1-11e7-829a-e303e31e8c16.png)\n\nThe left part contains only current session name.\n\nWindow tabs use Powerline arrows glyphs, so you need to install Powerline enabled font to make this work. See [Powerline docs](https://powerline.readthedocs.io/en/latest/installation.html#fonts-installation) for instructions and here is the [collection of patched fonts for powerline users](https://github.com/powerline/fonts)\n\nThe right part of status line consists of following components:\n\n- CPU, memory usage, system load average metrics. Powered by [tmux-plugin-sysstat](https://github.com/samoshkin/tmux-plugin-sysstat) (dislaimed, that's my own development, because I haven't managed to find any good plugin with CPU and memory/swap metrics)\n- username and hostname (invaluable when you SSH onto remote host)\n- current date time\n- battery information\n- visual indicator when you press prefix key: `[^A]`.\n- visual indicator when pane is zoomed: `[Z]`\n- online/offline visual indicator (just pings `google.com`)\n\nYou might want to hide status bar using `\u003cprefix\u003e C-s` keybinding.\n\n\nNested tmux sessions\n--------------------\nOne prefers using tmux on local machine to supercharge their terminal emulator experience, other use it only for remote scenarios to retain session/state in case of disconnect. Things are getting more complex, when you want to be on both sides. You end up with nested session, and face the question: **How you can control inner session, since all keybindings are caught and handled by outer session?**. Community provides several possible solutions.\n\nThe most common is to press `C-a` prefix twice. First one is caught by local session, whereas second is passed to remote one. Nothing extra steps need to be done, this works out of the box. However, root keytable bindings are still handled by outer session, and cannot be passed to inner one.\n\nSecond attempt to tackle this issue, is to [setup 2 individual prefixes](https://simplyian.com/2014/03/29/using-tmux-remotely-within-a-local-tmux-session/), `C-b` for local session, and `C-a` for remote session. And, you know, it feels like:\n\n![tmux in tmux](http://i.imgur.com/HQBdV1J.jpg)\n\nAnd finally accepted solution, turn off all keybindings and key prefix handling in outer session, when working with inner one. This way, outer session just sits aside, without interfering keystrokes passed to inner session. Credits to [http://stahlke.org/dan/tmux-nested/](http://stahlke.org/dan/tmux-nested/) and this [Github issue](https://github.com/tmux/tmux/issues/237)\n\nSo, how it works. When in outer session, simply press `F12` to toggle off all keybindings handling in outer session. Now work with inner session using the same keybinding scheme and same keyprefix. Press `F12` to turn on outer session back.\n\n![nested sessions](https://user-images.githubusercontent.com/768858/33151636-84a0bab2-cfe1-11e7-9d5d-412525689c9b.gif)\n\nYou might notice that when key bindings are \"OFF\", special `[OFF]` visual indicator is shown in the status line, and status line changes its style (colored to gray).\n\n###  Local and remote sessions\n\nRemote session is detected by existence of `$SSH_CLIENT` variable. When session is remote, following changes are applied:\n- status line is docked to bottom; so it does not stack with status line of local session\n- some widgets are removed from status line: battery, date time. The idea is to economy width, so on wider screens you can open two remote tmux sessions in side-by-side panes of single window of local session.\n\nYou can apply remote-specific settings by extending `~/.tmux/.tmux.remote.conf` file.\n\n\nCopy mode\n----------------------\nThere are some tweaks to copy mode and scrolling behavior, you should be aware of.\n\nThere is a root keybinding to enter Copy mode: `M-Up`. Once in copy mode, you have several scroll controls:\n\n- scroll by line: `M-Up`, `M-down`\n- scroll by half screen: `M-PageUp`, `M-PageDown`\n- scroll by whole screen: `PageUp`, `PageDown`\n- scroll by mouse wheel, scroll step is changed from `5` lines to `2`\n\n`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`.\n\n`y` just copies selected text and is equivalent to `Enter`,  `Y` copies whole line, and `D` copies by the end of line.\n\nAlso, note, that when text is copied any trailing new lines are stripped. So, when you paste buffer in a command prompt, it will not be immediately executed.\n\nYou 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. Text is copied, but copy mode is not cancelled and selection is not cleared. You can then reset selection by mouse click.\n\n![copy and scroll](https://user-images.githubusercontent.com/768858/33231146-e390afc8-d1f8-11e7-80ad-6977fc3a5df7.gif)\n\nClipboard integration\n----------------------\n\nWhen 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.\n\nThis is one of the major limitations of tmux, that you might just decide to give up using it. Let's explore possible solutions:\n\n- share text with OSX clipboard using **\"pbcopy\"**\n- 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).\n- share text with X selection using **\"xclip\"** or **\"xsel\"** (store text in primary and clipboard selections). Works on Linux when DISPLAY variable is set.\n\nAll 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.\n\nThere are 2 workarounds to address remote scenarios.\n\nUse **[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.\n\nSecond workaround is really involved and consists of [local network listener and SSH remote tunneling](https://apple.stackexchange.com/a/258168):\n\n- SSH onto target machine with remote tunneling on\n    ```\n    ssh -R 2222:localhost:3333  alexeys@192.168.33.100\n    ```\n- When text is copied inside tmux (by mouse, by keyboard by whatever configured shortcut), pipe text to network socket on remote machine\n    ```\n    echo \"buffer\" | nc localhost 2222\n    ```\n- Buffer will be sent thru SSH remote tunnel from port `2222` on remote machine to port `3333` on local machine.\n- 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`).\n\nThis 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. \n\nOn 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 -\u003e General -\u003e Applications in Terminal may access clipboard).\n\nOn 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.\n\n\n\n\n\nThemes and customization\n------------------------\n\nAll colors related to theme are declared as variables. You can change them in `~/.tmux.conf`.\n\n```\n# This is a theme CONTRACT, you are required to define variables below\n# Change values, but not remove/rename variables itself\ncolor_dark=\"$color_black\"\ncolor_light=\"$color_white\"\ncolor_session_text=\"$color_blue\"\ncolor_status_text=\"colour245\"\ncolor_main=\"$color_orange\"\ncolor_secondary=\"$color_purple\"\ncolor_level_ok=\"$color_green\"\ncolor_level_warn=\"$color_yellow\"\ncolor_level_stress=\"$color_red\"\ncolor_window_off_indicator=\"colour088\"\ncolor_window_off_status_bg=\"colour238\"\ncolor_window_off_status_current_bg=\"colour254\"\n```\n\nNote, 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.\n\n\niTerm2 and tmux integration\n---------------------------\n\nIf you're an iTerm use same to me, most likely you already have a muscle memory for most common actions and keybindings (split pane, focus pane, fullscreen pane, move between tabs, create new tab, etc). When I switched to tmux, I found new key table more difficult: more keys to type, don't forget to enter `prefix` and recall if you've already pressed it or not (compare `C-a, c` with \"⌘T\", or `C-a -\u003e` with \"⌘⌥-\u003e\"). iTerm2 keybinding was so natural to me, so I decided to remap most common keybindings to tell iTerm2 to execute corresponding tmux actions.\n\nYou can setup new profile in iTerm preferences to override default keybindings, to tell iTerm to send pre-configured sequences of keys, that will trigger corresponding action in tmux.\n\n![iterm preferences](https://user-images.githubusercontent.com/768858/33185301-54afc402-d08a-11e7-9622-232a4607df8b.png)\n\nFor example, when \"^⌘↑\" pressed, sequence of bytes `0x01 0x1b 0x5b 0x31 0x3b 0x35 0x41` are sent through terminal to running tmux instance, that interprets them as `C-a C-↑` keybinding and triggers `resize-pane -U` according to our `.tmux.conf` configuration.\n\nYou can get binary representation of any keys, using `showkey` or `od` commands\n\n```\n$od -t x1\n\n^A^[[1;5A   // press C-a C-↑ on your keyboard\n0000000 01 1b 5b 31 3b 35 41\n0000007\n```\n\n```\n$ showkey -a\nPress any keys - Ctrl-D will terminate this program\n\n^A        1 0001 0x01\n^[[1;5A  27 0033 0x1b\n         91 0133 0x5b\n         49 0061 0x31\n         59 0073 0x3b\n         53 0065 0x35\n         65 0101 0x41\n```\n\nYou can remap whatever key in this way, but I do this only for those ones, which have similar analogous action in tmux and are most common(resize pane, zoom pane, create new window, etc). See table with keybindings above.\n\nAs additional step, you can setup this new iTerm profile as default one, and tell it to jump into tmux session right off the start.\n\n![iterm tmux default profile](https://user-images.githubusercontent.com/768858/33185302-54d36b78-d08a-11e7-96b9-7ab3069fc369.png)\n\nYou can then go full screen in iTerm, so iTerm tabs and frame do not distract you (anyway now you're using iTerm just as a tunnel to your tmux, everything else happens inside tmux).\n\n![full screen mode](https://user-images.githubusercontent.com/768858/33185303-54fa0378-d08a-11e7-8fd3-068f0af712c7.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamoshkin%2Ftmux-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamoshkin%2Ftmux-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamoshkin%2Ftmux-config/lists"}