Defining aliases

function ls
    command ls --color=auto $argv
end

There are a few important things that need to be noted about aliases:

To easily create a function of this form, you can use the alias command. Unlike other shells, this just makes functions - fish has no separate concept of an "alias", we just use the word for a function wrapper like this.

For an alternative, try abbreviations. These are words that are expanded while you type, instead of being actual functions inside the shell.

Autoloading functions

When fish needs to load a function, it searches through any directories in the list variable $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.

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.

By default $fish_function_path contains the following:

If you are unsure, your functions probably belong in ~/.config/fish/functions.

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.

Autoloading also won't work for event handlers, 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 event handlers section for more information.

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.

If you are developing another program and want to install fish functions for it, install them to the "vendor" 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.

Wildcards ("Globbing")

Other shells, such as zsh, have a much richer glob syntax, like **(.) to only match regular files. Fish does not. Instead of reinventing the wheel, use programs like find to look for files. For example:

function ff --description 'Like ** but only returns plain files.'
    # This also ignores .git directories.
    find . \( -name .git -type d -prune \) -o -type f | \
        sed -n -e '/^\.\/\.git$/n' -e 's/^\.\///p'
end

You would then use it in place of ** like this, my_prog (ff), to pass only regular files in or below $PWD to my_prog. [3]

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.

Hidden files (where the name begins with a dot) are not considered when wildcarding unless the wildcard string has a dot in that place.

Examples:

For most commands, if any wildcard fails to expand, the command is not executed, $status is set to nonzero, and a warning is printed. This behavior is like what bash does with shopt -s failglob. There are exactly 4 exceptions, namely set, overriding variables in overrides, count and for. Their globs will instead expand to zero arguments (so the command won't see them at all), like with shopt -s nullglob in bash.

Examples:

# List the .foo files, or warns if there aren't any.
ls *.foo
# List the .foo files, if any.
set foos *.foo
if count $foos >/dev/null
    ls $foos
end

[3]

Technically, unix allows filenames with newlines, and this splits the find output on newlines. If you want to avoid that, use find's -print0 option and string split0.

Variable expansion

In the simplest case, this is just something like:

echo $HOME

which will replace $HOME with the home directory of the current user, and pass it to echo, which will then print it.

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 set:

set my_directory /home/cooluser/mystuff
ls $my_directory
# shows the contents of /home/cooluser/mystuff

For more on how setting variables works, see Shell variables and the following sections.

Sometimes a variable has no value because it is undefined or empty, and it expands to nothing:

echo $nonexistentvariable
# Prints no output.

To separate a variable name from text you can encase the variable within double-quotes or braces:

set WORD cat
echo The plural of $WORD is "$WORD"s
# Prints "The plural of cat is cats" because $WORD is set to "cat".
echo The plural of $WORD is {$WORD}s
# ditto

Without the quotes or braces, fish will try to expand a variable called $WORDs, which may not exist.

The latter syntax {$WORD} is a special case of brace expansion.

If $WORD here is undefined or an empty list, the "s" is not printed. However, it is printed if $WORD is the empty string (like after set WORD "").

Unlike all the other expansions, variable expansion also happens in double quoted strings. Inside double quotes ("these"), 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 path variable - in that case it will use a colon (:) instead [4].

Outside of double quotes, 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.

If a variable expands to nothing, it will cancel out any other strings attached to it. See the cartesian product section for more information.

The $ symbol can also be used multiple times, as a kind of "dereference" operator (the * in C or C++), like in the following code:

set foo a b c
set a 10; set b 20; set c 30
for i in (seq (count $$foo))
    echo $$foo[$i]
end
# Output is:
# 10
# 20
# 30

$$foo[$i] is "the value of the variable named by $foo[$i].

When using this feature together with list brackets, the brackets 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][5] (take the first element of $foo, use it as a variable name, then give the fifth element of that).

[4]

Unlike bash or zsh, which will join with the first character of $IFS (which usually is space).

Command substitution

When you write a command in parenthesis like outercommand (innercommand), the innercommand will be executed first. Its output will be taken and each line given as a separate argument to outercommand, which will then be executed. [5]

If the output is piped to string split or string split0 as the last step, those splits are used as they appear instead of splitting lines.

The exit status of the last run command substitution is available in the status variable if the substitution happens in the context of a set command (so if set -l (something) checks if something returned true).

Only part of the output can be used, see index range expansion for details.

Fish has a default limit of 100 MiB on the data it will read in a command sustitution. 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 read command.

Examples:

# Outputs 'image.png'.
echo (basename image.jpg .jpg).png
# Convert all JPEG files in the current directory to the
# PNG format using the 'convert' program.
for i in *.jpg; convert $i (basename $i .jpg).png; end
# Set the ``data`` variable to the contents of 'data.txt'
# without splitting it into a list.
begin; set -l IFS; set data (cat data.txt); end
# Set ``$data`` to the contents of data, splitting on NUL-bytes.
set data (cat data | string split0)

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 just pass it via a pipe, like:

grep fish myanimallist1 | wc -l

but if you need multiple or the command doesn't read from standard input, "process substitution" is useful. Other shells [6] allow this via foo <(bar) <(baz), and fish uses the psub command:

# Compare just the lines containing "fish" in two files:
diff -u (grep fish myanimallist1 | psub) (grep fish myanimallist2 | psub)

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.

[5]

Setting $IFS to empty will disable line splitting. This is deprecated, use string split instead.

[6]

Bash and Zsh at least, though it is a POSIX extension

Brace expansion

Examples:

> echo input.{c,h,txt}
input.c input.h input.txt
# Move all files with the suffix '.c' or '.h' to the subdirectory src.
> mv *.{c,h} src/
# Make a copy of `file` at `file.bak`.
> cp file{,.bak}
> set -l dogs hot cool cute "good "
> echo {$dogs}dog
hotdog cooldog cutedog good dog

If there is no "," or variable expansion between the curly braces, they will not be expanded:

# This {} isn't special
> echo foo-{}
foo-{}
# This passes "HEAD@{2}" to git
> git reset --hard HEAD@{2}
> echo {{a,b}}
{a} {b} # because the inner brace pair is expanded, but the outer isn't.

If after expansion there is nothing between the braces, the argument will be removed (see the cartesian product section):

> echo foo-{$undefinedvar}
# Output is an empty line, just like a bare `echo`.

If there is nothing between a brace and a comma or two commas, it's interpreted as an empty element:

> echo {,,/usr}/bin
/bin /bin /usr/bin

To use a "," as an element, quote or escape it.

Combining lists (Cartesian Product)

Examples:

# Brace expansion is the most familiar:
# All elements in the brace combine with the parts outside of the braces
>_ echo {good,bad}" apples"
good apples bad apples
# The same thing happens with variable expansion.
>_ set -l a x y z
>_ set -l b 1 2 3
# $a is {x,y,z}, $b is {1,2,3},
# so this is `echo {x,y,z}{1,2,3}`
>_ echo $a$b
x1 y1 z1 x2 y2 z2 x3 y3 z3
# Same thing if something is between the lists
>_ echo $a"-"$b
x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3
# Or a brace expansion and a variable
>_ echo {x,y,z}$b
x1 y1 z1 x2 y2 z2 x3 y3 z3
# A combined brace-variable expansion
>_ echo {$b}word
1word 2word 3word
# Special case: If $c has no elements, this expands to nothing
>_ echo {$c}word
# Output is an empty line

Sometimes this may be unwanted, especially that tokens can disappear after expansion. In those cases, you should double-quote variables - echo "$c"word.

This also happens after command substitution. To avoid tokens disappearing there, make the inner command return a trailing newline, or store the output in a variable and double-quote it.

E.g.

>_ set b 1 2 3
>_ echo (echo x)$b
x1 x2 x3
>_ echo (printf '%s' '')banana
# the printf prints nothing, so this is nothing times "banana",
# which is nothing.
>_ echo (printf '%s\n' '')banana
# the printf prints a newline,
# so the command substitution expands to an empty string,
# so this is `''banana`
banana

This can be quite useful. For example, if you want to go through all the files in all the directories in $PATH, use:

for file in $PATH/*

Because $PATH is a list, this expands to all the files in all the directories in it. And if there are no directories in $PATH, the right answer here is to expand to no files.

Index range expansion

# Make $var a list of four elements
set var one two three four
# Print the second:
echo $var[2]
# prints "two"
# or print the first three:
echo $var[1..3]
# prints "one two three"

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.

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.

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. 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.

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 range in the sequence.

Multiple ranges are also possible, separated with a space.

Some examples:

echo (seq 10)[1 2 3]
# Prints: 1 2 3
# Limit the command substitution output
echo (seq 10)[2..5]
# Uses elements from 2 to 5
# Output is: 2 3 4 5
echo (seq 10)[7..]
# Prints: 7 8 9 10
# Use overlapping ranges:
echo (seq 10)[2..5 1..3]
# Takes elements from 2 to 5 and then elements from 1 to 3
# Output is: 2 3 4 5 1 2 3
# Reverse output
echo (seq 10)[-1..1]
# Uses elements from the last output line to
# the first one in reverse direction
# Output is: 10 9 8 7 6 5 4 3 2 1
# The command substitution has only one line,
# so these will result in empty output:
echo (echo one)[2..-1]
echo (echo one)[-3..1]

The same works when setting or expanding variables:

# Reverse path variable
set PATH $PATH[-1..1]
# or
set PATH[-1..1] $PATH
# Use only n last items of the PATH
set n -3
echo $PATH[$n..-1]

Variables can be used as indices for expansion of variables, like so:

set index 2
set letters a b c d
echo $letters[$index] # returns 'b'

However using variables as indices for command substitution is currently not supported, so:

echo (seq 5)[$index] # This won't work
set sequence (seq 5) # It needs to be written on two lines like this.
echo $sequence[$index] # returns '2'

When using indirect variable expansion with multiple $ ($$name), you have to give all indices up to the variable you want to slice:

> set -l list 1 2 3 4 5
> set -l name list
> echo $$name[1]
1 2 3 4 5
> echo $$name[1..-1][1..3] # or $$name[1][1..3], since $name only has one element.
1 2 3

Home directory expansion

ls ~/Music # lists my music directory
echo ~root # prints root's home directory, probably "/root"

Combining different expansions

When combining multiple parameter expansions, expansions are performed in the following order:

Expansions are performed from right to left, nested bracket expansions are performed from the inside and out.

Example:

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.

Variable scope

Variables can be explicitly set to be universal with the -U or --universal switch, global with the -g or --global switch, or local with the -l or --local switch. The scoping rules when creating or updating a variable are:

There can be many variables with the same name, but different scopes. When you use a variable, 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.

Example:

There are a few possible uses for different scopes.

Typically inside funcions you should use local scope:

function something
    set -l file /path/to/my/file
    if not test -e "$file"
        set file /path/to/my/otherfile
    end
end

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:

# Don't shorten the working directory in the prompt
set -g fish_prompt_pwd_dir_length 0
# Set my preferred cursor style:
function setcursors
   set -g fish_cursor_default block
   set -g fish_cursor_insert line
   set -g fish_cursor_visual underscore
end
# Set my language
set -gx LANG de_DE.UTF-8

If you want to set some personal customization, universal variables are nice:

# Typically you'd run this interactively, fish takes care of keeping it.
set -U fish_color_autosuggestion 555

Here is an example of local vs function-scoped variables:

begin
    # This is a nice local scope where all variables will die
    set -l pirate 'There be treasure in them thar hills'
    set captain Space, the final frontier
end
echo $pirate
# This will not output anything, since the pirate was local
echo $captain
# This will output the good Captain's speech since $captain had function-scope.

Overriding variables for a single command

# Call git status on another directory
# (can also be done via `git -C somerepo status`)
GIT_DIR=somerepo git status

Unlike other shells, fish will first set the variable and then perform other expansions on the line, so:

set foo banana
foo=gagaga echo $foo # prints gagaga, while in other shells it might print "banana"

Multiple elements can be given in a brace expansion:

# Call bash with a reasonable default path.
PATH={/usr,}/{s,}bin bash

Or with a glob:

# Run vlc on all mp3 files in the current directory
# If no file exists it will still be run with no arguments
mp3s=*.mp3 vlc $mp3s

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.

This syntax is supported since fish 3.1.

More on universal variables

To see universal variables in action, start two fish sessions side by side, and issue the following command in one of them set fish_color_cwd blue. Since fish_color_cwd is a universal variable, the color of the current working directory listing in the prompt will instantly change to blue on both terminals.

Universal variables 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.

Do not append to universal variables in config.fish, because these variables will then get longer with each new shell instance. Instead, simply set them once at the command line.

Variable scope for functions

For example:

function shiver
    set phrase 'Shiver me timbers'
end
function avast
    set --local phrase 'Avast, mateys'
    # Calling the shiver function here can not
    # change any variables in the local scope
    shiver
    echo $phrase
end
avast
# Outputs "Avast, mateys"

Exporting variables

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 $PATH and locale variables.

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 identical to the scoping rules for variables:

As a naming convention, exported variables are in uppercase and unexported variables are in lowercase.

For example:

set -gx ANDROID_HOME ~/.android # /opt/android-sdk
set -gx CDPATH . ~ (test -e ~/Videos; and echo ~/Videos)
set -gx EDITOR emacs -nw
set -gx GOPATH ~/dev/go
set -gx GTK2_RC_FILES "$XDG_CONFIG_HOME/gtk-2.0/gtkrc"
set -gx LESSHISTFILE "-"

Note: Exporting is not a scope, 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 Overrides. They are copied to functions so the function can't alter them outside, and still available to commands.

Lists

> set mylist first second third
> printf '%s\n' $mylist # prints each element on its own line
first
second
third

To access one element of a list, use the index of the element inside of square brackets, like this:

echo $PATH[3]

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, just no argument at all).

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:

for i in $PATH
    echo $i is in the path
end

This goes over every directory in $PATH separately and prints a line saying it is in the path.

To create a variable smurf, containing the items blue and small, simply write:

set smurf blue small

It is also possible to set or erase individual elements of a list:

# Set smurf to be a list with the elements 'blue' and 'small'
set smurf blue small
# Change the second element of smurf to 'evil'
set smurf[2] evil
# Erase the first element
set -e smurf[1]
# Output 'evil'
echo $smurf

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:

> set fruit apple orange banana
> echo $fruit[-1]
banana
> echo $fruit[-2..-1]
orange
banana
> echo $fruit[-1..1] # reverses the list
banana
orange
apple

As you see, you can use a range of indices, see index range expansion for details.

All lists are one-dimensional and can't contain other lists, although it is possible to fake nested lists using dereferencing - see variable expansion.

When a list is exported as an environment variable, it is either space or colon delimited, depending on whether it is a path variable:

> set -x smurf blue small
> set -x smurf_PATH forest mushroom
> env | grep smurf
smurf=blue small
smurf_PATH=forest:mushroom

Fish automatically creates lists from all environment variables whose name ends in PATH (like $PATH, $CDPATH or $MANPATH), by splitting them on colons. Other variables are not automatically split.

Lists can be inspected with the count or the contains commands:

count $smurf
# 2
contains blue $smurf
# key found, exits with status 0
> contains -i blue $smurf
1

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 just pass it:

set -l grep_args -r "my string"
grep $grep_args . # will run the same as `grep -r "my string"` .

Unlike other shells, fish does not do "word splitting" - elements in a list stay as they are, even if they contain spaces or tabs.

Argument Handling

function myfunction
    echo $argv[1]
    echo $argv[3]
end

This function takes whatever arguments it gets and prints the first and third:

> myfunction first second third
first
third
> myfunction apple cucumber banana
apple
banana

Commandline tools often get various options and flags and positional arguments, and $argv would contain all of these.

A more robust approach to argument handling is argparse, which checks the defined options and puts them into various variables, leaving only the positional arguments in $argv. Here's a simple example:

function mybetterfunction
    argparse h/help s/second -- $argv
    or return # exit if argparse failed because it found an option it didn't recognize - it will print an error
    # If -h or --help is given, we print a little help text and return
    if set -q _flag_help
        echo "mybetterfunction [-h|--help] [-s|--second] [ARGUMENTS...]"
        return 0
    end
    # If -s or --second is given, we print the second argument,
    # not the first and third.
    if set -q _flag_second
        echo $argv[2]
    else
        echo $argv[1]
        echo $argv[3]
    end
end

The options will be removed from $argv, so $argv[2] is the second positional argument now:

> mybetterfunction first -s second third
second

PATH variables

PATH variables act as normal lists, except they are implicitly joined and split on colons.

set MYPATH 1 2 3
echo "$MYPATH"
# 1:2:3
set MYPATH "$MYPATH:4:5"
echo $MYPATH
# 1 2 3 4 5
echo "$MYPATH"
# 1:2:3:4:5

Variables can be marked or unmarked as PATH variables via the --path and --unpath options to set.

Special variables

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.

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.

Fish also uses some variables internally, their name usually starting with __fish. These are internal and should not typically be modified directly.

The status variable

Fish stores the exit status of the last process in the last job to exit in the status variable.

If fish encounters a problem while executing a command, the status variable may also be set to a specific value:

If a process exits through a signal, the exit status will be 128 plus the number of the signal.

The status can be negated with not (or !), which is useful in a condition. This turns a status of 0 into 1 and any non-zero status into 0.

There is also $pipestatus, which is a list of all status values of processes in a pipe. One difference is that not applies to $status, but not $pipestatus, because it loses information.

For example:

not cat file | grep -q fish
echo status is: $status pipestatus is $pipestatus

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.

So if both cat and grep succeeded, $status would be 1 because of the not, and $pipestatus would be 0 and 0.

Locale variables

The locale variables are: LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC and LC_TIME. These variables work as follows: LC_ALL forces all the aspects of the locale to the specified value. If LC_ALL is set, all other locale variables will be ignored (this is typically not recommended!). The other LC_ variables set the specified aspect of the locale information. LANG is a fallback value, it will be used if none of the LC_ variables are specified.

The most common way to set the locale to use a command like set -gx LANG en_GB.utf8, which sets the current locale to be the English language, as used in Great Britain, using the UTF-8 character set. That way any program that requires one setting differently can easily override just that and doesn't have to resort to LC_ALL. For a list of available locales on your system, try locale -a.

Because it needs to handle output that might include multibyte characters (like e.g. emojis), fish will try to set its own internal LC_CTYPE to one that is UTF8-capable even if given an effective LC_CTYPE of "C" (the default). This prevents issues with e.g. filenames given in autosuggestions even if the user started fish with LC_ALL=C. To turn this handling off, set fish_allow_singlebyte_locale to "1".