<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>doc_src/language.rst - fork/fish-shell @ master</title>
<meta name="description" content="doc_src/language.rst in fork/fish-shell at master.">
<meta property="og:title" content="doc_src/language.rst - fork/fish-shell @ master">
<meta property="og:description" content="doc_src/language.rst in fork/fish-shell at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="605c466379a074cf1b5cdb2b62bc8071aab8b47b">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/fish-shell</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/fish-shell</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Johannes Altmanninger</span><span class="commit-message" data-commit="2b1684a9bff92146c5e313b21280a67ca651dcbd">docs wildcards: mention that wildcards never expand to &quot;.&quot; or &quot;..&quot;</span><span class="snapshot-sha sha" data-commit="2b1684a9bff92146c5e313b21280a67ca651dcbd">2b1684a9b</span><time datetime="2026-07-04T12:30:05+02:00" title="2026-07-04 12:30:05 +0200">2026-07-04</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/fish-shell/ref/master/">master</a><a class="all" href="/fork/fish-shell/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/fish-shell/">fish-shell</a> / <a href="/fork/fish-shell/ref/master/tree/doc_src/">doc_src</a> / <span class="cur">language.rst</span></nav>
<span class="view-stats"><span>106.0 KiB</span><span>2177 lines</span></span><span class="actions"><a class="raw" href="/fork/fish-shell/raw/999c26d829ce220e17209a88f9d724103b1ffeeb/doc_src/language.rst">raw</a></span></header>
<pre class="code src"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text">The fish language</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text">=================</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">This document is a comprehensive overview of fish's scripting language.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">For interactive features see :doc:`Interactive use &lt;interactive&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">.. _syntax:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">Syntax overview</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">---------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">Shells like fish are used by giving them commands. A command is executed by writing the name of the command followed by any arguments. For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">    echo hello world</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">:doc:`echo &lt;cmds/echo&gt;` command writes its arguments to the screen. In this example the output is ``hello world``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">Everything in fish is done with commands. There are commands for repeating other commands, commands for assigning variables, commands for treating a group of commands as a single command, etc. All of these commands follow the same basic syntax.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">Every program on your computer can be used as a command in fish. If the program file is located in one of the :envvar:`PATH` directories, you can just type the name of the program to use it. Otherwise the whole filename, including the directory (like ``/home/me/code/checkers/checkers`` or ``../checkers``) is required.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">Here is a list of some useful commands:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">- :doc:`cd &lt;cmds/cd&gt;`: Change the current directory</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text">- ``ls``: List files and directories</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">- ``man``: Display a manual page - try ``man ls`` to get help on your &quot;ls&quot; command, or ``man mv`` to get information about &quot;mv&quot;.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">- ``mv``: Move (rename) files</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">- ``cp``: Copy files</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">- :doc:`open &lt;cmds/open&gt;`: Open files with the default application associated with each filetype</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">- ``less``: Display the contents of files</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">Commands and arguments are separated by the space character ``' '``. Every command ends with either a newline (by pressing the return key) or a semicolon ``;``. Multiple commands can be written on the same line by separating them with semicolons.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text">A switch is a very common special type of argument. Switches almost always start with one or more hyphens ``-`` and alter the way a command operates. For example, the ``ls`` command usually lists the names of all files and directories in the current working directory. By using the ``-l`` switch, the behavior of ``ls`` is changed to not only display the filename, but also the size, permissions, owner, and modification time of each file.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text">Switches differ between commands and are usually documented on a command's manual page. There are some switches, however, that are common to most commands. For example, ``--help`` will usually display a help text, ``--version`` will usually display the command version, and ``-i`` will often turn on interactive prompting before taking action. Try ``man your-command-here`` to get information on your command's switches.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text">So the basic idea of fish is the same as with other unix shells: It gets a commandline, runs :ref:`expansions &lt;expand&gt;`, and the result is then run as a command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text">Terminology</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text">-----------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text">Here we define some of the terms used on this page and throughout the rest of the fish documentation:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text">- **Argument**: A parameter given to a command. In ``echo foo``, the &quot;foo&quot; is an argument.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">- **Builtin**: A command that is implemented by the shell. Builtins are so closely tied to the operation of the shell that it is impossible to implement them as external commands. In ``echo foo``, the &quot;echo&quot; is a builtin.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text">- **Command**: A program that the shell can run, or more specifically an external program that the shell runs in another process. External commands are provided on your system, as executable files. In ``echo foo`` the &quot;echo&quot; is a builtin command, in ``command echo foo`` the &quot;echo&quot; is an external command, provided by a file like /bin/echo.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text">- **Function**: A block of commands that can be called as if they were a single command. By using functions, it is possible to string together multiple simple commands into one more advanced command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text">- **Job**: A running pipeline or command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">- **Pipeline**: A set of commands strung together so that the output of one command is the input of the next command. ``echo foo | grep foo`` is a pipeline.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text">- **Redirection**: An operation that changes one of the input or output streams associated with a job.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text">- **Switch** or **Option**: A special kind of argument that alters the behavior of a command. A switch almost always begins with one or two hyphens. In ``echo -n foo`` the &quot;-n&quot; is an option.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text">.. _quotes:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text">Quotes</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text">------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text">Sometimes you want to give a command an argument that contains characters special to fish, like spaces or ``$`` or ``*``. To do that, you can use quotes::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text">    rm &quot;my file.txt&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text">to remove a file called ``my file.txt`` instead of trying to remove two files, ``my`` and ``file.txt``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text">fish understands two kinds of quotes: Single (``'``) and double (``&quot;``), and both work slightly differently.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text">Between single quotes, fish performs no expansions. Between double quotes, fish only performs :ref:`variable expansion &lt;expand-variable&gt;` and :ref:`command substitution &lt;expand-command-substitution&gt;` in the ``$(command)``. No other kind of expansion (including :ref:`brace expansion &lt;expand-brace&gt;` or parameter expansion) is performed, and escape sequences (for example, ``\n``) are ignored. Within quotes, whitespace is not used to separate arguments, allowing quoted arguments to contain spaces.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text">The only meaningful escape sequences in single quotes are ``\'``, which escapes a single quote and ``\\``, which escapes the backslash symbol. The only meaningful escapes in double quotes are ``\&quot;``, which escapes a double quote, ``\$``, which escapes a dollar character, ``\`` followed by a newline, which deletes the backslash and the newline, and ``\\``, which escapes the backslash symbol.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text">Single quotes have no special meaning within double quotes and vice versa.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text">More examples::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text">    grep 'enabled)$' foo.txt</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text">searches for lines ending in ``enabled)`` in ``foo.txt`` (the ``$`` is special to ``grep``: it matches the end of the line).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text">::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text">    apt install &quot;postgres-*&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text">installs all packages with a name starting with &quot;postgres-&quot;, instead of looking through the current directory for files named &quot;postgres-something&quot;.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text">.. _escapes:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text">Escaping Characters</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text">-------------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text">Some characters cannot be written directly on the command line. For these characters, so-called escape sequences are provided. These are:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text">- ``\a`` represents the alert character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text">- ``\e`` represents the escape character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text">- ``\f`` represents the form feed character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text">- ``\n`` represents a newline character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text">- ``\r`` represents the carriage return character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text">- ``\t`` represents the tab character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text">- ``\v`` represents the vertical tab character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text">- ``\xHH`` or ``\XHH``, where ``HH`` is a hexadecimal number, represents a byte of data with the specified value. For example, ``\x9`` is the tab character. If you are using a multibyte encoding, this can be used to enter invalid strings. Typically fish is run with the ASCII or UTF-8 encoding, so anything up to ``\X7f`` is an ASCII character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text">- ``\ooo``, where ``ooo`` is an octal number, represents the ASCII character with the specified value. For example, ``\011`` is the tab character. The highest allowed value is ``\177``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text">- ``\uXXXX``, where ``XXXX`` is a hexadecimal number, represents the 16-bit Unicode character with the specified value. For example, ``\u9`` is the tab character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text">- ``\UXXXXXXXX``, where ``XXXXXXXX`` is a hexadecimal number, represents the 32-bit Unicode character with the specified value. For example, ``\U9`` is the tab character. The highest allowed value is \U10FFFF.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text">- ``\cX``, where ``X`` is a letter of the alphabet, represents the control sequence generated by pressing the control key and the specified letter. For example, ``\ci`` is the tab character</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text">Some characters have special meaning to the shell. For example, an apostrophe ``'`` disables expansion (see :ref:`Quotes&lt;quotes&gt;`). To tell the shell to treat these characters literally, escape them with a backslash. For example, the command::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text">    echo \'hello world\'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text">outputs ``'hello world'`` (including the apostrophes), while the command::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text">    echo 'hello world'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text">outputs ``hello world`` (without the apostrophes). In the former case the shell treats the apostrophes as literal ``'`` characters, while in the latter case it treats them as special expansion modifiers.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text">The special characters and their escape sequences are:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text">.. (next line features a non-breaking space - this will be rendered to a normal space instead of removed)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text">- :code:`\\\ ` (backslash space) escapes the space character. This keeps the shell from splitting arguments on the escaped space.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text">- ``\$`` escapes the dollar character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text">- ``\\`` escapes the backslash character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text">- ``\*`` escapes the star character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text">- ``\?`` escapes the question mark character (this is not necessary if the ``qmark-noglob`` :ref:`feature flag&lt;featureflags&gt;` is enabled).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text">- ``\~`` escapes the tilde character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text">- ``\#`` escapes the hash character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text">- ``\(`` escapes the left parenthesis character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text">- ``\)`` escapes the right parenthesis character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text">- ``\{`` escapes the left curly bracket character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text">- ``\}`` escapes the right curly bracket character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text">- ``\[`` escapes the left bracket character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text">- ``\]`` escapes the right bracket character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text">- ``\&lt;`` escapes the less than character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text">- ``\&gt;`` escapes the more than character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text">- ``\&amp;`` escapes the ampersand character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text">- ``\|`` escapes the vertical bar character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text">- ``\;`` escapes the semicolon character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text">- ``\&quot;`` escapes the quote character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text">- ``\'`` escapes the apostrophe character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text">As a special case, ``\`` immediately followed by a literal new line is a &quot;continuation&quot; and tells fish to ignore the line break and resume input at the start of the next line (without introducing any whitespace or terminating a token).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text">.. _redirects:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text">Input/Output Redirection</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text">-----------------------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text">Most programs use three input/output (I/O) streams:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text">- Standard input (stdin) for reading. Defaults to reading from the keyboard.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text">- Standard output (stdout) for writing output. Defaults to writing to the screen.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text">- Standard error (stderr) for writing errors and warnings. Defaults to writing to the screen.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text">Each stream has a number called the file descriptor (FD): 0 for stdin, 1 for stdout, and 2 for stderr.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text">The destination of a stream can be changed using something called *redirection*. For example, ``echo hello &gt; output.txt``, redirects the standard output of the ``echo`` command to a text file.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text">- To read standard input from a file, use ``&lt;SOURCE_FILE``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text">- To read standard input from a file or /dev/null if it can't be read, use ``&lt;?SOURCE_FILE``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text">- To write standard output to a file, use ``&gt;DESTINATION``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text">- To write standard error to a file, use ``2&gt;DESTINATION``. [#]_</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text">- To append standard output to a file, use ``&gt;&gt;DESTINATION_FILE``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text">- To append standard error to a file, use ``2&gt;&gt;DESTINATION_FILE``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text">- To not overwrite (&quot;clobber&quot;) an existing file, use ``&gt;?DESTINATION`` or ``2&gt;?DESTINATION``. This is known as the &quot;noclobber&quot; redirection.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text">``DESTINATION`` can be one of the following:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text">- A filename to write the output to. Often ``&gt;/dev/null`` to silence output by writing it to the special &quot;sinkhole&quot; file.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text">- An ampersand (``&amp;``) followed by the number of another file descriptor like ``&amp;2`` for standard error. The output will be written to the destination descriptor.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text">- An ampersand followed by a minus sign (``&amp;-``). The file descriptor will be closed. Note: This may cause the program to fail because its writes will be unsuccessful.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text">As a convenience, the redirection ``&amp;&gt;`` can be used to direct both stdout and stderr to the same destination. For example, ``echo hello &amp;&gt; all_output.txt`` redirects both stdout and stderr to the file ``all_output.txt``. This is equivalent to ``echo hello &gt; all_output.txt 2&gt;&amp;1``.  You can also use ``&amp;&gt;&gt;`` to append both stdout and stderr to the same destination.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text">Any arbitrary file descriptor can be used in a redirection by prefixing the redirection with the FD number.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text">- To redirect the input of descriptor N, use ``N&lt;DESTINATION``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text">- To redirect the output of descriptor N, use ``N&gt;DESTINATION``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text">- To append the output of descriptor N to a file, use ``N&gt;&gt;DESTINATION_FILE``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text">File descriptors cannot be used with a ``&lt;?`` input redirection, only a regular ``&lt;`` one.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text">For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text">  # Write `foo`'s standard error (file descriptor 2)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text">  # to a file called &quot;output.stderr&quot;:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L193" href="#L193">193</a><span class="code-text">  foo 2&gt; output.stderr</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L194" href="#L194">194</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L195" href="#L195">195</a><span class="code-text">  # if $num doesn't contain a number,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L196" href="#L196">196</a><span class="code-text">  # this test will be false and print an error,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L197" href="#L197">197</a><span class="code-text">  # so by ignoring the error we can be sure that we're dealing</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L198" href="#L198">198</a><span class="code-text">  # with a number in the &quot;if&quot; block:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L199" href="#L199">199</a><span class="code-text">  if test &quot;$num&quot; -gt 2 2&gt;/dev/null</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L200" href="#L200">200</a><span class="code-text">      # do things with $num as a number greater than 2</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L201" href="#L201">201</a><span class="code-text">  else</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L202" href="#L202">202</a><span class="code-text">      # do things if $num is &lt;= 2 or not a number</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L204" href="#L204">204</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text">  # Save `make`s output in a file:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L206" href="#L206">206</a><span class="code-text">  make &amp;&gt;/log</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L207" href="#L207">207</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L208" href="#L208">208</a><span class="code-text">  # Redirections stack and can be used with blocks:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L209" href="#L209">209</a><span class="code-text">  begin</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L210" href="#L210">210</a><span class="code-text">      echo stdout</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L211" href="#L211">211</a><span class="code-text">      echo stderr &gt;&amp;2 # &lt;- this goes to stderr!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L212" href="#L212">212</a><span class="code-text">  end &gt;/dev/null # ignore stdout, so this prints &quot;stderr&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L213" href="#L213">213</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L214" href="#L214">214</a><span class="code-text">  # print all lines that include &quot;foo&quot; from myfile, or nothing if it doesn't exist.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L215" href="#L215">215</a><span class="code-text">  string match '*foo*' &lt;?myfile</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L216" href="#L216">216</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L217" href="#L217">217</a><span class="code-text">It is an error to redirect a builtin, function, or block to a file descriptor above 2. However this is supported for external commands.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L218" href="#L218">218</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L219" href="#L219">219</a><span class="code-text">.. [#] Previous versions of fish also allowed specifying this as ``^DESTINATION``, but that made another character special so it was deprecated and removed. See :ref:`feature flags&lt;featureflags&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L220" href="#L220">220</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L221" href="#L221">221</a><span class="code-text">.. _pipes:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L222" href="#L222">222</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L223" href="#L223">223</a><span class="code-text">Piping</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L224" href="#L224">224</a><span class="code-text">------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L225" href="#L225">225</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L226" href="#L226">226</a><span class="code-text">Another way to redirect streams is a *pipe*. A pipe connects streams with each other. Usually the standard output of one command is connected with the standard input of another. This is done by separating commands with the pipe character ``|``. For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L227" href="#L227">227</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L228" href="#L228">228</a><span class="code-text">    cat foo.txt | head</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L229" href="#L229">229</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L230" href="#L230">230</a><span class="code-text">The command ``cat foo.txt`` sends the contents of ``foo.txt`` to stdout. This output is provided as input for the ``head`` program, which prints the first 10 lines of its input.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L231" href="#L231">231</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L232" href="#L232">232</a><span class="code-text">It is possible to pipe a different output file descriptor by prepending its FD number and the output redirect symbol to the pipe. For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L233" href="#L233">233</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L234" href="#L234">234</a><span class="code-text">    make fish 2&gt;| less</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L235" href="#L235">235</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L236" href="#L236">236</a><span class="code-text">will attempt to build ``fish``, and any errors will be shown using the ``less`` pager. [#]_</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L237" href="#L237">237</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L238" href="#L238">238</a><span class="code-text">As a convenience, the pipe ``&amp;|`` (as well as the ``|&amp;`` alias which is also supported by Bash) both redirect stdout and stderr to the same process.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L239" href="#L239">239</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L240" href="#L240">240</a><span class="code-text">.. [#] A &quot;pager&quot; here is a program that takes output and &quot;paginates&quot; it. ``less`` doesn't just do pages, it allows arbitrary scrolling (even back!).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L241" href="#L241">241</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L242" href="#L242">242</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L243" href="#L243">243</a><span class="code-text">Combining pipes and redirections</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L244" href="#L244">244</a><span class="code-text">--------------------------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L245" href="#L245">245</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L246" href="#L246">246</a><span class="code-text">It is possible to use multiple redirections and a pipe at the same time. In that case, they are read in this order:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L247" href="#L247">247</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L248" href="#L248">248</a><span class="code-text">1. First the pipe is set up.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L249" href="#L249">249</a><span class="code-text">2. Then the redirections are evaluated from left-to-right.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L250" href="#L250">250</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L251" href="#L251">251</a><span class="code-text">This is important when any redirections reference other file descriptors with the ``&amp;N`` syntax. When you say ``&gt;&amp;2``, that will redirect stdout to where stderr is pointing to *at that time*.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L252" href="#L252">252</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L253" href="#L253">253</a><span class="code-text">Consider this helper function::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L254" href="#L254">254</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L255" href="#L255">255</a><span class="code-text">  # Make a function that prints something to stdout and stderr</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L256" href="#L256">256</a><span class="code-text">  function print</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L257" href="#L257">257</a><span class="code-text">      echo out</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L258" href="#L258">258</a><span class="code-text">      echo err &gt;&amp;2</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L259" href="#L259">259</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L260" href="#L260">260</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L261" href="#L261">261</a><span class="code-text">Now let's see a few cases::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L262" href="#L262">262</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L263" href="#L263">263</a><span class="code-text">  # Redirect both stderr and stdout to less</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L264" href="#L264">264</a><span class="code-text">  print 2&gt;&amp;1 | less</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L265" href="#L265">265</a><span class="code-text">  # or</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L266" href="#L266">266</a><span class="code-text">  print &amp;| less</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L267" href="#L267">267</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L268" href="#L268">268</a><span class="code-text">  # Show the &quot;out&quot; on stderr, silence the &quot;err&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L269" href="#L269">269</a><span class="code-text">  print &gt;&amp;2 2&gt;/dev/null</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L270" href="#L270">270</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L271" href="#L271">271</a><span class="code-text">  # Silence both</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L272" href="#L272">272</a><span class="code-text">  print &gt;/dev/null 2&gt;&amp;1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L273" href="#L273">273</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L274" href="#L274">274</a><span class="code-text">.. _syntax-job-control:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L275" href="#L275">275</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L276" href="#L276">276</a><span class="code-text">Job control</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L277" href="#L277">277</a><span class="code-text">-----------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L278" href="#L278">278</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L279" href="#L279">279</a><span class="code-text">When you start a job in fish, fish itself will pause, and give control of the terminal to the program it just started. Sometimes, you want to continue using the commandline, and have the job run in the background. To create a background job, append an ``&amp;`` (ampersand) to your command. This will tell fish to run the job in the background. Background jobs are very useful when running programs that have a graphical user interface.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L280" href="#L280">280</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L281" href="#L281">281</a><span class="code-text">Example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L282" href="#L282">282</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L283" href="#L283">283</a><span class="code-text">  emacs &amp;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L284" href="#L284">284</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L285" href="#L285">285</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L286" href="#L286">286</a><span class="code-text">will start the emacs text editor in the background. :doc:`fg &lt;cmds/fg&gt;` can be used to bring it into the foreground again when needed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L287" href="#L287">287</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L288" href="#L288">288</a><span class="code-text">Most programs allow you to suspend the program's execution and return control to fish by pressing :kbd:`ctrl-z` (also referred to as ``^Z``). Once back at the fish commandline, you can start other programs and do anything you want. If you then want you can go back to the suspended command by using the :doc:`fg &lt;cmds/fg&gt;` (foreground) command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L289" href="#L289">289</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L290" href="#L290">290</a><span class="code-text">If you instead want to put a suspended job into the background, use the :doc:`bg &lt;cmds/bg&gt;` command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L291" href="#L291">291</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L292" href="#L292">292</a><span class="code-text">To get a listing of all currently started jobs, use the :doc:`jobs &lt;cmds/jobs&gt;` command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L293" href="#L293">293</a><span class="code-text">These listed jobs can be removed with the :doc:`disown &lt;cmds/disown&gt;` command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L294" href="#L294">294</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L295" href="#L295">295</a><span class="code-text">At the moment, functions cannot be started in the background. Functions that are stopped and then restarted in the background using the :doc:`bg &lt;cmds/bg&gt;` command will not execute correctly.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L296" href="#L296">296</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L297" href="#L297">297</a><span class="code-text">If the ``&amp;`` character is followed by a non-separating character, it is not interpreted as background operator. Separating characters are whitespace and the characters ``;&lt;&gt;&amp;|``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L298" href="#L298">298</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L299" href="#L299">299</a><span class="code-text">.. _syntax-function:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L300" href="#L300">300</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L301" href="#L301">301</a><span class="code-text">Functions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L302" href="#L302">302</a><span class="code-text">---------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L303" href="#L303">303</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L304" href="#L304">304</a><span class="code-text">Functions are programs written in the fish syntax. They group together various commands and their arguments using a single name.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L305" href="#L305">305</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L306" href="#L306">306</a><span class="code-text">For example, here's a simple function to list directories::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L307" href="#L307">307</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L308" href="#L308">308</a><span class="code-text">  function ll</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L309" href="#L309">309</a><span class="code-text">      ls -l $argv</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L310" href="#L310">310</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L311" href="#L311">311</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L312" href="#L312">312</a><span class="code-text">The first line tells fish to define a function by the name of ``ll``, so it can be used by writing ``ll`` on the commandline. The second line tells fish that the command ``ls -l $argv`` should be called when ``ll`` is invoked. :ref:`$argv &lt;variables-argv&gt;` is a :ref:`list variable &lt;variables-lists&gt;`, which always contains all arguments sent to the function. In the example above, these are passed on to the ``ls`` command. The ``end`` on the third line ends the definition.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L313" href="#L313">313</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L314" href="#L314">314</a><span class="code-text">Calling this as ``ll /tmp/`` will end up running ``ls -l /tmp/``, which will list the contents of /tmp.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L315" href="#L315">315</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L316" href="#L316">316</a><span class="code-text">This is a kind of function known as an :ref:`alias &lt;syntax-aliases&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L317" href="#L317">317</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L318" href="#L318">318</a><span class="code-text">fish's prompt is also defined in a function, called :doc:`fish_prompt &lt;cmds/fish_prompt&gt;`. It is run when the prompt is about to be displayed and its output forms the prompt::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L319" href="#L319">319</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L320" href="#L320">320</a><span class="code-text">  function fish_prompt</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L321" href="#L321">321</a><span class="code-text">      # A simple prompt. Displays the current directory</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L322" href="#L322">322</a><span class="code-text">      # (which fish stores in the $PWD variable)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L323" href="#L323">323</a><span class="code-text">      # and then a user symbol - a '►' for a normal user and a '#' for root.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L324" href="#L324">324</a><span class="code-text">      set -l user_char '►'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L325" href="#L325">325</a><span class="code-text">      if fish_is_root_user</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L326" href="#L326">326</a><span class="code-text">          set user_char '#'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L327" href="#L327">327</a><span class="code-text">      end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L328" href="#L328">328</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L329" href="#L329">329</a><span class="code-text">      echo (set_color yellow)$PWD (set_color purple)$user_char</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L330" href="#L330">330</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L331" href="#L331">331</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L332" href="#L332">332</a><span class="code-text">To edit a function, you can use :doc:`funced &lt;cmds/funced&gt;`, and to save a function :doc:`funcsave &lt;cmds/funcsave&gt;`. This will store it in a function file that fish will :ref:`autoload &lt;syntax-function-autoloading&gt;` when needed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L333" href="#L333">333</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L334" href="#L334">334</a><span class="code-text">The :doc:`functions &lt;cmds/functions&gt;` builtin can show a function's current definition (and :doc:`type &lt;cmds/type&gt;` will also do if given a function).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L335" href="#L335">335</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L336" href="#L336">336</a><span class="code-text">For more information on functions, see the documentation for the :doc:`function &lt;cmds/function&gt;` builtin.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L337" href="#L337">337</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L338" href="#L338">338</a><span class="code-text">.. _syntax-aliases:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L339" href="#L339">339</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L340" href="#L340">340</a><span class="code-text">Defining aliases</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L341" href="#L341">341</a><span class="code-text">^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L342" href="#L342">342</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L343" href="#L343">343</a><span class="code-text">One of the most common uses for functions is to slightly alter the behavior of an already existing command. For example, one might want to redefine the ``ls`` command to display colors. The switch for turning on colors on GNU systems is ``--color=auto``. An alias around ``ls`` might look like this::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L344" href="#L344">344</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L345" href="#L345">345</a><span class="code-text">  function ls</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L346" href="#L346">346</a><span class="code-text">      command ls --color=auto $argv</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L347" href="#L347">347</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L348" href="#L348">348</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L349" href="#L349">349</a><span class="code-text">There are a few important things that need to be noted about aliases:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L350" href="#L350">350</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L351" href="#L351">351</a><span class="code-text">- Always take care to add the :ref:`$argv &lt;variables-argv&gt;` variable to the list of parameters to the wrapped command. This makes sure that if the user specifies any additional parameters to the function, they are passed on to the underlying command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L352" href="#L352">352</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L353" href="#L353">353</a><span class="code-text">- If the alias has the same name as the aliased command, you need to prefix the call to the program with ``command`` to tell fish that the function should not call itself, but rather a command with the same name. If you forget to do so, the function would call itself until the end of time. Usually fish is smart enough to figure this out and will refrain from doing so (which is hopefully in your interest).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L354" href="#L354">354</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L355" href="#L355">355</a><span class="code-text">To easily create a function of this form, you can use the :doc:`alias &lt;cmds/alias&gt;` command. Unlike other shells, this just makes functions - fish has no separate concept of an &quot;alias&quot;, we just use the word for a simple wrapping function like this. :doc:`alias &lt;cmds/alias&gt;` immediately creates a function. Consider using ``alias --save`` or :doc:`funcsave &lt;cmds/funcsave&gt;` to save the created function into an autoload file instead of recreating the alias each time.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L356" href="#L356">356</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L357" href="#L357">357</a><span class="code-text">For an alternative, try :ref:`abbreviations &lt;abbreviations&gt;`. These are words that are expanded while you type, instead of being actual functions inside the shell.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L358" href="#L358">358</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L359" href="#L359">359</a><span class="code-text">.. _syntax-function-autoloading:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L360" href="#L360">360</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L361" href="#L361">361</a><span class="code-text">Autoloading functions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L362" href="#L362">362</a><span class="code-text">^^^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L363" href="#L363">363</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L364" href="#L364">364</a><span class="code-text">Functions can be defined on the commandline or in a configuration file, but they can also be automatically loaded. This has some advantages:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L365" href="#L365">365</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L366" href="#L366">366</a><span class="code-text">- An autoloaded function becomes available automatically to all running shells.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L367" href="#L367">367</a><span class="code-text">- If the function definition is changed, all running shells will automatically reload the altered version, after a while.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L368" href="#L368">368</a><span class="code-text">- Startup time and memory usage is improved, etc.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L369" href="#L369">369</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L370" href="#L370">370</a><span class="code-text">When fish needs to load a function, it searches through any directories in the :ref:`list variable &lt;variables-lists&gt;` ``$fish_function_path`` for a file with a name consisting of the name of the function plus the suffix ``.fish`` and loads the first it finds.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L371" href="#L371">371</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L372" href="#L372">372</a><span class="code-text">For example if you try to execute something called ``banana``, fish will go through all directories in $fish_function_path looking for a file called ``banana.fish`` and load the first one it finds.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L373" href="#L373">373</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L374" href="#L374">374</a><span class="code-text">By default ``$fish_function_path`` contains the following:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L375" href="#L375">375</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L376" href="#L376">376</a><span class="code-text">- A directory for users to keep their own functions, usually ``~/.config/fish/functions`` (controlled by the ``XDG_CONFIG_HOME`` environment variable).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L377" href="#L377">377</a><span class="code-text">- A directory for functions for all users on the system, usually ``/etc/fish/functions`` (really ``$__fish_sysconfdir/functions``).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L378" href="#L378">378</a><span class="code-text">- Directories for other software to put their own functions. These are in the directories under ``$__fish_user_data_dir`` (usually ``~/.local/share/fish``, controlled by the ``XDG_DATA_HOME`` environment variable) and in the ``XDG_DATA_DIRS`` environment variable, in a subdirectory called ``fish/vendor_functions.d``. The default value for ``XDG_DATA_DIRS`` is usually ``/usr/share/fish/vendor_functions.d`` and ``/usr/local/share/fish/vendor_functions.d``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L379" href="#L379">379</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L380" href="#L380">380</a><span class="code-text">If you are unsure, your functions probably belong in ``~/.config/fish/functions``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L381" href="#L381">381</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L382" href="#L382">382</a><span class="code-text">As we've explained, autoload files are loaded *by name*, so, while you can put multiple functions into one file, the file will only be loaded automatically once you try to execute the one that shares the name.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L383" href="#L383">383</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L384" href="#L384">384</a><span class="code-text">Autoloading also won't work for :ref:`event handlers &lt;event&gt;`, since fish cannot know that a function is supposed to be executed when an event occurs when it hasn't yet loaded the function. See the :ref:`event handlers &lt;event&gt;` section for more information.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L385" href="#L385">385</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L386" href="#L386">386</a><span class="code-text">If a file of the right name doesn't define the function, fish will not read other autoload files, instead it will go on to try builtins and finally commands. This allows masking a function defined later in $fish_function_path, e.g. if your administrator has put something into /etc/fish/functions that you want to skip.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L387" href="#L387">387</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L388" href="#L388">388</a><span class="code-text">If you are developing another program and want to install fish functions for it, install them to the &quot;vendor&quot; functions directory. As this path varies from system to system, you can use ``pkgconfig`` to discover it with the output of ``pkg-config --variable functionsdir fish``. Your installation system should support a custom path to override the pkgconfig path, as other distributors may need to alter it easily.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L389" href="#L389">389</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L390" href="#L390">390</a><span class="code-text">.. _comments:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L391" href="#L391">391</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L392" href="#L392">392</a><span class="code-text">Comments</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L393" href="#L393">393</a><span class="code-text">--------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L394" href="#L394">394</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L395" href="#L395">395</a><span class="code-text">Anything after a ``#`` until the end of the line is a comment. That means it's purely for the reader's benefit, fish ignores it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L396" href="#L396">396</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L397" href="#L397">397</a><span class="code-text">This is useful to explain what and why you are doing something::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L398" href="#L398">398</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L399" href="#L399">399</a><span class="code-text">  function ls</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L400" href="#L400">400</a><span class="code-text">      # The function is called ls,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L401" href="#L401">401</a><span class="code-text">      # so we have to explicitly call `command ls` to avoid calling ourselves.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L402" href="#L402">402</a><span class="code-text">      command ls --color=auto $argv</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L403" href="#L403">403</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L404" href="#L404">404</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L405" href="#L405">405</a><span class="code-text">There are no multiline comments. If you want to make a comment span multiple lines, start each line with a ``#``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L406" href="#L406">406</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L407" href="#L407">407</a><span class="code-text">Comments can also appear after a line like so::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L408" href="#L408">408</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L409" href="#L409">409</a><span class="code-text">  set -gx EDITOR emacs # I don't like vim.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L410" href="#L410">410</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L411" href="#L411">411</a><span class="code-text">.. _syntax-conditional:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L412" href="#L412">412</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L413" href="#L413">413</a><span class="code-text">Conditions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L414" href="#L414">414</a><span class="code-text">----------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L415" href="#L415">415</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L416" href="#L416">416</a><span class="code-text">fish has some builtins that let you execute commands only if a specific criterion is met: :doc:`if &lt;cmds/if&gt;`, :doc:`switch &lt;cmds/switch&gt;`, :doc:`and &lt;cmds/and&gt;` and :doc:`or &lt;cmds/or&gt;`, and also the familiar :ref:`&amp;&amp;/|| &lt;syntax-combiners&gt;` syntax.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L417" href="#L417">417</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L418" href="#L418">418</a><span class="code-text">.. _syntax-if:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L419" href="#L419">419</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L420" href="#L420">420</a><span class="code-text">The ``if`` statement</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L421" href="#L421">421</a><span class="code-text">^^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L422" href="#L422">422</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L423" href="#L423">423</a><span class="code-text">The :doc:`if &lt;cmds/if&gt;` statement runs a block of commands if the condition was true.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L424" href="#L424">424</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L425" href="#L425">425</a><span class="code-text">Like other shells, but unlike typical programming languages you might know, the condition here is a *command*. fish runs it, and if it returns a true :ref:`exit status &lt;variables-status&gt;` (that's 0), the if-block is run. For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L426" href="#L426">426</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L427" href="#L427">427</a><span class="code-text">  if test -e /etc/os-release</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L428" href="#L428">428</a><span class="code-text">      cat /etc/os-release</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L429" href="#L429">429</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L430" href="#L430">430</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L431" href="#L431">431</a><span class="code-text">This uses the :doc:`test &lt;cmds/test&gt;` command to see if the file /etc/os-release exists. If it does, it runs ``cat``, which prints it on the screen.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L432" href="#L432">432</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L433" href="#L433">433</a><span class="code-text">Unlike other shells, the condition command ends after the first job, there is no ``then`` here. Combiners like ``and`` and ``or`` extend the condition.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L434" href="#L434">434</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L435" href="#L435">435</a><span class="code-text">A more complicated example with a :ref:`command substitution &lt;expand-command-substitution&gt;`::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L436" href="#L436">436</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L437" href="#L437">437</a><span class="code-text">  if test &quot;$(uname)&quot; = Linux</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L438" href="#L438">438</a><span class="code-text">      echo I like penguins</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L439" href="#L439">439</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L440" href="#L440">440</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L441" href="#L441">441</a><span class="code-text">Because ``test`` can be used for many different tests, it is important to quote variables and command substitutions. If the ``$(uname)`` was not quoted, and ``uname`` printed nothing it would run ``test = Linux``, which is an error.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L442" href="#L442">442</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L443" href="#L443">443</a><span class="code-text">``if`` can also take ``else if`` clauses with additional conditions and an  :doc:`else &lt;cmds/else&gt;` clause that is executed when everything else was false::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L444" href="#L444">444</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L445" href="#L445">445</a><span class="code-text">  if test &quot;$number&quot; -gt 10</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L446" href="#L446">446</a><span class="code-text">     echo Your number was greater than 10</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L447" href="#L447">447</a><span class="code-text">  else if test &quot;$number&quot; -gt 5</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L448" href="#L448">448</a><span class="code-text">     echo Your number was greater than 5</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L449" href="#L449">449</a><span class="code-text">  else if test &quot;$number&quot; -gt 1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L450" href="#L450">450</a><span class="code-text">     echo Your number was greater than 1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L451" href="#L451">451</a><span class="code-text">  else</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L452" href="#L452">452</a><span class="code-text">     echo Your number was smaller or equal to 1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L453" href="#L453">453</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L454" href="#L454">454</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L455" href="#L455">455</a><span class="code-text">The :doc:`not &lt;cmds/not&gt;` keyword can be used to invert the status::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L456" href="#L456">456</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L457" href="#L457">457</a><span class="code-text">  # Check if the file contains the string &quot;fish&quot; anywhere.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L458" href="#L458">458</a><span class="code-text">  # This executes the `grep` command, which searches for a string,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L459" href="#L459">459</a><span class="code-text">  # and if it finds it returns a status of 0.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L460" href="#L460">460</a><span class="code-text">  # The `not` then turns 0 into 1 or anything else into 0.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L461" href="#L461">461</a><span class="code-text">  # The `-q` switch stops it from printing any matches.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L462" href="#L462">462</a><span class="code-text">  if not grep -q fish myanimals</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L463" href="#L463">463</a><span class="code-text">      echo &quot;You don't have fish!&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L464" href="#L464">464</a><span class="code-text">  else</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L465" href="#L465">465</a><span class="code-text">      echo &quot;You have fish!&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L466" href="#L466">466</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L467" href="#L467">467</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L468" href="#L468">468</a><span class="code-text">Other things commonly used in if-conditions:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L469" href="#L469">469</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L470" href="#L470">470</a><span class="code-text">- :doc:`contains &lt;cmds/contains&gt;` - to see if a list contains a specific element (``if contains -- /usr/bin $PATH``)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L471" href="#L471">471</a><span class="code-text">- :doc:`string &lt;cmds/string&gt;` - to e.g. match strings (``if string match -q -- '*-' $arg``)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L472" href="#L472">472</a><span class="code-text">- :doc:`path &lt;cmds/path&gt;` - to check if paths of some criteria exist (``if path is -rf -- ~/.config/fish/config.fish``)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L473" href="#L473">473</a><span class="code-text">- :doc:`type &lt;cmds/type&gt;` - to see if a command, function or builtin exists (``if type -q git``)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L474" href="#L474">474</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L475" href="#L475">475</a><span class="code-text">The ``switch`` statement</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L476" href="#L476">476</a><span class="code-text">^^^^^^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L477" href="#L477">477</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L478" href="#L478">478</a><span class="code-text">The :doc:`switch &lt;cmds/switch&gt;` command is used to execute one of possibly many blocks of commands depending on the value of a string. It can take multiple :doc:`case &lt;cmds/case&gt;` blocks that are executed when the string matches. They can take :ref:`wildcards &lt;expand-wildcard&gt;`. For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L479" href="#L479">479</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L480" href="#L480">480</a><span class="code-text">  switch (uname)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L481" href="#L481">481</a><span class="code-text">  case Linux</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L482" href="#L482">482</a><span class="code-text">      echo Hi Tux!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L483" href="#L483">483</a><span class="code-text">  case Darwin</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L484" href="#L484">484</a><span class="code-text">      echo Hi Hexley!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L485" href="#L485">485</a><span class="code-text">  case DragonFly '*BSD'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L486" href="#L486">486</a><span class="code-text">      echo Hi Beastie! # this also works for FreeBSD and NetBSD</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L487" href="#L487">487</a><span class="code-text">  case '*'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L488" href="#L488">488</a><span class="code-text">      echo Hi, stranger!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L489" href="#L489">489</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L490" href="#L490">490</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L491" href="#L491">491</a><span class="code-text">Unlike other shells or programming languages, there is no fallthrough - the first matching ``case`` block is executed and then control jumps out of the ``switch``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L492" href="#L492">492</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L493" href="#L493">493</a><span class="code-text">.. _syntax-combiners:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L494" href="#L494">494</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L495" href="#L495">495</a><span class="code-text">Combiners (``and`` / ``or`` / ``&amp;&amp;`` / ``||``)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L496" href="#L496">496</a><span class="code-text">^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L497" href="#L497">497</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L498" href="#L498">498</a><span class="code-text">For simple checks, you can use combiners. :doc:`and &lt;cmds/and&gt;` or ``&amp;&amp;`` run the second command if the first succeeded, while :doc:`or &lt;cmds/or&gt;` or ``||`` run it if the first failed. For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L499" href="#L499">499</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L500" href="#L500">500</a><span class="code-text">  # $XDG_CONFIG_HOME is a standard place to store configuration.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L501" href="#L501">501</a><span class="code-text">  # If it's not set applications should use ~/.config.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L502" href="#L502">502</a><span class="code-text">  set -q XDG_CONFIG_HOME; and set -l configdir $XDG_CONFIG_HOME</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L503" href="#L503">503</a><span class="code-text">  or set -l configdir ~/.config</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L504" href="#L504">504</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L505" href="#L505">505</a><span class="code-text">Note that combiners are *lazy* - only the part that is necessary to determine the final status is run.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L506" href="#L506">506</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L507" href="#L507">507</a><span class="code-text">Compare::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L508" href="#L508">508</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L509" href="#L509">509</a><span class="code-text">  if sleep 2; and false</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L510" href="#L510">510</a><span class="code-text">      echo 'How did I get here? This should be impossible'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L511" href="#L511">511</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L512" href="#L512">512</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L513" href="#L513">513</a><span class="code-text">and::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L514" href="#L514">514</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L515" href="#L515">515</a><span class="code-text">  if false; and sleep 2</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L516" href="#L516">516</a><span class="code-text">      echo 'How did I get here? This should be impossible'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L517" href="#L517">517</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L518" href="#L518">518</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L519" href="#L519">519</a><span class="code-text">These do essentially the same thing, but the former takes 2 seconds longer because the ``sleep`` always needs to run.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L520" href="#L520">520</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L521" href="#L521">521</a><span class="code-text">Or you can have a case where it is necessary to stop early::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L522" href="#L522">522</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L523" href="#L523">523</a><span class="code-text">  if command -sq foo; and foo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L524" href="#L524">524</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L525" href="#L525">525</a><span class="code-text">If this went on after seeing that the command &quot;foo&quot; doesn't exist, it would try to run ``foo`` and error because it wasn't found!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L526" href="#L526">526</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L527" href="#L527">527</a><span class="code-text">Combiners execute step-by-step, so it isn't recommended to build longer chains of them because they might do something you don't want. Consider::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L528" href="#L528">528</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L529" href="#L529">529</a><span class="code-text">  test -e /etc/my.config</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L530" href="#L530">530</a><span class="code-text">  or echo &quot;OH NO WE NEED A CONFIG FILE&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L531" href="#L531">531</a><span class="code-text">  and return 1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L532" href="#L532">532</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L533" href="#L533">533</a><span class="code-text">This will execute ``return 1`` also if the ``test`` succeeded. This is because fish runs ``test -e /etc/my.config``, sets $status to 0, then skips the ``echo``, keeps $status at 0, and then executes the ``return 1`` because $status is still 0.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L534" href="#L534">534</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L535" href="#L535">535</a><span class="code-text">So if you have more complex conditions or want to run multiple things after something failed, consider using an :ref:`if &lt;syntax-if&gt;`. Here that would be::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L536" href="#L536">536</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L537" href="#L537">537</a><span class="code-text">  if not test -e /etc/my.config</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L538" href="#L538">538</a><span class="code-text">      echo &quot;OH NO WE NEED A CONFIG FILE&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L539" href="#L539">539</a><span class="code-text">      return 1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L540" href="#L540">540</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L541" href="#L541">541</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L542" href="#L542">542</a><span class="code-text">.. _syntax-loops-and-blocks:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L543" href="#L543">543</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L544" href="#L544">544</a><span class="code-text">Loops and blocks</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L545" href="#L545">545</a><span class="code-text">----------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L546" href="#L546">546</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L547" href="#L547">547</a><span class="code-text">Like most programming language, fish also has the familiar :doc:`while &lt;cmds/while&gt;` and :doc:`for &lt;cmds/for&gt;` loops.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L548" href="#L548">548</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L549" href="#L549">549</a><span class="code-text">``while`` works like a repeated :ref:`if &lt;syntax-if&gt;`::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L550" href="#L550">550</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L551" href="#L551">551</a><span class="code-text">  while true</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L552" href="#L552">552</a><span class="code-text">      echo Still running</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L553" href="#L553">553</a><span class="code-text">      sleep 1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L554" href="#L554">554</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L555" href="#L555">555</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L556" href="#L556">556</a><span class="code-text">will print &quot;Still running&quot; once a second. You can abort it with ctrl-c.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L557" href="#L557">557</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L558" href="#L558">558</a><span class="code-text">``for`` loops work like in other shells, which is more like python's for-loops than e.g. C's::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L559" href="#L559">559</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L560" href="#L560">560</a><span class="code-text">  for file in *</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L561" href="#L561">561</a><span class="code-text">      echo file: $file</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L562" href="#L562">562</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L563" href="#L563">563</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L564" href="#L564">564</a><span class="code-text">will print each file in the current directory. The part after the ``in`` is a list of arguments, so you can use any :ref:`expansions &lt;expand&gt;` there::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L565" href="#L565">565</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L566" href="#L566">566</a><span class="code-text">  set moreanimals bird fox</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L567" href="#L567">567</a><span class="code-text">  for animal in {cat,}fish dog $moreanimals</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L568" href="#L568">568</a><span class="code-text">     echo I like the $animal</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L569" href="#L569">569</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L570" href="#L570">570</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L571" href="#L571">571</a><span class="code-text">If you need a list of numbers, you can use the ``seq`` command to create one::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L572" href="#L572">572</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L573" href="#L573">573</a><span class="code-text">  for i in (seq 1 5)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L574" href="#L574">574</a><span class="code-text">      echo $i</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L575" href="#L575">575</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L576" href="#L576">576</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L577" href="#L577">577</a><span class="code-text">:doc:`break &lt;cmds/break&gt;` is available to break out of a loop, and :doc:`continue &lt;cmds/continue&gt;` to jump to the next iteration.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L578" href="#L578">578</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L579" href="#L579">579</a><span class="code-text">:ref:`Input and output redirections &lt;redirects&gt;` (including :ref:`pipes &lt;pipes&gt;`) can also be applied to loops::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L580" href="#L580">580</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L581" href="#L581">581</a><span class="code-text">  while read -l line</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L582" href="#L582">582</a><span class="code-text">      echo line: $line</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L583" href="#L583">583</a><span class="code-text">  end &lt; file</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L584" href="#L584">584</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L585" href="#L585">585</a><span class="code-text">In addition there's a :doc:`begin &lt;cmds/begin&gt;` block that just groups commands together so you can redirect to a block or use a new :ref:`variable scope &lt;variables-scope&gt;` without any repetition::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L586" href="#L586">586</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L587" href="#L587">587</a><span class="code-text">  begin</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L588" href="#L588">588</a><span class="code-text">     set -l foo bar # this variable will only be available in this block!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L589" href="#L589">589</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L590" href="#L590">590</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L591" href="#L591">591</a><span class="code-text">.. _expand:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L592" href="#L592">592</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L593" href="#L593">593</a><span class="code-text">Parameter expansion</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L594" href="#L594">594</a><span class="code-text">-------------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L595" href="#L595">595</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L596" href="#L596">596</a><span class="code-text">When fish is given a commandline, it expands the parameters before sending them to the command. There are multiple different kinds of expansions:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L597" href="#L597">597</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L598" href="#L598">598</a><span class="code-text">- :ref:`Wildcards &lt;expand-wildcard&gt;`, to create filenames from patterns - ``*.jpg``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L599" href="#L599">599</a><span class="code-text">- :ref:`Variable expansion &lt;expand-variable&gt;`, to use the value of a variable - ``$HOME``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L600" href="#L600">600</a><span class="code-text">- :ref:`Command substitution &lt;expand-command-substitution&gt;`, to use the output of another command - ``$(cat /path/to/file)``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L601" href="#L601">601</a><span class="code-text">- :ref:`Brace expansion &lt;expand-brace&gt;`, to write lists with common pre- or suffixes in a shorter way ``{/usr,}/bin``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L602" href="#L602">602</a><span class="code-text">- :ref:`Tilde expansion &lt;expand-home&gt;`, to turn the ``~`` at the beginning of paths into the path to the home directory ``~/bin``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L603" href="#L603">603</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L604" href="#L604">604</a><span class="code-text">Parameter expansion is limited to 524288 items. There is a limit to how many arguments the operating system allows for any command, and 524288 is far above it. This is a measure to stop the shell from hanging doing useless computation.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L605" href="#L605">605</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L606" href="#L606">606</a><span class="code-text">.. _expand-wildcard:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L607" href="#L607">607</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L608" href="#L608">608</a><span class="code-text">Wildcards (&quot;Globbing&quot;)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L609" href="#L609">609</a><span class="code-text">^^^^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L610" href="#L610">610</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L611" href="#L611">611</a><span class="code-text">When a parameter includes an :ref:`unquoted &lt;quotes&gt;` ``*`` star (or &quot;asterisk&quot;) or a ``?`` question mark, fish uses it as a wildcard to match files.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L612" href="#L612">612</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L613" href="#L613">613</a><span class="code-text">- ``*`` matches any number of characters (including zero) in a file name, not including ``/``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L614" href="#L614">614</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L615" href="#L615">615</a><span class="code-text">- ``**`` matches any number of characters (including zero), and also descends into subdirectories. If ``**`` is a segment by itself, that segment may match zero times, for compatibility with other shells.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L616" href="#L616">616</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L617" href="#L617">617</a><span class="code-text">- ``?`` can match any single character except ``/``. This is deprecated and can be disabled via the ``qmark-noglob`` :ref:`feature flag&lt;featureflags&gt;`, so ``?`` will be an ordinary character.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L618" href="#L618">618</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L619" href="#L619">619</a><span class="code-text">Wildcard matches are sorted case insensitively. When sorting matches containing numbers, they are naturally sorted, so that the strings '1' '5' and '12' would be sorted like 1, 5, 12.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L620" href="#L620">620</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L621" href="#L621">621</a><span class="code-text">Hidden files (where the name begins with a dot) are not considered when wildcarding unless the wildcard string has a dot in that place.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L622" href="#L622">622</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L623" href="#L623">623</a><span class="code-text">Wildcards never expand to ``.`` (current directory) or ``..`` (parent directory).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L624" href="#L624">624</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L625" href="#L625">625</a><span class="code-text">Examples:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L626" href="#L626">626</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L627" href="#L627">627</a><span class="code-text">- ``a*`` matches any files beginning with an 'a' in the current directory.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L628" href="#L628">628</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L629" href="#L629">629</a><span class="code-text">- ``**`` matches any files and directories in the current directory and all of its subdirectories.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L630" href="#L630">630</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L631" href="#L631">631</a><span class="code-text">- ``~/.*`` matches all hidden files (also known as &quot;dotfiles&quot;) and directories in your home directory.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L632" href="#L632">632</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L633" href="#L633">633</a><span class="code-text">For most commands, if any wildcard fails to expand, the command is not executed, :ref:`$status &lt;variables-status&gt;` is set to nonzero, and a warning is printed. This behavior is like what bash does with ``shopt -s failglob``. There are exceptions, namely :doc:`set &lt;cmds/set&gt;` and :doc:`path &lt;cmds/path&gt;`, overriding variables in :ref:`overrides &lt;variables-override&gt;`, :doc:`count &lt;cmds/count&gt;` and :doc:`for &lt;cmds/for&gt;`. Their globs will instead expand to zero arguments (so the command won't see them at all), like with ``shopt -s nullglob`` in bash.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L634" href="#L634">634</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L635" href="#L635">635</a><span class="code-text">Examples::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L636" href="#L636">636</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L637" href="#L637">637</a><span class="code-text">    # List the .foo files, or warns if there aren't any.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L638" href="#L638">638</a><span class="code-text">    ls *.foo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L639" href="#L639">639</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L640" href="#L640">640</a><span class="code-text">    # List the .foo files, if any.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L641" href="#L641">641</a><span class="code-text">    set foos *.foo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L642" href="#L642">642</a><span class="code-text">    if count $foos &gt;/dev/null</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L643" href="#L643">643</a><span class="code-text">        ls $foos</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L644" href="#L644">644</a><span class="code-text">    end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L645" href="#L645">645</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L646" href="#L646">646</a><span class="code-text">Unlike bash (by default), fish will not pass on the literal glob character if no match was found, so for a command like ``apt install`` that does the matching itself, you need to add quotes::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L647" href="#L647">647</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L648" href="#L648">648</a><span class="code-text">    apt install &quot;ncurses-*&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L649" href="#L649">649</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L650" href="#L650">650</a><span class="code-text">.. _expand-variable:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L651" href="#L651">651</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L652" href="#L652">652</a><span class="code-text">Variable expansion</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L653" href="#L653">653</a><span class="code-text">^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L654" href="#L654">654</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L655" href="#L655">655</a><span class="code-text">One of the most important expansions in fish is the &quot;variable expansion&quot;. This is the replacing of a dollar sign (``$``) followed by a variable name with the _value_ of that variable.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L656" href="#L656">656</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L657" href="#L657">657</a><span class="code-text">A simple example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L658" href="#L658">658</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L659" href="#L659">659</a><span class="code-text">    echo $HOME</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L660" href="#L660">660</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L661" href="#L661">661</a><span class="code-text">which will replace ``$HOME`` with the home directory of the current user, and pass it to :doc:`echo &lt;cmds/echo&gt;`, which will then print it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L662" href="#L662">662</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L663" href="#L663">663</a><span class="code-text">Some variables like ``$HOME`` are already set because fish sets them by default or because fish's parent process passed them to fish when it started it. You can define your own variables by setting them with :doc:`set &lt;cmds/set&gt;`::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L664" href="#L664">664</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L665" href="#L665">665</a><span class="code-text">    set my_directory /home/cooluser/mystuff</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L666" href="#L666">666</a><span class="code-text">    ls $my_directory</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L667" href="#L667">667</a><span class="code-text">    # shows the contents of /home/cooluser/mystuff</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L668" href="#L668">668</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L669" href="#L669">669</a><span class="code-text">For more on how setting variables works, see :ref:`Shell variables &lt;variables&gt;` and the following sections.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L670" href="#L670">670</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L671" href="#L671">671</a><span class="code-text">Sometimes a variable has no value because it is undefined or empty, and it expands to nothing::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L672" href="#L672">672</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L673" href="#L673">673</a><span class="code-text">    echo $nonexistentvariable</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L674" href="#L674">674</a><span class="code-text">    # Prints no output.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L675" href="#L675">675</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L676" href="#L676">676</a><span class="code-text">To separate a variable name from text you can encase the variable within double-quotes or braces::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L677" href="#L677">677</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L678" href="#L678">678</a><span class="code-text">    set WORD cat</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L679" href="#L679">679</a><span class="code-text">    echo The plural of $WORD is &quot;$WORD&quot;s</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L680" href="#L680">680</a><span class="code-text">    # Prints &quot;The plural of cat is cats&quot; because $WORD is set to &quot;cat&quot;.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L681" href="#L681">681</a><span class="code-text">    echo The plural of $WORD is {$WORD}s</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L682" href="#L682">682</a><span class="code-text">    # ditto</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L683" href="#L683">683</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L684" href="#L684">684</a><span class="code-text">Without the quotes or braces, fish will try to expand a variable called ``$WORDs``, which may not exist.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L685" href="#L685">685</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L686" href="#L686">686</a><span class="code-text">The latter syntax ``{$WORD}`` is a special case of :ref:`brace expansion &lt;expand-brace&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L687" href="#L687">687</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L688" href="#L688">688</a><span class="code-text">If $WORD here is undefined or an empty list, the &quot;s&quot; is not printed. However, it is printed if $WORD is the empty string (like after ``set WORD &quot;&quot;``).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L689" href="#L689">689</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L690" href="#L690">690</a><span class="code-text">For more on shell variables, read the :ref:`Shell variables &lt;variables&gt;` section.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L691" href="#L691">691</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L692" href="#L692">692</a><span class="code-text">Quoting variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L693" href="#L693">693</a><span class="code-text">'''''''''''''''''</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L694" href="#L694">694</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L695" href="#L695">695</a><span class="code-text">Variable expansion also happens in double quoted strings. Inside double quotes (``&quot;these&quot;``), variables will always expand to exactly one argument. If they are empty or undefined, it will result in an empty string. If they have one element, they'll expand to that element. If they have more than that, the elements will be joined with spaces, unless the variable is a :ref:`path variable &lt;variables-path&gt;` - in that case it will use a colon (``:``) instead [#]_.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L696" href="#L696">696</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L697" href="#L697">697</a><span class="code-text">fish variables are all :ref:`lists &lt;variables-lists&gt;`, and they are split into elements when they are *set* - that means it is important to decide whether to use quotes or not with :doc:`set &lt;cmds/set&gt;`::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L698" href="#L698">698</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L699" href="#L699">699</a><span class="code-text">  set foo 1 2 3 # a variable with three elements</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L700" href="#L700">700</a><span class="code-text">  rm $foo # runs the equivalent of `rm 1 2 3` - trying to delete three files: 1, 2 and 3.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L701" href="#L701">701</a><span class="code-text">  rm &quot;$foo&quot; # runs `rm '1 2 3'` - trying to delete one file called '1 2 3'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L702" href="#L702">702</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L703" href="#L703">703</a><span class="code-text">  set foo # an empty variable</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L704" href="#L704">704</a><span class="code-text">  rm $foo # runs `rm` without arguments</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L705" href="#L705">705</a><span class="code-text">  rm &quot;$foo&quot; # runs the equivalent of `rm ''`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L706" href="#L706">706</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L707" href="#L707">707</a><span class="code-text">  set foo &quot;1 2 3&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L708" href="#L708">708</a><span class="code-text">  rm $foo # runs the equivalent of `rm '1 2 3'` - trying to delete one file</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L709" href="#L709">709</a><span class="code-text">  rm &quot;$foo&quot; # same thing</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L710" href="#L710">710</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L711" href="#L711">711</a><span class="code-text">This is unlike other shells, which do what is known as &quot;Word Splitting&quot;, where they split the variable when it is *used* in an expansion. E.g. in bash:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L712" href="#L712">712</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L713" href="#L713">713</a><span class="code-text">.. code-block:: sh</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L714" href="#L714">714</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L715" href="#L715">715</a><span class="code-text">   foo=&quot;1 2 3&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L716" href="#L716">716</a><span class="code-text">   rm $foo # runs the equivalent of `rm 1 2 3`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L717" href="#L717">717</a><span class="code-text">   rm &quot;$foo&quot; # runs the equivalent of `rm '1 2 3'`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L718" href="#L718">718</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L719" href="#L719">719</a><span class="code-text">This is the cause of very common problems with filenames with spaces in bash scripts.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L720" href="#L720">720</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L721" href="#L721">721</a><span class="code-text">In fish, unquoted variables will expand to as many arguments as they have elements. That means an empty list will expand to nothing, a variable with one element will expand to that element, and a variable with multiple elements will expand to each of those elements separately.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L722" href="#L722">722</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L723" href="#L723">723</a><span class="code-text">If a variable expands to nothing, it will cancel out any other strings attached to it. See the :ref:`Combining Lists &lt;cartesian-product&gt;` section for more information.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L724" href="#L724">724</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L725" href="#L725">725</a><span class="code-text">Most of the time, not quoting a variable is correct. The exception is when you need to ensure that the variable is passed as one element, even if it might be unset or have multiple elements. This happens often with :doc:`test &lt;cmds/test&gt;`::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L726" href="#L726">726</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L727" href="#L727">727</a><span class="code-text">  set -l foo one two three</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L728" href="#L728">728</a><span class="code-text">  test -n $foo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L729" href="#L729">729</a><span class="code-text">  # prints an error that it got too many arguments, because it was executed like</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L730" href="#L730">730</a><span class="code-text">  test -n one two three</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L731" href="#L731">731</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L732" href="#L732">732</a><span class="code-text">  test -n &quot;$foo&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L733" href="#L733">733</a><span class="code-text">  # works, because it was executed like</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L734" href="#L734">734</a><span class="code-text">  test -n &quot;one two three&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L735" href="#L735">735</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L736" href="#L736">736</a><span class="code-text">.. [#] Unlike bash or zsh, which will join with the first character of $IFS (which usually is space).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L737" href="#L737">737</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L738" href="#L738">738</a><span class="code-text">Dereferencing variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L739" href="#L739">739</a><span class="code-text">'''''''''''''''''''''''</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L740" href="#L740">740</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L741" href="#L741">741</a><span class="code-text">The ``$`` symbol can also be used multiple times, as a kind of &quot;dereference&quot; operator (the ``*`` in C or C++), like in the following code::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L742" href="#L742">742</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L743" href="#L743">743</a><span class="code-text">    set foo a b c</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L744" href="#L744">744</a><span class="code-text">    set a 10; set b 20; set c 30</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L745" href="#L745">745</a><span class="code-text">    for i in (seq (count $$foo))</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L746" href="#L746">746</a><span class="code-text">        echo $$foo[$i]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L747" href="#L747">747</a><span class="code-text">    end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L748" href="#L748">748</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L749" href="#L749">749</a><span class="code-text">    # Output is:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L750" href="#L750">750</a><span class="code-text">    # 10</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L751" href="#L751">751</a><span class="code-text">    # 20</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L752" href="#L752">752</a><span class="code-text">    # 30</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L753" href="#L753">753</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L754" href="#L754">754</a><span class="code-text">``$$foo[$i]`` is &quot;the value of the variable named by ``$foo[$i]``&quot;.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L755" href="#L755">755</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L756" href="#L756">756</a><span class="code-text">This can also be used to give a variable name to a function::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L757" href="#L757">757</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L758" href="#L758">758</a><span class="code-text">  function print_var</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L759" href="#L759">759</a><span class="code-text">      for arg in $argv</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L760" href="#L760">760</a><span class="code-text">          echo Variable $arg is $$arg</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L761" href="#L761">761</a><span class="code-text">      end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L762" href="#L762">762</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L763" href="#L763">763</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L764" href="#L764">764</a><span class="code-text">  set -g foo 1 2 3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L765" href="#L765">765</a><span class="code-text">  set -g bar a b c</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L766" href="#L766">766</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L767" href="#L767">767</a><span class="code-text">  print_var foo bar</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L768" href="#L768">768</a><span class="code-text">  # prints &quot;Variable foo is 1 2 3&quot; and &quot;Variable bar is a b c&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L769" href="#L769">769</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L770" href="#L770">770</a><span class="code-text">Of course the variable will have to be accessible from the function, so it needs to be :ref:`global/universal &lt;variables-scope&gt;` or :ref:`exported &lt;variables-export&gt;`. It also can't clash with a variable name used inside the function. So if we had made $foo there a local variable, or if we had named it &quot;arg&quot; instead, it would not have worked.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L771" href="#L771">771</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L772" href="#L772">772</a><span class="code-text">When using this feature together with :ref:`slices &lt;expand-slices&gt;`, the slices will be used from the inside out. ``$$foo[5]`` will use the fifth element of ``$foo`` as a variable name, instead of giving the fifth element of all the variables $foo refers to. That would instead be expressed as ``$$foo[1..-1][5]`` (take all elements of ``$foo``, use them as variable names, then give the fifth element of those).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L773" href="#L773">773</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L774" href="#L774">774</a><span class="code-text">Some more examples::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L775" href="#L775">775</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L776" href="#L776">776</a><span class="code-text">  set listone 1 2 3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L777" href="#L777">777</a><span class="code-text">  set listtwo 4 5 6</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L778" href="#L778">778</a><span class="code-text">  set var listone listtwo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L779" href="#L779">779</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L780" href="#L780">780</a><span class="code-text">  echo $$var</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L781" href="#L781">781</a><span class="code-text">  # Output is 1 2 3 4 5 6</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L782" href="#L782">782</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L783" href="#L783">783</a><span class="code-text">  echo $$var[1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L784" href="#L784">784</a><span class="code-text">  # Output is 1 2 3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L785" href="#L785">785</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L786" href="#L786">786</a><span class="code-text">  echo $$var[2][3]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L787" href="#L787">787</a><span class="code-text">  # $var[2] is listtwo, third element of that is 6, output is 6</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L788" href="#L788">788</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L789" href="#L789">789</a><span class="code-text">  echo $$var[..][2]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L790" href="#L790">790</a><span class="code-text">  # The second element of every variable, so output is 2 5</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L791" href="#L791">791</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L792" href="#L792">792</a><span class="code-text">Variables as command</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L793" href="#L793">793</a><span class="code-text">''''''''''''''''''''</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L794" href="#L794">794</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L795" href="#L795">795</a><span class="code-text">Like other shells, you can run the value of a variable as a command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L796" href="#L796">796</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L797" href="#L797">797</a><span class="code-text">::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L798" href="#L798">798</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L799" href="#L799">799</a><span class="code-text">   &gt; set -g EDITOR emacs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L800" href="#L800">800</a><span class="code-text">   &gt; $EDITOR foo # opens emacs, possibly the GUI version</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L801" href="#L801">801</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L802" href="#L802">802</a><span class="code-text">If you want to give the command an argument inside the variable it needs to be a separate element::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L803" href="#L803">803</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L804" href="#L804">804</a><span class="code-text">   &gt; set EDITOR emacs -nw</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L805" href="#L805">805</a><span class="code-text">   &gt; $EDITOR foo # opens emacs in the terminal even if the GUI is installed</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L806" href="#L806">806</a><span class="code-text">   &gt; set EDITOR &quot;emacs -nw&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L807" href="#L807">807</a><span class="code-text">   &gt; $EDITOR foo # tries to find a command called &quot;emacs -nw&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L808" href="#L808">808</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L809" href="#L809">809</a><span class="code-text">Also like other shells, this only works with commands, builtins and functions - it will not work with keywords because they have syntactical importance.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L810" href="#L810">810</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L811" href="#L811">811</a><span class="code-text">For instance ``set if $if`` won't allow you to make an if-block, and ``set cmd command`` won't allow you to use the :doc:`command &lt;cmds/command&gt;` decorator, but only uses like ``$cmd -q foo``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L812" href="#L812">812</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L813" href="#L813">813</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L814" href="#L814">814</a><span class="code-text">.. _expand-command-substitution:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L815" href="#L815">815</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L816" href="#L816">816</a><span class="code-text">Command substitution</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L817" href="#L817">817</a><span class="code-text">^^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L818" href="#L818">818</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L819" href="#L819">819</a><span class="code-text">A ``command substitution`` is an expansion that uses the *output* of a command as the arguments to another. For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L820" href="#L820">820</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L821" href="#L821">821</a><span class="code-text">  echo $(pwd)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L822" href="#L822">822</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L823" href="#L823">823</a><span class="code-text">This executes the :doc:`pwd &lt;cmds/pwd&gt;` command, takes its output (more specifically what it wrote to the standard output &quot;stdout&quot; stream) and uses it as arguments to :doc:`echo &lt;cmds/echo&gt;`. So the inner command (the ``pwd``) is run first and has to complete before the outer command can even be started.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L824" href="#L824">824</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L825" href="#L825">825</a><span class="code-text">If the inner command prints multiple lines, fish will use each separate line as a separate argument to the outer command. Unlike other shells, the value of ``$IFS`` is not used [#]_, fish splits on newlines.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L826" href="#L826">826</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L827" href="#L827">827</a><span class="code-text">Command substitutions can also be double-quoted::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L828" href="#L828">828</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L829" href="#L829">829</a><span class="code-text">  echo &quot;$(pwd)&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L830" href="#L830">830</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L831" href="#L831">831</a><span class="code-text">When using double quotes, the command output is not split up by lines, but trailing empty lines are still removed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L832" href="#L832">832</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L833" href="#L833">833</a><span class="code-text">If the output is piped to :doc:`string split or string split0 &lt;cmds/string-split&gt;` as the last step, those splits are used as they appear instead of splitting lines.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L834" href="#L834">834</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L835" href="#L835">835</a><span class="code-text">fish also allows spelling command substitutions without the dollar, like ``echo (pwd)``. This variant will not be expanded in double-quotes (``echo &quot;(pwd)&quot;`` will print ``(pwd)``).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L836" href="#L836">836</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L837" href="#L837">837</a><span class="code-text">The exit status of the last run command substitution is available in the :ref:`status &lt;variables-status&gt;` variable if the substitution happens in the context of a :doc:`set &lt;cmds/set&gt;` command (so ``if set -l (something)`` checks if ``something`` returned true).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L838" href="#L838">838</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L839" href="#L839">839</a><span class="code-text">To use only some lines of the output, refer to :ref:`slices &lt;expand-slices&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L840" href="#L840">840</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L841" href="#L841">841</a><span class="code-text">Examples::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L842" href="#L842">842</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L843" href="#L843">843</a><span class="code-text">    # Outputs 'image.png'.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L844" href="#L844">844</a><span class="code-text">    echo (basename image.jpg .jpg).png</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L845" href="#L845">845</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L846" href="#L846">846</a><span class="code-text">    # Convert all JPEG files in the current directory to the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L847" href="#L847">847</a><span class="code-text">    # PNG format using the 'convert' program.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L848" href="#L848">848</a><span class="code-text">    for i in *.jpg; convert $i (basename $i .jpg).png; end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L849" href="#L849">849</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L850" href="#L850">850</a><span class="code-text">    # Set the ``data`` variable to the contents of 'data.txt'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L851" href="#L851">851</a><span class="code-text">    # without splitting it into a list.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L852" href="#L852">852</a><span class="code-text">    set data &quot;$(cat data.txt)&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L853" href="#L853">853</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L854" href="#L854">854</a><span class="code-text">    # Set ``$data`` to the contents of data, splitting on NUL-bytes.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L855" href="#L855">855</a><span class="code-text">    set data (cat data | string split0)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L856" href="#L856">856</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L857" href="#L857">857</a><span class="code-text">Sometimes you want to pass the output of a command to another command that only accepts files. If it's just one file, you can usually pass it via a pipe, like::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L858" href="#L858">858</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L859" href="#L859">859</a><span class="code-text">    grep fish myanimallist1 | wc -l</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L860" href="#L860">860</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L861" href="#L861">861</a><span class="code-text">but if you need multiple or the command doesn't read from standard input, &quot;process substitution&quot; is useful. Other shells allow this via ``foo &lt;(bar) &lt;(baz)``, and fish uses the :doc:`psub &lt;cmds/psub&gt;` command::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L862" href="#L862">862</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L863" href="#L863">863</a><span class="code-text">    # Compare only the lines containing &quot;fish&quot; in two files:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L864" href="#L864">864</a><span class="code-text">    diff -u (grep fish myanimallist1 | psub) (grep fish myanimallist2 | psub)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L865" href="#L865">865</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L866" href="#L866">866</a><span class="code-text">This creates a temporary file, stores the output of the command in that file and prints the filename, so it is given to the outer command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L867" href="#L867">867</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L868" href="#L868">868</a><span class="code-text">fish has a default limit of 1 GiB on the data it will read in a command substitution. If that limit is reached the command (all of it, not just the command substitution - the outer command won't be executed at all) fails and ``$status`` is set to 122. This is so command substitutions can't cause the system to go out of memory, because typically your operating system has a much lower limit, so reading more than that would be useless and harmful. This limit can be adjusted with the ``fish_read_limit`` variable (`0` meaning no limit). This limit also affects the :doc:`read &lt;cmds/read&gt;` command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L869" href="#L869">869</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L870" href="#L870">870</a><span class="code-text">.. [#] One exception: Setting ``$IFS`` to empty will disable line splitting. This is deprecated, use :doc:`string split &lt;cmds/string-split&gt;` instead.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L871" href="#L871">871</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L872" href="#L872">872</a><span class="code-text">.. _expand-brace:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L873" href="#L873">873</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L874" href="#L874">874</a><span class="code-text">Brace expansion</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L875" href="#L875">875</a><span class="code-text">^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L876" href="#L876">876</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L877" href="#L877">877</a><span class="code-text">Curly braces can be used to write comma-separated lists. They will be expanded with each element becoming a new parameter, with the surrounding string attached. This is useful to save on typing, and to separate a variable name from surrounding text.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L878" href="#L878">878</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L879" href="#L879">879</a><span class="code-text">Examples::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L880" href="#L880">880</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L881" href="#L881">881</a><span class="code-text">  &gt; echo input.{c,h,txt}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L882" href="#L882">882</a><span class="code-text">  input.c input.h input.txt</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L883" href="#L883">883</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L884" href="#L884">884</a><span class="code-text">  # Move all files with the suffix '.c' or '.h' to the subdirectory src.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L885" href="#L885">885</a><span class="code-text">  &gt; mv *.{c,h} src/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L886" href="#L886">886</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L887" href="#L887">887</a><span class="code-text">  # Make a copy of `file` at `file.bak`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L888" href="#L888">888</a><span class="code-text">  &gt; cp file{,.bak}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L889" href="#L889">889</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L890" href="#L890">890</a><span class="code-text">  &gt; set -l dogs hot cool cute &quot;good &quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L891" href="#L891">891</a><span class="code-text">  &gt; echo {$dogs}dog</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L892" href="#L892">892</a><span class="code-text">  hotdog cooldog cutedog good dog</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L893" href="#L893">893</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L894" href="#L894">894</a><span class="code-text">If there is no &quot;,&quot; or variable expansion between the curly braces, they will not be expanded::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L895" href="#L895">895</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L896" href="#L896">896</a><span class="code-text">    # This {} isn't special</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L897" href="#L897">897</a><span class="code-text">    &gt; echo foo-{}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L898" href="#L898">898</a><span class="code-text">    foo-{}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L899" href="#L899">899</a><span class="code-text">    # This passes &quot;HEAD@{2}&quot; to git</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L900" href="#L900">900</a><span class="code-text">    &gt; git reset --hard HEAD@{2}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L901" href="#L901">901</a><span class="code-text">    &gt; echo {{a,b}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L902" href="#L902">902</a><span class="code-text">    {a} {b} # because the inner brace pair is expanded, but the outer isn't.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L903" href="#L903">903</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L904" href="#L904">904</a><span class="code-text">If after expansion there is nothing between the braces, the argument will be removed (see :ref:`the Combining Lists &lt;cartesian-product&gt;` section)::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L905" href="#L905">905</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L906" href="#L906">906</a><span class="code-text">    &gt; echo foo-{$undefinedvar}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L907" href="#L907">907</a><span class="code-text">    # Output is an empty line, like a bare `echo`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L908" href="#L908">908</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L909" href="#L909">909</a><span class="code-text">If there is nothing between a brace and a comma or two commas, it's interpreted as an empty element::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L910" href="#L910">910</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L911" href="#L911">911</a><span class="code-text">    &gt; echo {,,/usr}/bin</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L912" href="#L912">912</a><span class="code-text">    /bin /bin /usr/bin</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L913" href="#L913">913</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L914" href="#L914">914</a><span class="code-text">To use a &quot;,&quot; as an element, :ref:`quote &lt;quotes&gt;` or :ref:`escape &lt;escapes&gt;` it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L915" href="#L915">915</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L916" href="#L916">916</a><span class="code-text">The very first character of a command token is never interpreted as expanding brace, because it's the beginning of a :doc:`compound statement &lt;cmds/begin&gt;`::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L917" href="#L917">917</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L918" href="#L918">918</a><span class="code-text">    &gt; {echo hello, &amp;&amp; echo world}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L919" href="#L919">919</a><span class="code-text">    hello,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L920" href="#L920">920</a><span class="code-text">    world</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L921" href="#L921">921</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L922" href="#L922">922</a><span class="code-text">.. _cartesian-product:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L923" href="#L923">923</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L924" href="#L924">924</a><span class="code-text">Combining lists</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L925" href="#L925">925</a><span class="code-text">^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L926" href="#L926">926</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L927" href="#L927">927</a><span class="code-text">fish expands lists like :ref:`brace expansions &lt;expand-brace&gt;`::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L928" href="#L928">928</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L929" href="#L929">929</a><span class="code-text">  &gt;_ set -l foo x y z</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L930" href="#L930">930</a><span class="code-text">  &gt;_ echo 1$foo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L931" href="#L931">931</a><span class="code-text">  # Any element of $foo is combined with the &quot;1&quot;:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L932" href="#L932">932</a><span class="code-text">  1x 1y 1z</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L933" href="#L933">933</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L934" href="#L934">934</a><span class="code-text">  &gt;_ echo {good,bad}&quot; apples&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L935" href="#L935">935</a><span class="code-text">  # Any element of the {} is combined with the &quot; apples&quot;:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L936" href="#L936">936</a><span class="code-text">  good apples bad apples</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L937" href="#L937">937</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L938" href="#L938">938</a><span class="code-text">  # Or we can mix the two:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L939" href="#L939">939</a><span class="code-text">  &gt;_ echo {good,bad}&quot; &quot;$foo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L940" href="#L940">940</a><span class="code-text">  good x bad x good y bad y good z bad z</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L941" href="#L941">941</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L942" href="#L942">942</a><span class="code-text">Any string attached to a list will be concatenated to each element.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L943" href="#L943">943</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L944" href="#L944">944</a><span class="code-text">Two lists will be expanded in all combinations  - every element of the first with every element of the second::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L945" href="#L945">945</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L946" href="#L946">946</a><span class="code-text">    &gt;_ set -l a x y z; set -l b 1 2 3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L947" href="#L947">947</a><span class="code-text">    &gt;_ echo $a$b # same as {x,y,z}{1,2,3}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L948" href="#L948">948</a><span class="code-text">    x1 y1 z1 x2 y2 z2 x3 y3 z3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L949" href="#L949">949</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L950" href="#L950">950</a><span class="code-text">A result of this is that, if a list has no elements, this combines the string with no elements, which means the entire token is removed!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L951" href="#L951">951</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L952" href="#L952">952</a><span class="code-text">::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L953" href="#L953">953</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L954" href="#L954">954</a><span class="code-text">    &gt;_ set -l c # &lt;- this list is empty!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L955" href="#L955">955</a><span class="code-text">    &gt;_ echo {$c}word</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L956" href="#L956">956</a><span class="code-text">    # Output is an empty line - the &quot;word&quot; part is gone</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L957" href="#L957">957</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L958" href="#L958">958</a><span class="code-text">This can be quite useful. For example, if you want to go through all the files in all the directories in :envvar:`PATH`, use</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L959" href="#L959">959</a><span class="code-text">::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L960" href="#L960">960</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L961" href="#L961">961</a><span class="code-text">    for file in $PATH/*</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L962" href="#L962">962</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L963" href="#L963">963</a><span class="code-text">Because :envvar:`PATH` is a list, this expands to all the files in all the directories in it. And if there are no directories in :envvar:`PATH`, the right answer here is to expand to no files.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L964" href="#L964">964</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L965" href="#L965">965</a><span class="code-text">Sometimes this may be unwanted, especially that tokens can disappear after expansion. In those cases, you should double-quote variables - ``echo &quot;$c&quot;word``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L966" href="#L966">966</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L967" href="#L967">967</a><span class="code-text">This also happens after :ref:`command substitution &lt;expand-command-substitution&gt;`. To avoid tokens disappearing there, make the inner command return a trailing newline, or double-quote it::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L968" href="#L968">968</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L969" href="#L969">969</a><span class="code-text">    &gt;_ set b 1 2 3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L970" href="#L970">970</a><span class="code-text">    &gt;_ echo (echo x)$b</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L971" href="#L971">971</a><span class="code-text">    x1 x2 x3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L972" href="#L972">972</a><span class="code-text">    &gt;_ echo (printf '%s' '')banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L973" href="#L973">973</a><span class="code-text">    # the printf prints nothing, so this is nothing times &quot;banana&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L974" href="#L974">974</a><span class="code-text">    # which is nothing.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L975" href="#L975">975</a><span class="code-text">    &gt;_ echo (printf '%s\n' '')banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L976" href="#L976">976</a><span class="code-text">    # the printf prints a newline,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L977" href="#L977">977</a><span class="code-text">    # so the command substitution expands to an empty string,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L978" href="#L978">978</a><span class="code-text">    # so this is `''banana`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L979" href="#L979">979</a><span class="code-text">    banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L980" href="#L980">980</a><span class="code-text">    &gt;_ echo &quot;$(printf '%s' '')&quot;banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L981" href="#L981">981</a><span class="code-text">    # quotes mean this is one argument, the banana stays</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L982" href="#L982">982</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L983" href="#L983">983</a><span class="code-text">.. _expand-slices:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L984" href="#L984">984</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L985" href="#L985">985</a><span class="code-text">Slices</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L986" href="#L986">986</a><span class="code-text">^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L987" href="#L987">987</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L988" href="#L988">988</a><span class="code-text">Sometimes it's necessary to access only some of the elements of a :ref:`list &lt;variables-lists&gt;` (all fish variables are lists), or some of the lines a :ref:`command substitution &lt;expand-command-substitution&gt;` outputs. Both are possible in fish by writing a set of indices in brackets, like::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L989" href="#L989">989</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L990" href="#L990">990</a><span class="code-text">  # Make $var a list of four elements</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L991" href="#L991">991</a><span class="code-text">  set var one two three four</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L992" href="#L992">992</a><span class="code-text">  # Print the second:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L993" href="#L993">993</a><span class="code-text">  echo $var[2]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L994" href="#L994">994</a><span class="code-text">  # prints &quot;two&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L995" href="#L995">995</a><span class="code-text">  # or print the first three:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L996" href="#L996">996</a><span class="code-text">  echo $var[1..3]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L997" href="#L997">997</a><span class="code-text">  # prints &quot;one two three&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L998" href="#L998">998</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L999" href="#L999">999</a><span class="code-text">In index brackets, fish understands ranges written like ``a..b`` ('a' and 'b' being indices). They are expanded into a sequence of indices from a to b (so ``a a+1 a+2 ... b``), going up if b is larger and going down if a is larger. Negative indices can also be used - they are taken from the end of the list, so ``-1`` is the last element, and ``-2`` the one before it. If an index doesn't exist the range is clamped to the next possible index.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1000" href="#L1000">1000</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1001" href="#L1001">1001</a><span class="code-text">If a list has 5 elements the indices go from 1 to 5, so a range of ``2..16`` will only go from element 2 to element 5.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1002" href="#L1002">1002</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1003" href="#L1003">1003</a><span class="code-text">If the end is negative the range always goes up, so ``2..-2`` will go from element 2 to 4, and ``2..-16`` won't go anywhere because there is no way to go from the second element to one that doesn't exist, while going up.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1004" href="#L1004">1004</a><span class="code-text">If the start is negative the range always goes down, so ``-2..1`` will go from element 4 to 1, and ``-16..2`` won't go anywhere because there is no way to go from an element that doesn't exist to the second element, while going down.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1005" href="#L1005">1005</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1006" href="#L1006">1006</a><span class="code-text">A missing starting index in a range defaults to 1. This is allowed if the range is the first index expression of the sequence. Similarly, a missing ending index, defaulting to -1 is allowed for the last index in the sequence.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1007" href="#L1007">1007</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1008" href="#L1008">1008</a><span class="code-text">Multiple ranges are also possible, separated with a space.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1009" href="#L1009">1009</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1010" href="#L1010">1010</a><span class="code-text">Some examples::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1011" href="#L1011">1011</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1012" href="#L1012">1012</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1013" href="#L1013">1013</a><span class="code-text">    echo (seq 10)[1 2 3]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1014" href="#L1014">1014</a><span class="code-text">    # Prints: 1 2 3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1015" href="#L1015">1015</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1016" href="#L1016">1016</a><span class="code-text">    # Limit the command substitution output</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1017" href="#L1017">1017</a><span class="code-text">    echo (seq 10)[2..5]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1018" href="#L1018">1018</a><span class="code-text">    # Uses elements from 2 to 5</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1019" href="#L1019">1019</a><span class="code-text">    # Output is: 2 3 4 5</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1020" href="#L1020">1020</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1021" href="#L1021">1021</a><span class="code-text">    echo (seq 10)[7..]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1022" href="#L1022">1022</a><span class="code-text">    # Prints: 7 8 9 10</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1023" href="#L1023">1023</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1024" href="#L1024">1024</a><span class="code-text">    # Use overlapping ranges:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1025" href="#L1025">1025</a><span class="code-text">    echo (seq 10)[2..5 1..3]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1026" href="#L1026">1026</a><span class="code-text">    # Takes elements from 2 to 5 and then elements from 1 to 3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1027" href="#L1027">1027</a><span class="code-text">    # Output is: 2 3 4 5 1 2 3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1028" href="#L1028">1028</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1029" href="#L1029">1029</a><span class="code-text">    # Reverse output</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1030" href="#L1030">1030</a><span class="code-text">    echo (seq 10)[-1..1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1031" href="#L1031">1031</a><span class="code-text">    # Uses elements from the last output line to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1032" href="#L1032">1032</a><span class="code-text">    # the first one in reverse direction</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1033" href="#L1033">1033</a><span class="code-text">    # Output is: 10 9 8 7 6 5 4 3 2 1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1034" href="#L1034">1034</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1035" href="#L1035">1035</a><span class="code-text">    # The command substitution has only one line,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1036" href="#L1036">1036</a><span class="code-text">    # so these will result in empty output:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1037" href="#L1037">1037</a><span class="code-text">    echo (echo one)[2..-1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1038" href="#L1038">1038</a><span class="code-text">    echo (echo one)[-3..1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1039" href="#L1039">1039</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1040" href="#L1040">1040</a><span class="code-text">The same works when setting or expanding variables::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1041" href="#L1041">1041</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1042" href="#L1042">1042</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1043" href="#L1043">1043</a><span class="code-text">    # Reverse path variable</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1044" href="#L1044">1044</a><span class="code-text">    set PATH $PATH[-1..1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1045" href="#L1045">1045</a><span class="code-text">    # or</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1046" href="#L1046">1046</a><span class="code-text">    set PATH[-1..1] $PATH</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1047" href="#L1047">1047</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1048" href="#L1048">1048</a><span class="code-text">    # Use only n last items of the PATH</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1049" href="#L1049">1049</a><span class="code-text">    set n -3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1050" href="#L1050">1050</a><span class="code-text">    echo $PATH[$n..-1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1051" href="#L1051">1051</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1052" href="#L1052">1052</a><span class="code-text">Variables can be used as indices for expansion of variables, like so::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1053" href="#L1053">1053</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1054" href="#L1054">1054</a><span class="code-text">    set index 2</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1055" href="#L1055">1055</a><span class="code-text">    set letters a b c d</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1056" href="#L1056">1056</a><span class="code-text">    echo $letters[$index] # returns 'b'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1057" href="#L1057">1057</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1058" href="#L1058">1058</a><span class="code-text">However using variables as indices for command substitution is currently not supported, so::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1059" href="#L1059">1059</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1060" href="#L1060">1060</a><span class="code-text">    echo (seq 5)[$index] # This won't work</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1061" href="#L1061">1061</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1062" href="#L1062">1062</a><span class="code-text">    set sequence (seq 5) # It needs to be written on two lines like this.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1063" href="#L1063">1063</a><span class="code-text">    echo $sequence[$index] # returns '2'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1064" href="#L1064">1064</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1065" href="#L1065">1065</a><span class="code-text">When using indirect variable expansion with multiple ``$`` (``$$name``), you have to give all indices up to the variable you want to slice::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1066" href="#L1066">1066</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1067" href="#L1067">1067</a><span class="code-text">    &gt; set -l list 1 2 3 4 5</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1068" href="#L1068">1068</a><span class="code-text">    &gt; set -l name list</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1069" href="#L1069">1069</a><span class="code-text">    &gt; echo $$name[1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1070" href="#L1070">1070</a><span class="code-text">    1 2 3 4 5</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1071" href="#L1071">1071</a><span class="code-text">    &gt; echo $$name[1..-1][1..3] # or $$name[1][1..3], since $name only has one element.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1072" href="#L1072">1072</a><span class="code-text">    1 2 3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1073" href="#L1073">1073</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1074" href="#L1074">1074</a><span class="code-text">.. _expand-home:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1075" href="#L1075">1075</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1076" href="#L1076">1076</a><span class="code-text">Home directory expansion</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1077" href="#L1077">1077</a><span class="code-text">^^^^^^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1078" href="#L1078">1078</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1079" href="#L1079">1079</a><span class="code-text">The ``~`` (tilde) character at the beginning of a parameter, followed by a username, is expanded into the home directory of the specified user. A lone ``~``, or a ``~`` followed by a slash, is expanded into the home directory of the process owner::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1080" href="#L1080">1080</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1081" href="#L1081">1081</a><span class="code-text">  ls ~/Music # lists my music directory</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1082" href="#L1082">1082</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1083" href="#L1083">1083</a><span class="code-text">  echo ~root # prints root's home directory, probably &quot;/root&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1084" href="#L1084">1084</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1085" href="#L1085">1085</a><span class="code-text">Combining different expansions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1086" href="#L1086">1086</a><span class="code-text">^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1087" href="#L1087">1087</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1088" href="#L1088">1088</a><span class="code-text">All of the above expansions can be combined. If several expansions result in more than one parameter, all possible combinations are created.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1089" href="#L1089">1089</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1090" href="#L1090">1090</a><span class="code-text">When combining multiple parameter expansions, expansions are performed in the following order:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1091" href="#L1091">1091</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1092" href="#L1092">1092</a><span class="code-text">- Command substitutions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1093" href="#L1093">1093</a><span class="code-text">- Variable expansions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1094" href="#L1094">1094</a><span class="code-text">- Bracket expansion</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1095" href="#L1095">1095</a><span class="code-text">- Wildcard expansion</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1096" href="#L1096">1096</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1097" href="#L1097">1097</a><span class="code-text">Expansions are performed from right to left, nested bracket expansions and command substitutions are performed from the inside and out.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1098" href="#L1098">1098</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1099" href="#L1099">1099</a><span class="code-text">Example:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1100" href="#L1100">1100</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1101" href="#L1101">1101</a><span class="code-text">If the current directory contains the files 'foo' and 'bar', the command ``echo a(ls){1,2,3}`` will output ``abar1 abar2 abar3 afoo1 afoo2 afoo3``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1102" href="#L1102">1102</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1103" href="#L1103">1103</a><span class="code-text">Table Of Operators</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1104" href="#L1104">1104</a><span class="code-text">------------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1105" href="#L1105">1105</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1106" href="#L1106">1106</a><span class="code-text">Putting it together, here is a quick reference to fish's operators, all of the special symbols it uses:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1107" href="#L1107">1107</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1108" href="#L1108">1108</a><span class="code-text">====================    ==========================================================   =================================================</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1109" href="#L1109">1109</a><span class="code-text">Symbol                  Meaning                                                      Example</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1110" href="#L1110">1110</a><span class="code-text">====================    ==========================================================   =================================================</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1111" href="#L1111">1111</a><span class="code-text">``$``                   :ref:`Variable expansion &lt;expand-variable&gt;`                  ``echo $foo``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1112" href="#L1112">1112</a><span class="code-text">``$()`` and ``()``      :ref:`Command substitution &lt;expand-command-substitution&gt;`    ``cat (grep foo bar)`` or ``cat $(grep foo bar)``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1113" href="#L1113">1113</a><span class="code-text">``&lt;`` and ``&gt;``         :ref:`Redirection &lt;redirects&gt;`, like ``command &gt; file``      ``git shortlog -nse . &gt; authors``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1114" href="#L1114">1114</a><span class="code-text">``|``                   :ref:`Pipe &lt;pipes&gt;`, connect two or more commands            ``foo | grep bar | grep baz``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1115" href="#L1115">1115</a><span class="code-text">``;``                   End of the command, instead of a newline                     ``command1; command2``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1116" href="#L1116">1116</a><span class="code-text">``&amp;``                   :ref:`Backgrounding &lt;syntax-job-control&gt;`                    ``sleep 5m &amp;``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1117" href="#L1117">1117</a><span class="code-text">``{}``                  :ref:`Brace expansion &lt;expand-brace&gt;`                        ``ls {/usr,}/bin``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1118" href="#L1118">1118</a><span class="code-text">``&amp;&amp;`` and ``||``       :ref:`Combiners &lt;syntax-combiners&gt;`                          ``mkdir foo &amp;&amp; cd foo`` or ``rm foo || exit``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1119" href="#L1119">1119</a><span class="code-text">``*`` and ``**``        :ref:`Wildcards &lt;expand-wildcard&gt;`                           ``cat *.fish`` or ``count **.jpg``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1120" href="#L1120">1120</a><span class="code-text">``\\``                  :ref:`Escaping &lt;escapes&gt;`                                    ``echo foo\nbar`` or ``echo \$foo``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1121" href="#L1121">1121</a><span class="code-text">``''`` and ``&quot;&quot;``       :ref:`Quoting &lt;quotes&gt;`                                      ``rm &quot;file with spaces&quot;`` or ``echo '$foo'``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1122" href="#L1122">1122</a><span class="code-text">``~``                   :ref:`Home directory expansion &lt;expand-home&gt;`                ``ls ~/`` or ``ls ~root/``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1123" href="#L1123">1123</a><span class="code-text">``#``                   :ref:`Comments`                                              ``echo Hello # this isn't printed``</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1124" href="#L1124">1124</a><span class="code-text">====================    ==========================================================   =================================================</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1125" href="#L1125">1125</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1126" href="#L1126">1126</a><span class="code-text">.. _variables:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1127" href="#L1127">1127</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1128" href="#L1128">1128</a><span class="code-text">Shell variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1129" href="#L1129">1129</a><span class="code-text">---------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1130" href="#L1130">1130</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1131" href="#L1131">1131</a><span class="code-text">Variables are a way to save data and pass it around. They can be used just by the shell, or they can be &quot;:ref:`exported &lt;variables-export&gt;`&quot;, so that a copy of the variable is available to any external command the shell starts. An exported variable is referred to as an &quot;environment variable&quot;.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1132" href="#L1132">1132</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1133" href="#L1133">1133</a><span class="code-text">To set a variable value, use the :doc:`set &lt;cmds/set&gt;` command. A variable name can not be empty and can contain only letters, digits, and underscores. It may begin and end with any of those characters.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1134" href="#L1134">1134</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1135" href="#L1135">1135</a><span class="code-text">Example:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1136" href="#L1136">1136</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1137" href="#L1137">1137</a><span class="code-text">To set the variable ``smurf_color`` to the value ``blue``, use the command ``set smurf_color blue``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1138" href="#L1138">1138</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1139" href="#L1139">1139</a><span class="code-text">After a variable has been set, you can use the value of a variable in the shell through :ref:`variable expansion &lt;expand-variable&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1140" href="#L1140">1140</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1141" href="#L1141">1141</a><span class="code-text">Example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1142" href="#L1142">1142</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1143" href="#L1143">1143</a><span class="code-text">    set smurf_color blue</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1144" href="#L1144">1144</a><span class="code-text">    echo Smurfs are usually $smurf_color</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1145" href="#L1145">1145</a><span class="code-text">    set pants_color red</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1146" href="#L1146">1146</a><span class="code-text">    echo Papa smurf, who is $smurf_color, wears $pants_color pants</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1147" href="#L1147">1147</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1148" href="#L1148">1148</a><span class="code-text">So you set a variable with ``set``, and use it with a ``$`` and the name.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1149" href="#L1149">1149</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1150" href="#L1150">1150</a><span class="code-text">.. _variables-scope:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1151" href="#L1151">1151</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1152" href="#L1152">1152</a><span class="code-text">Variable Scope</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1153" href="#L1153">1153</a><span class="code-text">^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1154" href="#L1154">1154</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1155" href="#L1155">1155</a><span class="code-text">All variables in fish have a scope. For example they can be global or local to a function or block::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1156" href="#L1156">1156</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1157" href="#L1157">1157</a><span class="code-text">  # This variable is global, we can use it everywhere.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1158" href="#L1158">1158</a><span class="code-text">  set --global name Patrick</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1159" href="#L1159">1159</a><span class="code-text">  # This variable is local, it will not be visible in a function we call from here.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1160" href="#L1160">1160</a><span class="code-text">  set --local place &quot;at the Krusty Krab&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1161" href="#L1161">1161</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1162" href="#L1162">1162</a><span class="code-text">  function local</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1163" href="#L1163">1163</a><span class="code-text">      # This can find $name, but not $place</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1164" href="#L1164">1164</a><span class="code-text">      echo Hello this is $name $place</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1165" href="#L1165">1165</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1166" href="#L1166">1166</a><span class="code-text">      # This variable is local, it will not be available</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1167" href="#L1167">1167</a><span class="code-text">      # outside of this function</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1168" href="#L1168">1168</a><span class="code-text">      set --local instrument mayonnaise</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1169" href="#L1169">1169</a><span class="code-text">      echo My favorite instrument is $instrument</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1170" href="#L1170">1170</a><span class="code-text">      # This creates a local $name, and won't touch the global one</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1171" href="#L1171">1171</a><span class="code-text">      set --local name Spongebob</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1172" href="#L1172">1172</a><span class="code-text">      echo My best friend is $name</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1173" href="#L1173">1173</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1174" href="#L1174">1174</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1175" href="#L1175">1175</a><span class="code-text">  local</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1176" href="#L1176">1176</a><span class="code-text">  # Will print:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1177" href="#L1177">1177</a><span class="code-text">  # Hello this is Patrick</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1178" href="#L1178">1178</a><span class="code-text">  # My favorite instrument is mayonnaise</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1179" href="#L1179">1179</a><span class="code-text">  # My best friend is Spongebob</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1180" href="#L1180">1180</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1181" href="#L1181">1181</a><span class="code-text">  echo $name, I am $place and my instrument is $instrument</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1182" href="#L1182">1182</a><span class="code-text">  # Will print:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1183" href="#L1183">1183</a><span class="code-text">  # Patrick, I am at the Krusty Krab and my instrument is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1184" href="#L1184">1184</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1185" href="#L1185">1185</a><span class="code-text">There are four kinds of variable scopes in fish: universal, global, function and local variables.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1186" href="#L1186">1186</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1187" href="#L1187">1187</a><span class="code-text">- Universal variables are shared between all fish sessions a user is running on one computer. They are stored on disk and persist even after reboot.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1188" href="#L1188">1188</a><span class="code-text">- Global variables are specific to the current fish session. They can be erased by explicitly requesting ``set -e``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1189" href="#L1189">1189</a><span class="code-text">- Function variables are specific to the currently executing function. They are erased (&quot;go out of scope&quot;) when the current function ends. Outside of a function, they don't go out of scope.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1190" href="#L1190">1190</a><span class="code-text">- Local variables are specific to the current block of commands, and automatically erased when a specific block goes out of scope. A block of commands is a series of commands that begins with one of the commands ``for``, ``while`` , ``if``, ``function``, ``begin`` or ``switch``, and ends with the command ``end``. Outside of a block, this is the same as the function scope.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1191" href="#L1191">1191</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1192" href="#L1192">1192</a><span class="code-text">Variables can be explicitly set to be universal with the ``-U`` or ``--universal`` switch, global with ``-g`` or ``--global``, function-scoped with ``-f`` or ``--function`` and local to the current block with ``-l`` or ``--local``.  The scoping rules when creating or updating a variable are:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1193" href="#L1193">1193</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1194" href="#L1194">1194</a><span class="code-text">- When a scope is explicitly given, it will be used. If a variable of the same name exists in a different scope, that variable will not be changed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1195" href="#L1195">1195</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1196" href="#L1196">1196</a><span class="code-text">- When no scope is given, but a variable of that name exists, the variable of the smallest scope will be modified. The scope will not be changed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1197" href="#L1197">1197</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1198" href="#L1198">1198</a><span class="code-text">- When no scope is given and no variable of that name exists, the variable is created in function scope if inside a function, or global scope if no function is executing.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1199" href="#L1199">1199</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1200" href="#L1200">1200</a><span class="code-text">There can be many variables with the same name, but different scopes. When you :ref:`use a variable &lt;expand-variable&gt;`, the smallest scoped variable of that name will be used. If a local variable exists, it will be used instead of the global or universal variable of the same name.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1201" href="#L1201">1201</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1202" href="#L1202">1202</a><span class="code-text">Example:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1203" href="#L1203">1203</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1204" href="#L1204">1204</a><span class="code-text">There are a few possible uses for different scopes.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1205" href="#L1205">1205</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1206" href="#L1206">1206</a><span class="code-text">Typically inside functions you should use local scope::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1207" href="#L1207">1207</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1208" href="#L1208">1208</a><span class="code-text">    function something</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1209" href="#L1209">1209</a><span class="code-text">        set -l file /path/to/my/file</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1210" href="#L1210">1210</a><span class="code-text">        if not test -e &quot;$file&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1211" href="#L1211">1211</a><span class="code-text">            set file /path/to/my/otherfile</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1212" href="#L1212">1212</a><span class="code-text">        end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1213" href="#L1213">1213</a><span class="code-text">    end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1214" href="#L1214">1214</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1215" href="#L1215">1215</a><span class="code-text">    # or</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1216" href="#L1216">1216</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1217" href="#L1217">1217</a><span class="code-text">    function something</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1218" href="#L1218">1218</a><span class="code-text">        if test -e /path/to/my/file</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1219" href="#L1219">1219</a><span class="code-text">            set -f file /path/to/my/file</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1220" href="#L1220">1220</a><span class="code-text">        else</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1221" href="#L1221">1221</a><span class="code-text">            set -f file /path/to/my/otherfile</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1222" href="#L1222">1222</a><span class="code-text">        end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1223" href="#L1223">1223</a><span class="code-text">    end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1224" href="#L1224">1224</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1225" href="#L1225">1225</a><span class="code-text">If you want to set something in config.fish, or set something in a function and have it available for the rest of the session, global scope is a good choice::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1226" href="#L1226">1226</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1227" href="#L1227">1227</a><span class="code-text">    # Don't shorten the working directory in the prompt</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1228" href="#L1228">1228</a><span class="code-text">    set -g fish_prompt_pwd_dir_length 0</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1229" href="#L1229">1229</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1230" href="#L1230">1230</a><span class="code-text">    # Set my preferred cursor style:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1231" href="#L1231">1231</a><span class="code-text">    function setcursors</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1232" href="#L1232">1232</a><span class="code-text">       set -g fish_cursor_default block</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1233" href="#L1233">1233</a><span class="code-text">       set -g fish_cursor_insert line</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1234" href="#L1234">1234</a><span class="code-text">       set -g fish_cursor_visual underscore</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1235" href="#L1235">1235</a><span class="code-text">    end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1236" href="#L1236">1236</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1237" href="#L1237">1237</a><span class="code-text">    # Set my language</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1238" href="#L1238">1238</a><span class="code-text">    set -gx LANG de_DE.UTF-8</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1239" href="#L1239">1239</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1240" href="#L1240">1240</a><span class="code-text">Here is an example of local vs function-scoped variables::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1241" href="#L1241">1241</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1242" href="#L1242">1242</a><span class="code-text">  function test-scopes</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1243" href="#L1243">1243</a><span class="code-text">      begin</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1244" href="#L1244">1244</a><span class="code-text">          # This is a nice local scope where all variables will die</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1245" href="#L1245">1245</a><span class="code-text">          set -l pirate 'There be treasure in them thar hills'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1246" href="#L1246">1246</a><span class="code-text">          set -f captain Space, the final frontier</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1247" href="#L1247">1247</a><span class="code-text">          # If no variable of that name was defined, it is function-local.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1248" href="#L1248">1248</a><span class="code-text">          set gnu &quot;In the beginning there was nothing, which exploded&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1249" href="#L1249">1249</a><span class="code-text">      end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1250" href="#L1250">1250</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1251" href="#L1251">1251</a><span class="code-text">      # This will not output anything, since the pirate was local</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1252" href="#L1252">1252</a><span class="code-text">      echo $pirate</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1253" href="#L1253">1253</a><span class="code-text">      # This will output the good Captain's speech</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1254" href="#L1254">1254</a><span class="code-text">      # since $captain had function-scope.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1255" href="#L1255">1255</a><span class="code-text">      echo $captain</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1256" href="#L1256">1256</a><span class="code-text">      # This will output Sir Terry's wisdom.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1257" href="#L1257">1257</a><span class="code-text">      echo $gnu</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1258" href="#L1258">1258</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1259" href="#L1259">1259</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1260" href="#L1260">1260</a><span class="code-text">When a function calls another, local variables aren't visible::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1261" href="#L1261">1261</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1262" href="#L1262">1262</a><span class="code-text">    function shiver</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1263" href="#L1263">1263</a><span class="code-text">        set phrase 'Shiver me timbers'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1264" href="#L1264">1264</a><span class="code-text">    end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1265" href="#L1265">1265</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1266" href="#L1266">1266</a><span class="code-text">    function avast</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1267" href="#L1267">1267</a><span class="code-text">        set --local phrase 'Avast, mateys'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1268" href="#L1268">1268</a><span class="code-text">        # Calling the shiver function here can not</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1269" href="#L1269">1269</a><span class="code-text">        # change any variables in the local scope</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1270" href="#L1270">1270</a><span class="code-text">        # so phrase remains as we set it here.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1271" href="#L1271">1271</a><span class="code-text">        shiver</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1272" href="#L1272">1272</a><span class="code-text">        echo $phrase</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1273" href="#L1273">1273</a><span class="code-text">    end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1274" href="#L1274">1274</a><span class="code-text">    avast</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1275" href="#L1275">1275</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1276" href="#L1276">1276</a><span class="code-text">    # Outputs &quot;Avast, mateys&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1277" href="#L1277">1277</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1278" href="#L1278">1278</a><span class="code-text">When in doubt, use function-scoped variables. When you need to make a variable accessible everywhere, make it global. When you need to persistently store configuration, make it universal. When you want to use a variable only in a short block, make it local.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1279" href="#L1279">1279</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1280" href="#L1280">1280</a><span class="code-text">.. _variables-override:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1281" href="#L1281">1281</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1282" href="#L1282">1282</a><span class="code-text">Overriding variables for a single command</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1283" href="#L1283">1283</a><span class="code-text">^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1284" href="#L1284">1284</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1285" href="#L1285">1285</a><span class="code-text">If you want to override a variable for a single command, you can use &quot;var=val&quot; statements before the command::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1286" href="#L1286">1286</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1287" href="#L1287">1287</a><span class="code-text">  # Call git status on another directory</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1288" href="#L1288">1288</a><span class="code-text">  # (can also be done via `git -C somerepo status`)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1289" href="#L1289">1289</a><span class="code-text">  GIT_DIR=somerepo git status</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1290" href="#L1290">1290</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1291" href="#L1291">1291</a><span class="code-text">Unlike other shells, fish will first set the variable and then perform other expansions on the line, so::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1292" href="#L1292">1292</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1293" href="#L1293">1293</a><span class="code-text">  set foo banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1294" href="#L1294">1294</a><span class="code-text">  foo=gagaga echo $foo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1295" href="#L1295">1295</a><span class="code-text">  # prints gagaga, while in other shells it might print &quot;banana&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1296" href="#L1296">1296</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1297" href="#L1297">1297</a><span class="code-text">Multiple elements can be given in a :ref:`brace expansion&lt;expand-brace&gt;`::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1298" href="#L1298">1298</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1299" href="#L1299">1299</a><span class="code-text">  # Call bash with a reasonable default path.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1300" href="#L1300">1300</a><span class="code-text">  PATH={/usr,}/{s,}bin bash</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1301" href="#L1301">1301</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1302" href="#L1302">1302</a><span class="code-text">Or with a :ref:`glob &lt;expand-wildcard&gt;`::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1303" href="#L1303">1303</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1304" href="#L1304">1304</a><span class="code-text">  # Run vlc on all mp3 files in the current directory</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1305" href="#L1305">1305</a><span class="code-text">  # If no file exists it will still be run with no arguments</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1306" href="#L1306">1306</a><span class="code-text">  mp3s=*.mp3 vlc $mp3s</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1307" href="#L1307">1307</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1308" href="#L1308">1308</a><span class="code-text">Unlike other shells, this does *not* inhibit any lookup (aliases or similar). Calling a command after setting a variable override will result in the exact same command being run.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1309" href="#L1309">1309</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1310" href="#L1310">1310</a><span class="code-text">This syntax is supported since fish 3.1.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1311" href="#L1311">1311</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1312" href="#L1312">1312</a><span class="code-text">.. _variables-universal:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1313" href="#L1313">1313</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1314" href="#L1314">1314</a><span class="code-text">Universal Variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1315" href="#L1315">1315</a><span class="code-text">^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1316" href="#L1316">1316</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1317" href="#L1317">1317</a><span class="code-text">Universal variables are variables that are shared between all the user's fish sessions on the computer.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1318" href="#L1318">1318</a><span class="code-text">All changes to universal variables are persistent and instantly propagated across fish sessions.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1319" href="#L1319">1319</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1320" href="#L1320">1320</a><span class="code-text">:ref:`Universal variables &lt;variables-universal&gt;` are stored in the file ``.config/fish/fish_variables``. Do not edit this file directly, as your edits may be overwritten. Edit the variables through fish scripts or by using fish interactively instead.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1321" href="#L1321">1321</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1322" href="#L1322">1322</a><span class="code-text">Do not append to universal variables in :ref:`config.fish &lt;configuration&gt;`, because these variables will then get longer with each new shell instance. Instead, set them once at the command line.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1323" href="#L1323">1323</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1324" href="#L1324">1324</a><span class="code-text">.. _variables-export:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1325" href="#L1325">1325</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1326" href="#L1326">1326</a><span class="code-text">Exporting variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1327" href="#L1327">1327</a><span class="code-text">^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1328" href="#L1328">1328</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1329" href="#L1329">1329</a><span class="code-text">Variables in fish can be exported, so they will be inherited by any commands started by fish. In particular, this is necessary for variables used to configure external commands like ``PAGER`` or ``GOPATH``, but also for variables that contain general system settings like ``PATH`` or ``LANGUAGE``. If an external command needs to know a variable, it needs to be exported. Exported variables are also often called &quot;environment variables&quot;.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1330" href="#L1330">1330</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1331" href="#L1331">1331</a><span class="code-text">This also applies to fish - when it starts up, it receives environment variables from its parent (usually the terminal). These typically include system configuration like :envvar:`PATH` and :ref:`locale variables &lt;variables-locale&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1332" href="#L1332">1332</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1333" href="#L1333">1333</a><span class="code-text">Variables can be explicitly set to be exported with the ``-x`` or ``--export`` switch, or not exported with the ``-u`` or ``--unexport`` switch.  The exporting rules when setting a variable are similar to the scoping rules for variables - when an option is passed it is respected, otherwise the variable's existing state is used. If no option is passed and the variable didn't exist yet it is not exported.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1334" href="#L1334">1334</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1335" href="#L1335">1335</a><span class="code-text">As a naming convention, exported variables are in uppercase and unexported variables are in lowercase.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1336" href="#L1336">1336</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1337" href="#L1337">1337</a><span class="code-text">For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1338" href="#L1338">1338</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1339" href="#L1339">1339</a><span class="code-text">    set -gx ANDROID_HOME ~/.android # /opt/android-sdk</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1340" href="#L1340">1340</a><span class="code-text">    set -gx CDPATH . ~ (test -e ~/Videos; and echo ~/Videos)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1341" href="#L1341">1341</a><span class="code-text">    set -gx EDITOR emacs -nw</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1342" href="#L1342">1342</a><span class="code-text">    set -gx GOPATH ~/dev/go</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1343" href="#L1343">1343</a><span class="code-text">    set -gx GTK2_RC_FILES &quot;$XDG_CONFIG_HOME/gtk-2.0/gtkrc&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1344" href="#L1344">1344</a><span class="code-text">    set -gx LESSHISTFILE &quot;-&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1345" href="#L1345">1345</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1346" href="#L1346">1346</a><span class="code-text">Note: Exporting is not a :ref:`scope &lt;variables-scope&gt;`, but an additional state. It typically makes sense to make exported variables global as well, but local-exported variables can be useful if you need something more specific than :ref:`Overrides &lt;variables-override&gt;`. They are *copied* to functions so the function can't alter them outside, and still available to commands. Global variables are accessible to functions whether they are exported or not.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1347" href="#L1347">1347</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1348" href="#L1348">1348</a><span class="code-text">.. _variables-lists:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1349" href="#L1349">1349</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1350" href="#L1350">1350</a><span class="code-text">Lists</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1351" href="#L1351">1351</a><span class="code-text">^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1352" href="#L1352">1352</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1353" href="#L1353">1353</a><span class="code-text">fish can store a list (or an &quot;array&quot; if you wish) of multiple strings inside of a variable::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1354" href="#L1354">1354</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1355" href="#L1355">1355</a><span class="code-text">   &gt; set mylist first second third</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1356" href="#L1356">1356</a><span class="code-text">   &gt; printf '%s\n' $mylist # prints each element on its own line</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1357" href="#L1357">1357</a><span class="code-text">   first</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1358" href="#L1358">1358</a><span class="code-text">   second</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1359" href="#L1359">1359</a><span class="code-text">   third</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1360" href="#L1360">1360</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1361" href="#L1361">1361</a><span class="code-text">To access one element of a list, use the index of the element inside of square brackets, like this::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1362" href="#L1362">1362</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1363" href="#L1363">1363</a><span class="code-text">   echo $PATH[3]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1364" href="#L1364">1364</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1365" href="#L1365">1365</a><span class="code-text">List indices start at 1 in fish, not 0 like in other languages. This is because it requires less subtracting of 1 and many common Unix tools like ``seq`` work better with it (``seq 5`` prints 1 to 5, not 0 to 5). An invalid index is silently ignored resulting in no value (not even an empty string, no argument at all).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1366" href="#L1366">1366</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1367" href="#L1367">1367</a><span class="code-text">If you don't use any brackets, all the elements of the list will be passed to the command as separate items. This means you can iterate over a list with ``for``::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1368" href="#L1368">1368</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1369" href="#L1369">1369</a><span class="code-text">    for i in $PATH</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1370" href="#L1370">1370</a><span class="code-text">        echo $i is in the path</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1371" href="#L1371">1371</a><span class="code-text">    end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1372" href="#L1372">1372</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1373" href="#L1373">1373</a><span class="code-text">This goes over every directory in :envvar:`PATH` separately and prints a line saying it is in the path.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1374" href="#L1374">1374</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1375" href="#L1375">1375</a><span class="code-text">To create a variable ``smurf``, containing the items ``blue`` and ``small``, write::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1376" href="#L1376">1376</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1377" href="#L1377">1377</a><span class="code-text">    set smurf blue small</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1378" href="#L1378">1378</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1379" href="#L1379">1379</a><span class="code-text">It is also possible to set or erase individual elements of a list::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1380" href="#L1380">1380</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1381" href="#L1381">1381</a><span class="code-text">    # Set smurf to be a list with the elements 'blue' and 'small'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1382" href="#L1382">1382</a><span class="code-text">    set smurf blue small</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1383" href="#L1383">1383</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1384" href="#L1384">1384</a><span class="code-text">    # Change the second element of smurf to 'evil'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1385" href="#L1385">1385</a><span class="code-text">    set smurf[2] evil</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1386" href="#L1386">1386</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1387" href="#L1387">1387</a><span class="code-text">    # Erase the first element</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1388" href="#L1388">1388</a><span class="code-text">    set -e smurf[1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1389" href="#L1389">1389</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1390" href="#L1390">1390</a><span class="code-text">    # Output 'evil'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1391" href="#L1391">1391</a><span class="code-text">    echo $smurf</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1392" href="#L1392">1392</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1393" href="#L1393">1393</a><span class="code-text">If you specify a negative index when expanding or assigning to a list variable, the index will be taken from the *end* of the list. For example, the index -1 is the last element of the list::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1394" href="#L1394">1394</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1395" href="#L1395">1395</a><span class="code-text">    &gt; set fruit apple orange banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1396" href="#L1396">1396</a><span class="code-text">    &gt; echo $fruit[-1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1397" href="#L1397">1397</a><span class="code-text">    banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1398" href="#L1398">1398</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1399" href="#L1399">1399</a><span class="code-text">    &gt; echo $fruit[-2..-1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1400" href="#L1400">1400</a><span class="code-text">    orange</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1401" href="#L1401">1401</a><span class="code-text">    banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1402" href="#L1402">1402</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1403" href="#L1403">1403</a><span class="code-text">    &gt; echo $fruit[-1..1] # reverses the list</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1404" href="#L1404">1404</a><span class="code-text">    banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1405" href="#L1405">1405</a><span class="code-text">    orange</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1406" href="#L1406">1406</a><span class="code-text">    apple</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1407" href="#L1407">1407</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1408" href="#L1408">1408</a><span class="code-text">As you see, you can use a range of indices, see :ref:`slices &lt;expand-slices&gt;` for details.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1409" href="#L1409">1409</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1410" href="#L1410">1410</a><span class="code-text">All lists are one-dimensional and can't contain other lists, although it is possible to fake nested lists using dereferencing - see :ref:`variable expansion &lt;expand-variable&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1411" href="#L1411">1411</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1412" href="#L1412">1412</a><span class="code-text">When a list is exported as an environment variable, it is either space or colon delimited, depending on whether it is a :ref:`path variable &lt;variables-path&gt;`::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1413" href="#L1413">1413</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1414" href="#L1414">1414</a><span class="code-text">    &gt; set -x smurf blue small</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1415" href="#L1415">1415</a><span class="code-text">    &gt; set -x smurf_PATH forest mushroom</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1416" href="#L1416">1416</a><span class="code-text">    &gt; env | grep smurf</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1417" href="#L1417">1417</a><span class="code-text">    smurf=blue small</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1418" href="#L1418">1418</a><span class="code-text">    smurf_PATH=forest:mushroom</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1419" href="#L1419">1419</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1420" href="#L1420">1420</a><span class="code-text">fish automatically creates lists from all environment variables whose name ends in ``PATH`` (like :envvar:`PATH`, :envvar:`CDPATH` or :envvar:`MANPATH`), by splitting them on colons. Other variables are not automatically split.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1421" href="#L1421">1421</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1422" href="#L1422">1422</a><span class="code-text">Lists can be inspected with the :doc:`count &lt;cmds/count&gt;` or the :doc:`contains &lt;cmds/contains&gt;` commands::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1423" href="#L1423">1423</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1424" href="#L1424">1424</a><span class="code-text">    &gt; count $smurf</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1425" href="#L1425">1425</a><span class="code-text">    2</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1426" href="#L1426">1426</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1427" href="#L1427">1427</a><span class="code-text">    &gt; contains blue $smurf</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1428" href="#L1428">1428</a><span class="code-text">    # blue was found, so it exits with status 0</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1429" href="#L1429">1429</a><span class="code-text">    # (without printing anything)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1430" href="#L1430">1430</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1431" href="#L1431">1431</a><span class="code-text">    &gt; echo $status</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1432" href="#L1432">1432</a><span class="code-text">    0</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1433" href="#L1433">1433</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1434" href="#L1434">1434</a><span class="code-text">    &gt; contains -i blue $smurf</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1435" href="#L1435">1435</a><span class="code-text">    1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1436" href="#L1436">1436</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1437" href="#L1437">1437</a><span class="code-text">A nice thing about lists is that they are passed to commands one element as one argument, so once you've set your list, you can pass it::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1438" href="#L1438">1438</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1439" href="#L1439">1439</a><span class="code-text">  set -l grep_args -r &quot;my string&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1440" href="#L1440">1440</a><span class="code-text">  grep $grep_args . # will run the same as `grep -r &quot;my string&quot;` .</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1441" href="#L1441">1441</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1442" href="#L1442">1442</a><span class="code-text">Unlike other shells, fish does not do &quot;word splitting&quot; - elements in a list stay as they are, even if they contain spaces or tabs.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1443" href="#L1443">1443</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1444" href="#L1444">1444</a><span class="code-text">.. _variables-argv:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1445" href="#L1445">1445</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1446" href="#L1446">1446</a><span class="code-text">Argument Handling</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1447" href="#L1447">1447</a><span class="code-text">^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1448" href="#L1448">1448</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1449" href="#L1449">1449</a><span class="code-text">An important list is ``$argv``, which contains the arguments to a function or script. For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1450" href="#L1450">1450</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1451" href="#L1451">1451</a><span class="code-text">  function myfunction</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1452" href="#L1452">1452</a><span class="code-text">      echo $argv[1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1453" href="#L1453">1453</a><span class="code-text">      echo $argv[3]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1454" href="#L1454">1454</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1455" href="#L1455">1455</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1456" href="#L1456">1456</a><span class="code-text">This function takes whatever arguments it gets and prints the first and third::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1457" href="#L1457">1457</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1458" href="#L1458">1458</a><span class="code-text">  &gt; myfunction first second third</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1459" href="#L1459">1459</a><span class="code-text">  first</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1460" href="#L1460">1460</a><span class="code-text">  third</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1461" href="#L1461">1461</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1462" href="#L1462">1462</a><span class="code-text">  &gt; myfunction apple cucumber banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1463" href="#L1463">1463</a><span class="code-text">  apple</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1464" href="#L1464">1464</a><span class="code-text">  banana</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1465" href="#L1465">1465</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1466" href="#L1466">1466</a><span class="code-text">That covers the positional arguments, but commandline tools often get various options and flags, and $argv would contain them intermingled with the positional arguments. Typical unix argument handling allows short options (``-h``, also grouped like in ``ls -lah``), long options (``--help``) and allows those options to take arguments (``--color=auto`` or ``--position anywhere`` or ``complete -C&quot;git &quot;``) as well as a ``--`` separator to signal the end of options. Handling all of these manually is tricky and error-prone.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1467" href="#L1467">1467</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1468" href="#L1468">1468</a><span class="code-text">A more robust approach to option handling is :doc:`argparse &lt;cmds/argparse&gt;`, which checks the defined options and puts them into various variables, leaving only the positional arguments in $argv. Here's a simple example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1469" href="#L1469">1469</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1470" href="#L1470">1470</a><span class="code-text">  function mybetterfunction</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1471" href="#L1471">1471</a><span class="code-text">      # We tell argparse about -h/--help and -s/--second</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1472" href="#L1472">1472</a><span class="code-text">      # - these are short and long forms of the same option.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1473" href="#L1473">1473</a><span class="code-text">      # The &quot;--&quot; here is mandatory,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1474" href="#L1474">1474</a><span class="code-text">      # it tells it from where to read the arguments.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1475" href="#L1475">1475</a><span class="code-text">      argparse h/help s/second -- $argv</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1476" href="#L1476">1476</a><span class="code-text">      # exit if argparse failed because</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1477" href="#L1477">1477</a><span class="code-text">      # it found an option it didn't recognize</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1478" href="#L1478">1478</a><span class="code-text">      # - it will print an error</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1479" href="#L1479">1479</a><span class="code-text">      or return</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1480" href="#L1480">1480</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1481" href="#L1481">1481</a><span class="code-text">      # If -h or --help is given, we print a little help text and return</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1482" href="#L1482">1482</a><span class="code-text">      if set -ql _flag_help</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1483" href="#L1483">1483</a><span class="code-text">          echo &quot;mybetterfunction [-h|--help] [-s|--second] [ARGUMENT ...]&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1484" href="#L1484">1484</a><span class="code-text">          return 0</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1485" href="#L1485">1485</a><span class="code-text">      end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1486" href="#L1486">1486</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1487" href="#L1487">1487</a><span class="code-text">      # If -s or --second is given, we print the second argument,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1488" href="#L1488">1488</a><span class="code-text">      # not the first and third.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1489" href="#L1489">1489</a><span class="code-text">      # (this is also available as _flag_s because of the short version)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1490" href="#L1490">1490</a><span class="code-text">      if set -ql _flag_second</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1491" href="#L1491">1491</a><span class="code-text">          echo $argv[2]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1492" href="#L1492">1492</a><span class="code-text">      else</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1493" href="#L1493">1493</a><span class="code-text">          echo $argv[1]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1494" href="#L1494">1494</a><span class="code-text">          echo $argv[3]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1495" href="#L1495">1495</a><span class="code-text">      end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1496" href="#L1496">1496</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1497" href="#L1497">1497</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1498" href="#L1498">1498</a><span class="code-text">The options will be *removed* from $argv, so $argv[2] is the second *positional* argument now::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1499" href="#L1499">1499</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1500" href="#L1500">1500</a><span class="code-text">  &gt; mybetterfunction first -s second third</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1501" href="#L1501">1501</a><span class="code-text">  second</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1502" href="#L1502">1502</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1503" href="#L1503">1503</a><span class="code-text">For more information on argparse, like how to handle option arguments, see :doc:`the argparse documentation &lt;cmds/argparse&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1504" href="#L1504">1504</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1505" href="#L1505">1505</a><span class="code-text">.. _variables-path:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1506" href="#L1506">1506</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1507" href="#L1507">1507</a><span class="code-text">PATH variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1508" href="#L1508">1508</a><span class="code-text">^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1509" href="#L1509">1509</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1510" href="#L1510">1510</a><span class="code-text">Path variables are a special kind of variable used to support colon-delimited path lists including :envvar:`PATH`, :envvar:`CDPATH`, :envvar:`MANPATH`, :envvar:`PYTHONPATH`, :envvar:`LANGUAGE` (for :doc:`localization &lt;cmds/_&gt;`) etc. All variables that end in &quot;PATH&quot; (case-sensitive) become PATH variables by default.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1511" href="#L1511">1511</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1512" href="#L1512">1512</a><span class="code-text">PATH variables act as normal lists, except they are implicitly joined and split on colons.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1513" href="#L1513">1513</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1514" href="#L1514">1514</a><span class="code-text">::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1515" href="#L1515">1515</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1516" href="#L1516">1516</a><span class="code-text">    set MYPATH 1 2 3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1517" href="#L1517">1517</a><span class="code-text">    echo &quot;$MYPATH&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1518" href="#L1518">1518</a><span class="code-text">    # 1:2:3</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1519" href="#L1519">1519</a><span class="code-text">    set MYPATH &quot;$MYPATH:4:5&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1520" href="#L1520">1520</a><span class="code-text">    echo $MYPATH</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1521" href="#L1521">1521</a><span class="code-text">    # 1 2 3 4 5</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1522" href="#L1522">1522</a><span class="code-text">    echo &quot;$MYPATH&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1523" href="#L1523">1523</a><span class="code-text">    # 1:2:3:4:5</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1524" href="#L1524">1524</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1525" href="#L1525">1525</a><span class="code-text">Path variables will also be exported in the colon form, so ``set -x MYPATH 1 2 3`` will have external commands see it as ``1:2:3``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1526" href="#L1526">1526</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1527" href="#L1527">1527</a><span class="code-text">::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1528" href="#L1528">1528</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1529" href="#L1529">1529</a><span class="code-text">   &gt; set -gx MYPATH /bin /usr/bin /sbin</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1530" href="#L1530">1530</a><span class="code-text">   &gt; env | grep MYPATH</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1531" href="#L1531">1531</a><span class="code-text">   MYPATH=/bin:/usr/bin:/sbin</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1532" href="#L1532">1532</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1533" href="#L1533">1533</a><span class="code-text">This is for compatibility with other tools. Unix doesn't have variables with multiple elements, the closest thing it has are colon-lists like :envvar:`PATH`. For obvious reasons this means no element can contain a ``:``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1534" href="#L1534">1534</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1535" href="#L1535">1535</a><span class="code-text">Variables can be marked or unmarked as PATH variables via the ``--path`` and ``--unpath`` options to ``set``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1536" href="#L1536">1536</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1537" href="#L1537">1537</a><span class="code-text">.. _variables-special:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1538" href="#L1538">1538</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1539" href="#L1539">1539</a><span class="code-text">Special variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1540" href="#L1540">1540</a><span class="code-text">^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1541" href="#L1541">1541</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1542" href="#L1542">1542</a><span class="code-text">You can change the settings of fish by changing the values of certain variables.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1543" href="#L1543">1543</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1544" href="#L1544">1544</a><span class="code-text">.. envvar:: PATH</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1545" href="#L1545">1545</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1546" href="#L1546">1546</a><span class="code-text">   A list of directories in which to search for commands. This is a common unix variable also used by other tools.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1547" href="#L1547">1547</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1548" href="#L1548">1548</a><span class="code-text">.. envvar:: CDPATH</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1549" href="#L1549">1549</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1550" href="#L1550">1550</a><span class="code-text">   A list of directories in which the :doc:`cd &lt;cmds/cd&gt;` builtin looks for a new directory.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1551" href="#L1551">1551</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1552" href="#L1552">1552</a><span class="code-text">.. describe:: Locale Variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1553" href="#L1553">1553</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1554" href="#L1554">1554</a><span class="code-text">   Locale variables such as :envvar:`LANG`, :envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, :envvar:`LC_NUMERIC` and :envvar:`LC_TIME` set the language option for the shell and subprograms.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1555" href="#L1555">1555</a><span class="code-text">   See the section :ref:`Locale variables &lt;variables-locale&gt;` and :ref:`status language &lt;status-language&gt;` for more information.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1556" href="#L1556">1556</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1557" href="#L1557">1557</a><span class="code-text">.. describe:: Color variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1558" href="#L1558">1558</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1559" href="#L1559">1559</a><span class="code-text">   A number of variable starting with the prefixes ``fish_color`` and ``fish_pager_color``. See :ref:`Variables for changing highlighting colors &lt;variables-color&gt;` for more information.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1560" href="#L1560">1560</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1561" href="#L1561">1561</a><span class="code-text">.. envvar:: fish_term24bit</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1562" href="#L1562">1562</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1563" href="#L1563">1563</a><span class="code-text">   If this is set to 0, fish will not output 24-bit RGB true-color sequences but the nearest color on the 256 color palette (or the 16 color palette, if :envvar:`fish_term256` is 0).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1564" href="#L1564">1564</a><span class="code-text">   See also :doc:`set_color &lt;cmds/set_color&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1565" href="#L1565">1565</a><span class="code-text">   The default is 1 but for historical reasons, fish defaults to behaving as if it was 0 on some terminals that are known to not support true-color sequences.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1566" href="#L1566">1566</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1567" href="#L1567">1567</a><span class="code-text">.. envvar:: fish_term256</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1568" href="#L1568">1568</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1569" href="#L1569">1569</a><span class="code-text">   If this is set to 0 and :envvar:`fish_term24bit` is 0, translate RGB colors down to the 16 color palette.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1570" href="#L1570">1570</a><span class="code-text">   Also, if this is set to 0, :doc:`set_color &lt;cmds/set_color&gt;` commands such as ``set_color ff0000 red`` will prefer the named color.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1571" href="#L1571">1571</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1572" href="#L1572">1572</a><span class="code-text">.. envvar:: fish_ambiguous_width</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1573" href="#L1573">1573</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1574" href="#L1574">1574</a><span class="code-text">   controls the computed width of ambiguous-width characters. This should be set to 1 if your terminal renders these characters as single-width (typical), or 2 if double-width.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1575" href="#L1575">1575</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1576" href="#L1576">1576</a><span class="code-text">.. envvar:: fish_emoji_width</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1577" href="#L1577">1577</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1578" href="#L1578">1578</a><span class="code-text">   controls whether fish assumes emoji render as 2 cells or 1 cell wide. This is necessary because the correct value changed from 1 to 2 in Unicode 9, and some terminals may not be aware. Set this if you see graphical glitching related to emoji (or other &quot;special&quot; characters). It defaults to 2.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1579" href="#L1579">1579</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1580" href="#L1580">1580</a><span class="code-text">.. envvar:: fish_autosuggestion_enabled</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1581" href="#L1581">1581</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1582" href="#L1582">1582</a><span class="code-text">   controls if :ref:`autosuggestions` are enabled. Set it to 0 to disable, anything else to enable. By default they are on.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1583" href="#L1583">1583</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1584" href="#L1584">1584</a><span class="code-text">.. envvar:: fish_transient_prompt</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1585" href="#L1585">1585</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1586" href="#L1586">1586</a><span class="code-text">   If this is set to 1, fish will redraw prompts with a ``--final-rendering`` argument before running a commandline, allowing you to change it before pushing it to the scrollback. This enables :ref:`transient prompts &lt;transient-prompt&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1587" href="#L1587">1587</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1588" href="#L1588">1588</a><span class="code-text">.. envvar:: fish_handle_reflow</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1589" href="#L1589">1589</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1590" href="#L1590">1590</a><span class="code-text">   determines whether fish should try to repaint the commandline when the terminal resizes. In terminals that reflow text this should be disabled. Set it to 1 to enable, anything else to disable.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1591" href="#L1591">1591</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1592" href="#L1592">1592</a><span class="code-text">.. envvar:: fish_key_bindings</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1593" href="#L1593">1593</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1594" href="#L1594">1594</a><span class="code-text">   the name of the function that sets up the keyboard shortcuts for the :ref:`command-line editor &lt;editor&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1595" href="#L1595">1595</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1596" href="#L1596">1596</a><span class="code-text">.. envvar:: fish_escape_delay_ms</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1597" href="#L1597">1597</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1598" href="#L1598">1598</a><span class="code-text">   sets how long fish waits for another key after seeing an escape, to distinguish pressing the escape key from the start of an escape sequence. The default is 30ms. Increasing it increases the latency but allows pressing escape instead of alt for alt+character bindings. For more information, see :ref:`the chapter in the bind documentation &lt;cmd-bind-escape&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1599" href="#L1599">1599</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1600" href="#L1600">1600</a><span class="code-text">.. envvar:: fish_sequence_key_delay_ms</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1601" href="#L1601">1601</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1602" href="#L1602">1602</a><span class="code-text">   sets how long fish waits for another key after seeing a key that is part of a longer sequence, to disambiguate. For instance if you had bound ``\cx\ce`` to open an editor, fish would wait for this long in milliseconds to see a ctrl-e after a ctrl-x. If the time elapses, it will handle it as a ctrl-x (by default this would copy the current commandline to the clipboard). See also :ref:`Key sequences &lt;interactive-key-sequences&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1603" href="#L1603">1603</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1604" href="#L1604">1604</a><span class="code-text">.. envvar:: fish_complete_path</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1605" href="#L1605">1605</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1606" href="#L1606">1606</a><span class="code-text">   determines where fish looks for completion. When trying to complete for a command, fish looks for files in the directories in this variable.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1607" href="#L1607">1607</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1608" href="#L1608">1608</a><span class="code-text">.. envvar:: fish_cursor_selection_mode</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1609" href="#L1609">1609</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1610" href="#L1610">1610</a><span class="code-text">    controls whether the selection is inclusive or exclusive of the character under the cursor (see :ref:`Copy and Paste &lt;killring&gt;`).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1611" href="#L1611">1611</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1612" href="#L1612">1612</a><span class="code-text">.. envvar:: fish_function_path</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1613" href="#L1613">1613</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1614" href="#L1614">1614</a><span class="code-text">   determines where fish looks for functions. When fish :ref:`autoloads &lt;syntax-function-autoloading&gt;` a function, it will look for files in these directories.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1615" href="#L1615">1615</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1616" href="#L1616">1616</a><span class="code-text">.. envvar:: fish_greeting</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1617" href="#L1617">1617</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1618" href="#L1618">1618</a><span class="code-text">   the greeting message printed on startup. This is printed by a function of the same name that can be overridden for more complicated changes (see :doc:`funced &lt;cmds/funced&gt;`)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1619" href="#L1619">1619</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1620" href="#L1620">1620</a><span class="code-text">.. envvar:: fish_history</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1621" href="#L1621">1621</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1622" href="#L1622">1622</a><span class="code-text">   the current history session name. If set, all subsequent commands within an</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1623" href="#L1623">1623</a><span class="code-text">   interactive fish session will be logged to a separate file identified by the value of the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1624" href="#L1624">1624</a><span class="code-text">   variable. If unset, the default session name &quot;fish&quot; is used. If set to an</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1625" href="#L1625">1625</a><span class="code-text">   empty string, history is not saved to disk (but is still available within the interactive</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1626" href="#L1626">1626</a><span class="code-text">   session).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1627" href="#L1627">1627</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1628" href="#L1628">1628</a><span class="code-text">.. envvar:: fish_trace</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1629" href="#L1629">1629</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1630" href="#L1630">1630</a><span class="code-text">   if set and not empty, will cause fish to print commands before they execute, similar to ``set -x`` in bash.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1631" href="#L1631">1631</a><span class="code-text">   The trace is printed to the path given by the `--debug-output` option to fish or the :envvar:`FISH_DEBUG_OUTPUT` variable.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1632" href="#L1632">1632</a><span class="code-text">   It goes to stderr by default.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1633" href="#L1633">1633</a><span class="code-text">   Set it to ``all`` to also trace execution of key bindings, event handlers as well as prompt and title functions.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1634" href="#L1634">1634</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1635" href="#L1635">1635</a><span class="code-text">.. envvar:: FISH_DEBUG</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1636" href="#L1636">1636</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1637" href="#L1637">1637</a><span class="code-text">   Controls which debug categories :command:`fish` enables for output, analogous to the ``--debug`` option.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1638" href="#L1638">1638</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1639" href="#L1639">1639</a><span class="code-text">.. envvar:: FISH_DEBUG_OUTPUT</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1640" href="#L1640">1640</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1641" href="#L1641">1641</a><span class="code-text">   Specifies a file to direct debug output to.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1642" href="#L1642">1642</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1643" href="#L1643">1643</a><span class="code-text">.. envvar:: fish_user_paths</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1644" href="#L1644">1644</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1645" href="#L1645">1645</a><span class="code-text">   a list of directories that are prepended to :envvar:`PATH`. This can be a universal variable.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1646" href="#L1646">1646</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1647" href="#L1647">1647</a><span class="code-text">.. envvar:: umask</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1648" href="#L1648">1648</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1649" href="#L1649">1649</a><span class="code-text">   the current file creation mask. The preferred way to change the umask variable is through the :doc:`umask &lt;cmds/umask&gt;` function. An attempt to set umask to an invalid value will always fail.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1650" href="#L1650">1650</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1651" href="#L1651">1651</a><span class="code-text">.. envvar:: SHELL_PROMPT_PREFIX</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1652" href="#L1652">1652</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1653" href="#L1653">1653</a><span class="code-text">   if set, this string is automatically prepended to the left prompt. This is a standard environment variable that may be set by tools like systemd's ``run0`` to indicate special shell sessions.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1654" href="#L1654">1654</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1655" href="#L1655">1655</a><span class="code-text">.. envvar:: SHELL_PROMPT_SUFFIX</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1656" href="#L1656">1656</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1657" href="#L1657">1657</a><span class="code-text">   if set, this string is automatically appended to the left prompt. This is a standard environment variable that may be set by tools like systemd's ``run0`` to indicate special shell sessions.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1658" href="#L1658">1658</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1659" href="#L1659">1659</a><span class="code-text">.. envvar:: SHELL_WELCOME</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1660" href="#L1660">1660</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1661" href="#L1661">1661</a><span class="code-text">   if set, this string is displayed when an interactive shell starts, after the greeting. This is a standard environment variable that may be set by tools like systemd's ``run0`` to display session information.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1662" href="#L1662">1662</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1663" href="#L1663">1663</a><span class="code-text">.. envvar:: BROWSER</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1664" href="#L1664">1664</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1665" href="#L1665">1665</a><span class="code-text">   your preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1666" href="#L1666">1666</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1667" href="#L1667">1667</a><span class="code-text">fish also provides additional information through the values of certain environment variables. Most of these variables are read-only and their value can't be changed with ``set``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1668" href="#L1668">1668</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1669" href="#L1669">1669</a><span class="code-text">.. envvar:: _</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1670" href="#L1670">1670</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1671" href="#L1671">1671</a><span class="code-text">   the name of the currently running command (though this is deprecated, and the use of ``status current-command`` is preferred).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1672" href="#L1672">1672</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1673" href="#L1673">1673</a><span class="code-text">.. envvar:: argv</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1674" href="#L1674">1674</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1675" href="#L1675">1675</a><span class="code-text">   a list of arguments to the shell or function. ``argv`` is only defined when inside a function call, or if fish was invoked with a list of arguments, like ``fish myscript.fish foo bar``. This variable can be changed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1676" href="#L1676">1676</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1677" href="#L1677">1677</a><span class="code-text">.. envvar:: argv_opts</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1678" href="#L1678">1678</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1679" href="#L1679">1679</a><span class="code-text">   :doc:`argparse &lt;cmds/argparse&gt;` sets this to the list of successfully parsed options, including option-arguments. This variable can be changed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1680" href="#L1680">1680</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1681" href="#L1681">1681</a><span class="code-text">.. envvar:: CMD_DURATION</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1682" href="#L1682">1682</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1683" href="#L1683">1683</a><span class="code-text">   the runtime of the last command in milliseconds.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1684" href="#L1684">1684</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1685" href="#L1685">1685</a><span class="code-text">.. describe:: COLUMNS and LINES</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1686" href="#L1686">1686</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1687" href="#L1687">1687</a><span class="code-text">   the current size of the terminal in height and width. These values are only used by fish if the operating system does not report the size of the terminal. Both variables must be set in that case otherwise a default of 80x24 will be used. They are updated when the window size changes.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1688" href="#L1688">1688</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1689" href="#L1689">1689</a><span class="code-text">.. envvar:: fish_kill_signal</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1690" href="#L1690">1690</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1691" href="#L1691">1691</a><span class="code-text">   the signal that terminated the last foreground job, or 0 if the job exited normally.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1692" href="#L1692">1692</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1693" href="#L1693">1693</a><span class="code-text">.. envvar:: fish_killring</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1694" href="#L1694">1694</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1695" href="#L1695">1695</a><span class="code-text">   a list of entries in fish's :ref:`kill ring &lt;killring&gt;` of cut text.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1696" href="#L1696">1696</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1697" href="#L1697">1697</a><span class="code-text">.. envvar:: fish_read_limit</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1698" href="#L1698">1698</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1699" href="#L1699">1699</a><span class="code-text">   how many bytes fish will process with :doc:`read &lt;cmds/read&gt;` or in a :ref:`command substitution &lt;expand-command-substitution&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1700" href="#L1700">1700</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1701" href="#L1701">1701</a><span class="code-text">.. envvar:: fish_pid</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1702" href="#L1702">1702</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1703" href="#L1703">1703</a><span class="code-text">   the process ID (PID) of the shell.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1704" href="#L1704">1704</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1705" href="#L1705">1705</a><span class="code-text">.. envvar:: fish_terminal_color_theme</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1706" href="#L1706">1706</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1707" href="#L1707">1707</a><span class="code-text">   a read-only variable;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1708" href="#L1708">1708</a><span class="code-text">   set to ``light`` or ``dark`` when the terminal uses a light or dark color theme respectively;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1709" href="#L1709">1709</a><span class="code-text">   set to ``unknown`` if the terminal does not :ref:`report its colors &lt;term-compat-query-background-color&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1710" href="#L1710">1710</a><span class="code-text">   Like :ref:`status terminal &lt;status-terminal&gt;`, this is only populated once the first interactive prompt is shown.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1711" href="#L1711">1711</a><span class="code-text">   This is used in an :ref:`--on-variable event handler &lt;event&gt;` to update :ref:`syntax highlighting &lt;syntax-highlighting&gt;` variables whenever the terminal's color theme changes.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1712" href="#L1712">1712</a><span class="code-text">   See :ref:`here &lt;fish-config-theme-files&gt;` for how to specify ``light`` and ``dark`` variants in your theme.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1713" href="#L1713">1713</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1714" href="#L1714">1714</a><span class="code-text">.. envvar:: history</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1715" href="#L1715">1715</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1716" href="#L1716">1716</a><span class="code-text">   a list containing the last commands that were entered.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1717" href="#L1717">1717</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1718" href="#L1718">1718</a><span class="code-text">.. ENVVAR:: HOME</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1719" href="#L1719">1719</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1720" href="#L1720">1720</a><span class="code-text">   the user's home directory. This variable can be changed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1721" href="#L1721">1721</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1722" href="#L1722">1722</a><span class="code-text">.. envvar:: hostname</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1723" href="#L1723">1723</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1724" href="#L1724">1724</a><span class="code-text">   the machine's hostname.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1725" href="#L1725">1725</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1726" href="#L1726">1726</a><span class="code-text">.. ENVVAR:: IFS</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1727" href="#L1727">1727</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1728" href="#L1728">1728</a><span class="code-text">   the internal field separator that is used for word splitting with the :doc:`read &lt;cmds/read&gt;` builtin. Setting this to the empty string will also disable line splitting in :ref:`command substitution &lt;expand-command-substitution&gt;`. This variable can be changed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1729" href="#L1729">1729</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1730" href="#L1730">1730</a><span class="code-text">.. envvar:: last_pid</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1731" href="#L1731">1731</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1732" href="#L1732">1732</a><span class="code-text">   the process ID (PID) of the last background process.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1733" href="#L1733">1733</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1734" href="#L1734">1734</a><span class="code-text">.. ENVVAR:: PWD</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1735" href="#L1735">1735</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1736" href="#L1736">1736</a><span class="code-text">   the current working directory.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1737" href="#L1737">1737</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1738" href="#L1738">1738</a><span class="code-text">.. envvar:: pipestatus</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1739" href="#L1739">1739</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1740" href="#L1740">1740</a><span class="code-text">   a list of exit statuses of all processes that made up the last executed pipe. See :ref:`exit status &lt;variables-status&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1741" href="#L1741">1741</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1742" href="#L1742">1742</a><span class="code-text">.. ENVVAR:: SHLVL</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1743" href="#L1743">1743</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1744" href="#L1744">1744</a><span class="code-text">   the level of nesting of shells. fish increments this in interactive shells, otherwise it only passes it along.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1745" href="#L1745">1745</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1746" href="#L1746">1746</a><span class="code-text">.. envvar:: status</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1747" href="#L1747">1747</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1748" href="#L1748">1748</a><span class="code-text">   the :ref:`exit status &lt;variables-status&gt;` of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1749" href="#L1749">1749</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1750" href="#L1750">1750</a><span class="code-text">.. envvar:: status_generation</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1751" href="#L1751">1751</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1752" href="#L1752">1752</a><span class="code-text">   the &quot;generation&quot; count of ``$status``. This will be incremented only when the previous command produced an explicit status. (For example, background jobs will not increment this).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1753" href="#L1753">1753</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1754" href="#L1754">1754</a><span class="code-text">.. ENVVAR:: USER</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1755" href="#L1755">1755</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1756" href="#L1756">1756</a><span class="code-text">   the current username. This variable can be changed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1757" href="#L1757">1757</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1758" href="#L1758">1758</a><span class="code-text">.. ENVVAR:: EUID</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1759" href="#L1759">1759</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1760" href="#L1760">1760</a><span class="code-text">   the current effective user id, set by fish at startup. This variable can be changed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1761" href="#L1761">1761</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1762" href="#L1762">1762</a><span class="code-text">.. envvar:: version</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1763" href="#L1763">1763</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1764" href="#L1764">1764</a><span class="code-text">   the version of the currently running fish (also available as ``FISH_VERSION`` for backward compatibility).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1765" href="#L1765">1765</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1766" href="#L1766">1766</a><span class="code-text">As a convention, an uppercase name is usually used for exported variables, while lowercase variables are not exported. (``CMD_DURATION`` is an exception for historical reasons). This rule is not enforced by fish, but it is good coding practice to use casing to distinguish between exported and unexported variables.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1767" href="#L1767">1767</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1768" href="#L1768">1768</a><span class="code-text">fish also uses some variables internally, their name usually starting with ``__fish``. These are internal and should not typically be modified directly.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1769" href="#L1769">1769</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1770" href="#L1770">1770</a><span class="code-text">.. _variables-status:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1771" href="#L1771">1771</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1772" href="#L1772">1772</a><span class="code-text">The status variable</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1773" href="#L1773">1773</a><span class="code-text">^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1774" href="#L1774">1774</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1775" href="#L1775">1775</a><span class="code-text">Whenever a process exits, an exit status is returned to the program that started it (usually the shell). This exit status is an integer number, which tells the calling application how the execution of the command went. In general, a zero exit status means that the command executed without problem, but a non-zero exit status means there was some form of problem.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1776" href="#L1776">1776</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1777" href="#L1777">1777</a><span class="code-text">fish stores the exit status of the last process in the last job to exit in the ``status`` variable.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1778" href="#L1778">1778</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1779" href="#L1779">1779</a><span class="code-text">If fish encounters a problem while executing a command, the status variable may also be set to a specific value:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1780" href="#L1780">1780</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1781" href="#L1781">1781</a><span class="code-text">- 0 is generally the exit status of commands if they successfully performed the requested operation.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1782" href="#L1782">1782</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1783" href="#L1783">1783</a><span class="code-text">- 1 is generally the exit status of commands if they failed to perform the requested operation.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1784" href="#L1784">1784</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1785" href="#L1785">1785</a><span class="code-text">- 121 is generally the exit status of commands if they were supplied with invalid arguments.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1786" href="#L1786">1786</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1787" href="#L1787">1787</a><span class="code-text">- 123 means that the command was not executed because the command name contained invalid characters.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1788" href="#L1788">1788</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1789" href="#L1789">1789</a><span class="code-text">- 124 means that the command was not executed because none of the wildcards in the command produced any matches.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1790" href="#L1790">1790</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1791" href="#L1791">1791</a><span class="code-text">- 125 means that while an executable with the specified name was located, the operating system could not actually execute the command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1792" href="#L1792">1792</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1793" href="#L1793">1793</a><span class="code-text">- 126 means that while a file with the specified name was located, it was not executable.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1794" href="#L1794">1794</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1795" href="#L1795">1795</a><span class="code-text">- 127 means that no function, builtin or command with the given name could be located.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1796" href="#L1796">1796</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1797" href="#L1797">1797</a><span class="code-text">If a process exits through a signal, the exit status will be 128 plus the number of the signal.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1798" href="#L1798">1798</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1799" href="#L1799">1799</a><span class="code-text">The status can be negated with :doc:`not &lt;cmds/not&gt;` (or ``!``), which is useful in a :ref:`condition &lt;syntax-conditional&gt;`. This turns a status of 0 into 1 and any non-zero status into 0.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1800" href="#L1800">1800</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1801" href="#L1801">1801</a><span class="code-text">There is also ``$pipestatus``, which is a list of all ``status`` values of processes in a pipe. One difference is that :doc:`not &lt;cmds/not&gt;` applies to ``$status``, but not ``$pipestatus``, because it loses information.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1802" href="#L1802">1802</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1803" href="#L1803">1803</a><span class="code-text">For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1804" href="#L1804">1804</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1805" href="#L1805">1805</a><span class="code-text">  not cat file | grep -q fish</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1806" href="#L1806">1806</a><span class="code-text">  echo status is: $status pipestatus is $pipestatus</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1807" href="#L1807">1807</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1808" href="#L1808">1808</a><span class="code-text">Here ``$status`` reflects the status of ``grep``, which returns 0 if it found something, negated with ``not`` (so 1 if it found something, 0 otherwise). ``$pipestatus`` reflects the status of ``cat`` (which returns non-zero for example when it couldn't find the file) and ``grep``, without the negation.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1809" href="#L1809">1809</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1810" href="#L1810">1810</a><span class="code-text">So if both ``cat`` and ``grep`` succeeded, ``$status`` would be 1 because of the ``not``, and ``$pipestatus`` would be 0 and 0.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1811" href="#L1811">1811</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1812" href="#L1812">1812</a><span class="code-text">It's possible for the first command to fail while the second succeeds. One common example is when the second program quits early.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1813" href="#L1813">1813</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1814" href="#L1814">1814</a><span class="code-text">For example, if you have a pipeline like::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1815" href="#L1815">1815</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1816" href="#L1816">1816</a><span class="code-text">  cat file1 file2 | head -n 50</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1817" href="#L1817">1817</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1818" href="#L1818">1818</a><span class="code-text">This will tell ``cat`` to print two files, &quot;file1&quot; and &quot;file2&quot;, one after the other, and the ``head`` will then only print the first 50 lines. In this case you might often see this constellation::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1819" href="#L1819">1819</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1820" href="#L1820">1820</a><span class="code-text">  &gt; cat file1 file2 | head -n 50</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1821" href="#L1821">1821</a><span class="code-text">  # 50 lines of output</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1822" href="#L1822">1822</a><span class="code-text">  &gt; echo $pipestatus</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1823" href="#L1823">1823</a><span class="code-text">  141 0</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1824" href="#L1824">1824</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1825" href="#L1825">1825</a><span class="code-text">Here, the &quot;141&quot; signifies that ``cat`` was killed by signal number 13 (128 + 13 == 141) - a ``SIGPIPE``. You can also use :envvar:`fish_kill_signal` to see the signal number. This happens because it was still working, and then ``head`` closed the pipe, so ``cat`` received a signal that it didn't ignore and so it died.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1826" href="#L1826">1826</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1827" href="#L1827">1827</a><span class="code-text">Whether ``cat`` here will see a SIGPIPE depends on how long the file is and how much it writes at once, so you might see a pipestatus of &quot;0 0&quot;, depending on the implementation. This is a general unix issue and not specific to fish. Some shells feature a &quot;pipefail&quot; feature that will call a pipeline failed if one of the processes in it failed, and this is a big problem with it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1828" href="#L1828">1828</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1829" href="#L1829">1829</a><span class="code-text">.. _variables-locale:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1830" href="#L1830">1830</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1831" href="#L1831">1831</a><span class="code-text">Locale Variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1832" href="#L1832">1832</a><span class="code-text">^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1833" href="#L1833">1833</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1834" href="#L1834">1834</a><span class="code-text">The &quot;locale&quot; of a program is its set of language and regional settings.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1835" href="#L1835">1835</a><span class="code-text">In UNIX, these are made up of several categories. The categories used by fish are:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1836" href="#L1836">1836</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1837" href="#L1837">1837</a><span class="code-text">.. envvar:: LANG</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1838" href="#L1838">1838</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1839" href="#L1839">1839</a><span class="code-text">   This is the typical environment variable for specifying a locale.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1840" href="#L1840">1840</a><span class="code-text">   A user may set this variable to express the language they speak, their region, and a character encoding.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1841" href="#L1841">1841</a><span class="code-text">   The encoding part is ignored, fish always assumes UTF-8. The actual values are specific to their platform, except for special values like ``C`` or ``POSIX``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1842" href="#L1842">1842</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1843" href="#L1843">1843</a><span class="code-text">   The value of ``LANG`` is used for each category unless the variable for that category was set or ``LC_ALL`` is set. So typically you only need to set LANG.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1844" href="#L1844">1844</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1845" href="#L1845">1845</a><span class="code-text">   Example values are ``en_US.UTF-8`` for the American English or ``de_AT.UTF-8`` for Austrian German.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1846" href="#L1846">1846</a><span class="code-text">   Your operating system might have a ``locale`` command that you can call as ``locale -a`` to see a list of defined locales.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1847" href="#L1847">1847</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1848" href="#L1848">1848</a><span class="code-text">.. envvar:: LANGUAGE</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1849" href="#L1849">1849</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1850" href="#L1850">1850</a><span class="code-text">   This is treated like :envvar:`LC_MESSAGES` except that it can hold multiple values,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1851" href="#L1851">1851</a><span class="code-text">   which allows to specify a priority list of languages for translation.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1852" href="#L1852">1852</a><span class="code-text">   It's a :ref:`PATH variable &lt;variables-path&gt;`, like in `GNU gettext &lt;https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html&gt;`__.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1853" href="#L1853">1853</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1854" href="#L1854">1854</a><span class="code-text">   Language identifiers without a region specified (e.g. ``zh``) result in all available variants of this language being tried in arbitrary order.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1855" href="#L1855">1855</a><span class="code-text">   In this example, we might first look for messages in the ``zh_CN`` catalog, followed by ``zh_TW``, or the other way around.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1856" href="#L1856">1856</a><span class="code-text">   This is different from GNU gettext, which uses a &quot;default&quot; variant of the language instead.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1857" href="#L1857">1857</a><span class="code-text">   If you prefer a certain variant, specify it earlier in the list,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1858" href="#L1858">1858</a><span class="code-text">   e.g. ``zh_TW:zh`` if your preferred language is ``zh_TW``, and you prefer any other variants of ``zh`` over the English default.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1859" href="#L1859">1859</a><span class="code-text">   If ``zh_TW`` is the only variant of ``zh`` you want,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1860" href="#L1860">1860</a><span class="code-text">   specifying ``zh_TW`` in the ``LANGUAGE`` variable will result in messages which are not available in ``zh_TW`` being displayed in English.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1861" href="#L1861">1861</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1862" href="#L1862">1862</a><span class="code-text">   See also :doc:`builtin _ (underscore) &lt;cmds/_&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1863" href="#L1863">1863</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1864" href="#L1864">1864</a><span class="code-text">.. envvar:: LC_ALL</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1865" href="#L1865">1865</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1866" href="#L1866">1866</a><span class="code-text">   Overrides the :envvar:`LANG` and all other ``LC_*`` variables.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1867" href="#L1867">1867</a><span class="code-text">   Please use ``LC_ALL`` only as a temporary override.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1868" href="#L1868">1868</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1869" href="#L1869">1869</a><span class="code-text">.. envvar:: LC_MESSAGES</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1870" href="#L1870">1870</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1871" href="#L1871">1871</a><span class="code-text">   Determines the language in which messages are displayed, see :doc:`builtin _ (underscore) &lt;cmds/_&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1872" href="#L1872">1872</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1873" href="#L1873">1873</a><span class="code-text">.. envvar:: LC_NUMERIC</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1874" href="#L1874">1874</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1875" href="#L1875">1875</a><span class="code-text">   Sets the locale for :doc:`formatting numbers &lt;cmds/printf&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1876" href="#L1876">1876</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1877" href="#L1877">1877</a><span class="code-text">.. envvar:: LC_TIME</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1878" href="#L1878">1878</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1879" href="#L1879">1879</a><span class="code-text">   Determines how date and time are displayed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1880" href="#L1880">1880</a><span class="code-text">   Used in the :ref:`history &lt;history-show-time&gt;` builtin.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1881" href="#L1881">1881</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1882" href="#L1882">1882</a><span class="code-text">.. _builtin-overview:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1883" href="#L1883">1883</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1884" href="#L1884">1884</a><span class="code-text">Builtin commands</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1885" href="#L1885">1885</a><span class="code-text">----------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1886" href="#L1886">1886</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1887" href="#L1887">1887</a><span class="code-text">fish includes a number of commands in the shell directly. We call these &quot;builtins&quot;. These include:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1888" href="#L1888">1888</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1889" href="#L1889">1889</a><span class="code-text">- Builtins that manipulate the shell state - :doc:`cd &lt;cmds/cd&gt;` changes directory, :doc:`set &lt;cmds/set&gt;` sets variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1890" href="#L1890">1890</a><span class="code-text">- Builtins for dealing with data, like :doc:`string &lt;cmds/string&gt;` for strings and :doc:`math &lt;cmds/math&gt;` for numbers, :doc:`count &lt;cmds/count&gt;` for counting lines or arguments, :doc:`path &lt;cmds/path&gt;` for dealing with path</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1891" href="#L1891">1891</a><span class="code-text">- :doc:`status &lt;cmds/status&gt;` for asking about the shell's status</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1892" href="#L1892">1892</a><span class="code-text">- :doc:`printf &lt;cmds/printf&gt;` and :doc:`echo &lt;cmds/echo&gt;` for creating output</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1893" href="#L1893">1893</a><span class="code-text">- :doc:`test &lt;cmds/test&gt;` for checking conditions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1894" href="#L1894">1894</a><span class="code-text">- :doc:`argparse &lt;cmds/argparse&gt;` for parsing function arguments</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1895" href="#L1895">1895</a><span class="code-text">- :doc:`source &lt;cmds/source&gt;` to read a script in the current shell (so changes to variables stay) and :doc:`eval &lt;cmds/eval&gt;` to execute a string as script</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1896" href="#L1896">1896</a><span class="code-text">- :doc:`random &lt;cmds/random&gt;` to get random numbers or pick a random element from a list</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1897" href="#L1897">1897</a><span class="code-text">- :doc:`read &lt;cmds/read&gt;` for reading from a pipe or the terminal</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1898" href="#L1898">1898</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1899" href="#L1899">1899</a><span class="code-text">For a list of all builtins, use ``builtin -n``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1900" href="#L1900">1900</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1901" href="#L1901">1901</a><span class="code-text">For a list of all builtins, functions and commands shipped with fish, see the :doc:`list of commands &lt;commands&gt;`. The documentation is also available by using the ``--help`` switch.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1902" href="#L1902">1902</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1903" href="#L1903">1903</a><span class="code-text">Command lookup</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1904" href="#L1904">1904</a><span class="code-text">--------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1905" href="#L1905">1905</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1906" href="#L1906">1906</a><span class="code-text">When fish is told to run something, it goes through multiple steps to find it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1907" href="#L1907">1907</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1908" href="#L1908">1908</a><span class="code-text">If it contains a ``/``, fish tries to execute the given file, from the current directory on.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1909" href="#L1909">1909</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1910" href="#L1910">1910</a><span class="code-text">If it doesn't contain a ``/``, it could be a function, builtin, or external command, and so fish goes through the full lookup.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1911" href="#L1911">1911</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1912" href="#L1912">1912</a><span class="code-text">In order:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1913" href="#L1913">1913</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1914" href="#L1914">1914</a><span class="code-text">1. It tries to resolve it as a :ref:`function &lt;syntax-function&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1915" href="#L1915">1915</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1916" href="#L1916">1916</a><span class="code-text">   - If the function is already known, it uses that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1917" href="#L1917">1917</a><span class="code-text">   - If there is a file of the name with a &quot;.fish&quot; suffix in :envvar:`fish_function_path`, it :ref:`loads that &lt;syntax-function-autoloading&gt;`. (If there is more than one file only the first is used)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1918" href="#L1918">1918</a><span class="code-text">   - If the function is now defined it uses that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1919" href="#L1919">1919</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1920" href="#L1920">1920</a><span class="code-text">2. It tries to resolve it as a :ref:`builtin &lt;builtin-overview&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1921" href="#L1921">1921</a><span class="code-text">3. It tries to find an executable file in :envvar:`PATH`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1922" href="#L1922">1922</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1923" href="#L1923">1923</a><span class="code-text">   - If it finds a file, it tells the kernel to run it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1924" href="#L1924">1924</a><span class="code-text">   - If the kernel knows how to run the file (e.g. via a ``#!`` line - ``#!/bin/sh`` or ``#!/usr/bin/python``), it does it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1925" href="#L1925">1925</a><span class="code-text">   - If the kernel reports that it couldn't run it because of a missing interpreter, and the file passes a rudimentary check, fish tells ``/bin/sh`` to run it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1926" href="#L1926">1926</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1927" href="#L1927">1927</a><span class="code-text">If none of these work, fish runs the function :doc:`fish_command_not_found &lt;cmds/fish_command_not_found&gt;` and sets :envvar:`status` to 127.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1928" href="#L1928">1928</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1929" href="#L1929">1929</a><span class="code-text">You can use :doc:`type &lt;cmds/type&gt;` to see how fish resolved something::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1930" href="#L1930">1930</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1931" href="#L1931">1931</a><span class="code-text">  &gt; type --short --all echo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1932" href="#L1932">1932</a><span class="code-text">  echo is a builtin</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1933" href="#L1933">1933</a><span class="code-text">  echo is /usr/bin/echo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1934" href="#L1934">1934</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1935" href="#L1935">1935</a><span class="code-text">.. _user-input:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1936" href="#L1936">1936</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1937" href="#L1937">1937</a><span class="code-text">Querying for user input</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1938" href="#L1938">1938</a><span class="code-text">-----------------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1939" href="#L1939">1939</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1940" href="#L1940">1940</a><span class="code-text">Sometimes, you want to ask the user for input, for instance to confirm something. This can be done with the :doc:`read &lt;cmds/read&gt;` builtin.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1941" href="#L1941">1941</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1942" href="#L1942">1942</a><span class="code-text">Let's make up an example. This function will :ref:`glob &lt;expand-wildcard&gt;` the files in all the directories it gets as :ref:`arguments &lt;variables-argv&gt;`, and :ref:`if &lt;syntax-conditional&gt;` there are :doc:`more than five &lt;cmds/test&gt;` it will ask the user if it is supposed to show them, but only if it is connected to a terminal::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1943" href="#L1943">1943</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1944" href="#L1944">1944</a><span class="code-text">    function show_files</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1945" href="#L1945">1945</a><span class="code-text">        # This will glob on all arguments. Any non-directories will be ignored.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1946" href="#L1946">1946</a><span class="code-text">        set -l files $argv/*</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1947" href="#L1947">1947</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1948" href="#L1948">1948</a><span class="code-text">        # If there are more than 5 files</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1949" href="#L1949">1949</a><span class="code-text">        if test (count $files) -gt 5</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1950" href="#L1950">1950</a><span class="code-text">            # and both stdin (for reading input)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1951" href="#L1951">1951</a><span class="code-text">            # and stdout (for writing the prompt)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1952" href="#L1952">1952</a><span class="code-text">            # are terminals</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1953" href="#L1953">1953</a><span class="code-text">            and isatty stdin</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1954" href="#L1954">1954</a><span class="code-text">            and isatty stdout</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1955" href="#L1955">1955</a><span class="code-text">            # Keep asking until we get a valid response</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1956" href="#L1956">1956</a><span class="code-text">            while read --nchars 1 -l response --prompt-str=&quot;Are you sure? (y/n)&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1957" href="#L1957">1957</a><span class="code-text">                  or return 1 # if the read was aborted with ctrl-c/ctrl-d</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1958" href="#L1958">1958</a><span class="code-text">                switch $response</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1959" href="#L1959">1959</a><span class="code-text">                    case y Y</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1960" href="#L1960">1960</a><span class="code-text">                        echo Okay</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1961" href="#L1961">1961</a><span class="code-text">                        # We break out of the while and go on with the function</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1962" href="#L1962">1962</a><span class="code-text">                        break</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1963" href="#L1963">1963</a><span class="code-text">                    case n N</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1964" href="#L1964">1964</a><span class="code-text">                        # We return from the function without printing</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1965" href="#L1965">1965</a><span class="code-text">                        echo Not showing</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1966" href="#L1966">1966</a><span class="code-text">                        return 1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1967" href="#L1967">1967</a><span class="code-text">                    case '*'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1968" href="#L1968">1968</a><span class="code-text">                        # We go through the while loop and ask again</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1969" href="#L1969">1969</a><span class="code-text">                        echo Not valid input</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1970" href="#L1970">1970</a><span class="code-text">                        continue</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1971" href="#L1971">1971</a><span class="code-text">                end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1972" href="#L1972">1972</a><span class="code-text">            end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1973" href="#L1973">1973</a><span class="code-text">        end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1974" href="#L1974">1974</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1975" href="#L1975">1975</a><span class="code-text">        # And now we print the files</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1976" href="#L1976">1976</a><span class="code-text">        printf '%s\n' $files</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1977" href="#L1977">1977</a><span class="code-text">    end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1978" href="#L1978">1978</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1979" href="#L1979">1979</a><span class="code-text">If you run this as ``show_files /``, it will most likely ask you until you press Y/y or N/n. If you run this as ``show_files / | cat``, it will print the files without asking. If you run this as ``show_files .``, it might print something without asking because there are fewer than five files.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1980" href="#L1980">1980</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1981" href="#L1981">1981</a><span class="code-text">Shell variable and function names</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1982" href="#L1982">1982</a><span class="code-text">---------------------------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1983" href="#L1983">1983</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1984" href="#L1984">1984</a><span class="code-text">The names given to variables and functions (so-called &quot;identifiers&quot;) have to follow certain rules:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1985" href="#L1985">1985</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1986" href="#L1986">1986</a><span class="code-text">- A variable name cannot be empty. It can contain only letters, digits, and underscores. It may begin and end with any of those characters.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1987" href="#L1987">1987</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1988" href="#L1988">1988</a><span class="code-text">- A function name cannot be empty. It may not begin with a hyphen (&quot;-&quot;) and may not contain a slash (&quot;/&quot;). All other characters, including a space, are valid. A function name also can't be the same as a reserved keyword or essential builtin like ``if`` or ``set``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1989" href="#L1989">1989</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1990" href="#L1990">1990</a><span class="code-text">- A bind mode name (e.g., ``bind -m abc ...``) must be a valid variable name.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1991" href="#L1991">1991</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1992" href="#L1992">1992</a><span class="code-text">Other things have other restrictions. For instance what is allowed for file names depends on your system, but at the very least they cannot contain a &quot;/&quot; (because that is the path separator) or NULL byte (because that is how UNIX ends strings).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1993" href="#L1993">1993</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1994" href="#L1994">1994</a><span class="code-text">.. _configuration:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1995" href="#L1995">1995</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1996" href="#L1996">1996</a><span class="code-text">Configuration files</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1997" href="#L1997">1997</a><span class="code-text">-------------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1998" href="#L1998">1998</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L1999" href="#L1999">1999</a><span class="code-text">When fish is started, it reads and runs its configuration files. Where these are depends on build configuration and environment variables.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2000" href="#L2000">2000</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2001" href="#L2001">2001</a><span class="code-text">The main file is ``~/.config/fish/config.fish`` (or more precisely ``$XDG_CONFIG_HOME/fish/config.fish``).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2002" href="#L2002">2002</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2003" href="#L2003">2003</a><span class="code-text">Configuration files are run in the following order:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2004" href="#L2004">2004</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2005" href="#L2005">2005</a><span class="code-text">- Configuration snippets (named ``*.fish``) in the directories:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2006" href="#L2006">2006</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2007" href="#L2007">2007</a><span class="code-text">  - ``$__fish_config_dir/conf.d`` (by default, ``~/.config/fish/conf.d/``)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2008" href="#L2008">2008</a><span class="code-text">  - ``$__fish_sysconf_dir/conf.d`` (by default, ``/etc/fish/conf.d/``)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2009" href="#L2009">2009</a><span class="code-text">  - Directories for others to ship configuration snippets for their software:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2010" href="#L2010">2010</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2011" href="#L2011">2011</a><span class="code-text">    - the directories under ``$__fish_user_data_dir`` (usually ``~/.local/share/fish``, controlled by the ``XDG_DATA_HOME`` environment variable)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2012" href="#L2012">2012</a><span class="code-text">    - a ``fish/vendor_conf.d`` directory in the directories listed in ``$XDG_DATA_DIRS`` (default ``/usr/share/fish/vendor_conf.d`` and ``/usr/local/share/fish/vendor_conf.d``)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2013" href="#L2013">2013</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2014" href="#L2014">2014</a><span class="code-text">    These directories are also accessible in ``$__fish_vendor_confdirs``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2015" href="#L2015">2015</a><span class="code-text">    Note that changing that in a running fish won't do anything as by that point the directories have already been read.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2016" href="#L2016">2016</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2017" href="#L2017">2017</a><span class="code-text">  If there are multiple files with the same name in these directories, only the first will be executed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2018" href="#L2018">2018</a><span class="code-text">  They are executed in order of their filename, sorted (like globs) in a natural order (i.e. &quot;01&quot; sorts before &quot;2&quot;).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2019" href="#L2019">2019</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2020" href="#L2020">2020</a><span class="code-text">- System-wide configuration files, where administrators can include initialization for all users on the system - similar to ``/etc/profile`` for POSIX-style shells - in ``$__fish_sysconf_dir`` (usually ``/etc/fish/config.fish``).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2021" href="#L2021">2021</a><span class="code-text">- User configuration, usually in ``~/.config/fish/config.fish`` (controlled by the ``XDG_CONFIG_HOME`` environment variable, and accessible as ``$__fish_config_dir``).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2022" href="#L2022">2022</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2023" href="#L2023">2023</a><span class="code-text">``~/.config/fish/config.fish`` is sourced *after* the snippets. This is so you can copy snippets and override some of their behavior.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2024" href="#L2024">2024</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2025" href="#L2025">2025</a><span class="code-text">These files are all executed on the startup of every shell. If you want to run a command only on starting an interactive shell, use the exit status of the command ``status --is-interactive`` to determine if the shell is interactive. If you want to run a command only when using a login shell, use ``status --is-login`` instead. This will speed up the starting of non-interactive or non-login shells.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2026" href="#L2026">2026</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2027" href="#L2027">2027</a><span class="code-text">If you are developing another program, you may want to add configuration for all users of fish on a system. This is discouraged; if not carefully written, they may have side-effects or slow the startup of the shell. Additionally, users of other shells won't benefit from the fish-specific configuration. However, if they are required, you can install them to the &quot;vendor&quot; configuration directory. As this path may vary from system to system, ``pkg-config`` should be used to discover it: ``pkg-config --variable confdir fish``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2028" href="#L2028">2028</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2029" href="#L2029">2029</a><span class="code-text">For system integration, fish also ships a file called ``__fish_build_paths.fish``. This can be customized during build, for instance because your system requires special paths to be used.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2030" href="#L2030">2030</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2031" href="#L2031">2031</a><span class="code-text">.. _featureflags:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2032" href="#L2032">2032</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2033" href="#L2033">2033</a><span class="code-text">Future feature flags</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2034" href="#L2034">2034</a><span class="code-text">--------------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2035" href="#L2035">2035</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2036" href="#L2036">2036</a><span class="code-text">Feature flags are how fish stages changes that might break scripts. Breaking changes are introduced as opt-in, in a few releases they become opt-out, and eventually the old behavior is removed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2037" href="#L2037">2037</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2038" href="#L2038">2038</a><span class="code-text">You can see the current list of features via ``status features``::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2039" href="#L2039">2039</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2040" href="#L2040">2040</a><span class="code-text">    &gt; status features</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2041" href="#L2041">2041</a><span class="code-text">    stderr-nocaret          on  3.0 ^ no longer redirects stderr</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2042" href="#L2042">2042</a><span class="code-text">    qmark-noglob            on  3.0 ? no longer globs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2043" href="#L2043">2043</a><span class="code-text">    regex-easyesc           on  3.1 string replace -r needs fewer \\'s</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2044" href="#L2044">2044</a><span class="code-text">    ampersand-nobg-in-token on  3.4 &amp; only backgrounds if followed by a separating character</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2045" href="#L2045">2045</a><span class="code-text">    remove-percent-self     off 4.0 %self is no longer expanded (use $fish_pid)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2046" href="#L2046">2046</a><span class="code-text">    test-require-arg        off 4.0 builtin test requires an argument</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2047" href="#L2047">2047</a><span class="code-text">    mark-prompt             on  4.0 write OSC 133 prompt markers to the terminal</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2048" href="#L2048">2048</a><span class="code-text">    ignore-terminfo         on  4.1 do not look up $TERM in terminfo database</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2049" href="#L2049">2049</a><span class="code-text">    query-term              on  4.1 query the TTY to enable extra functionality</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2050" href="#L2050">2050</a><span class="code-text">    omit-term-workarounds   off 4.3 skip workarounds for incompatible terminals</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2051" href="#L2051">2051</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2052" href="#L2052">2052</a><span class="code-text">Here is what they mean:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2053" href="#L2053">2053</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2054" href="#L2054">2054</a><span class="code-text">- ``stderr-nocaret`` was introduced in fish 3.0 and cannot be turned off since fish 3.5. It can still be tested for compatibility, but a ``no-stderr-nocaret`` value will be ignored. The flag made ``^`` an ordinary character instead of denoting an stderr redirection. Use ``2&gt;`` instead.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2055" href="#L2055">2055</a><span class="code-text">- ``qmark-noglob`` was also introduced in fish 3.0 (and made the default in 4.0). It makes ``?`` an ordinary character instead of a single-character glob. Use a ``*`` instead (which will match multiple characters) or find other ways to match files like ``find``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2056" href="#L2056">2056</a><span class="code-text">- ``regex-easyesc`` was introduced in 3.1 (and made the default in 3.5). It makes it so the replacement expression in ``string replace -r`` does one fewer round of escaping. Before, to escape a backslash you would have to use ``string replace -ra '([ab])' '\\\\\\\\$1'``. After, just ``'\\\\$1'`` is enough. Check your ``string replace`` calls if you use this anywhere.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2057" href="#L2057">2057</a><span class="code-text">- ``ampersand-nobg-in-token`` was introduced in fish 3.4 (and made the default in 3.5). It makes it so a ``&amp;`` is no longer interpreted as the backgrounding operator in the middle of a token, so dealing with URLs becomes easier. Either put spaces or a semicolon after the ``&amp;``. This is recommended formatting anyway, and ``fish_indent`` will have done it for you already.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2058" href="#L2058">2058</a><span class="code-text">- ``remove-percent-self`` turns off the special ``%self`` expansion. It was introduced in 4.0. To get fish's pid, you can use the :envvar:`fish_pid` variable.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2059" href="#L2059">2059</a><span class="code-text">- ``test-require-arg`` removes :doc:`builtin test &lt;cmds/test&gt;`'s one-argument form (``test &quot;string&quot;``. It was introduced in 4.0. To test if a string is non-empty, use ``test -n &quot;string&quot;``. If disabled, any call to ``test`` that would change sends a :ref:`debug message &lt;debugging-fish&gt;` of category &quot;deprecated-test&quot;, so starting fish with ``fish --debug=deprecated-test`` can be used to find offending calls.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2060" href="#L2060">2060</a><span class="code-text">- ``mark-prompt`` makes fish report to the terminal the beginning and end of both shell prompts and command output.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2061" href="#L2061">2061</a><span class="code-text">- ``ignore-terminfo`` was introduced in fish 4.1 and cannot be turned off since fish 4.5. It can still be tested for compatibility, but a ``no-ignore-terminfo`` value will be ignored. The flag disabled lookup of $TERM in the terminfo database.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2062" href="#L2062">2062</a><span class="code-text">- ``query-term`` allows fish to query the terminal by writing escape sequences and reading the terminal's response.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2063" href="#L2063">2063</a><span class="code-text">  This enables features such as :ref:`scrolling &lt;term-compat-cursor-position-report&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2064" href="#L2064">2064</a><span class="code-text">  If you use an incompatible terminal, you can -- for the time being -- work around it by running (once) ``set -Ua fish_features no-query-term``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2065" href="#L2065">2065</a><span class="code-text">- ``omit-term-workarounds`` prevents fish from trying to work around incompatible terminals.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2066" href="#L2066">2066</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2067" href="#L2067">2067</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2068" href="#L2068">2068</a><span class="code-text">These changes are introduced off by default. They can be enabled on a per session basis::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2069" href="#L2069">2069</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2070" href="#L2070">2070</a><span class="code-text">    &gt; fish --features qmark-noglob,regex-easyesc</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2071" href="#L2071">2071</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2072" href="#L2072">2072</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2073" href="#L2073">2073</a><span class="code-text">or opted into globally for a user::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2074" href="#L2074">2074</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2075" href="#L2075">2075</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2076" href="#L2076">2076</a><span class="code-text">    &gt; set -U fish_features regex-easyesc qmark-noglob</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2077" href="#L2077">2077</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2078" href="#L2078">2078</a><span class="code-text">Features will only be set on startup, so this variable will only take effect if it is universal or exported.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2079" href="#L2079">2079</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2080" href="#L2080">2080</a><span class="code-text">You can also use the version as a group, so ``3.0`` is equivalent to &quot;stderr-nocaret&quot; and &quot;qmark-noglob&quot;. Instead of a version, the special group ``all`` enables all features.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2081" href="#L2081">2081</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2082" href="#L2082">2082</a><span class="code-text">Prefixing a feature with ``no-`` turns it off instead. E.g. to reenable the ``?`` single-character glob::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2083" href="#L2083">2083</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2084" href="#L2084">2084</a><span class="code-text">  set -Ua fish_features no-qmark-noglob</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2085" href="#L2085">2085</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2086" href="#L2086">2086</a><span class="code-text">.. _event:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2087" href="#L2087">2087</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2088" href="#L2088">2088</a><span class="code-text">Event handlers</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2089" href="#L2089">2089</a><span class="code-text">--------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2090" href="#L2090">2090</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2091" href="#L2091">2091</a><span class="code-text">When defining a new function in fish, it is possible to make it into an event handler, i.e. a function that is automatically run when a specific event takes place. Events that can trigger a handler currently are:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2092" href="#L2092">2092</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2093" href="#L2093">2093</a><span class="code-text">- When a signal is delivered</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2094" href="#L2094">2094</a><span class="code-text">- When a job exits</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2095" href="#L2095">2095</a><span class="code-text">- When the value of a variable is updated</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2096" href="#L2096">2096</a><span class="code-text">- When the prompt is about to be shown</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2097" href="#L2097">2097</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2098" href="#L2098">2098</a><span class="code-text">Example:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2099" href="#L2099">2099</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2100" href="#L2100">2100</a><span class="code-text">To specify a signal handler for the WINCH signal, write::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2101" href="#L2101">2101</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2102" href="#L2102">2102</a><span class="code-text">    function my_signal_handler --on-signal WINCH</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2103" href="#L2103">2103</a><span class="code-text">        echo Got WINCH signal!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2104" href="#L2104">2104</a><span class="code-text">    end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2105" href="#L2105">2105</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2106" href="#L2106">2106</a><span class="code-text">fish already has the following named events for the ``--on-event`` switch:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2107" href="#L2107">2107</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2108" href="#L2108">2108</a><span class="code-text">- ``fish_prompt`` is emitted whenever a new fish prompt is about to be displayed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2109" href="#L2109">2109</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2110" href="#L2110">2110</a><span class="code-text">- ``fish_preexec`` is emitted right before executing an interactive command. The commandline is passed as the first parameter. Not emitted if command is empty.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2111" href="#L2111">2111</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2112" href="#L2112">2112</a><span class="code-text">- ``fish_posterror`` is emitted right after executing a command with syntax errors. The commandline is passed as the first parameter.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2113" href="#L2113">2113</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2114" href="#L2114">2114</a><span class="code-text">- ``fish_postexec`` is emitted right after executing an interactive command. The commandline is passed as the first parameter. Not emitted if command is empty.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2115" href="#L2115">2115</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2116" href="#L2116">2116</a><span class="code-text">- ``fish_exit`` is emitted right before fish exits.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2117" href="#L2117">2117</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2118" href="#L2118">2118</a><span class="code-text">- ``fish_cancel`` is emitted when a commandline is cleared.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2119" href="#L2119">2119</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2120" href="#L2120">2120</a><span class="code-text">- ``fish_focus_in`` is emitted when fish's terminal gains focus.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2121" href="#L2121">2121</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2122" href="#L2122">2122</a><span class="code-text">- ``fish_focus_out`` is emitted when fish's terminal loses focus.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2123" href="#L2123">2123</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2124" href="#L2124">2124</a><span class="code-text">Events can be fired with the :doc:`emit &lt;cmds/emit&gt;` command, and do not have to be defined before. The names just need to match. For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2125" href="#L2125">2125</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2126" href="#L2126">2126</a><span class="code-text">  function handler --on-event imdone</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2127" href="#L2127">2127</a><span class="code-text">      echo generator is done $argv</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2128" href="#L2128">2128</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2129" href="#L2129">2129</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2130" href="#L2130">2130</a><span class="code-text">  function generator</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2131" href="#L2131">2131</a><span class="code-text">      sleep 1</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2132" href="#L2132">2132</a><span class="code-text">      # The &quot;imdone&quot; is the name of the event</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2133" href="#L2133">2133</a><span class="code-text">      # the rest is the arguments to pass to the handler</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2134" href="#L2134">2134</a><span class="code-text">      emit imdone with $argv</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2135" href="#L2135">2135</a><span class="code-text">  end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2136" href="#L2136">2136</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2137" href="#L2137">2137</a><span class="code-text">If there are multiple handlers for an event, they will all be run, but the order might change between fish releases, so you should not rely on it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2138" href="#L2138">2138</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2139" href="#L2139">2139</a><span class="code-text">Please note that event handlers only become active when a function is loaded, which means you need to otherwise :doc:`source &lt;cmds/source&gt;` or execute a function instead of relying on :ref:`autoloading &lt;syntax-function-autoloading&gt;`. One approach is to put it into your :ref:`configuration file &lt;configuration&gt;`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2140" href="#L2140">2140</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2141" href="#L2141">2141</a><span class="code-text">For more information on how to define new event handlers, see the documentation for the :doc:`function &lt;cmds/function&gt;` command.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2142" href="#L2142">2142</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2143" href="#L2143">2143</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2144" href="#L2144">2144</a><span class="code-text">.. _debugging:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2145" href="#L2145">2145</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2146" href="#L2146">2146</a><span class="code-text">Debugging fish scripts</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2147" href="#L2147">2147</a><span class="code-text">----------------------</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2148" href="#L2148">2148</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2149" href="#L2149">2149</a><span class="code-text">fish includes basic built-in debugging facilities that allow you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt where you can execute any fish command to inspect or change state (there are no debug commands as such). For example, you can check or change the value of any variables using :doc:`printf &lt;cmds/printf&gt;` and :doc:`set &lt;cmds/set&gt;`. As another example, you can run :doc:`status print-stack-trace &lt;cmds/status&gt;` to see how the current breakpoint was reached. To resume normal execution of the script, type :doc:`exit &lt;cmds/exit&gt;` or :kbd:`ctrl-d`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2150" href="#L2150">2150</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2151" href="#L2151">2151</a><span class="code-text">To start a debug session insert the :doc:`builtin command &lt;cmds/breakpoint&gt;` ``breakpoint`` at the point in a function or script where you wish to gain control, then run the function or script. Also, the default action of the ``TRAP`` signal is to call this builtin, meaning a running script can be actively debugged by sending it the ``TRAP`` signal (``kill -s TRAP &lt;PID&gt;``). There is limited support for interactively setting or modifying breakpoints from this debug prompt: it is possible to insert new breakpoints in (or remove old ones from) other functions by using the ``funced`` function to edit the definition of a function, but it is not possible to add or remove a breakpoint from the function/script currently loaded and being executed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2152" href="#L2152">2152</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2153" href="#L2153">2153</a><span class="code-text">Another way to debug script issues is to set the :envvar:`fish_trace` variable, e.g. ``fish_trace=1 fish_prompt`` to see which commands fish executes when running the :doc:`fish_prompt &lt;cmds/fish_prompt&gt;` function.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2154" href="#L2154">2154</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2155" href="#L2155">2155</a><span class="code-text">.. _profiling:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2156" href="#L2156">2156</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2157" href="#L2157">2157</a><span class="code-text">Profiling fish scripts</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2158" href="#L2158">2158</a><span class="code-text">^^^^^^^^^^^^^^^^^^^^^^</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2159" href="#L2159">2159</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2160" href="#L2160">2160</a><span class="code-text">If you specifically want to debug performance issues, :program:`fish` can be run with the ``--profile /path/to/profile.log`` option to save a profile to the specified path. This profile log includes a breakdown of how long each step in the execution took.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2161" href="#L2161">2161</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2162" href="#L2162">2162</a><span class="code-text">For example::</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2163" href="#L2163">2163</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2164" href="#L2164">2164</a><span class="code-text">  &gt; fish --profile /tmp/sleep.prof -ic 'sleep 3s'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2165" href="#L2165">2165</a><span class="code-text">  &gt; cat /tmp/sleep.prof</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2166" href="#L2166">2166</a><span class="code-text">  Time    Sum     Command</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2167" href="#L2167">2167</a><span class="code-text">  3003419 3003419 &gt; sleep 3s</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2168" href="#L2168">2168</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2169" href="#L2169">2169</a><span class="code-text">This will show the time for each command itself in the first column, the time for the command and every subcommand (like any commands inside of a :ref:`function &lt;syntax-function&gt;` or :ref:`command substitutions &lt;expand-command-substitution&gt;`) in the second and the command itself in the third, separated with tabs.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2170" href="#L2170">2170</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2171" href="#L2171">2171</a><span class="code-text">The time is given in microseconds.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2172" href="#L2172">2172</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2173" href="#L2173">2173</a><span class="code-text">To see the slowest commands last, ``sort -nk2 /path/to/logfile`` is useful.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2174" href="#L2174">2174</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2175" href="#L2175">2175</a><span class="code-text">For profiling fish's startup there is also ``--profile-startup /path/to/logfile``.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2176" href="#L2176">2176</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2177" href="#L2177">2177</a><span class="code-text">See :doc:`fish &lt;cmds/fish&gt;` for more information.</span></span></pre>
</main>
</body>
</html>
