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

Contents

  - [[#intro|Introduction]]
  - [[#start|Starting Screen, detaching and reattaching]]
  - [[#multiwin|Multiple windows]]
  - [[#multisession|Multiple sessions]]
  - [[#share|Sharing screen sessions]]
  - [[#tmux.conf|.tmux.conf]]
  - [[#cheatsheet|Cheat sheet]]
  - [[#reset|Reset Lost Session]]
  - [[#resources|Resources]]

===== 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.

      # 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"

===== 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"

===== 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]]
  * [[http://en.wikipedia.org/wiki/Tmux| http://en.wikipedia.org/wiki/Tmux]]

----

$Id: tmux.html,v 1.6 2014/06/09 06:08:42 ike Exp $