doc_src/terminal-compatibility.rst
fish writes various control sequences to the terminal. Some must be implemented to enable basic functionality, while others enable optional features and may be ignored by the terminal.
The terminal must be able to parse Control Sequence Introducer (CSI) commands, Operating System Commands (OSC) and :ref:optionally <term-compat-dcs-gnu-screen> Device Control Strings (DCS).
These are defined by ECMA-48.
If a valid CSI, OSC or DCS sequence does not represent a command implemented by the terminal, the terminal must ignore it.
For historical reasons, OSC sequences may be terminated with \x07 instead of \e\\.
Control sequences are denoted in a fish-like syntax.
Special characters other than \ are not escaped.
Spaces are only added for readability and are not part of the sequence.
Placeholders are written as Ps for a number or Pt for an arbitrary printable string.
NOTE: fish does not rely on your system's terminfo database. In this document, terminfo (TI) codes are included for reference only.
.. list-table:: :widths: auto :header-rows: 1
\r\n\e[ Ps A\e[ Ps C\x08\e[ Ps D\e[H\e[K\e[J\e[2J.. _term-compat-primary-da:
\e[0c
Request Primary Device Attribute.
The terminal must respond with a CSI command that starts with the ? parameter byte (so a sequence starting with \e[?) and has c as final byte.
Failure to implement this will cause a brief pause at startup followed by a warning.
For the time being, both can be turned off by turning off the query-terminal :ref:feature flag <featureflags>.
printf %0"$COLUMNS"d 0; sleep 3.. list-table:: :widths: auto :header-rows: 1
\t\e[m\e[1m\e[2m\e[3m\e[4m\e[4:2m\e[4:3m\e[4:4m\e[4:5m\e[7m\e[9m\e[23m\e[24m\e[29m\e[38;5; Ps m\e[48;5; Ps m\e[58:5: Ps m (note: colons not semicolons)\e[ Ps m\e[38;2; Ps ; Ps ; Ps m\e[48;2; Ps ; Ps ; Ps m\e[39m\e[49m\e[58:2:: Ps : Ps : Ps m (note: colons not semicolons)\e[59m.. _term-compat-indn:
\e[ Ps S
indn
Scroll up the content (not the viewport) Ps lines (called SCROLL UP / SU by ECMA-48 and "scroll forward" by terminfo).
When fish detects support for this feature, :ref:status test-terminal-features scroll-content-up <status-test-terminal-features> will return 0,
which enables the :kbd:ctrl-l binding to use the :ref:scrollback-push <special-input-functions-scrollback-push> special input function.
\e[= Ps u, \e[? Ps u.. _term-compat-cursor-position-report:
\e[6n
n/a
Request cursor position report.
The response must be of the form \e[ Ps ; Ps R
where the first parameter is the row number
and the second parameter is the column number.
Both start at 1.
This is used for truncating multiline autosuggestions at the screen's bottom edge,
by the :ref:scrollback-push <special-input-functions-scrollback-push> special input function,
and inside terminals that implement the OSC 133 :ref:click_events <term-compat-osc-133> feature.
\e[ \x20 q\e[ Ps \x20 q.. _term-compat-xtversion:
\e[ Ps q
n/a
Request terminal name and version (XTVERSION). This is only used for temporary workarounds for incompatible terminals.
\e[?25h\e[?1004h\e[?1004l\e[?1049h\e[?1049l\e[?2004h\e[?2004l\e[?2031hcolor theme reporting <https://contour-terminal.org/vt-extensions/color-palette-update-notifications/>_.
When enabled, the terminal should send \e[?997;1n or \e[?997;2n whenever its color theme has changed.
This prompts fish to query for :ref:background color <term-compat-query-background-color>.\e[?2031l.. _term-compat-osc-0:
\e]0; Pt \e\\
ts
Set terminal window title (OSC 0). Used in :doc:fish_title <cmds/fish_title>.
\e]2; Pt \e\\fish_tab_title <cmds/fish_tab_title>.\e]7;file:// Pt / Pt \e\\localhost... _term-compat-osc-8:
\e]8;; Pt \e\\
Create a hyperlink (OSC 8) <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>_.
This is used in fish's man pages.
.. _term-compat-query-background-color:
\e]11;?\e\\
n/a
Query background color.
A valid response would be of the form \e]11;rgb: Pt / Pt / Pt \e\\ or \e]11;rgba: Pt / Pt / Pt / Pt\e\\
where the first three parameters consist of one to four hex digits each, representing red, blue and green components.
This is used to populate :envvar:fish_terminal_color_theme,
which is used to select a :ref:theme variant <fish-config-theme-files> optimized for the terminal's color theme.
.. _term-compat-osc-52:
\e]52;c; Pt \e\\
Copy to clipboard (OSC 52). Used by :doc:fish_clipboard_copy <cmds/fish_clipboard_copy>.
.. _term-compat-osc-133:
\e]133;A; click_events=1\e\\
Mark prompt start (OSC 133), with kitty's click_events extension.
The click_events extension enables mouse clicks to move the cursor or select pager items,
assuming that :ref:cursor position reporting <term-compat-cursor-position-report> is available.
\e]133;B\e\\\e]133;C; cmdline_url= Pt \e\\cmdline_url extension whose parameter is the URL-encoded command line.\e]133;D; Ps \e\\.. _term-compat-xtgettcap:
\eP+q Pt \e\\
Request terminfo capability (XTGETTCAP). The parameter is the capability's hex-encoded terminfo code.
The response must be of the form
\eP1+q Pt \e\\ ("boolean") or \eP1+q Pt = Pt \e\\ ("string").
In either variant, the first parameter must be the same as the request parameter.
fish queries the following string capabilities:
:ref:indn <term-compat-indn>
The response's second parameter is ignored.
query-os-name (for :ref:status terminal-os <status-terminal-os>)
Terminals running on Unix should respond with the hex encoding of $(uname -s) as second parameter.
.. _term-compat-dcs-gnu-screen:
DCS parsing is optional because fish temporarily switches to the alternate screen before printing any DCS commands.
However, since GNU screen neither allows turning on the alternate screen buffer by default,
nor treats DCS commands in a compatible way,
fish's initial prompt may be garbled by a DCS payload like +q696e646e.
For the time being, fish works around this by checking for presence of the :envvar:STY environment variable.
If that doesn't work for some reason, you can add this to your ~/.screenrc:
.. code-block:: none
altscreen on
Or add this to your config.fish::
function GNU-screen-workaround --on-event fish_prompt
commandline -f repaint
functions --erase GNU-screen-workaround
end
.. _term-compat-unicode-codepoints:
By default, fish outputs the following non-ASCII characters::
× ► ¶ ⏎ • ● … μ – ’ ‘ “ ” ← → ↑ ↓
as well as control pictures (U+2400 through U+241F),
and locale-specific ones in :ref:translated strings <variables-locale>.