Dive into Fish


Fish is the Friendly Interactive Shell. It also offers a relative clean syntax for shell scripting. (I myself find that rc has a more clean syntax. Fish’s tab completion is powerful. Though plan9 fans may say that we should implement tab completion in terminal emulator.)


help command or command --help.

Syntax overview

command [argument ...]

Commands and arguments are separated by the space character ( ). Every command ends with either a newline or a semicolon (;).

Quotes and escaping

Variable expansions take place in double quoted strings but not in single quoted ones.

Escapes in single quotes: \’ and \.

Escapes in double quotes: \”, \\, and \$.

$ - ? * ~ # ( ) { } [ ] < > ^ & ; ' "

These characters and the space character have special meanings in fish. We need to escape them by prepending them with a backslash. We escape a backslach with another backslash (\).

IO redirection and piping

DESTINATION can be one of the following:

For example, redirect both standard output and standard error to the file all_output.txt:

echo Hello >all_output.txt ^&1

Any FD can be redirected in an arbitrary way by prefixing the redirection with the number of the FD:

Prepend the desired FD number and then output redirect symbol to the pipe. For example:

make fish 2>| less


Functions and conditional structure

See help page for function, if, switch, and, or, for, while, begin, end, etc.

Notes on wrapper functions:


fish suggests commands as you type, based on command history, completions, and valid file paths. As you type commands, you will see a completion offered after the cursor, in a muted gray color.

To accept the autosuggestion (replacing the command line contents), hit right arrow or Control-E.

Tab completion

Fish tab completion list features descriptions of the completions and it is scrollable by arrow keys, page up/page keys, the tab key or the space bar. Pressing any other key will exit the list and insert the pressed key into the command line.

fish provides completions for:

fish provides a large number of program specific completions.

You can write your own builtin. See help complete and /usr/share/fish/completions.

Set variables

set name value1 value2 ...


When calling a function, all current local variables temporarily disappear.

Special variables

Command line expansions


?, *, and ** match non-hidden file names.

Use . as the first character to match hidden files.

Command substitution:


Variable expansion:

$array  # --> multiple arguments
"$array" # --> one argument

Brace expansion:

{$USER}san # Neat, isn't it?

Home directory expansion:


Process expansion:

%self # shell pid
%id  # group id
%user # pids of processes owned by user


$PATH[3] # indices start at 1
(seq 10)[2..5]
(seq 10)[2..5 1..3]
(seq 10)[-1..1]  # Reverse output
$$foo[1] # the same as ${$foo[1]}


Press ‘up’ and ‘down’ to search commands containing the string entered. Press Alt-up and Alt-down, match against the token under the cursor. Press escape to abort.

Config files

Variables definitions: ~/.config/fish/

Function definitions: ~/.config/fish/functions/

Completion definitions: ~/.config/fish/completions/

History file: ~/.config/fish/fish_history.


This work is based on the fish user documentation shipped in the fish distributions:

Copyright (C) 2005 Axel Liljencrantz. Released under the GNU General Public License.