File: //usr/share/doc/fish/tutorial.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
<meta name="generator" content="Doxygen 1.8.8"/>
<title>fish: Tutorial</title>
<link href="user_doc.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top" class="qindex"><!-- do not close this div here, it is closed by doxygen! -->
<a href="http://fishshell.com/"><code>fish</code> shell</a>
|
<a href="index.html">Documentation</a>
|
<a href="tutorial.html">Tutorial</a>
|
<a href="design.html">Design</a>
|
<a href="commands.html">Commands</a>
|
<a href="faq.html">FAQ</a>
|
<a href="license.html">License</a>
<!-- Generated by Doxygen 1.8.8 -->
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Tutorial </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock">
<div class="fish_left_bar">
<div class="logo"></div>
<div class="menu tutorial_menu">
<ul>
<li><a href="#tut_why_fish">Why fish?</a></li>
<li><a href="#tut_learning_Fish">Learning fish</a></li>
<li><a href="#tut_running_commands">Running Commands</a></li>
<li><a href="#tut_getting_help">Getting Help</a></li>
<li><a href="#tut_syntax_highlighting">Syntax Highlighting</a></li>
<li><a href="#tut_wildcards">Wildcards</a></li>
<li><a href="#tut_pipes_and_redirections">Pipes and Redirections</a></li>
<li><a href="#tut_autosuggestions">Autosuggestions</a></li>
<li><a href="#tut_tab_completions">Tab Completions</a></li>
<li><a href="#tut_variables">Variables</a></li>
<li><a href="#tut_exit_status">Exit Status</a></li>
<li><a href="#tut_exports">Shell Variables</a></li>
<li><a href="#tut_lists">Lists</a></li>
<li><a href="#tut_command_substitutions">Command Substitutions</a></li>
<li><a href="#tut_combiners">Combiners (And, Or, Not)</a></li>
<li><a href="#tut_conditionals">Conditionals (If, Else, Switch)</a></li>
<li><a href="#tut_functions">Functions</a></li>
<li><a href="#tut_loops">Loops</a></li>
<li><a href="#tut_prompt">Prompt</a></li>
<li><a href="#tut_path">$PATH</a></li>
<li><a href="#tut_startup">Startup</a></li>
<li><a href="#tut_autoload">Autoloading Functions</a></li>
<li><a href="#tut_universal">Universal Variables</a></li>
<li><a href="#tut_more">Ready for more?</a></li>
</ul>
</div>
</div>
<div class="tutorial fish_right_bar">
<h1 class="interior_title">fish tutorial</h1>
<h1><a class="anchor" id="tut_why_fish"></a>
Why fish?</h1>
<p><code>fish</code> is a fully-equipped command line shell (like bash or zsh) that is smart and user-friendly. <code>fish</code> supports powerful features like syntax highlighting, autosuggestions, and tab completions that just work, with nothing to learn or configure.</p>
<p>If you want to make your command line more productive, more useful, and more fun, without learning a bunch of arcane syntax and configuration options, then <code>fish</code> might be just what you're looking for!</p>
<h1><a class="anchor" id="tut_learning_Fish"></a>
Learning fish</h1>
<p>This tutorial assumes a basic understanding of command line shells and Unix commands, and that you have a working copy of <code>fish</code>.</p>
<p>If you have a strong understanding of other shells, and want to know what <code>fish</code> does differently, search for the magic phrase <em>unlike other shells</em>, which is used to call out important differences.</p>
<p>When you start <code>fish</code>, you should see this:</p>
<pre class="fish cli-dark">
<span class="output">Welcome to fish, the friendly interactive shell</span>
<span class="output">Type <span class="cwd">help</span> for instructions on how to use fish</span>
you<span>@</span>hostname <span class="prompt"><span class="path">~</span>></span><span class="cursor"> </span>
</pre><p><code>fish</code> comes with a default prompt that shows your username, hostname, and working directory. You'll see <a href="#tut_prompt">how to change your prompt</a> further down. From now on, we'll pretend your prompt is just a '<code>></code>' to save space.</p>
<h1><a class="anchor" id="tut_running_commands"></a>
Running Commands</h1>
<p><code>fish</code> runs commands like other shells: you type a command, followed by its arguments. Spaces are separators:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">echo</span> <span class="argument">hello</span> <span class="argument">world</span>
<span class="output">hello world</span>
</pre><p>You can include a literal space in an argument with a backslash, or by using single or double quotes:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary"><span class="argument">mkdir</span></span> <span class="path">My\ Files</span>
<span class="prompt">></span> <span class="binary">cp</span> <span class="path">~/Some\ File</span> <span class="string">'My Files'</span>
<span class="prompt">></span> <span class="binary">ls</span> <span class="string">"My Files"</span>
<span class="output">Some File</span>
</pre><p>Commands can be chained with semicolons.</p>
<h1><a class="anchor" id="tut_getting_help"></a>
Getting Help</h1>
<p><code>fish</code> has excellent help and man pages. Run <code>help</code> to open help in a web browser, and <code>man</code> to open it in a man page. You can also ask for help with a specific command, for example, <code>help set</code> to open in a web browser, or <code>man set</code> to see it in the terminal.</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">man</span> <span class="argument">set</span>
<span class="output">set - handle shell variables</span>
<span class="output"> Synopsis...</span>
</pre><h1><a class="anchor" id="tut_syntax_highlighting"></a>
Syntax Highlighting</h1>
<p>You'll quickly notice that <code>fish</code> performs syntax highlighting as you type. Invalid commands are colored red by default:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="error">/bin/mkd</span>
</pre><p>A command may be invalid because it does not exist, or refers to a file that you cannot execute. When the command becomes valid, it is shown in a different color:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="path">/bin/mkdir</span>
</pre><p><code>fish</code> will underline valid file paths as you type them:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">cat</span> <span class="underline">~/somefi</span><span class="cursor"> </span>
</pre><p>This tells you that there exists a file that starts with '<code>somefi</code>', which is useful feedback as you type.</p>
<p>These colors, and many more, can be changed by running <code>fish_config</code>, or by modifying variables directly.</p>
<h1><a class="anchor" id="tut_wildcards"></a>
Wildcards</h1>
<p><code>fish</code> supports the familiar wildcard <code>*</code>. To list all JPEG files:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">ls</span> <span class="file">*.jpg</span>
<span class="output">lena.jpg</span>
<span class="output">meena.jpg</span>
<span class="output">santa maria.jpg</span>
</pre><p>You can include multiple wildcards:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">ls</span> <span class="file">l*.p*</span>
<span class="output">lena.png</span>
<span class="output">lesson.pdf</span>
</pre><p>Especially powerful is the recursive wildcard ** which searches directories recursively:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">ls</span> <span class="path">/var/**.log</span>
<span class="output">/var/log/system.log</span>
<span class="output">/var/run/sntp.log</span>
</pre><p>If that directory traversal is taking a long time, you can <span class="key"><em>Control</em><span>-</span><b>C</b></span> out of it.</p>
<h1><a class="anchor" id="tut_pipes_and_redirections"></a>
Pipes and Redirections</h1>
<p>You can pipe between commands with the usual vertical bar:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">echo</span> <span class="argument">hello</span> <span class="argument">world</span> <span class="redirect">|</span> <span class="binary">wc</span>
<span class="output"> 1 2 12</span>
</pre><p>stdin and stdout can be redirected via the familiar < and >. Unlike other shells, stderr is redirected with a caret ^</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">grep</span> <span class="argument">fish</span> <span class="redirect">< /etc/shells</span> <span class="redirect">> ~/output.txt</span> <span class="redirect">^ ~/errors.txt</span>
</pre><h1><a class="anchor" id="tut_autosuggestions"></a>
Autosuggestions</h1>
<p><code>fish</code> suggests commands as you type, and shows the suggestion to the right of the cursor, in gray. For example:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="error">/bin/h</span><span class="suggest"><span class="cursor">o</span>stname</span>
</pre><p>It knows about paths and options:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">grep</span> <span class="argument">--i</span><span class="suggest"><span class="cursor">g</span>nore-case</span>
</pre><p>And history too. Type a command once, and you can re-summon it by just typing a few letters:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="error">r</span><span class="suggest"><span class="cursor">s</span>ync -avze ssh . myname<span>@</span>somelonghost.com:/some/long/path/doo/dee/doo/dee/doo</span>
</pre><p>To accept the autosuggestion, hit <span class="key"><b>→</b></span> or <span class="key"><em>Control</em><span>-</span><b>F</b></span>. To accept a single word of the autosuggestion, <span class="key"><em>Alt</em><span>-</span><b>→</b></span> (right arrow). If the autosuggestion is not what you want, just ignore it.</p>
<h1><a class="anchor" id="tut_tab_completions"></a>
Tab Completions</h1>
<p><code>fish</code> comes with a rich set of tab completions, that work "out of the box."</p>
<p>Press <span class="key"><b>Tab</b></span>, and <code>fish</code> will attempt to complete the command, argument, or path:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="error">/pri</span> <span>@</span>key{Tab} → <span class="path">/private/</span>
</pre><p>If there's more than one possibility, it will list them:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="error">~/stuff/s</span> <span>@</span>key{Tab}
<span class="output"><span class="match">~/stuff/s</span>cript.sh <em>(Executable, 4.8kB)</em> <span class="match">~/stuff/s</span>ources/ <em>(Directory)</em></span>
</pre><p>Hit tab again to cycle through the possibilities.</p>
<p><code>fish</code> can also complete many commands, like git branches:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">git</span> <span class="argument">merge</span> <span class="argument">pr</span> <span>@</span>key{Tab} → <span class="binary">git</span> <span class="argument">merge</span> <span class="argument">prompt_designer</span>
<span class="prompt">></span> <span class="binary">git</span> <span class="argument">checkout</span> <span class="argument">b</span> <span>@</span>key{Tab}
<span class="output"><span class="match">b</span>uiltin_list_io_merge <em>(Branch)</em> <span class="match">b</span>uiltin_set_color <em>(Branch)</em> <span class="match">b</span>usted_events <em>(Tag)</em></span>
</pre><p>Try hitting tab and see what <code>fish</code> can do!</p>
<h1><a class="anchor" id="tut_variables"></a>
Variables</h1>
<p>Like other shells, a dollar sign performs variable substitution:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">echo</span> <span class="argument">My</span> <span class="argument">home</span> <span class="argument">directory</span> <span class="argument">is</span> <span class="variable"><span class="operator">$</span>HOME</span>
<span class="output">My home directory is /home/tutorial</span>
</pre><p>Variable substitution also occurs in double quotes, but not single quotes:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">echo</span> <span class="string">"My current directory is $PWD"</span>
<span class="output">My current directory is /home/tutorial</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="string">'My current directory is $PWD'</span>
<span class="output">My current directory is $PWD</span>
</pre><p>Unlike other shells, <code>fish</code> has no dedicated syntax for setting variables. Instead it has an ordinary command: <code>set</code>, which takes a variable name, and then its value.</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">set</span> <span class="argument">name</span> <span class="string">'Mister Noodle'</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>name</span>
<span class="output">Mister Noodle</span>
</pre><p>(Notice the quotes: without them, <code>Mister</code> and <code>Noodle</code> would have been separate arguments, and <code>$name</code> would have been made into a list of two elements.)</p>
<p>Unlike other shells, variables are not further split after substitution:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary"><span class="argument">mkdir</span></span> <span class="variable"><span class="operator">$</span>name</span>
<span class="prompt">></span> <span class="binary">ls</span>
<span class="output">Mister Noodle</span>
</pre><p>In bash, this would have created two directories "Mister" and "Noodle". In <code>fish</code>, it created only one: the variable had the value "Mister Noodle", so that is the argument that was passed to <code>mkdir</code>, spaces and all. Other shells use the term "arrays", rather than lists.</p>
<h1><a class="anchor" id="tut_exit_status"></a>
Exit Status</h1>
<p>Unlike other shells, <code>fish</code> stores the exit status of the last command in <code>$status</code> instead of <code>$?</code>.</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">false</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>status</span>
<span class="output">1</span>
</pre><p>Zero is considered success, and non-zero is failure.</p>
<h1><a class="anchor" id="tut_exports"></a>
Exports (Shell Variables)</h1>
<p>Unlike other shells, <code>fish</code> does not have an export command. Instead, a variable is exported via an option to <code>set</code>, either <code>--export</code> or just <code>-x</code>.</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">set</span> <span class="argument">-x</span> <span class="argument">MyVariable</span> <span class="argument">SomeValue</span>
<span class="prompt">></span> <span class="binary">env</span> <span class="redirect">|</span> <span class="binary">grep</span> <span class="argument">MyVariable</span>
<span class="output"><span class="search_match">MyVariable</span>=SomeValue</span>
</pre><p>You can erase a variable with <code>-e</code> or <code>--erase</code></p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">set</span> <span class="argument">-e</span> <span class="argument">MyVariable</span>
<span class="prompt">></span> <span class="binary">env</span> <span class="redirect">|</span> <span class="binary">grep</span> <span class="argument">MyVariable</span>
<span class="output">(no output)</span>
</pre><h1><a class="anchor" id="tut_lists"></a>
Lists</h1>
<p>The <code>set</code> command above used quotes to ensure that <code>Mister Noodle</code> was one argument. If it had been two arguments, then <code>name</code> would have been a list of length 2. In fact, all variables in <code>fish</code> are really lists, that can contain any number of values, or none at all.</p>
<p>Some variables, like <code>$PWD</code>, only have one value. By convention, we talk about that variable's value, but we really mean its first (and only) value.</p>
<p>Other variables, like <code>$PATH</code>, really do have multiple values. During variable expansion, the variable expands to become multiple arguments:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>PATH</span>
<span class="output">/usr/bin /bin /usr/sbin /sbin /usr/local/bin</span>
</pre><p>Lists cannot contain other lists: there is no recursion. A variable is a list of strings, full stop.</p>
<p>Get the length of a list with <code>count</code>:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">count</span> <span class="variable"><span class="operator">$</span>PATH</span>
<span class="output">5</span>
</pre><p>You can append (or prepend) to a list by setting the list to itself, with some additional arguments. Here we append /usr/local/bin to $PATH:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">set</span> <span class="argument">PATH</span> <span class="variable"><span class="operator">$</span>PATH</span> <span class="path">/usr/local/bin</span>
</pre><p>You can access individual elements with square brackets. Indexing starts at 1 from the beginning, and -1 from the end:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>PATH</span>
<span class="output">/usr/bin /bin /usr/sbin /sbin /usr/local/bin</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>PATH</span><span class="argument">[1]</span>
<span class="output">/usr/bin</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>PATH</span><span class="argument">[-1]</span>
<span class="output">/usr/local/bin</span>
</pre><p>You can also access ranges of elements, known as "slices:"</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>PATH</span><span class="argument">[1..2]</span>
<span class="output">/usr/bin /bin</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>PATH</span><span class="argument">[-1..2]</span>
<span class="output">/usr/local/bin /sbin /usr/sbin /bin</span>
</pre><p>You can iterate over a list (or a slice) with a for loop:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">for</span> <span class="argument">val</span> <span class="command">in</span> <span class="variable"><span class="operator">$</span>PATH</span>
<span class="command">echo</span> <span class="string">"entry: $val"</span>
<span class="command">end</span>
<span class="output">entry: /usr/bin/</span>
<span class="output">entry: /bin</span>
<span class="output">entry: /usr/sbin</span>
<span class="output">entry: /sbin</span>
<span class="output">entry: /usr/local/bin</span>
</pre><p>Lists adjacent to other lists or strings are expanded as <a href="index.html#cartesian-product">cartesian products</a> unless quoted (see <a href="index.html#expand-variable">Variable expansion</a>):</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">set</span> <span class="argument">-l</span> <span class="argument">a</span> <span class="argument">1</span> <span class="argument">2</span> <span class="argument">3</span>
<span class="prompt">></span> <span class="command">set</span> <span class="argument">-l</span> <span class="argument">1</span> <span class="argument">a</span> <span class="argument">b</span> <span class="argument">c</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>a</span><span class="variable"><span class="operator">$</span>1</span>
<span class="output">1a 2a 3a 1b 2b 3b 1c 2c 3c</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>a</span><span class="string">" banana"</span>
<span class="output">1 banana 2 banana 3 banana</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="string">"$a banana"</span>
<span class="output">1 2 3 banana</span>
</pre><p>This is similar to <a href="index.html#expand-brace">Brace expansion</a>.</p>
<h1><a class="anchor" id="tut_command_substitutions"></a>
Command Substitutions</h1>
<p>Command substitutions use the output of one command as an argument to another. Unlike other shells, <code>fish</code> does not use backticks ` for command substitutions. Instead, it uses parentheses:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">echo</span> <span class="argument">In</span> <span class="operator">(</span><span class="command">pwd</span><span class="operator">)</span>, <span class="argument">running</span> <span class="operator">(</span><span class="binary">uname</span><span class="operator">)</span>
<span class="output">In /home/tutorial, running FreeBSD</span>
</pre><p>A common idiom is to capture the output of a command in a variable:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">set</span> <span class="argument">os</span> <span class="operator">(</span><span class="binary">uname</span><span class="operator">)</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>os</span>
<span class="output">Linux</span>
</pre><p>Command substitutions are not expanded within quotes. Instead, you can temporarily close the quotes, add the command substitution, and reopen them, all in the same argument:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">touch</span> <em><span class="string">"testing_"</span></em><span class="operator">(</span><span class="binary">date</span> <span class="argument">+<span>%</span>s</span><span class="operator">)</span><em><span class="string">".txt"</span></em>
<span class="prompt">></span> <span class="binary">ls</span> <span class="file">*.txt</span>
<span class="output">testing_1360099791.txt</span>
</pre><h1><a class="anchor" id="tut_combiners"></a>
Combiners (And, Or, Not)</h1>
<p>Unlike other shells, <code>fish</code> does not have special syntax like && or || to combine commands. Instead it has commands <code>and</code>, <code>or</code>, and <code>not</code>.</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">cp</span> <span class="file">file1.txt</span> <span class="file">file1_bak.txt</span><span class="redirect">;</span> <span class="command">and</span> <span class="command">echo</span> <span class="string">"Backup successful"</span><span class="redirect">;</span> <span class="command">or</span> <span class="command">echo</span> <span class="string">"Backup failed"</span>
<span class="output">Backup failed</span>
</pre><h1><a class="anchor" id="tut_conditionals"></a>
Conditionals (If, Else, Switch)</h1>
<p>Use <code>if</code>, <code>else if</code>, and <code>else</code> to conditionally execute code, based on the exit status of a command.</p>
<pre class="fish cli-dark">
<span class="command">if</span> <span class="binary">grep</span> <span class="argument">fish</span> <span class="path">/etc/shells</span>
<span class="command">echo</span> <span class="argument">Found</span> <span class="argument">fish</span>
<span class="command">else</span> <span class="command">if</span> <span class="binary">grep</span> <span class="argument">bash</span> <span class="path">/etc/shells</span>
<span class="command">echo</span> <span class="argument">Found</span> <span class="argument">bash</span>
<span class="command">else</span>
<span class="command">echo</span> <span class="argument">Got</span> <span class="argument">nothing</span>
<span class="command">end</span>
</pre><p>There is also a <code>switch</code> command:</p>
<pre class="fish cli-dark">
<span class="command">switch</span> <span class="operator">(</span><span class="binary">uname</span><span class="operator">)</span>
<span class="command">case</span> <span class="argument">Linux</span>
<span class="command">echo</span> <span class="argument">Hi</span> <span class="argument">Tux!</span>
<span class="command">case</span> <span class="argument">Darwin</span>
<span class="command">echo</span> <span class="argument">Hi</span> <span class="argument">Hexley!</span>
<span class="command">case</span> <span class="argument">FreeBSD</span> <span class="argument">NetBSD</span> <span class="argument">DragonFly</span>
<span class="command">echo</span> <span class="argument">Hi</span> <span class="argument">Beastie!</span>
<span class="command">case</span> <span class="string">'*'</span>
<span class="command">echo</span> <span class="argument">Hi,</span> <span class="argument">stranger!</span>
<span class="command">end</span>
</pre><p>Note that <code>case</code> does not fall through, and can accept multiple arguments or (quoted) wildcards.</p>
<h1><a class="anchor" id="tut_functions"></a>
Functions</h1>
<p>A <code>fish</code> function is a list of commands, which may optionally take arguments. Unlike other shells, arguments are not passed in "numbered variables" like <code>$1</code>, but instead in a single list <code>$argv</code>. To create a function, use the <code>function</code> builtin:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">function</span> <span class="argument">say_hello</span>
<span class="command">echo</span> <span class="argument">Hello</span> <span class="variable"><span class="operator">$</span>argv</span>
<span class="command">end</span>
<span class="prompt">></span> <span class="argument">say_hello</span>
<span class="output">Hello</span>
<span class="prompt">></span> <span class="argument">say_hello</span> <span class="argument">everybody!</span>
<span class="output">Hello everybody!</span>
</pre><p>Unlike other shells, <code>fish</code> does not have aliases or special prompt syntax. Functions take their place.</p>
<p>You can list the names of all functions with the <code>functions</code> keyword (note the plural!). <code>fish</code> starts out with a number of functions:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">functions</span>
<span class="output">alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, trap, type, umask, up-or-search, vared</span>
</pre><p>You can see the source for any function by passing its name to <code>functions</code>:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">functions</span> <span class="argument">ls</span>
<span class="command">function</span> <span class="argument">ls</span> <span class="argument">--description</span> <span class="string">'List contents of directory'</span>
<span class="command">command</span> <span class="binary">ls</span> <span class="argument">-G</span> <span class="variable"><span class="operator">$</span>argv</span>
<span class="command">end</span>
</pre><h1><a class="anchor" id="tut_loops"></a>
Loops</h1>
<p>While loops:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">while</span> <span class="argument">true</span>
<span class="command">echo</span> <em><span class="string">"Loop forever"</span></em>
<span class="command">end</span>
<span class="output">Loop forever</span>
<span class="output">Loop forever</span>
<span class="output">Loop forever</span>
<span class="output">...</span>
</pre><p>For loops can be used to iterate over a list. For example, a list of files:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">for</span> <span class="argument">file</span> <span class="command">in</span> <span class="file">*.txt</span>
<span class="binary">cp</span> <span class="variable"><span class="operator">$</span>file</span> <span class="variable"><span class="operator">$</span>file</span><span class="argument">.bak</span>
<span class="command">end</span>
</pre><p>Iterating over a list of numbers can be done with <code>seq</code>:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">for</span> <span class="argument">x</span> <span class="command">in</span> <span class="operator">(</span><span class="binary">seq</span> <span class="argument">5</span><span class="operator">)</span>
<span class="binary">touch</span> <span class="argument">file_</span><span class="variable"><span class="operator">$</span>x</span><span class="argument">.txt</span>
<span class="command">end</span>
</pre><h1><a class="anchor" id="tut_prompt"></a>
Prompt</h1>
<p>Unlike other shells, there is no prompt variable like PS1. To display your prompt, <code>fish</code> executes a function with the name <code>fish_prompt</code>, and its output is used as the prompt.</p>
<p>You can define your own prompt:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">function</span> <span class="argument">fish_prompt</span>
<span class="command">echo</span> <span class="string">"New Prompt % "</span>
<span class="command">end</span>
New Prompt % <span class="cursor"> </span>
</pre><p>Multiple lines are OK. Colors can be set via <code>set_color</code>, passing it named ANSI colors, or hex RGB values:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">function</span> <span class="argument">fish_prompt</span>
<span class="command">set_color</span> <span class="argument">purple</span>
<span class="binary">date</span> <span class="string">"+<span>%</span>m/<span>%</span>d/<span>%</span>y"</span>
<span class="command">set_color</span> <span class="argument">FF0</span>
<span class="command">echo</span> <span class="operator">(</span><span class="command">pwd</span><span class="operator">)</span> <span class="string">'>'</span>
<span class="command">set_color</span> <span class="argument">normal</span>
<span class="command">end</span>
<span style="color: purple">02/06/13</span>
<span style="color: #FF0">/home/tutorial ></span><span class="cursor"> </span>
</pre><p>You can choose among some sample prompts by running <code>fish_config prompt</code>. <code>fish</code> also supports RPROMPT through <code>fish_right_prompt</code>.</p>
<h1><a class="anchor" id="tut_path"></a>
$PATH</h1>
<p><code>$PATH</code> is an environment variable containing the directories in which <code>fish</code> searches for commands. Unlike other shells, $PATH is a <a href="#tut_lists">list</a>, not a colon-delimited string.</p>
<p>To prepend /usr/local/bin and /usr/sbin to <code>$PATH</code>, you can write:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">set</span> <span class="argument">PATH</span> <span class="path">/usr/local/bin</span> <span class="path">/usr/sbin</span> <span class="variable"><span class="operator">$</span>PATH</span>
</pre><p>You can do so directly in <code>config.fish</code>, like you might do in other shells with <code>.profile</code>. See <a href="#path_example">this example</a>.</p>
<p>A faster way is to modify the <code>$fish_user_paths</code> <a href="#tut_universal">universal variable</a>, which is automatically prepended to <code>$PATH</code>. For example, to permanently add <code>/usr/local/bin</code> to your <code>$PATH</code>, you could write:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">set</span> <span class="argument">-U</span> <span class="argument">fish_user_paths</span> <span class="path">/usr/local/bin</span> <span class="variable"><span class="operator">$</span>fish_user_paths</span>
</pre><p>The advantage is that you don't have to go mucking around in files: just run this once at the command line, and it will affect the current session and all future instances too. (Note: you should NOT add this line to <code>config.fish</code>. If you do, the variable will get longer each time you run fish!)</p>
<h1><a class="anchor" id="tut_startup"></a>
Startup (Where's .bashrc?)</h1>
<p><code>fish</code> starts by executing commands in <code>~/.config/fish/config.fish</code>. You can create it if it does not exist.</p>
<p>It is possible to directly create functions and variables in <code>config.fish</code> file, using the commands shown above. For example:</p>
<p><a class="anchor" id="path_example"></a> </p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">cat</span> <span class="path">~/.config/fish/config.fish</span>
<span class="command">set</span> <span class="argument">-x</span> <span class="argument">PATH</span> <span class="variable"><span class="operator">$</span>PATH</span> <span class="path">/sbin/</span>
<span class="command">function</span> <span class="argument">ll</span>
<span class="binary">ls</span> <span class="argument">-lh</span> <span class="variable"><span class="operator">$</span>argv</span>
<span class="command">end</span>
</pre><p>However, it is more common and efficient to use autoloading functions and universal variables.</p>
<h1><a class="anchor" id="tut_autoload"></a>
Autoloading Functions</h1>
<p>When <code>fish</code> encounters a command, it attempts to autoload a function for that command, by looking for a file with the name of that command in <code>~/.config/fish/functions/</code>.</p>
<p>For example, if you wanted to have a function <code>ll</code>, you would add a text file <code>ll.fish</code> to <code>~/.config/fish/functions</code>:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">cat</span> <span class="path">~/.config/fish/functions/ll.fish</span>
<span class="command">function</span> <span class="argument">ll</span>
<span class="binary">ls</span> <span class="argument">-lh</span> <span class="variable"><span class="operator">$</span>argv</span>
<span class="command">end</span>
</pre><p>This is the preferred way to define your prompt as well:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">cat</span> <span class="path">~/.config/fish/functions/fish_prompt.fish</span>
<span class="command">function</span> <span class="argument">fish_prompt</span>
<span class="command">echo</span> <span class="operator">(</span><span class="command">pwd</span><span class="operator">)</span> <span class="string">"> "</span>
<span class="command">end</span>
</pre><p>See the documentation for <a href="commands.html#funced">funced</a> and <a href="commands.html#funcsave">funcsave</a> for ways to create these files automatically.</p>
<h1><a class="anchor" id="tut_universal"></a>
Universal Variables</h1>
<p>A universal variable is a variable whose value is shared across all instances of <code>fish</code>, now and in the future – even after a reboot. You can make a variable universal with <code>set -U</code>:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">set</span> <span class="argument">-U</span> <span class="argument">EDITOR</span> <span class="argument">vim</span>
</pre><p>Now in another shell:</p>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>EDITOR</span>
<span class="binary">vim</span>
</pre><h1><a class="anchor" id="tut_more"></a>
Ready for more?</h1>
<p>If you want to learn more about fish, there is <a href="index.html">lots of detailed documentation</a>, an <a href="https://lists.sourceforge.net/lists/listinfo/fish-users">official mailing list</a>, the IRC channel #fish on <code>irc.oftc.net</code>, and the <a href="https://github.com/fish-shell/fish-shell/">github page</a>.</p>
</div>
</div></div><!-- contents -->
</body>
</html>