diff options
Diffstat (limited to 'FAQ')
| -rw-r--r-- | FAQ | 454 |
1 files changed, 454 insertions, 0 deletions
@@ -0,0 +1,454 @@ +tmux frequently asked questions + +****************************************************************************** +* PLEASE NOTE: most display problems are due to incorrect TERM! Before * +* reporting problems make SURE that TERM settings are correct inside and * +* outside tmux. * +* * +* Inside tmux TERM must be "screen" or similar (such as "screen-256color"). * +* Don't bother reporting problems where it isn't! * +* * +* Outside, it must match your terminal: particularly, use "rxvt" for rxvt * +* and derivatives. * +****************************************************************************** + +* How is tmux different from GNU screen? + +tmux and GNU screen have many similarities. Some of the main differences I am +aware of are (bearing in mind I haven't used screen for a few years now): + +- tmux uses a client-server model. Each server has single Unix domain socket in + /tmp and within one server there are multiple sessions which may be attached + to multiple clients (terminals). + + This has advantages, notably: windows may be linked simultaneously to + multiple sessions; windows may be moved freely between sessions; and a client + may be switched between sessions easily (C-b D). There is one major + disadvantage: if the server crashes, game over, all sessions die. In + practice, however, tmux is quite stable and gets more so as people report any + bugs they hit :-). + + This model is different from screen, where typically each new screen instance + is independent. tmux supports the same behaviour by using multiple servers + with the -L option but it is not typically recommended. + +- Different command interfaces. One of the goals of tmux is that the shell + should be easily usable as a scripting language - almost all tmux commands + can be used from the shell and behave identically whether used from the + shell, from a key binding or from the command prompt. Personally I also find + tmux's command interface much more consistent and clearer, but this is + subjective. + +- tmux calls window names (what you see in the status line) "names", screen + calls them "titles". + +- tmux has a multiple paste buffers. Not a major one but comes in handy quite a + lot. + +- tmux supports automatically renaming windows to the running application + without gross hacks using escape sequences. Its even on by default. + +- tmux has a choice of vi or emacs key layouts. Again, not major, but I use + emacs so if tmux did support only one key set it would be emacs and then all + the vi users would get humpy. Key bindings may be completely reconfigured in + any case. + +- tmux has an option to limit the window size. + +- tmux has search in windows (C-b f). + +- The window split (pane) model is different. tmux has two objects, windows and + panes; screen has just windows. This difference has several implications: + + * In screen you can have a window appear in several layouts, in tmux a pane + can only be in one window (fixing this is a big todo item but quite + invasive). + + * tmux layouts are immutable and do not get changed unless you modify them. + + * In tmux, all panes are closed when you kill a window. + + * tmux panes do not have individual names, titles and so on. + + I think tmux's model is much easier to manage and navigate within a window, + but breaking panes off from and joining them to windows is more clumsy. + + tmux also has support for preset pane layouts. + +- tmux's status line syntax is more readable and easier to use. I think it'd be + hard for anyone to argue with this. tmux doesn't support running a command + constantly and always using the last line of its output, commands must be run + again each time. + +- tmux has modern, easily extended code. Again hard to argue screen is better + if you have looked at the code. + +- tmux depends on libevent. I don't see this as a disadvantage: libevent is + small and portable, and on modern systems with current package management + systems dependencies are not an issue. libevent brings advantages in code + simplicity and performance. + +- screen allows the window to be bigger than the terminal and can pan around + it. tmux limits the size to the largest attached client. This is a big todo + item for tmux but it is not trivial. + +- screen has builtin serial and telnet support; this is bloat and is unlikely + to be added to tmux. + +- Environment handling is different. + +- tmux tends to be more demanding on the terminal so tends to show up terminal + and application bugs which screen does not. + +- screen has wider platform support, for example IRIX, and for odd terminals. + +* I found a bug! What do I do? + +Check the latest version of tmux from Git to see if the problem is still +reproducible. Sometimes the length of time between releases means a lot of +fixes can be sitting in Git and the problem might already be fixed. + +Please send bug reports by email to nicholas.marriott@gmail.com or +tmux-users@googlegroups.com. Please include as much of the following +information as possible: + +- the version of tmux you are running; +- the operating system you are using and its version; +- the terminal emulator you are using and the TERM setting when tmux was + started; +- a description of the problem; +- if the problem is repeatable, the steps to repeat the problem; +- for screen corruption issues, a screenshot and the output of "infocmp $TERM" + from outside tmux are often very useful. + +* Why doesn't tmux do $x? + +Please send feature requests by email to tmux-users@googlegroups.com. + +* Why do you use the screen terminal description inside tmux? It sucks. + +It is already widely available. It is planned to change to something else such +as xterm-xfree86 at some point, if possible. + +* I don't see any colour in my terminal! Help! + +On some platforms, common terminal descriptions such as xterm do not include +colour. screen ignores this, tmux does not. If the terminal emulator in use +supports colour, use a value for TERM which correctly lists this, such as +xterm-color. + +* tmux freezes my terminal when I attach to a session. I even have to kill -9 + the shell it was started from to recover! + +Some consoles really really don't like attempts to set the window title. Tell +tmux not to do this by turning off the "set-titles" option (you can do this +in .tmux.conf): + + set -g set-titles off + +If this doesn't fix it, send a bug report. + +* Why is C-b the prefix key? How do I change it? + +The default key is C-b because the prototype of tmux was originally developed +inside screen and C-b was chosen not to clash with the screen meta key. It +also has the advantage of not interfering with the use of C-a for start-of-line +in emacs and the shell (although it does interfere with previous-character). + +Changing is simple: change the "prefix-key" option, and - if required - move +the binding of the "send-prefix" command from C-b (C-b C-b sends C-b by +default) to the new key. For example: + + set -g prefix C-a + unbind C-b + bind C-a send-prefix + +* How do I use UTF-8? + +When running tmux in a UTF-8 capable terminal, UTF-8 must be turned on in tmux; +as of release 0.9, tmux attempts to autodetect a UTF-8-capable terminal by +checking the LC_ALL, LC_CTYPE and LANG environment variables. list-clients may +be used to check if this is detected correctly; if not, the -u command-line +flag may be specified when creating or attaching a client to a tmux session: + + $ tmux -u new + +Since the 1.0 release, tmux will turn on UTF-8 related options automatically +(ie status-utf8, and utf8) if the above conditions are met. + +* How do I use a 256 colour terminal? + +Provided the underlying terminal supports 256 colours, it is usually sufficient +to add the following to ~/.tmux.conf: + + set -g default-terminal "screen-256color" + +Note that some platforms do not support "screen-256color" ("infocmp +screen-256color" will return an error) - in this case see the next entry in +this FAQ. + +tmux attempts to detect a 256 colour terminal both by looking at the colors +terminfo entry and by looking for the string "256col" in the TERM environment +variable. + +If both these methods fail, the -2 flag may be passed to tmux when attaching +to a session to indicate the terminal supports 256 colours. + +* vim or $otherprogram doesn't display 256 colours. What's up? + +Some programs attempt to detect the number of colours a terminal is capable of +by checking the colors terminfo or Co termcap entry. However, this is not +reliable, and in any case is missing from the "screen" terminal description +used inside tmux. + +There are two options (aside from using "screen-256color") to allow programs to +recognise they are running on a 256-colour terminal inside tmux: + +- Manually force the application to use 256 colours always or if TERM is set to + screen. For vim, you can do this by overriding the t_Co option, see + http://vim.wikia.com/wiki/256_colors_in_vim. +- Creating a custom terminfo file that includes colors#256 in ~/.terminfo and + using it instead. These may be compiled with tic(1). + +* How do I make Ctrl-PgUp and Ctrl-PgDn work in vim? + +tmux supports passing through ctrl (and where supported by the client terminal, +alt and shift) modifiers to function keys using xterm(1)-style key sequences. +This may be enabled per window, or globally with the tmux command: + + setw -g xterm-keys on + +Because the TERM variable inside tmux must be set to "screen", vim will not +automatically detect these keys are available; however, the appropriate key +sequences can be overridden in .vimrc using the following: + + if &term == "screen" + set t_kN=^[[6;*~ + set t_kP=^[[5;*~ + endif + +And similarly for any other keys for which modifiers are desired. + +Please note that the "xterm-keys" setting may affect other programs, in the +same way as running them in a standard xterm; for example most shells do not +expect to receive xterm(1)-style key sequences so this setting may prevent keys +such as ctrl-left and ctrl-right working correctly. tmux also passes through +the ctrl (bit 5 set, for example ^[[5~ to ^[[5^) modifier in non-xterm(1) mode; +it may be possible to configure vim to accept these, an example of how to do so +would be welcome. + +vim users may also want to set the "ttyfast" option inside tmux. + +* How do I make ctrl and shift arrow keys work in emacs? + +The terminal-init-screen function in term/screen.el is called for new frames, +but it doesn't configure any function keys. + +If the tmux xterm-keys option is on, it is enough to define the same keys as +xterm. Add the following to init.el or .emacs to do this: + +(defadvice terminal-init-screen + ;; The advice is named `tmux', and is run before `terminal-init-screen' runs. + (before tmux activate) + ;; Docstring. This describes the advice and is made available inside emacs; + ;; for example when doing C-h f terminal-init-screen RET + "Apply xterm keymap, allowing use of keys passed through tmux." + ;; This is the elisp code that is run before `terminal-init-screen'. + (if (getenv "TMUX") + (let ((map (copy-keymap xterm-function-map))) + (set-keymap-parent map (keymap-parent input-decode-map)) + (set-keymap-parent input-decode-map map)))) + +And ensure .tmux.conf contains "set -g xterm-keys on". + +Alternatively, the screen.el file can be copied to the load path and +customized. + +* Why doesn't elinks set the window title inside tmux? + +There isn't a way to detect if a terminal supports setting the window title, so +elinks attempts to guess by looking at the environment. Rather than looking for +TERM=screen, it uses the STY variable to detect if it is running in screen; +tmux does not use this so the check fails. A workaround is to set STY before +running elinks. + +The following shell function does this, and also clears the window title on +exit (elinks, for some strange reason, sets it to the value of TERM): + + elinks() { + STY= `which elinks` $* + echo -ne \\033]0\;\\007; + } + +* What is the proper way to escape characters with #(command)? + +When using the #(command) construction to include the output from a command in +the status line, the command will be parsed twice. First, when it's read by the +configuration file or the command-prompt parser, and second when the status +line is being drawn and the command is passed to the shell. For example, to +echo the string "(test)" to the status line, either single or double quotes +could be used: + + set -g status-right "#(echo \\\\(test\\\\))" + set -g status-right '#(echo \\\(test\\\))' + +In both cases, the status-right option will be set to the string "#(echo +\\(test\\))" and the command executed will be "echo \(test\)". + +* tmux uses too much CPU. What do I do? + +Automatic window renaming may use a lot of CPU, particularly on slow computers: +if this is a problem, turn it off with "setw -g automatic-rename off". If this +doesn't fix it, please report the problem. + +* I use PuTTY and my tmux window pane separators are all qqqqqqqqq's! + +PuTTY is using a character set translation that doesn't support ACS line +drawing. With a Unicode font, try setting PuTTY to use a different translation +on the Window -> Translation configuration page. For example, change UTF-8 to +ISO-8859-1 or CP437. It may also be necessary to adjust the way PuTTY treats +line drawing characters in the lower part of the same configuration page. + +* What is the best way to display the load average? Why no #L? + +It isn't possible to get the load average portably in code and it is preferable +not to add portability goop. The following works on at least Linux, *BSD and OS +X: + +uptime|awk '{split(substr($0, index($0, "load")), a, ":"); print a[2]}' + +* How do I attach the same session to multiple clients but with a different + current window, like screen -x? + +One or more of the windows can be linked into multiple sessions manually with +link-window, or a grouped session with all the windows can be created with +new-session -t. + +* Ctrl and arrow keys doesn't work in putty! What do I do? + +putty inverts the sense of the cursor key mode on ctrl, which is a bit hard for +tmux to detect properly. To get ctrl keys right, change the terminfo settings +so kUP5 (Ctrl-Up etc) are the adjusted versions, and disable smkx/rmkx so tmux +doesn't change the mode. For example with this line in .tmux.conf (assuming you +have TERM set to xterm): + +set -g terminal-overrides "xterm*:kLFT5=\eOD:kRIT5=\eOC:kUP5=\eOA:kDN5=\eOB:smkx@:rmkx@" + +Note that this will only work in tmux 1.2 and above. + +* How can I blank the tmux window? + +GNU screen has a feature whereby it will blank the screen after a period of +inactivity. To do the same thing in tmux, use the lock-command setting, for +example (with GNU bash): + +set -g lock-command 'tput civis && read -s -n1' + +This will remove the cursor and tell the shell to quit once a key has been +pressed. For zsh, use "read -s -k1". + +In addition, it's possible to have both blanking and locking (for instance via +lock(1) or vlock(1)) by using the following: + +bind x set lock-command '/usr/bin/vlock' \; lock-client \; set lock-command 'tput civis && read -s -n1' + +* I don't see italics! Or less and vim show italics and reverse the wrong way round! + +GNU screen does not support italics and the "screen" terminfo description uses +the italics escape sequence incorrectly. + +As of tmux 2.1, if default-terminal is set to "screen" or matches "screen-*", +tmux will behave like screen and italics will be disabled. + +To enable italics, create a new terminfo entry called "tmux" (some platforms +may already have this, you can check with "infocmp tmux"): + + $ cat <<EOF|tic -x - + tmux|tmux terminal multiplexer, + ritm=\E[23m, rmso=\E[27m, sitm=\E[3m, smso=\E[7m, Ms@, + use=xterm+tmux, use=screen, + + tmux-256color|tmux with 256 colors, + use=xterm+256setaf, use=tmux, + EOF + $ + +And tell tmux to use it in ~/.tmux.conf: + + set -g default-terminal "tmux" + +If using urxvt, make sure you have an italics capable font enabled. for +example, add to ~/.Xdefaults: + + urxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true + +* How can I make tmux use my terminal's scrollback buffer? + +Normally, tmux enables the terminal's "alternate screen". Most terminals (such +as xterm) do not save scrollback for the alternate screen. You might prefer +tmux to use the normal screen, so it uses your terminal's scrollback +buffer. This way, you can access the scrollback buffer as usual, for example +using the mouse wheel - although there is no guarantee output inside tmux will +always (or ever) be added to the scrollback. + +You can make tmux use the normal screen by telling it that your terminal does +not have an alternate screen. Put the following in ~/.tmux.conf: + + set -ga terminal-overrides ',xterm*:smcup@:rmcup@' + +Adjust if your $TERM does not start with xterm. + +tmux will still emulate the alternate screen for applications run under tmux, +so you don't really lose anything with this setting. The only disadvantage is +that when you exit tmux, it will not restore whatever was there before you +started. + +* How do I see the default configuration? + +Show the default session options by starting a new tmux server with no +configuration file: + + $ tmux -Lfoo -f/dev/null start\; show -g + +Or the default window options: + + $ tmux -Lfoo -f/dev/null start\; show -gw + +* How do I copy a selection from tmux to the system's clipboard? + +When running in xterm(1), tmux can automatically send copied text to the +clipboard. This is controlled by the set-clipboard option and also needs this +X resource to be set: + + XTerm*disallowedWindowOps: 20,21,SetXprop + +For rxvt-unicode (urxvt), there is an unofficial Perl extension here: + + http://anti.teamidiot.de/static/nei/*/Code/urxvt/ + +Otherwise a key binding for copy mode using xclip (or xsel) works: + + bind -temacs-copy C-y copy-pipe "xclip -i >/dev/null" + +Or for inside and outside copy mode with the prefix key: + + bind C-y run -b "tmux save-buffer - | xclip -i" + +On OS X, reattach-to-usernamespace lets pbcopy/pbpaste work: + + https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard + +* Why do I see dots around a session when I attach to it? + +tmux limits the size of the window to the smallest attached session. If +it didn't do this then it would be impossible to see the entire window. +The dots mark the size of the window tmux can display. + +To avoid this, detach all other clients when attaching: + + $ tmux attach -d + +Or from inside tmux by detaching individual clients with C-b D or all +using: + + C-b : attach -d |