View source for Screen and tmux

{{#addbodyclass:tag_tech}}
{{ShellsAndAdmin}}

Note: For something similar for X11, see [[xpra]]

=Intro=


'''Why it's useful'''

When you open a shell (or more) ''inside'' tmux or screen session,
you can disconnect from that screen/tmux session, 
the shell it will stick around ''inside'' that session,
and you can reconnect to that session later.


'''Learn by doing:'''
* Log into a remote host (ssh, putty)

* Run {{inlinecode|tmux}}, or {{inlinecode|screen}}

* You are now again at a terminal.
:: Do stuff with it. 

* Disconnect
: there's a nice way of disconnecting
: but you can also simulate a broken network connection e.g. by closing the terminal window you're currently using

* Connect to the remote host again and run {{inlinecode|tmux att}} or {{inlinecode|screen -rd}} (whichever you were using) 
:: Notice you are now looking at the same interactive terminal you had before the disconnect



Of these two programs,
: '''screen''' is the better known and more likely to be installed. It's a fairly stagnated project now, though.
: '''tmux''' is more actively developed, so has a few more features.



{{zzz|More detailed info|
Screen and tmux distinguish themselves from a regular shell in a few significant ways.



[[File:screentmux-diagram.png|320px|thumb|right|One of the most complex cases in too much detail.<br/>Much of the point is that the things you are really running are only tied to that background session hosting process -- so when ''anything else'' breaks {{comment|(e.g. the viewing terminal, which might be remote access as diagrammed above)}} it has no effect on them]]



'''Terminal multiplexing''' means they can host/view many process at a time.

One hosted session can contain ''many'' interactive shells side by side,
* ...analogous to a tabbed web browser, though shown a little differently


'''Those shells/processes are separated from the shell you logged in with'''

You can think of screen/tmux as a background service that hosts interactive processes.
* when you start starting screen/tmux, you create both that host process, plus an interactive viewer into it  
* Each 'window' you start within that service defaults to start its own shell


The viewer can switch between these windows
: Doing so mainly amounts to connecting your keyboard input and text output to one of the varied process/shell at different times.
: When said viewer stops, it doesn't affect the service what it was looking at.


This is useful for anyone who who 
* runs long-term jobs, 
* wants to leave a text editor or other work open until tomorrow/later, 
* wants to work remotely but has a internet/WiFi connection that sometimes drops, 
or whatnot.
}}


{{zzz|''For contrast, the usual case ''without'' screen, tmux, or similar:''

A program is a child of a shell, that shell is the child of either the graphical terminal, or sshd or such. 

When that parent stops for any reason, all proceses under it gets cleaned up.

Additionally, because the other issue is that your process's stdin, stdout, and stderr (keyboard input, terminal output)
are typically tied to the shell you started it in. 
When one of those streams gets disconnected, the program tends to not deal with that and crashes.


You can get ''some'' relief from [[nohup]].

Instead of said process cleanup, the process is moved to be a child of init instead.
This usually means you can no longer interact, though. 

nohup can also handle stdin/stderr/stout by redirecting them elsehwere. 
Tying its input/output to a terminal again may even be possible, but a pain at best, so you don't really want this for interactive stuff.
}}

=tmux=
{{stub}}

For newcomers, you are probably most interested in:
* starting a new session {{inlinecode|tmux}}  (or <tt>tmux new</tt>)
* creating new windows: ''Prefix''-{{key|c}}
* disconnecting from a session: ''Prefix''-{{key|d}}
* reconnecting    to a session: {{inlinecode|tmux att}}

Closing/removing a window is often done by exiting the shell. {{comment|(If something is hung in it, you ''can'' kill the window explicitly)}}


'''''Prefix''''' is {{keyhold|Ctrl}}{{key|b}} by default, but '''you may want to change it''' to {{keyhold|Ctrl}}{{key|a}} to avoid confusion when you're on a host that only has screen.
Because that will happen. {{comment|(For the same reason, I like to rebind keys so that overlapping features have the same keys. See the example config below.)}}



==Tmux when compared to screen==

From those who know [[#Screen|screen]], the difference is mainly:
* both has different key shortcuts 
: but both are configurable
: my switch from screen to tmux went surprisingly smoothly once I rebound keys to imitate screen :) (see below)

* tmux is a more active project than screen, so more likely to have/get features you want

* tmux can be less bother when you use X forwarding 
: in that ''new windows'' will fetch DISPLAY according to the outside environment (of the most recent attach {{verify}})

* tmux can be more flexible layout-wise
: and the split+layout is remembered better

* tmux can be more easily made to automatically rename windows according to what they are running

* is ''a bit'' more modular and scriptable

==Terminology==
You, as a '''client''', connect to a session (more than one client can connect to a session).

Multiple '''sessions''' can be useful, say, to split work and home use.

Within a client/session you look at one '''window''' at a time (named, fixed numbering, often switched to by index).

Windows ''can'' be split into '''panes''' if you think that useful (numbered by current position, can be cycled through).

Maybe you'll prefer putting distinct tasks into distinct windows (e.g. IRC, different coding projects), and put related bits of the one task in panes (e.g. editing code, running it, viewing the log).
<!--
* <tt>window</tt>    - In practice more like tabs. You see one at at a time. Numbering is fixed within a session. Can be named. Number and name shown at the bottom.
* <tt>pane</tt>      - each window can be split into panes. (You can break off a pane into its own window)
-->


==Interaction I use most==
There are plenty of cheat sheets out therem.<br/>
The way I use it most of the time:


tmux's '''Prefix''' is '''Ctrl-b''' by default, but most people {{comment|(apparently including the tmux devs)}} seem to remap it to '''Ctrl-a''' so that your screen-related muscle memory works. {{comment|(For the remapping mentioned here, see the config file example somewhere below)}}



'''starting, attaching, detaching'''
* {{inlinecode|tmux}}, or {{inlinecode|tmux new}}  starts a new session
* {{inlinecode|tmux attach}} attach - if you have just one, you don't have to worry about the details
: By default it will leave other connected clients attached {{comment|(and use the smallest window size of the set, padding the rest)}}. If you want it to detach other clients after attaching, the easiest way is probably {{inlinecode|tmux att -d}}
* {{inlinecode|tmux ls}} - list sessions
* Prefix-{{key|d}}       Detach the current client               {{comment|(same as in screen)}}



'''scrollback'''
* Prefix-{{key|[}} - start navigating in tmux scrollback for the pane
:: You can then also do Ctrl-S and Ctrl-R (forward and backward search)


'''window'''
* Prefix-{{key|c}}       Create a new window                     {{comment|(same as in screen)}}

* Prefix-{{key|0}} through Prefix-{{key|9}} Move to window by number      {{comment|(same as in screen. I like to configure tmux so that 1 is the first window, not 0)}}

* Prefix-{{key|w}}       List windows {{comment|(I like to remap this to Prefix-{{key|"}})}}

* Prefix-{{key|l}}       Move to the previously selected window  {{comment|(same as in screen. I like to add Prefix-Prefix to do the same)}}

* Prefix-{{key|&}}       Kill the current window                 {{comment|(I like to remap this to Prefix-{{key|K}})}}

* Prefix-{{key|,}}       Rename the current window               {{comment|(I like to remap this to Prefix-{{key|A}})}}
<!--
* Prefix-{{key|n}}       Change to the next window               {{comment|(same as in screen)}}
* Prefix-{{key|p}}       Change to the previous window           {{comment|(same as in screen)}}
-->


'''Pane'''

* Prefix-{{key|%}}      Split into two panes, vertically. {{comment|(I like to remap this to Prefix-{{key|&#x7C;}} }})
* Prefix-{{key|"}}       Split into two panes, horizontally {{comment|(I like to remap this to Prefix-{{key|-}} )}}

* Prefix-{{key|x}}       Kill current pane {{comment|(...but I typically just log out of its shell)}}

* Navigate
** I don't like the standard way (that I've seen)
** I like to map Prefix-arrowkeys to do this (and only ever use that)<!--
** (standard alt-tab-like method seems to be Prefix-{{key|o}}, and Prefix + n)
-->

* Relayout:
** Prefix-{{key|''space''}} use next layout (easier), OR 
** Prefix-{{modkey|Alt}}-{{key|1}} through Prefix-{{modkey|Alt}}-{{key|5}} to use specific layouts. When I actually care to relayout, I seem to use 5 most.

* Resize
** I like to map Prefix-{{modkey|Alt}}-arrowkeys to do this

<!--
* Prefix-{{key|q}}       Show pane numbers. If you press a number while they are still visible, you will switch to it.
* Prefix-{{key|<nowiki>{</nowiki>}}       shift current pane left in sequence
* Prefix-{{key|<nowiki>}</nowiki>}}       shift current pane right in sequence
-->


'''Session'''
* Prefix-{{key|s}} - list sessions
* Prefix-{{key|(}} - switch to user's previous session 
* Prefix-{{key|)}} - switch to user's next session 


'''Misc'''
* Prefix-{{key|?}}       List all key bindings                   (same as in screen)


<!--
==More on windows and panes==
http://unix.stackexchange.com/questions/14300/tmux-move-window-to-pane
-->

==on tmux's copy mode==
<!--

If you see something like {{inlinecode|[0/0]}} in a corner, you are in copy mode. Either:
* move around, start with space, and copy with enter
* get out with Esc (and probably other shortcuts)

You probably got into copy mode via prefix-[.
You can paste with prefix-]



: '''tmux, the mouse, and copy/paste'''

Having any mouse feature on seems to capture the mouse away from your X-style select-to-copy and middle-mouse-to-paste behaviour.

A few solutions:
* hold Shift. In many terminals this has the net effect of selecting instead of sending mouse events {{verify}}

* disable all tmux mouse features:
 set-option -g mouse-select-pane off
 set-option -g mouse-resize-pane off
 set-option -g mouse-select-window off
 set-window-option -g mode-mouse off

* get tmux to interact with the X (or OSX) clipboard.

# move x clipboard into tmux paste buffer
bind C-p run "tmux set-buffer \"$(xclip -o)\"; tmux paste-buffer"
# move tmux copy buffer into x clipboard
bind C-y run "tmux show-buffer | xclip -i"

##CLIPBOARD selection integration
##Requires prefix key before the command key
#Copy tmux paste buffer to CLIPBOARD
bind C-c run "tmux show-buffer | xclip -i -selection clipboard"
#Copy CLIPBOARD to tmux paste buffer and paste tmux paste buffer
bind C-v run "tmux set-buffer -- \"$(xclip -o -selection clipboard)\"; tmux paste-buffer"


Right now, it seems to mean you can only get tmux to copy from a single pane if you learn tmux's copying.

* Try to see 
 set -g mouse-mode on 
 set -g set-clipboard on
The latter forces <tt>=\E]52;%p1%s;%p2%s\007<tt> style copying, rather than basing it on whether you have a <tt>Ms</tt> entry in the advertised term.

-->

<!--
==On extended colors==
-->

==More on panes and windows==

<!--
I occasionally find myself wanting to make multiple windows into panes in one window

 join-pane [-dhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
    (alias: joinp)
    Like split-window, but instead of splitting dst-pane and 
    creating a new pane, split it and move src-pane into the 
    space.  This can be used to reverse break-pane.



Take from elsewere, move here:
 -s [session]:window[.pane]
 # for example, if I'm positioned in window 1 and want to move window 2 into a pane in window 1:
 :join-pane -s :2

Take from here, move elsewhere:
 -t [session]:window[.pane]

The colon isn't optional. 



If you want to bind a key, you may want something like the following:
 bind-key @ command-prompt -p "create pane from:"  "join-pane -s ':%%'"


-->

==Example config (<tt>~/.tmux.conf</tt>)==

Note that tmux is under active development.  And some distros are a ''bunch'' of versions behind that, 
: so there are plenty of things that lead to heavy complains in other versions, and trial-and-erroring and "works for me". This can be messy.
: {{comment|(non-old versions report their version using {{inlinecode|tmux -V}}. Alternatively, look at your package management to see which version you have installed)}}


'''Config notes'''
* for key binding commands
** bind is the same as bind-key
** Prefix ? shows a list of current keybinds
** {{inlinecode|-r}} means 'repeatable without repeating the prefix'
*** e.g. useful when using arrow keys for pane resizes
** {{inlinecode|-n}} means 'does not need prefix'
*** probably rare because that makes the key ''generally'' unusable.
*** I e.g. have F12 as a 'go to next pane': {{inlinecode|bind -n f12 select-pane -t :.+}}

<!--

* some terms
** server - a set of sessions. You connect to them separately but they are controlled under the same parent process
** session - a set of windows, plus a notion of which of them is window current
** window  - single visible screen. May be made of one or more panes


* keep in mind that tmux settings will not start from scratch until you've exited ''all'' sessions
: most people choose to bind something to {{inlinecode|source-file ~/.tmux.conf}}
:: which, note '''isn't''' the same as reloading, in that sets all the things but doesn't address previously-set things it ''doesn't'' overwrite by doing set.   Most of the time this doesn't matter, ''somtimes'' it is the source of your confusion.



* '''to understand the variations of set'''
: know that there are three classes of options: server, session, and window (and more recently also pane)
:: this seems intended as an "inherit from something more general, but allow more specific per-session and per-windo behaviour" via  "take value from the most specific part that sets it, fall back to more general part"
:: if you don't care to ever use that, how you set matters much less.   If you do, put options in the most general section (so probably set -g)

: -g is the global session
: (no option) is session, overrides global session
: -w is window: overrides global session and session  (set-window-option seems the same)

: set -u  un-sets
:: note that if you have it set in a wider section, it implies using that value, rather than a tmux default

: set -a  appends to a current value (for strings)

: in a running session, this layered thing is not done on the fly - assume you need a new session{{verify}} for that to evaluate quite as you want

for e.g. {{inlinecode|set}} and {{inlinecode|show-options}},
* -s          server options
* (no option) session options
* -w          window options
* -p          pane options 

There is also 
* a 'global window' (-w -g) set, inherited into all windows (rather than applied to the current) {{verify}}
* a 'global session' (just -g; because session is the detault) {{verify}}

-->


'''Config examples'''

<syntaxhighlight lang="python">

# be screen-like by using Ctrl-a, not Ctrl-b, as Prefix
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# announce in TERM that we are good with colors
set -g default-terminal "screen-256color"

# execute things from the config file, avoids having to restart to get a new config
# (note: not quite the same as a reload, because it leaves what it doesn't overwrite)
unbind r
bind r source-file ~/.tmux.conf

# more history than the default 2000. Can be unlimited, but you may not want that.
set -g history-limit 8192

# lock session after inactivity
set -g lock-command vlock
set -g lock-after-time 300   # Seconds; 0 = never
# I learned this habit imitaging windows/gnome's Win-L.  Overrides last-session binding
bind L lock-session    

# mouse used to have more separate options, was generalized around 2.1.
#   I used this mainly for navigation (there is more) 
#   but do not use it enough to merit extra behaviour
set -g mouse off

#set -g set-clipboard off



### WINDOW STUFF  ###########################################################################################

# things like running a shell command will rename a window  (unless/until we set one manually)
set -g set-titles on
set -g set-titles-string '#W,    #T'
bind A command-prompt "rename-window '%%'"
set -g automatic-rename on
set -g allow-rename off



### PANE STUFF  ###########################################################################################
# I can remember - and | as horizontal and vertical splits better than % and "
unbind %
bind | splitw -h
unbind '"'
bind - splitw -v
bind _ splitw -v

# Shift-arrows resizes panes in that direction
bind -r S-Left resize-pane -L 2
bind -r S-Right resize-pane -R 2
bind -r S-Down resize-pane -D 2
bind -r S-Up resize-pane -U 2


# highlight current pane
# (tmux 3ish style, earlier was different)
set -g pane-active-border fg=green
set -ag pane-active-border bg=magenta



### NAVIGATION ###########################################################################################
# start numbering at 1, eases window switch by number (C-a 1, C-a 2)
set -g base-index 1


# toggle between last two windows
unbind ^A
bind ^A last-window

# choose a window visually
bind '"' choose-window


# Prefix arrows  moves through panes in that direction  (arrows repeatable)
bind -r Left select-pane -L
bind -r Right select-pane -R
bind -r Down select-pane -D
bind -r Up select-pane -U


## Experiments
# cycle through panes
bind -n f12 select-pane   -t :.+
# cycle through windows
bind -n f10 select-window -n
# cycle through sessions   -   note there's always ( and )
bind -n f8  switch-client -n
</syntaxhighlight>

<!--
set-hook pane-focus-in "set -g pane-border-status top"
set -g pane-border-format "#{pane_index} #{pane_current_command}"

# Set screen-like shortcuts  (also to avoid Ctrl-b for vi users)
unbind C-b
set -g prefix C-a
unbind ^a
bind-key ^a  last-window            # C-a C-a: quick switch to last-viewed window
                    # note: you may instead like this to do send-prefix
                    #   so that you can easily send commands to an inner/remote tmux.
bind-key ^i  select-pane -t :.+     # C-a C-i: cycle between panes in window
bind-key A   command-prompt "rename-window '%%'"         
bind-key '"' choose-window     
bind-key k   confirm-before -p "kill-pane #W? (y/n)" kill-pane
bind-key K   confirm-before -p "kill-window #W? (y/n)" kill-window  


# Joining windows into panes. (will relayout if the thing being moved is already paned)
# taken from http://unix.stackexchange.com/questions/14300/tmux-move-window-to-pane
bind-key j command-prompt -p "join pane from:"  "join-pane -s '%%'"
bind-key s command-prompt -p "send pane to:"  "join-pane -t '%%'"
# You may also want to know about break-pane, 
#         and remember relayouting via Prefix Meta-[0-5]




You may want to look at fancier styles, e.g. 
https://www.hamvocke.com/blog/a-guide-to-customizing-your-tmux-conf/

-->

Special values in titles include:
 #(shell-command)  First line of the command's output
 #H                local hostname
 #F                Current window flag                     
 #I                Current window index                    
 #P                Current pane index                      
 #S                Session name
 #T                Current window title (a shell thing? typically user@host:path ?)    
 #W                Current window name  (tmux's own, the one shown in the bottom bar)
 ##                A literal ‘#’
 #[attributes]     Colour or attribute change
You can also use [http://linux.die.net/man/3/strftime strftime] variables. Keep in mind those start with a percent sign instead.

The color/attribute changes look like:
 <nowiki>#[nobright fg=green]</nowiki>
<!--Notes:
* Apparently, on 256-color terminals you have color0 through color255-->
When doing complex things, it may help to know that <nowiki>#[]</nowiki> is interpreted after all other # sequences.

<!--
It seems that tmux defaults to basic 8 color support, because you can't reliably detect more
 tmux -2

# by default, tmux advertizes itself as screen (implying basic 8-color support)
set -g default-terminal "screen-256color"
-->



See also:
* http://robots.thoughtbot.com/post/2641409235/a-tmux-crash-course
* http://blog.hawkhost.com/2010/07/02/tmux-%E2%80%93-the-terminal-multiplexer-part-2/
* http://mutelight.org/articles/practical-tmux
* http://www.techrepublic.com/blog/opensource/is-tmux-the-gnu-screen-killer/1901

* http://www.dayid.org/os/notes/tm.html  (tmux/screen cheat sheet)

* https://mutelight.org/practical-tmux


===Color based on host===

That is, have the bottom bar colored according to a hash of the hostname.

When administering many hosts, this can help lessen confusion of which host you're on.

See e.g. the solutions at  http://unix.stackexchange.com/questions/122508/set-tmux-status-line-color-based-on-hostname

===On status lines and titles===
{{stub}}

<!--
[[Status line]]s/[[hardstatus]] are a terminal feature intended for messages from the active program.
You can often get GUI terminals to read out the hardstatus, 
and use it for their title bar.
It is often (though not only) used to mention what is currently running on that shell. 


Since tmux/screen are a layer inbetween shell and terminal, they have to choose to carry these through. 
It also means they would have to remember it per contained window/pane.

Things are slightly more complex when using tmux/screen. 
Because they contain terminals, they can choose to separate:

* the status they receive from each terminal - is stored per terminal
: which is what is altered by escape-sequence sets within that term

* the terminal status they expose 
: i.e. to the terminal that is currently showing the tmux/screen viewer

* what they show on-screen themselves 
: which often ''isn't'' directly related to either of the above. 
: ...so isn't actually a hardstatus. But often more useful than one.

Relatively few programs set status line, 
which is why tmux/screen chooses to use it itself.


To see what setting one does from a term, run:
 printf '\033kNAME\033\\'

-->

====For tmux====
{{stub}}

What is shown on-screen is configurable {{comment|(and not exposed anywhere - it's not a hardstatus at all)}}
: comes from multiple places, including window titles and configured things
* {{inlinecode|status-interval}} - how often to update
* {{inlinecode|status-left}}  (default [#S])
* {{inlinecode|status-right}} (default is current window title, date, time) 
* ...and a whole bunch more, mainly controlling what to put in there, and its formatting


What it exposed in its own status line is controlled via: {{verify}}
* {{inlinecode|set-titles on}} (off by default) 
: (checks via termcap; uses tsl, fsl)
: (does this set tmux window title, or its terminal hard)

* {{inlinecode|set-titles-string}}

The interesting part is the difference between contained-term status and window names (and pane titles).


Primarily that each window (though you'ld usually control this globally) has settings:
* {{inlinecode|automatic-rename}} (added in 1.6, default seems to be on{{verify}})
: whether to rename a window automatically (using automatic-rename-format)
: disabled after an explicit name is set {{comment|(...at start via new-window or new-session, or later with rename-window)}}

* {{inlinecode|automatic-rename-format}} (added in 1.9, default {{inlinecode|<nowiki>#{pane_current_cmd}</nowiki>}}) 
: (in 1.6..1.8, current pane command was the only automatic-rename behaviour there was) 

* {{inlinecode|allow-rename}} (default was on in 1.6..2.6{{verify}}, off in 2.7)
: don't listen to escape sequence in contained terminal{{verify}}
: (does it also disable automatic-rename? or imply it?)

{{comment|(versions matter because most things are on older versions still, e.g. AOTW RHEL seems to be on 1.8, Ubuntu on 2.1)}}



<!--

It seems that tmux usually(/always?) sets the terms's status line when it sets the window title.

But it doesn't necessarily update the window title when it sees a hardstatus update control code{{verify}}

At first it seemed that it's actually abusing the hardstatus as the variable in which they store/retrieve the window title -- except that it can ignore escapes from the contained term. So actually it's keeping 







...and there's some specific logic to what the window title is. For (attempted) completeness:

* tmux session has a name (mostly irrelevant here)

* tmux windows have names
: set at creation time
: set with rename-window (or the key sequence bound to that)
: set automatically, if so configured via automatic-rename
:: (with some details whether it's allowed to rename once manually named)
: if using multiple panes, then a window's title is set to title of the active pane {{verify}}

* tmux panes have titles
: inital value is the hostname
: can be set with escape sequence (?)


The question is who (you, shell, tmux) you want to set what (window title, status line).






based on automatic-rename-format (using tmux-specific things, which include )





* there is an escape sequence, meant to set the status line
: ...that can also be intercepted by tmux to set the title for the tmuxwindow that came from


set-option -g automatic-rename-format '#(basename "#{pane_current_path}")'



# automatic window naming can effectively come from two sources:
# - escape sequences set by your shell, see          allow-rename
# - tmux,        see automatic-rename and automatic-rename-format
# You want only latter when you want manual naming to stick, 
#    because it stops once you manually set a window name (or a window is named at creation time). So:
set-option -g allow-rename off

# Separately from tmux's naming of windows (which is disabled automatically
# when you manually name a window), there is also escape-sequence-based naming,
# which you may want to disable if your shell does this



'''tmux itself being bothersome'''





https://that.guru/blog/automatically-set-tmux-window-name/





-->

====If your tmux windows won't stop renaming====
...even after you've manually set a name, it's not automatic-rename but your contained shell doing so.

In my case it was [https://bugzilla.redhat.com/show_bug.cgi?id=969429#c5 RHEL's /etc/bashrc] trying to help screen {{comment|(and the issue is arguably tmux pretending too to be a screen-type TERM)}} by setting:
 PROMPT_COMMAND='printf "\033k%s@%s:%s\033\\" "${USER}" "${HOSTNAME%%.*}" "${PWD/#$HOME/~}"'
The fix would be removing that.


oh-my-zsh can be doing this (can be disabled in it)

====For screen====
<!--
* captions 



-->

==Semi-sorted (tmux)==

===More than ~eight colors===
{{stub}}

It looks like
* Tmux plays conservative about assuming its environment supports more than the basic eight-or-so colors.
* when it sees 256-color and true-color escapes it seems to actively rewrite them into more basic colors
* you can get more colors by starting tmux with -2




===Scripting tmux===
{{stub}}

====via startup commands====
<!--

You could hand in multiple commands somehow - once.

Says the man page: 
 Multiple commands may be specified together as part of a command sequence. 
 Each command should be separated by spaces and a semicolon;
 commands are executed sequentially from left to right and lines ending 
 with a backslash continue on to the next line, except when escaped by another backslash.
 A literal semicolon may be included by escaping it with a backslash
 (for example, when specifying a command sequence to bind-key).


So, for example, to create four new fresh shells:
 tmux new-session  \; split-window \; split-window \; split-window \; select-layout even-vertical

Shells, because when no argument is given (to new-session or split-window), it runs {{inlinecode|default-command}}, which defaults to {{inlinecode|default-shell}}, which you probably have as bash.



A pane is closed once the command finishes, which is why you probably ''want'' it to be a shell.

That means specifying commands comes down to sending characters to each pane, e.g.:
 tmux \
   new-session  \; send-keys 'ls' Enter \; \
   split-window \; send-keys 'ls' Enter \; \
   split-window \; send-keys 'ls' Enter \; \
   split-window \; send-keys 'ls' Enter \; \
   select-layout even-vertical


You can also have tmux source a file, which can be a little cleaner to write
 tmux new-session \; source-file ~/newdevsession
Where that file contains something like:
 send-keys 'vi' Enter
 select-layout even-vertical
 
 split-window
 send-keys 'emacs' Enter 
 select-layout even-vertical
 
 split-window
 send-keys 'nano' Enter 
 select-layout even-vertical
 
 split-window
 send-keys 'ed' Enter
 select-layout even-vertical

{{comment|(The relayouting is done repeatedly to try to avoid avoid the increasingly small panes leading to "create pane failed: pane too small" error.)}}


Notes:
* Enter is a tmux-specific shorthand. See also:
: https://stackoverflow.com/questions/19313807/tmux-send-keys-syntax
: http://man.openbsd.org/OpenBSD-current/man1/tmux.1#KEY_BINDINGS



If you don't mind installing stuff, look at:
* [[#byobu|byobu]] has something similar to the sourcing files

* [https://github.com/tmuxinator/tmuxinator tmuxinator]

* [https://github.com/remiprev/teamocil teamocil]
-->


====command line arguments====

You can manage existing sessions via command line arguments (list-sessions, list-windows, new-window, etc.)

It's a little verbose to do directly, perhaps, so you may prefers some code wrappers e.g. [https://github.com/tmux-python/libtmux/ this python library].



====Control mode====

Control mode is tmux itself exposing a basic text-mode protocol, separate from the sessions it manages.

It is meant to let programs automate use of tmux, as well as be able to give you some (asynchronous) notifications.

It can also be used for better UI integration - see e.g. what iTerm2 does.<!--
https://medium.com/@gveloper/using-iterm2s-built-in-integration-with-tmux-d5d0ef55ec30
-->

<!--
tmux -C starts tmix in control mode, but doesn't change any terminal attributes, e.g. with echo still enabled.
: mainly meant for testing use of control mode?
 
tmux -CC 
: disables echo
: adds some escapes that a wrapping process can use

entering an empty line (just pressing Enter) will detach the client.
-->

See also:
* https://github.com/tmux/tmux/wiki/Control-Mode

===Tmux doesn't change COLUMNS /  shell and programs draw incorrectly===
{{stub}}
<!--

Tmux itself seems to know its size well ({{inlinecode|tmux lsp}}).

tmux does seem to rate-limit them, effectively sending just the first and last of a quick series of resizes 
: in some tests, this seems to be the thing that messed up?


There seem to be two further questions
: does it make its way into the shell?
:: check the first line of {{inlinecode|stty -a | grep columns}}
:: it seems it often won't while it's running something - it goes to the terminal's controlling process

: does it send a SIGWINCH 
:: it seems tmux sometimes stops doing so after a while (e.g. testing with the python script below, and noticing that <tt>stty -a</tt> output also stops changing) for all panes within a specific window





Helpers to see whether they arrive
<syntaxhighlight lang="python">
#!/usr/bin/python
import signal, time
def pr():
    print "WINCH"
signal.signal(signal.SIGWINCH,  lambda signum,sframe: pr() )
while True:
    time.sleep(1)
</syntaxhighlight>

Or very similar in the shell:
 example(){ echo "Window resized"; }    ; trap 'example' WINCH
 




https://github.com/fish-shell/fish-shell/issues/3180

https://github.com/fish-shell/fish-shell/issues/2980

https://serverfault.com/questions/452340/debian-ssh-resizing-terminal-does-not-register-with-bash

https://news.ycombinator.com/item?id=7757812

-->



===Environment===

<!--
You likely care to see things like DISPLAY and SSH_AUTH_SOCK updated more often than you start a new tmux window or a new shell.

tl-dr:
* things are handed in

Short story: You want something in your shell to 

The tmux process keeps ''its'' values updated (based on the update-environment setting?).
It hands them along when you create a new window and it shell.

It can't do anything after that time, since you can't push environment into a shell.
But they can ask tmux for its environment, and then set it themselves

: You can access the environment that tmux itself sees via 



Auto-updating:
* http://babushk.in/posts/renew-environment-tmux.html
* http://stackoverflow.com/questions/18241406/tmux-environment-variables-dont-show-up-in-session
* https://raim.codingfarm.de/blog/2013/01/30/tmux-update-environment/


TODO: 
* check effect of default-command on env stuff

* exact difference between show-environment and show-environment -g 
-->

=Screen=

The manual calls <tt>screen</tt> "''a full-screen window manager that multiplexes a physical terminal between several processes (typically interactive shells)."''

<!--
From a more practical view: 
* it runs as a background service,
* hosts shells,
* stays around when you disconnect from it {{comment|(manual disconnect, broken ssh/telnet connection, etc.)}}
* you can reconnect to your own running instances of screen later, to continue using the shells that it houses

Perhaps the '''largest difference''' is that screen intentionally does ''not'' run nder the terminal you logged in as {{comment|(in the usual case, the shell runs as a child of sshd, X, or a [http://en.wikipedia.org/wiki/Getty_%28Unix%29 getty] program -- and the entire process tree would implicitly be closed if the ssh connection, graphical window closes or you log out of the physical terminal)}}.

This means you can log out of that physical shell, the remote connection can break, and this will only affect your ''view'' of the running screen - not screen itself or the processes in it.

Think of screen as a background service that you can put some running shells and programs in.

They can be very useful to leave work around, leave editors open, to host commmand-line daemons, on whatever host you were working on. 
It means you don't have to have many separate shell windows open, don't have to have many connections, and don't have to worry what happens to the programs/work if such shells get disconnected. 





{{comment|(The terminal emulation that screen itself hosts is often a little different from your typical ssh or X shell, so behaviour may differ a little from the prompt you had outside screen (e.g. line drawing, scrollback, sometimes color handling), but you can change most of those details.)}}
-->

==Usage basics==

===Windows===
The distinct things within an instantiation of screen are called windows. 

By default, each window starts with your default shell, so each window is useful for a distinct task, say, running and editor, running a program, viewing logs.

Window-related commands you may well use:
* Creating a new one: '''Ctrl-a ''c'''''
* You can switch to a window by its number '''Ctrl-a ''number'''''
* You can toggle to/from the last used window with '''Ctrl-a Ctrl-a'''
* You can get a list of windows with '''Ctrl-a "'''


You may like to have an on-screen list of windows. See configuration notes below (or look to byobu).



===Instantiations of screen===

: '''starting, stopping'''

To start a screen, type {{inlinecode|screen}}. This starts a new screen process and creates a single window inside it, with a shell according to your user settings.

Most commands are ''Ctrl-a'' followed by something. For example, help is ''Ctrl-a, h''

The usual way to stop a screen by stopping the processes from its last window {{comment|(or, if you can't easily stop the contained process, kill that window - '''Ctrl-a, k''')}}.



: '''Detach, reattach'''

You '''detach''' (disconnect) from a running screen instantiation with '''Ctrl-a, d'''.


'''Reattaching''' comes in quite a few flavours, though out of habit you'll probably remember just one or two convenient ones.

* {{inlinecode|screen -list}} shows all the running screens for the current user. Makes sense when you run more than one.

* reconnect commands can often be used with or without argument. 
** without tends to mean:
*** ''"If there is exactly one screen process, reconnect to it"''
*** ''"If there are more, show a list"''
** with tends to mean ''"reconnect when there is one unique string-starting match"'' 
*** For example, if you have <tt>18720.pts-0.hostnm</tt> and <tt>23972.pts-0.hostnm</tt>, then {{inlinecode|screen -r 23972}} but also {{inlinecode|screen -r 23}} will connect to the second.

If you don't want names like <tt>5730.pts-0.hostnm</tt>, you can specify your own with <tt>-S</tt>



As to the different reconnect commands: {{verify}} (this needs clarification / double-checking)
* {{inlinecode|-r}} for 'resume'. Won't connect to an already-attached screen (and won't create a screen)

* {{inlinecode|-R}} - largely like like <tt>-r</tt>, but if no screen exists (or it is attached and there is no request to detach it), it will create one

* {{inlinecode|-RR}} - basically ''"connect to the first (detached) screen you can find; if one isn't running, start a new screen."''

* {{inlinecode|-d}} - when connecting to a currently attached screen, this will disconnect the others first

* {{inlinecode|-D}} - like <tt>-d</tt>, plus it causes logout from the shell the other connection came from.
** Usually means your other remote login (terminal/emulator) will be closed or logged out, which is nice for peace of mind.

* {{inlinecode|-x}}, which means 'join an attached screen without detaching others'
** This means sharing both input and output, without any choice. You may want multiuser mode instead
** (the smallest window size between the logins will be used)


These can be combined. There's more than a dozen combinations
* -rd roughly means "connect to the last one and detach others"
* -RD roughly means "-rd, detach+logout if it was attached, create it if necessary" - possibly the easiest do-what-I-want
<!--
* -xRR roughtly means "share-reconnect if possible. Create if not."
-->

==Some more key commands==
<!--Note: Hosted things are referred to as windows. 'A screen' refers to an instance of screen that contains various windows. -->

The key shortcuts I consider useful are:
* Window stuff:
** <tt>'''Ctrl-a 1'''</tt>   switches to window by number, 1 though 9.
** <tt>'''Ctrl-a Ctrl-a'''</tt>   switches between last activated windows
** <tt>'''Ctrl-a "'''</tt>   gives list of windows, also allows switching with arrows and enter
** <tt>'''Ctrl-a c'''</tt>   creates new window {{comment|(removing one can be done with a logout, or:)}}
** <tt>'''Ctrl-a K'''</tt>   removes (kills) current window {{comment|(useful for things you can't Ctrl-C)}}

* Split screen:
** <tt>'''Ctrl-a S'''</tt>   (capital S) splits screen top-bottom
** <tt>'''Ctrl-a |'''</tt>   (pipe) splits screen left-right
** <tt>'''Ctrl-a Ctrl-i'''</tt>   switches to next part of split screen
** <tt>'''Ctrl-a -'''</tt>   makes current part of split screen smaller
** <tt>'''Ctrl-a +'''</tt> (on US keyboards meaning <tt>'''Ctrl-a Shift-='''</tt>)  makes current part of split screen larger

* Other:
** <tt>'''Ctrl-a ?'''</tt>   displays various keyboard commands
** <tt>'''Ctrl-a d'''</tt>   disconnects


<!--
Notes:
* I like to bind some things I commonly use to something simpler, like F-keys
* e.g. moving between windows, resizing
-->

==Scrollback==
Copy mode (which doubles as a scrollback viewer):
* Use <tt>'''Ctrl-a ['''</tt> to enter copy mode, ''Esc'' to exit.

In scrollback/copy mode, you can:
* '''Navigate'''
** vi-style line/column movement: h, j, k, l
** page-based movement:
*** PgUp and PgDn often work
*** C-u, C-d: half page up, down
*** C-b, C-f: full page up, down
** For more, see e.g. [http://www.delorie.com/gnu/docs/screen/screen_77.html]

* '''Search'''
** using <tt>/</tt> (forward) and <tt>?</tt> (backward)

==Configuration==

===Line drawing and/or Unicode===
Screen picks up on locale settings and should just work. If it doesn't, it usually means the locale settings do not handle what you want, or your terminal program is using some different interpretation.


Assuming you want to use UTF8 {{comment|(and unless you specifically ''must'' have something else, you want UTF8)}}, you should generally check two things:
* that (your account at) the server has an UTF-8 based locale (check whether <tt>LANG</tt> and/or <tt>LC_ALL</tt>{{verify}}) are set this way. 
* that the terminal program interprets the server correctly. For example, PuTTY defaults to 8859-1 and not UTF8.


If LANG nor LC_ALL does not mention utf8, you probably have to set up your system first; see [[Localization%2C_internationalization#Linux_locale_setting]]

Alternatively, you can also force UTF8 treatment throughout screen by starting screen with the <tt>-U</tt> option, but this isn't always ideal (it ignores the context of the system it runs in).


===A bunch of configuration possibles===
You can create <tt>~/.screenrc</tt> to have some settings, for example: 

 # hide the 'this is screen' message that appears when you start 
 startup_message off
 
 # allow more scrollback than 100
 defscrolback 2000
 

<!--
 # I accidentally disable control flow sometimes so don't want flow control:
 flow off
 defflow off

 # split screen commands
 bind = resize =
 bind + resize +1
 bind - resize -1
 bind _ resize max

 # visual instead of audible bell, Change message
 vbell on
 vbell_msg " *beep* "
 #or if you want the beep
 vbell off


 # change the escape  that screen uses -- Ctrl-A by default
 # emacs users may want to change this
 escape ^zz

 #TODO: figure this out
 charset something
 defutf8 on
-->

 # If you are primarily using remote text logins, you probably don't want 
 # X programs assuming they can use DISPLAY, so clear it:
 unsetenv DISPLAY

<!--
 # Likewise, for charset
 setenv LC_CTYPE en_US.UTF-8


 charset set
-->

 # remove some Ctrl-A <key> bindings that you only really use by mistake, 
 #  e.g. lock screen, hardcopy, write termcap, perhaps others
 bind ^x
 bind h
 bind .

<!--

On termcap:

http://sunsite.ualberta.ca/Documentation/Gnu/screen-3.9.4/html_chapter/screen_16.html#SEC104
 termcapinfo  *
 # or even
 termcapinfo  xterm*|Eterm|mlterm
-->


====Caption and hardstatus====
{{stub}}

 # always show caption, not only when using split screen 
 # (I like seeing that I'm using screen, and what host I'm on)
 caption always
 caption always "%H | %>%{kw}%?%-Lw%?%{wb}%n*%f %t%?(%u)%?%{kw}%?%+Lw%?%<"

The funky caption line is to show the list of all windows, with the current one highlighted -- because by default it will show only the current window number and name. Example result:<br style="clear:both">
[[Image:Simple-screen-window-bar.png]]

You can do much funkier things here - see for example [https://launchpad.net/byobu/ byobu] (formerly screen-profiles).




{{stub}}
Copied examples that show the window list:

 # white bar, current window blue
 caption always "%H | %>%{kw}%?%-Lw%?%{wb}%n*%f %t%?(%u)%?%{kw}%?%+Lw%?%<"
 
 # transparent bar, current window inverse (subtler)
 caption always "%>%{wk}%?%-Lw%?%{bw}%n*%f %t%?(%u)%?%{wk}%?%+Lw%?%<"

<!--

Fragments:
* Date 
** (ISO order): {{inlinecode|%Y-%m-%d}}

* Time
** {{inlinecode|%c:%s}} %c is ''hours'':''minutes'', %s is seconds
** "time on the right (when there's place)": {{inlinecode|<nowiki>%=   %c:%s</nowiki>


 # A copy-pasted example:
 caption always "%?%F%{-b bc}%:%{-b}%?%C|%D|%M %d|%H%?%F%{+u wb}%? %L=%-Lw%45>%{+b by}%n%f* %t%{-}%+Lw%-0<"
 (Shows time, date, hostname, window names and highlights current window)

 %?          - Start of a conditional statement.
  %F         - Use this part of the statement if the window has focus (i.e. it
               is the only window or the currently active one).
  %{-b bc}   - Turn off bold, blue foreground, cyan background.
 %:          - else
  %{-b bb}   - Turn off bold, blue foreground, blue background (this obscures
               the text on non-focused windows and just gives a blue line).
 %?          - End conditional statement.
  %C         - time (hh:mm, leading space) in 12 hour format
  %D         - Three-letter day-of-week appreviation
  %M         - Three-letter month appreviation
  %d         - Day of the month
  %H         - hostname
  %?         - Start of conditional statement.
   %F        - Use this part of the statement if the window has focus.
   %{+u wb}  - underlined, white foreground, blue background
  %?         - End conditional (if not focused, text remaind blue on blue).
    %L=      - truncation/padding point.  With the 'L' qualifier, basically
               just acts as a reference point.  Further truncation/padding is
               done relative to here, not the beginning of the string
    %-Lw     - window list up to but not including the current window (-),
               show window flags (L)
    %45>     - truncation/padding marker; place this point about 45% of the
               way into the display area (45)
    %{+b by} - add bold (still underlined from before), blue foreground,
               yellow background
      %n     - number of the current window
      %f     - flags for current window
      %t     - title of current window
    %{-}     - undo last color change (so now we're back to underlined white
               on blue)  (technically, this is a pop; a second invocation
               would drop things back to unadorned blue on cyan)
    %+Lw     - window list from the next window on (-), show window flags (L)
    %-0<     - truncation/padding point.  Place this point zero spaces (0)
               from the right margin (-).

# Color table:
# 0 Black             .    leave color unchanged
# 1 Red               b    blue
# 2 Green             c    cyan
# 3 Brown / yellow    d    default color
# 4 Blue              g    green           b    bold
# 5 Purple            k    blacK           B    blinking
# 6 Cyan              m    magenta         d    dim
# 7 White             r    red             r    reverse
# 8 unused/illegal    w    white           s    standout
# 9 transparent       y    yellow          u    underline


http://www.softpanorama.org/Utilities/Screen/screenrc_examples.shtml
-->



: '''hardstatus'''

The hardstatus is a slightly more complex subject. It's roughly a separate string that can be updated via terminal control codes. Your terminal/emulator has to support it, as well as allow setting it.

<!--It's also distinct from the caption - you can have both shown at the same time.-->


You can tell various terminals and emulators (particularly graphical ones, e.g. PuTTY, the regular ones in *nices,) to show it.
For example, you can alter your [[termcap]] with something like:
 # advertize hardstatus support to terminal 
 #   and use escapes to put it in the window title
 termcapinfo xterm 'hs:ts=\E]2;:fs=\007:ds=\E]2;\007'
 termcapinfo rxvt  'hs:ts=\E]2;:fs=\007:ds=\E]2;\007'
This can be handy when screen opts to set the title to just 'screen'


You can tell what screen should do when hardstatus support is ''not'' advertised (via termcap), one of:
 hardstatus ignore       # if not supported by terminal, don't show
 hardstatus lastline     # reserve last line in terminal
 hardstatus message      # use whatever screen's message mechanism currently is
Prepending {{inlinecode|always}} to any of these (alwaysignore, alwayslastline, alwaysmessage) will force the option even if the terminal supports hardstatus. Just <tt>always</tt> seems to be shorthand for the always variant of the default (lastline?).


You can tell screen to set particular things in the hardstatus. For example:
 # basic message to the hardstatus
 hardstatus on            # if off, hardstatus messages are printed on screen {{verify}}
 hardstatus string "%H [%n%?: %t%?] %h"  
<!--
Note: Each screen-window has its own hardstatus.{{verify}} 
-->


The <tt>hardstatus string</tt> line tells screen how to use the hardsatus.

%h  refers to the stored hardstatus (settable via {{inlinecode|<nowiki>"ESC]0;<string>^G"</nowiki>}} or {{inlinecode|<nowiki>"ESC_<string>ESC\"</nowiki>}})

====Titles for screen's own windows====
While you can set these manually (Ctrl-A Shift-A).

You can also set them via escapes, but the most convenient way for that to work is automatically.

If you want to also show things like the current directory, the place you probably want to send those escapes from is the prompt string. 

See e.g.
* [[Bash_and_profiles#Funky_things:_setting_the_screen_window.27s_title]]
* http://aperiodic.net/screen/title_examples

<!--
====Other termcap tricks====
http://sunsite.ualberta.ca/Documentation/Gnu/screen-3.9.4/html_chapter/screen_16.html#SEC104
-->

==Warnings==
==="Attaching from inside of screen?"===
Note that if you see "Attaching from inside of screen?", you probably did a <tt>screen -rd</tt> (or so) from within screen.

It says this in the screen you tried to do it from - so if you did a -rd or such, you'll only see it once you return to the screen. (which may be hard to see unless you use a caption-like thing to help you see when you're in a screen session)


In the case where you (implicitly or explicitly) referred to the screen you were in, in which case the net effect is that you will be disconnected (you'll see <tt>[remote detached]</tt>), and you will see the "Attaching from inside of screen?" message once you (re)connect to that screen.


<!--
==Nested screens==

You may have created the situation of running screen within a screen.

It can even be useful intentionally.
* to persisting split regions beyond a detach, by using one screen to stay connected to the split screen)



When nesting screens, commands go to the first screen that gets it - the outer one.

You can tell a screen to pass through a command with the <tt>a</tt> command. So

Ctrl-a a 


Giving commands:

Basically, 'a' 

-->



==Semi-sorted (screen)==

===Flow control===
Particularly emacs users might accidentally trigger flow control, since Ctrl-S is stop (Ctrl-Q is continue).

Can be enabled/disabled with ''Ctrl-a f''. If that solves your problem, you can disable it for all new sessions via screen config: {{inlinecode|flow off}} and/or {{inlinecode|defflow off}}



===screen and X tunneling===

Screen will mess with SSH tunneling of X. 

Once you reconnect to screen it will contain the DISPLAY inherited from the shell you started screen from, which will likely result in a:
 cannot open display


The SSH client ''did'' set the new X tunnel in the connecting shell's DISPLAY, of course, 
so you'll have to update it manually. 
Basically:
 # after connecting to the host, before reconnecting to screen, find the new SSH connection's DISPLAY value:
 user@host:~ $ echo $DISPLAY
 localhost:12.0
 
 # connect to the screen and in the relevant shell(s) do something like:
 export DISPLAY="localhost:12.0"


TODO: 
* figure out whether there is any more automated way to do this.
* tmux will try to do this automatically <!--(see its <tt>update-environment</tt> setting)-->

==="Cannot open your terminal ‘/dev/pts/x’ – please check."===

Probably means you used {{inlinecode|su}} to change users.


The problem is that the permissions on that pseudoterminal do not include you (even if you're root{{verify}}).
An {{inlinecode|ls -l /dev/pts}} will probably show something like:
 crw--w---- 1 myusername tty 136, 6 Apr 12 13:16 /dev/pts/6


To work around this, you can do:
 chmod a+rw /dev/pts/6
It's insecure, but useful enough for, say, an admin checking up on screens before rebooting.





If you su'd to a user you want to actively use for a while, you may like workarounds:
* use tmux instead of screen :)
* avoid su, by logging in or <tt>ssh</tt>ing to the user directly (only if you know the password)
* use {{inlinecode|script /dev/null}} - it's a weird fix, but it works. See http://serverfault.com/questions/116775/sudo-as-different-user-and-running-screen/116830#116830

==See also==
* the man page (an online version [http://www.mediacollege.com/cgi-bin/man/page.cgi?topic=screen here]) 
* the user manual (like [http://www.delorie.com/gnu/docs/screen/screen_toc.html here]).

* http://hyperpolyglot.org/multiplexers




=On byobu=

tl;dr: [http://byobu.co/ Byobu]
* is a wrapper to tmux and screen (defaults to tmux when available)
* adds system information in the status bar (package, battery, cpu, memory, network, and more)


<!--

Running {{inlinecode|byobu}} runs either {{inlinecode|byobu-tmux}} (preferred if installed), or {{inlinecode|byobu-screen}}. Both with options passed through.

See also:
* http://byobu.co/
-->

=To check=

https://github.com/spolu/warp