rootnroll/demo-fish-shell repository overview

fish⁠ is a fully-equipped command line shell (like bash or zsh) that is smart and user-friendly. fish supports powerful features like syntax highlighting, autosuggestions, and tab completions that just work, with nothing to learn or configure.

⁠Running Commands

fish runs commands like other shells: you type a command, followed by its arguments. Spaces are separators:

> echo hello world
hello world

You can include a literal space in an argument with a backslash, or by using single or double quotes:

> mkdir My\ Files
> cp ~/Some\ File 'My Files'
> ls "My Files"
Some File

Commands can be chained with semicolons.

⁠Getting Help

fish has excellent help and man pages. Run help to open help in a web browser, and man to open it in a man page. You can also ask for help with a specific command, for example, help set to open in a web browser, or man set to see it in the terminal.

> man set
set - handle shell variables
  Synopsis...

⁠Syntax Highlighting

You'll quickly notice that fish performs syntax highlighting as you type. Invalid commands are colored red by default:

> /bin/mkd

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:

> /bin/mkdir

fish will underline valid file paths as you type them:

> cat ~/somefi 

This tells you that there exists a file that starts with somefi, which is useful feedback as you type.

These colors, and many more, can be changed by running fish_config, or by modifying variables directly.

⁠Wildcards

fish supports the familiar wildcard *. To list all JPEG files:

> ls *.jpg
lena.jpg
meena.jpg
santa maria.jpg

You can include multiple wildcards:

> ls l*.p*
lena.png
lesson.pdf

Especially powerful is the recursive wildcard ** which searches directories recursively:

> ls /var/**.log
/var/log/system.log
/var/run/sntp.log

If that directory traversal is taking a long time, you can Control-C out of it.

⁠Pipes and Redirections

You can pipe between commands with the usual vertical bar:

> echo hello world | wc
       1       2      12

stdin and stdout can be redirected via the familiar < and >. Unlike other shells, stderr is redirected with a caret ^

> grep fish < /etc/shells > ~/output.txt ^ ~/errors.txt

⁠Autosuggestions

fish suggests commands as you type, and shows the suggestion to the right of the cursor, in gray. For example:

> /bin/hostname

It knows about paths and options:

> grep --ignore-case

And history too. Type a command once, and you can re-summon it by just typing a few letters:

> r<\@args{ync} \ ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo}

To accept the autosuggestion, hit → or Control-F. To accept a single word of the autosuggestion, Alt-→ (right arrow). If the autosuggestion is not what you want, just ignore it.

⁠Tab Completions

fish comes with a rich set of tab completions, that work "out of the box."

Press Tab, and fish will attempt to complete the command, argument, or path:

> /pri @key{Tab} → /private/

If there's more than one possibility, it will list them:

> ~/stuff/s @key{Tab}
~/stuff/script.sh  (Executable, 4.8kB)  ~/stuff/sources/  (Directory)

Hit tab again to cycle through the possibilities.

fish can also complete many commands, like git branches:

> git merge pr @key{Tab} → git merge prompt_designer
> git checkout b @key{Tab}
builtin_list_io_merge (Branch) builtin_set_color (Branch) busted_events (Tag)

Try hitting tab and see what fish can do!

⁠Variables

Like other shells, a dollar sign performs variable substitution:

> echo My home directory is $HOME
My home directory is /home/tutorial

Variable substitution also occurs in double quotes, but not single quotes:

> echo "My current directory is $PWD"
My current directory is /home/tutorial
> echo 'My current directory is $PWD'
My current directory is $PWD

Unlike other shells, fish has no dedicated syntax for setting variables. Instead it has an ordinary command: set, which takes a variable name, and then its value.

> set name 'Mister Noodle'
> echo $name
Mister Noodle

(Notice the quotes: without them, Mister and Noodle would have been separate arguments, and $name would have been made into a list of two elements.)

Unlike other shells, variables are not further split after substitution:

> mkdir $name
> ls
Mister Noodle

In bash, this would have created two directories "Mister" and "Noodle". In fish, it created only one: the variable had the value "Mister Noodle", so that is the argument that was passed to mkdir, spaces and all. Other shells use the term "arrays", rather than lists.

⁠Exit Status

Unlike other shells, fish stores the exit status of the last command in $status instead of $?.

> false
> echo $status
1

Zero is considered success, and non-zero is failure.

⁠Exports (Shell Variables)

Unlike other shells, fish does not have an export command. Instead, a variable is exported via an option to set, either --export or just -x.

> set -x MyVariable SomeValue
> env | grep MyVariable
MyVariable=SomeValue

You can erase a variable with -e or --erase

> set -e MyVariable
> env | grep MyVariable
(no output)

⁠Lists

The set command above used quotes to ensure that Mister Noodle was one argument. If it had been two arguments, then name would have been a list of length 2. In fact, all variables in fish are really lists, that can contain any number of values, or none at all.

Some variables, like $PWD, only have one value. By convention, we talk about that variable's value, but we really mean its first (and only) value.

Other variables, like $PATH, really do have multiple values. During variable expansion, the variable expands to become multiple arguments:

> echo $PATH
/usr/bin /bin /usr/sbin /sbin /usr/local/bin

Note that there are three environment variables that are automatically split on colons to become lists when fish starts running: PATH, CDPATH, MANPATH. Conversely, they are joined on colons when exported to subcommands. All other environment variables (e.g., LD_LIBRARY_PATH) which have similar semantics are treated as simple strings.

Lists cannot contain other lists: there is no recursion. A variable is a list of strings, full stop.

Get the length of a list with count:

> count $PATH
5

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:

> set PATH $PATH /usr/local/bin

You can access individual elements with square brackets. Indexing starts at 1 from the beginning, and -1 from the end:

> echo $PATH
/usr/bin /bin /usr/sbin /sbin /usr/local/bin
> echo $PATH[1]
/usr/bin
> echo $PATH[-1]
/usr/local/bin

You can also access ranges of elements, known as "slices:"

> echo $PATH[1..2]
/usr/bin /bin
> echo $PATH[-1..2]
/usr/local/bin /sbin /usr/sbin /bin

You can iterate over a list (or a slice) with a for loop:

> for val in $PATH
    echo "entry: $val"
  end
entry: /usr/bin/
entry: /bin
entry: /usr/sbin
entry: /sbin
entry: /usr/local/bin

Lists adjacent to other lists or strings are expanded as cartesian products⁠ unless quoted (see Variable expansion⁠):

> set -l a 1 2 3
> set -l 1 a b c
> echo $a$1
1a 2a 3a 1b 2b 3b 1c 2c 3c
> echo $a" banana"
1 banana 2 banana 3 banana
> echo "$a banana"
1 2 3 banana

This is similar to Brace expansion⁠.

⁠Command Substitutions

Command substitutions use the output of one command as an argument to another. Unlike other shells, fish does not use backticks ` for command substitutions. Instead, it uses parentheses:

> echo In (pwd), running (uname)
In /home/tutorial, running FreeBSD

A common idiom is to capture the output of a command in a variable:

> set os (uname)
> echo $os
Linux

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:

> touch "testing_"(date +%s)".txt"
> ls *.txt
testing_1360099791.txt

Unlike other shells, fish does not split command substitutions on any whitespace (like spaces or tabs), only newlines. This can be an issue with commands like pkg-config that print what is meant to be multiple arguments on a single line. To split it on spaces too, use string split.

> printf '%s\n' (pkg-config --libs gio-2.0)
-lgio-2.0 -lgobject-2.0 -lglib-2.0
> printf '%s\n' (pkg-config --libs gio-2.0 | string split " ")
-lgio-2.0
-lgobject-2.0
-lglib-2.0

⁠Separating Commands (Semicolon)

Like other shells, fish allows multiple commands either on separate lines or the same line.

To write them on the same line, use the semicolon (";"). That means the following two examples are equivalent:

echo fish; echo chips

# or
echo fish
echo chips

⁠Combiners (And, Or, Not)

Unlike other shells, fish does not have special syntax like && or || to combine commands. Instead it has commands and, or, and not.

> cp file1.txt file1_bak.txt; and echo "Backup successful"; or echo "Backup failed"
Backup failed

As mentioned in the section on the semicolon⁠, this can also be written in multiple lines, like so:

cp file1.txt file1_bak.txt
and echo "Backup successful"
or echo "Backup failed"

⁠Conditionals (If, Else, Switch)

Use if, else if, and else to conditionally execute code, based on the exit status of a command.

if grep fish /etc/shells
    echo Found fish
else if grep bash /etc/shells
    echo Found bash
else
    echo Got nothing
end

Combiners⁠ can also be used to make more complex conditions, like

if grep fish /etc/shells; and command -sq fish
    echo fish is installed and configured
end

For even more complex conditions, use begin and end to group parts of them.

There is also a switch command:

switch (uname