diff options
Diffstat (limited to 'FAQ')
| -rw-r--r-- | FAQ | 445 |
1 files changed, 445 insertions, 0 deletions
@@ -0,0 +1,445 @@ +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. + +- screen has support for updating utmp. Nobody has really come up with a clean, + portable way to do this without making tmux setuid or setgid yet. + +- 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? + +Please send bug reports by email to nicm@users.sourceforge.net or +tmux-users@lists.sourceforge.net. 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 nicm@users.sourceforge.net. + +* 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. + +* 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' + +* How can I open a new window in the same directory as the current window? + +One option is to just run "TMUX= tmux" in the window. However, this only works if no +command is running, so that you can input the command. + +A workaround is to let tmux know about the current path through an environment +variable. To do so, use the following command: + + [ -n "$TMUX" ] && tmux setenv TMUXPWD_$(tmux display -p "#I") $PWD + +Which sets TMUXPWD_i (where i is the number of the current window) to the path +of the current directory. This command can be added to PS1, for example: + + PS1='$([ -n "$TMUX" ] && tmux setenv TMUXPWD_$(tmux display -p "#I") $PWD)\h$ ' + +When a new window is created, the shell should be asked to change +directory. You can define a new binding (for example, if using GNU bash): + + bind-key C-c run-shell 'tmux neww "cd $(tmux display -p "\$TMUXPWD_#I"); exec bash"' + +This solution will work even if a command is currently running in the terminal, +but it will not work from a window that has just been swapped with another +because TMUXPWD_i will not be updated after a swap. However, once a new prompt +is displayed, TMUXPWD_i is updated properly. + +* tmux doesn't start with "daemon failed" + +tmux shows something similar to this when started: + + fatal: server_start: daemon failed: No such file or directory + fatal: main_dispatch: imsg_read failed + +A possible reason is that /dev/null is not a character device or is otherwise +inaccessible. + +Check with: + + file /dev/null + ls -l /dev/null + +If it is not a character device or has incorrect permissions, it can typically +be recreated with: + + cd /dev && rm null && ./MAKEDEV null + +* vim displays reverse video instead of italics, while less displays italics + (or just regular text) instead of reverse. What's wrong? + +Screen's terminfo description lacks italics mode and has standout mode in its +place, but using the same escape sequence that urxvt uses for italics. This +means applications (like vim) looking for italics will not find it and might +turn to reverse in its place, while applications (like less) asking for +standout will end up with italics instead of reverse. To make applications +aware that tmux supports italics and to use a proper escape sequence for +standout, you'll need to create a new terminfo file with modified sgr, smso, +rmso, sitm and ritm entries: + + $ mkdir $HOME/.terminfo/ + $ screen_terminfo="screen" + $ infocmp "$screen_terminfo" | sed \ + -e 's/^screen[^|]*|[^,]*,/screen-it|screen with italics support,/' \ + -e 's/%?%p1%t;3%/%?%p1%t;7%/' \ + -e 's/smso=[^,]*,/smso=\\E[7m,/' \ + -e 's/rmso=[^,]*,/rmso=\\E[27m,/' \ + -e '$s/$/ sitm=\\E[3m, ritm=\\E[23m,/' > /tmp/screen.terminfo + $ tic /tmp/screen.terminfo + +And tell tmux to use it in ~/.tmux.conf: + + set -g default-terminal "screen-it" + +If your terminal supports 256 colors, use: + + $ screen_terminfo="screen-256color" + +instead of "screen". See the FAQ entry about 256 colors support for more info. +Also note that tmux will still display reverse video on terminals that do not +support italics. + +If your urxvt cannot display italics at all, 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 -g 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 + +$Id$ |