From fb288ef9a758394ed8124f5e2bde6d4e27c18ed1 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott Date: Wed, 7 Jun 2017 11:13:05 +0100 Subject: [PATCH] Remove a bunch of out-of-date stuff from the FAQ or stuff that is documentation for other programs. --- FAQ | 362 ++++++++++-------------------------------------------------- 1 file changed, 57 insertions(+), 305 deletions(-) diff --git a/FAQ b/FAQ index 4a45c140..caa089e3 100644 --- a/FAQ +++ b/FAQ @@ -14,150 +14,68 @@ tmux frequently asked questions * 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 and GNU screen have many similarities and similar goals but now many +differences. Most things that can be achieved one can be achieved in the other, +however. -- 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). +* What is TERM and what does it do? - 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 :-). +The environment variable TERM tells applications the name of a terminal +description to read from the terminfo(5) database. Each description consists of +a number of named capabilities which tell applications what to send to control +the terminal. For example, the "cup" capability contains the escape sequence +used to move the cursor up. - 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. +It is important that TERM points to the correct description for the terminal an +application is running in - if it doesn't, applications may misbehave. -- 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. +The infocmp(1) command shows the contents of a terminal description and the +tic(1) command builds and installs a description from a file (the -x flag is +normally required with both). -- 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? +* I found a bug in tmux! 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. +present. 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. +tmux-users@googlegroups.com or by opening a GitHub issue. Please see the +CONTRIBUTING file for information on what to include. * 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. +* Why do you use the screen terminal description inside tmux? -It is already widely available. It is planned to change to something else such -as xterm-xfree86 at some point, if possible. +It is already widely available. tmux and tmux-256color entries are provided by +modern ncurses and can be used instead by setting the default-terminal option. * I don't see any colour in my terminal! Help! -On some platforms, common terminal descriptions such as xterm do not include +On a few 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! +* tmux freezes my terminal when I attach to a session. I 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): +Some consoles 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 + 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). +inside screen and C-b was chosen not to clash with the screen meta key. -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: +To change it, change the "prefix" 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 @@ -165,120 +83,39 @@ default) to the new key. For example: * 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 requires a system that supports UTF-8 (that is, where the C library has a +UTF-8 locale) and will not start if support is missing. + +tmux will attempt to detect if the terminal it is running in supports UTF-8 by +looking at the LC_ALL, LC_CTYPE and LANG environment variables. + +If it believes the terminal is not compatible with UTF-8, any UTF-8 characters +will be replaced with underscores. The -u flag explicitly tells tmux that the +terminal supports UTF-8: $ 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: +to add one of 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. +Or: -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. + set -g default-terminal "tmux-256color" -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. +And make sure that TERM outside tmux also shows 256 colours, or use the tmux -2 +flag. -* vim or $otherprogram doesn't display 256 colours. What's up? +* How do I make Ctrl-PgUp and Ctrl-PgDn work inside tmux? -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; - } +tmux sends modified function keys using xterm(1)-style escape +sequences. However, many applications don't accept these when TERM is set to +screen or screen-256color inside tmux because these terminal descriptions lack +the capabilities for modified function keys. The tmux and tmux-256color +descriptions do have such capabilities, so using those instead may work. * What is the proper way to escape characters with #(command)? @@ -301,21 +138,13 @@ 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]}' + 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? @@ -324,85 +153,18 @@ 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? +* I don't see italics! Or italics and reverse are the wrong way round! -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 +GNU screen does not support italics and the "screen" terminal 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 <