====== Tmux ======

===== Introduction =====

A newer alternative to the classic [[http://savannah.gnu.org/projects/screen/|Screen]] is [[http://tmux.sourceforge.net/|Tmux]]. As a terminal multiplexer, enables you to have multiple terminals open in a windows, saved in a session. You can detach from that session and come back later, and all your windows and programs running on it will still be alive, and share sessions.

A Tmux command is usually of the form **CTRL-b KEY**, i.e., you'll have to press the **CTRL** key along with b, followed by a generic KEY. This initial part of a command is called prefix, and can be configured.

You'll need to be a [[http://sdf.org/?join#meta|MetaARPA]] member in order to use Tmux on SDF

===== Starting Tmux, detaching and reattaching =====

You can run tmux with:

''$ tmux''

You will create a tmux session name 0. If you want to create a session with a more meaningful name, use:

''$ tmux new-session -s session_name''

In your terminal a status bar will show up, with the name of your shell in the bottom left (actually, the name of the terminal window you're on), and a clock in the bottom right. There are many customizations possible for this status bar, you can check the documentation for all available options. To detach from a session, type **CTRL-b d**, and you will return to a normal promopt. Tmux will keep your session alive, and to resume it run:

''$ tmux attach -t session_name''

===== Multiple windows =====

By default, a Tmux session starts with only one window. You can create more by typing **CTRL-b c**. All windows have a numeric id, and start named as the current shell or command being run. To rename the current window, type **CTRL-b ,**. Then you can switch between windows typing **CTRL-b "number"**, where "number" is the number of a window. **CTRL-b n** and **CTRL-b p** are both shortcuts to, respectively, the next and previous window.

===== Multiple sessions =====

As said before, ''$ tmux new-session -s session name'' creates a new session, with the given name. To list all running session, run:

''$ tmux ls''

Now, supose you want to connect to your tmux session from one machine, let's say your work computer connected to SDF, and open the same tmux session from another machine, e.g. your home computer. By design, you can't do this directly, like in Screen. To achieve that, you "clone" the existing session in a new one, and then connect to it, so both session will contain the same windows and data. Note that the main assumption here is that you are logging on SDF (or any other server with tmux) with the **same user**. You can do that running:

''$ tmux new-session -t existing_session -s new_session_name''

It is possible to split windows in a session with **CTRL-b "** or **CTRL-b %**, respectively, for horizontal or vertical orientation. Each one of these split windows is called a pane. In fact, a window in Tmux terminology is a collection of panes, so a window with no splits also contains an unique pane.

===== Sharing screen sessions =====

Sharing a tmux session between users is simple. Optionally, when starting a shared session, you should specify a socket file, running:

''$ tmux -S /tmp/socket_file new-session -s session_name''

Then, you need to change the permissions of that socket to 777

''$ chmod 777 /tmp/socket_file''

And finally, you will be able to share a session with other users. A caveat is that all users connected to that section will use the Tmux configuration of the user who created it. To attach to a shared session:

''$ tmux -S /tmp/socket_file attach''

===== .tmux.conf =====

Tmux is configured by a file located at $HOME/.tmux.conf, and a sample configuration file is presented below.

<file config $HOME/.tmux.conf>

# makes window's indexes start from 1
set -g base-index 1

# resize windows only when a smaller client is using a session
setw -g aggressive-resize on

# disables panel selection using mouse
set -g mouse-select-pane off

# open a man page in a separated split pane
bind m command-prompt -p "man page:" "split-window -h 'exec man %%'"

# set default terminal
set -g default-terminal "screen-256color"

</file>

===== Reset Lost Sessions =====

If you lose the ability to attach a session of tmux (or even see it in `tmux list-sessions`), but can see it's pid is still running, try the following:

''$ killall -s SIGUSR1 tmux''

''$ tmux attach''

===== Emulating Emacs-like registers =====

If you have a need for multiple clipboard-like buffers for storing and retrieving text (akin to registers in Emacs or Vim), Tmux already supports that, although this functionality is not well exposed by default. Below is a sample piece of configuration that makes available 26 registers designated by single lower-case letters //a-z//.

<file>

# Initialize alphanumerical registers to avoid the problem with 'delete-buffer'
run "tmux set-buffer -b a \"$(echo ' ')\""
run "tmux set-buffer -b b \"$(echo ' ')\""
run "tmux set-buffer -b c \"$(echo ' ')\""
run "tmux set-buffer -b d \"$(echo ' ')\""
run "tmux set-buffer -b e \"$(echo ' ')\""
run "tmux set-buffer -b f \"$(echo ' ')\""
run "tmux set-buffer -b g \"$(echo ' ')\""
run "tmux set-buffer -b h \"$(echo ' ')\""
run "tmux set-buffer -b i \"$(echo ' ')\""
run "tmux set-buffer -b j \"$(echo ' ')\""
run "tmux set-buffer -b k \"$(echo ' ')\""
run "tmux set-buffer -b l \"$(echo ' ')\""
run "tmux set-buffer -b m \"$(echo ' ')\""
run "tmux set-buffer -b n \"$(echo ' ')\""
run "tmux set-buffer -b o \"$(echo ' ')\""
run "tmux set-buffer -b p \"$(echo ' ')\""
run "tmux set-buffer -b q \"$(echo ' ')\""
run "tmux set-buffer -b r \"$(echo ' ')\""
run "tmux set-buffer -b s \"$(echo ' ')\""
run "tmux set-buffer -b t \"$(echo ' ')\""
run "tmux set-buffer -b u \"$(echo ' ')\""
run "tmux set-buffer -b v \"$(echo ' ')\""
run "tmux set-buffer -b w \"$(echo ' ')\""
run "tmux set-buffer -b x \"$(echo ' ')\""
run "tmux set-buffer -b y \"$(echo ' ')\""
run "tmux set-buffer -b z \"$(echo ' ')\""
    
</file>

<file>

# Copy to user-selected register
bind -T copy-mode r command-prompt -1 -p '(register)' 'delete-buffer -b %1 ; send -X copy-pipe "tmux set-buffer -n %1"'
# Paste from user-selected register
bind -T prefix C-] command-prompt -1 -p '(register)' 'paste-buffer -b %1'
    
</file>

The way it works is this: when in //copy-mode// you get an additional key binding //r// which prompts you for a single-letter named register in which to store the marked region. In normal mode you get a prefix command //C-b C-]// which prompts for the name of the register whose contents will be pasted at the cursor. You can also list the contents of all buffers by running //C-b :list-buffers//. Manual initializing of all the buffers seems necessary, because otherwise //delete-buffer// complains about trying to delete a nonexistent buffer when used for the first time for a given letter.

===== Troubleshooting Colors =====

If colors are not working in your tmux session try running tmux with the -2 flag.

''$ tmux -2''

To persist 256color support in your terminal you can add the following line to your ~/.bashrc

''TERM=screen-256color''

===== Resources =====

  * [[http://www.dayid.org/os/notes/tm.html| http://www.dayid.org/os/notes/tm.html]]
  * [[http://blog.hawkhost.com/2010/06/28/tmux-the-terminal-multiplexer/| http://blog.hawkhost.com/2010/06/28/tmux-the-terminal-multiplexer/]]
  * [[https://wiki.archlinux.org/index.php/Tmux| https://wiki.archlinux.org/index.php/Tmux]]
  * [[http://robots.thoughtbot.com/post/2641409235/a-tmux-crash-course| http://robots.thoughtbot.com/post/2641409235/a-tmux-crash-course]]
  * [[wp>Tmux|https://en.wikipedia.org/wiki/Tmux]]

----

$Id: tmux.html,v 1.6 2014/06/09 06:08:42 ike Exp $ [[http://sdf.org/?tutorials/tmux|Tmux: terminal multiplexer; multiple terminals]] - traditional link (using [[wp>Revision_Control_System|RCS]])