tutes-dump/site-tutorials/tmux.html

202 lines
7.2 KiB
HTML
Raw Normal View History

2020-07-11 06:11:19 -04:00
<!-- Based on the screen tutorial also found at SDF, by dickey -->
<h1>Tmux</h1>
<style type="text/css">
.kbd { font-weight: bold; }
code, .prompt { background-color: black; color: white; padding: 5px; }
.prompt { padding: 0 ;
h1 { font-size: 180%; }
h2 { font-size: 160%; }
h2 { font-size: 140%; }
</style>
<div id="toc">
<span>Contents</span>
<ol>
<li><a href="#intro">Introduction</a></li>
<li><a href="#start">Starting Screen, detaching and reattaching</a></li>
<li><a href="#multiwin">Multiple windows</a></li>
<li><a href="#multisession">Multiple sessions</a></li>
<li><a href="#share">Sharing screen sessions</a></li>
<li><a href="#tmux.conf">.tmux.conf</a></li>
<li><a href="#cheatsheet">Cheat sheet</a></li>
<li><a href="#reset">Reset Lost Session</a></li>
<li><a href="#resources">Resources</a></li>
</ol>
</div>
<h2><a name="intro"></a>Introduction</h2>
<p>
A newer alternative to the classic <a href="http://savannah.gnu.org/projects/screen/">Screen</a>
is <a href="http://tmux.sourceforge.net/">Tmux</a>. As a <q>terminal multiplexer</q>,
enables you to have multiple terminals open in a windows, saved in a session.
You can <q>detach</q> from that session and come back later, and all your
windows and programs running on it will still be alive, and share sessions.
</p>
<p>
A Tmux command is usually of the form <span class="kbd">CTRL-b KEY</span>,
i.e., you'll have to press the <span class="kbd">CTRL</span> key along
with <q>b</q>, followed by a generic KEY. This initial part of a command
is called <q>prefix</q>, and can be configured.
</p>
<p>
You'll need to be a <a href="http://sdf.org/?join#meta">MetaARPA</a> member
in order to use Tmux on SDF
</p>
<h2><a name="start"></a>Starting Tmux, detaching and reattaching</h2>
<p>
You can run tmux with:
</p>
<code><span class="prompt">$ </span><span class="command">tmux</span></code>
<p>
You will create a tmux session name <q>0</q>. If you want to create a session
with a more meaningful name, use:
</p>
<code><span class="prompt">$ </span><span class="command">tmux new-session -s session_name</span></code>
<p>
In your terminal a <q>status bar</q> 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
<q>status bar</q>, you can check the documentation for all available options.
To detach from a session, type <span class="kbd">CTRL-b d</span>, and you will
return to a normal promopt. Tmux will keep your session alive, and to resume
it run:
</p>
<code><span class="prompt">$ </span><span class="command">tmux attach -t session_name</span></code>
<h2><a name="multiwin"></a>Multiple windows</h2>
<p>
By default, a Tmux session starts with only one window. You can create more
by typing <span class="kbd">CTRL-b c</span>. All windows have a numeric id, and
start named as the current shell or command being run. To rename the current
window, type <span class="kbd">CTRL-b ,</span>. Then you can switch between
windows typing <span class="kbd">CTRL-b <q>number</q></span>, where
<q>number</q> is the number of a window. <span class="kbd">CTRL-b n</span> and
<span class="kbd">CTRL-b p</span> are both shortcuts to, respectively, the next
and previous window.
</p>
<!-- TODO: add information about tmux configuration -->
<h2><a name="multisession"></a>Multiple sessions</h2>
<p>
As said before, <code><span class="prompt">$ </span><span class="command">tmux new-session -s session name</span></code> creates
a new session, with the given name. To list all running session, run:
</p>
<code><span class="prompt">$ </span><span class="command">tmux ls</span></code>
<p>
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 <b>same user</b>. You can do that running:
</p>
<code><span class="prompt">$ </span><span class="command">tmux new-session -t existing_session -s new_session_name</span></code>
<p>
It is possible to split windows in a session with <span class="kbd">CTRL-b "</span>
or <span class="kbd">CTRL-b %</span>, respectively, for horizontal
or vertical orientation. Each one of these split windows is called a <q>pane</q>. In fact,
a <q>window</q> in Tmux terminology is a collection of <q>panes</q>, so
a window with no splits also contains an unique pane.
</p>
<h2><a name="share"></a>Sharing screen sessions</h2>
<p>
Sharing a tmux session between users is simple. Optionally, when starting
a shared session, you should specify a socket file, running:
</p>
<code><span class="prompt">$ </span><span class="command">tmux -S /tmp/socket_file new-session -s session_name</span></code>
<p>
Then, you need to change the permissions of that socket to 777
</p>
<code><span class="prompt">$ </span><span class="command">chmod 777 /tmp/socket_file</span></code>
<p>
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:
</p>
<code><span class="prompt">$ </span><span class="command">tmux -S /tmp/socket_file attach</span></code>
<h2><a name="tmux.conf"></a>.tmux.conf</h2>
<p>
Tmux is configured by a file located at $HOME/.tmux.conf, and a sample configuration file
is presented below.
</p>
<pre>
# 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"
</pre>
<h2><a name="Reset"></a>Reset Lost Sessions</h2>
<p>
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:
</p>
<code><span class="prompt">$ </span><span class="command">killall -s SIGUSR1 tmux</span></code>
<p>
</p>
<code><span class="prompt">$ </span><span class="command">tmux attach</span></code>
<h2>Resources</h2>
<ul>
<li><a href="http://www.dayid.org/os/notes/tm.html">
http://www.dayid.org/os/notes/tm.html</a></li>
<li><a href="http://blog.hawkhost.com/2010/06/28/tmux-the-terminal-multiplexer/">
http://blog.hawkhost.com/2010/06/28/tmux-the-terminal-multiplexer/</a></li>
<li><a href="https://wiki.archlinux.org/index.php/Tmux">
https://wiki.archlinux.org/index.php/Tmux</a></li>
<li><a href="http://robots.thoughtbot.com/post/2641409235/a-tmux-crash-course">
http://robots.thoughtbot.com/post/2641409235/a-tmux-crash-course</a></li>
<li><a href="http://en.wikipedia.org/wiki/Tmux">
http://en.wikipedia.org/wiki/Tmux</a></li>
</ul>
<hr />
$Id: tmux.html,v 1.6 2014/06/09 06:08:42 ike Exp $