FreeBSD Manual Pages

home | help

FISH-DOC(1) fish-shell FISH-DOC(1)

This is the documentation for fish, the friendly interactive shell.

A shell is a program that helps you operate your computer by starting other
programs. fish offers a command-line interface focused on usability and inter-
active use.

Some of the special features of fish are:

• Extensive UI: Syntax highlighting, Autosuggestions, tab completion
and selection lists that can be navigated and filtered.

• No configuration needed: fish is designed to be ready to use immedi-
ately, without requiring extensive configuration.

• Easy scripting: New functions can be added on the fly. The syntax is
easy to learn and use.

This page explains how to install and set up fish and where to get more
information.

WHERE TO GO?
If this is your first time using fish, see the tutorial.

If you are already familiar with other shells like bash and want to see
the scripting differences, see Fish For Bash Users.

For a comprehensive overview of fish's scripting language, see The Fish
Language.

For information on using fish interactively, see Interactive use.

If you need to install fish first, read on, the rest of this document
will tell you how to get, install and configure fish.

INSTALLATION
This section describes how to install, uninstall, start, and exit fish.
It also explains how to make fish the default shell.

Installation
Up-to-date instructions for installing the latest version of fish are
on the fish homepage.

To install the development version of fish, see the instructions on the
project's GitHub page.

Starting and Exiting
Once fish has been installed, open a terminal. If fish is not the de-
fault shell:

• Type fish to start a shell:

> fish

• Type exit to end the session:

> exit

Default Shell
There are multiple ways to switch to fish (or any other shell) as your
default.

The simplest method is to set your terminal emulator (eg GNOME Termi-
nal, Apple's Terminal.app, or Konsole) to start fish directly. See its
configuration and set the program to start to /usr/local/bin/fish (if
that's where fish is installed - substitute another location as appro-
priate).

Alternatively, you can set fish as your login shell so that it will be
started by all terminal logins, including SSH.

WARNING:
Setting fish as your login shell may cause issues, such as an incor-
rect PATH. Some operating systems, including a number of Linux dis-
tributions, require the login shell to be Bourne-compatible and to
read configuration from /etc/profile. fish may not be suitable as a
login shell on these systems.

To change your login shell to fish:

1. Add the shell to /etc/shells with:

> echo /usr/local/bin/fish | sudo tee -a /etc/shells

2. Change your default shell with:

> chsh -s /usr/local/bin/fish

Again, substitute the path to fish for /usr/local/bin/fish - see com-
mand -s fish inside fish. To change it back to another shell, just sub-
stitute /usr/local/bin/fish with /bin/bash, /bin/tcsh or /bin/zsh as
appropriate in the steps above.

Uninstalling
For uninstalling fish: see FAQ: Uninstalling fish.

Shebang Line
Because shell scripts are written in many different languages, they
need to carry information about which interpreter should be used to ex-
ecute them. For this, they are expected to have a first line, the she-
bang line, which names the interpreter executable.

A script written in bash would need a first line like this:

#!/bin/bash

When the shell tells the kernel to execute the file, it will use the
interpreter /bin/bash.

For a script written in another language, just replace /bin/bash with
the interpreter for that language. For example: /usr/bin/python for a
python script, or /usr/local/bin/fish for a fish script, if that is
where you have them installed.

If you want to share your script with others, you might want to use env
to allow for the interpreter to be installed in other locations. For
example:

#!/usr/bin/env fish
echo Hello from fish $version

This will call env, which then goes through PATH to find a program
called "fish". This makes it work, whether fish is installed in (for
example) /usr/local/bin/fish, /usr/bin/fish, or ~/.local/bin/fish, as
long as that directory is in PATH.

The shebang line is only used when scripts are executed without speci-
fying the interpreter. For functions inside fish or when executing a
script with fish /path/to/script, a shebang is not required (but it
doesn't hurt!).

When executing files without an interpreter, fish, like other shells,
tries your system shell, typically /bin/sh. This is needed because some
scripts are shipped without a shebang line.

CONFIGURATION
To store configuration write it to a file called ~/.config/fish/con-
fig.fish.

.fish scripts in ~/.config/fish/conf.d/ are also automatically executed
before config.fish.

These files are read on the startup of every shell, whether interactive
and/or if they're login shells. Use status --is-interactive and status
--is-login to do things only in interactive/login shells, respectively.

This is the short version; for a full explanation, like for sysadmins
or integration for developers of other software, see Configuration
files.

If you want to see what you changed over fish's defaults, see
fish_delta.

Examples:
To add ~/linux/bin to PATH variable when using a login shell, add this
to ~/.config/fish/config.fish file:

if status --is-login
set -gx PATH $PATH ~/linux/bin
end

This is just an example; using fish_add_path e.g. fish_add_path
~/linux/bin which only adds the path if it isn't included yet is eas-
ier.

To run commands on exit, use an event handler that is triggered by the
exit of the shell:

function on_exit --on-event fish_exit
echo fish is now exiting
end

RESOURCES
• The GitHub page

• The official Gitter channel

• The official mailing list at fish-users@lists.sourceforge.net

If you have an improvement for fish, you can submit it via the GitHub
page.

OTHER HELP PAGES
Frequently asked questions
What is the equivalent to this thing from bash (or other shells)?
See Fish for bash users

How do I set or clear an environment variable?
Use the set command:

set -x key value # typically set -gx key value
set -e key

Since fish 3.1 you can set an environment variable for just one command
using the key=value some command syntax, like in other shells. The two
lines below behave identically - unlike other shells, fish will output
value both times:

key=value echo $key
begin; set -lx key value; echo $key; end

Note that "exported" is not a scope, but an additional bit of state. A
variable can be global and exported or local and exported or even uni-
versal and exported. Typically it makes sense to make an exported vari-
able global.

How do I check whether a variable is defined?
Use set -q var. For example, if set -q var; echo variable defined;
end. To check multiple variables you can combine with and and or like
so:

if set -q var1; or set -q var2
echo either variable defined
end

Keep in mind that a defined variable could also be empty, either by
having no elements (if set like set var) or only empty elements (if set
like set var ""). Read on for how to deal with those.

How do I check whether a variable is not empty?
Use string length -q -- $var. For example, if string length -q --
$var; echo not empty; end. Note that string length will interpret a
list of multiple variables as a disjunction (meaning any/or):

if string length -q -- $var1 $var2 $var3
echo at least one of these variables is not empty
end

Alternatively, use test -n "$var", but remember that the variable must
be double-quoted. For example, if test -n "$var"; echo not empty; end.
The test command provides its own and (-a) and or (-o):

if test -n "$var1" -o -n "$var2" -o -n "$var3"
echo at least one of these variables is not empty
end

If you want to know if a variable has no elements, use set -q var[1].

Why doesn't set -Ux (exported universal variables) seem to work?
A global variable of the same name already exists.

Environment variables such as EDITOR or TZ can be set universally using
set -Ux. However, if there is an environment variable already set be-
fore fish starts (such as by login scripts or system administrators),
it is imported into fish as a global variable. The variable scopes are
searched from the "inside out", which means that local variables are
checked first, followed by global variables, and finally universal
variables.

This means that the global value takes precedence over the universal
value.

To avoid this problem, consider changing the setting which fish inher-
its. If this is not possible, add a statement to your configuration
file (usually ~/.config/fish/config.fish):

set -gx EDITOR vim

How do I run a command every login? What's fish's equivalent to .bashrc or
.profile?
Edit the file ~/.config/fish/config.fish [1], creating it if it does
not exist (Note the leading period).

Unlike .bashrc and .profile, this file is always read, even in non-in-
teractive or login shells.

To do something only in interactive shells, check status is-interactive
like:

if status is-interactive
# use the coolbeans theme
fish_config theme choose coolbeans
end

[1] The "~/.config" part of this can be set via $XDG_CONFIG_HOME,
that's just the default.

How do I set my prompt?
The prompt is the output of the fish_prompt function. Put it in ~/.con-
fig/fish/functions/fish_prompt.fish. For example, a simple prompt is:

function fish_prompt
set_color $fish_color_cwd
echo -n (prompt_pwd)
set_color normal
echo -n ' > '
end

You can also use the Web configuration tool, fish_config, to preview
and choose from a gallery of sample prompts.

Or you can use fish_config from the commandline:

> fish_config prompt show
# displays all the prompts fish ships with
> fish_config prompt choose disco
# loads the disco prompt in the current shell
> fish_config prompt save
# makes the change permanent

If you want to modify your existing prompt, you can use funced and
funcsave like:

>_ funced fish_prompt
# This opens up your editor (set in $EDITOR).
# Modify the function,
# save the file and repeat to your liking.
# Once you are happy with it:
>_ funcsave fish_prompt

This also applies to fish_right_prompt and fish_mode_prompt.

Why does my prompt show a [I]?
That's the fish_mode_prompt. It is displayed by default when you've ac-
tivated vi mode using fish_vi_key_bindings.

If you haven't activated vi mode on purpose, you might have installed a
third-party theme or plugin that does it.

If you want to change or disable this display, modify the
fish_mode_prompt function, for instance via funced.

How do I customize my syntax highlighting colors?
Use the web configuration tool, fish_config, or alter the fish_color
family of environment variables.

You can also use fish_config on the commandline, like:

> fish_config theme show
# to demonstrate all the colorschemes
> fish_config theme choose coolbeans
# to load the "coolbeans" theme
> fish_config theme save
# to make the change permanent

How do I change the greeting message?
Change the value of the variable fish_greeting or create a
fish_greeting function. For example, to remove the greeting use:

set -U fish_greeting

Or if you prefer not to use a universal variable, use:

set -g fish_greeting

in config.fish.

How do I run a command from history?
Type some part of the command, and then hit the (up) or (down) arrow
keys to navigate through history matches, or press Control+R to open
the history in a searchable pager. In this pager you can press Con-
trol+R or Control+S to move to older or younger history respectively.

Additional default key bindings include Control+P (up) and Control+N
(down). See Searchable command history for more information.

Why doesn't history substitution ("!$" etc.) work?
Because history substitution is an awkward interface that was invented
before interactive line editing was even possible. Instead of adding
this pseudo-syntax, fish opts for nice history searching and recall
features. Switching requires a small change of habits: if you want to
modify an old line/word, first recall it, then edit.

As a special case, most of the time history substitution is used as
sudo !!. In that case just press Alt+S, and it will recall your last
commandline with sudo prefixed (or toggle a sudo prefix on the current
commandline if there is anything).

In general, fish's history recall works like this:

• Like other shells, the Up arrow, recalls whole lines, starting from
the last executed line. A single press replaces "!!", later presses
replace "!-3" and the like.

• If the line you want is far back in the history, type any part of the
line and then press Up one or more times. This will filter the re-
called lines to ones that include this text, and you will get to the
line you want much faster. This replaces "!vi", "!?bar.c" and the
like.

• Alt+ recalls individual arguments, starting from the last argument in
the last executed line. A single press replaces "!$", later presses
replace "!!:4" and such. As an alternate key binding, Alt+. can be
used.

• If the argument you want is far back in history (e.g. 2 lines back -
that's a lot of words!), type any part of it and then press Alt+.
This will show only arguments containing that part and you will get
what you want much faster. Try it out, this is very convenient!

• If you want to reuse several arguments from the same line ("!!:3*"
and the like), consider recalling the whole line and removing what
you don't need (Alt+D and Alt+Backspace are your friends).

See documentation for more details about line editing in fish.

How do I run a subcommand? The backtick doesn't work!
fish uses parentheses for subcommands. For example:

for i in (ls)
echo $i
end

It also supports the familiar $() syntax, even in quotes. Backticks are
not supported because they are discouraged even in POSIX shells. They
nest poorly and are hard to tell from single quotes ('').

My command (pkg-config) gives its output as a single long string?
Unlike other shells, fish splits command substitutions only on new-
lines, not spaces or tabs or the characters in $IFS.

That means if you run

count (printf '%s ' a b c)

It will print 1, because the "a b c " is used in one piece. But if you
do

count (printf '%s\n' a b c)

it will print 3, because it gave count the arguments "a", "b" and "c"
separately.

In the overwhelming majority of cases, splitting on spaces is unwanted,
so this is an improvement. This is why you hear about problems with
filenames with spaces, after all.

However sometimes, especially with pkg-config and related tools, split-
ting on spaces is needed.

In these cases use string split -n " " like:

g++ example_01.cpp (pkg-config --cflags --libs gtk+-2.0 | string split -n " ")

The -n is so empty elements are removed like POSIX shells would do.

How do I get the exit status of a command?
Use the $status variable. This replaces the $? variable used in other
shells.

somecommand
if test $status -eq 7
echo "That's my lucky number!"
end

If you are just interested in success or failure, you can run the com-
mand directly as the if-condition:

if somecommand
echo "Command succeeded"
else
echo "Command failed"
end

Or if you just want to do one command in case the first succeeded or
failed, use and or or:

somecommand
or someothercommand

See the Conditions and the documentation for test and if for more in-
formation.

My command prints "No matches for wildcard" but works in bash
In short: quote or escape the wildcard:

scp user@ip:/dir/"string-*"

When fish sees an unquoted *, it performs wildcard expansion. That
means it tries to match filenames to the given string.

If the wildcard doesn't match any files, fish prints an error instead
of running the command:

> echo *this*does*not*exist
fish: No matches for wildcard '*this*does*not*exist'. See `help expand`.
echo *this*does*not*exist
^

Now, bash also tries to match files in this case, but when it doesn't
find a match, it passes along the literal wildcard string instead.

That means that commands like the above

scp user@ip:/dir/string-*

apt install postgres-*

appear to work, because most of the time the string doesn't match and
so it passes along the string-*, which is then interpreted by the re-
ceiving program.

But it also means that these commands can stop working at any moment
once a matching file is encountered (because it has been created or the
command is executed in a different working directory), and to deal with
that bash needs workarounds like

for f in ./*.mpg; do
# We need to test if the file really exists because
# the wildcard might have failed to match.
test -f "$f" || continue
mympgviewer "$f"
done

(from http://mywiki.wooledge.org/BashFAQ/004)

For these reasons, fish does not do this, and instead expects asterisks
to be quoted or escaped if they aren't supposed to be expanded.

This is similar to bash's "failglob" option.

I accidentally entered a directory path and fish changed directory. What
happened?
If fish is unable to locate a command with a given name, and it starts
with ., / or ~, fish will test if a directory of that name exists. If
it does, it assumes that you want to change your directory. For exam-
ple, the fastest way to switch to your home directory is to simply
press ~ and enter.

The open command doesn't work.
The open command uses the MIME type database and the .desktop files
used by Gnome and KDE to identify filetypes and default actions. If at
least one of these environments is installed, but the open command is
not working, this probably means that the relevant files are installed
in a non-standard location. Consider asking for more help.

Why won't SSH/SCP/rsync connect properly when fish is my login shell?
This problem may show up as messages like "Received message too long",
"open terminal failed: not a terminal", "Bad packet length", or "Con-
nection refused" with strange output in ssh_exchange_identification
messages in the debug log.

This usually happens because fish reads the user configuration file
(~/.config/fish/config.fish) always, whether it's in an interactive or
login or non-interactive or non-login shell.

This simplifies matters, but it also means when config.fish generates
output, it will do that even in non-interactive shells like the one
ssh/scp/rsync start when they connect.

Anything in config.fish that produces output should be guarded with
status is-interactive (or status is-login if you prefer):

if status is-interactive
...
end

The same applies for example when you start tmux in config.fish without
guards, which will cause a message like sessions should be nested with
care, unset $TMUX to force.

I'm getting weird graphical glitches (a staircase effect, ghost characters,
cursor in the wrong position,...)?
In a terminal, the application running inside it and the terminal it-
self need to agree on the width of characters in order to handle cursor
movement.

This is more important to fish than other shells because features like
syntax highlighting and autosuggestions are implemented by moving the
cursor.

Sometimes, there is disagreement on the width. There are numerous
causes and fixes for this:

• It is possible the character is simply too new for your system to
know - in this case you need to refrain from using it.

• Fish or your terminal might not know about the character or handle it
wrong - in this case fish or your terminal needs to be fixed, or you
need to update to a fixed version.

• The character has an "ambiguous" width and fish thinks that means a
width of X while your terminal thinks it's Y. In this case you either
need to change your terminal's configuration or set $fish_ambigu-
ous_width to the correct value.

• The character is an emoji and the host system only supports Unicode
8, while you are running the terminal on a system that uses Unicode
>= 9. In this case set $fish_emoji_width to 2.

This also means that a few things are unsupportable:

• Non-monospace fonts - there is no way for fish to figure out what
width a specific character has as it has no influence on the termi-
nal's font rendering.

• Different widths for multiple ambiguous width characters - there is
no way for fish to know which width you assign to each character.

Uninstalling fish
If you want to uninstall fish, first make sure fish is not set as your
shell. Run chsh -s /bin/bash if you are not sure.

If you installed it with a package manager, just use that package man-
ager's uninstall function. If you built fish yourself, assuming you in-
stalled it to /usr/local, do this:

rm -Rf /usr/local/etc/fish /usr/local/share/fish ~/.config/fish
rm /usr/local/share/man/man1/fish*.1
cd /usr/local/bin
rm -f fish fish_indent

Where can I find extra tools for fish?
The fish user community extends fish in unique and useful ways via
scripts that aren't always appropriate for bundling with the fish pack-
age. Typically because they solve a niche problem unlikely to appeal to
a broad audience. You can find those extensions, including prompts,
themes and useful functions, in various third-party repositories. These
include:

• Fisher

• Fundle

• Oh My Fish

• Tacklebox

This is not an exhaustive list and the fish project has no opinion re-
garding the merits of the repositories listed above or the scripts
found therein.

Interactive use
Fish prides itself on being really nice to use interactively. That's
down to a few features we'll explain in the next few sections.

Fish is used by giving commands in the fish language, see The Fish Lan-
guage for information on that.

Help
Fish has an extensive help system. Use the help command to obtain help
on a specific subject or command. For instance, writing help syntax
displays the syntax section of this documentation.

Fish also has man pages for its commands, and translates the help pages
to man pages. For example, man set will show the documentation for set
as a man page.

Help on a specific builtin can also be obtained with the -h parameter.
For instance, to obtain help on the fg builtin, either type fg -h or
help fg.

The main page can be viewed via help index (or just help) or man
fish-doc. The tutorial can be viewed with help tutorial or man fish-tu-
torial.

Autosuggestions
fish suggests commands as you type, based on command history, comple-
tions, and valid file paths. As you type commands, you will see a sug-
gestion offered after the cursor, in a muted gray color (which can be
changed with the fish_color_autosuggestion variable).

To accept the autosuggestion (replacing the command line contents),
press or Control+F. To accept the first suggested word, press Alt+ or
Alt+F. If the autosuggestion is not what you want, just ignore it: it
won't execute unless you accept it.

Autosuggestions are a powerful way to quickly summon frequently entered
commands, by typing the first few characters. They are also an effi-
cient technique for navigating through directory hierarchies.

If you don't like autosuggestions, you can disable them by setting
$fish_autosuggestion_enabled to 0:

set -g fish_autosuggestion_enabled 0

Tab Completion
Tab completion is a time saving feature of any modern shell. When you
type Tab, fish tries to guess the rest of the word under the cursor. If
it finds just one possibility, it inserts it. If it finds more, it in-
serts the longest unambiguous part and then opens a menu (the "pager")
that you can navigate to find what you're looking for.

The pager can be navigated with the arrow keys, Page Up / Page Down,
Tab or Shift+Tab. Pressing Control+S (the pager-toggle-search binding -
/ in vi-mode) opens up a search menu that you can use to filter the
list.

Fish provides some general purpose completions, like for commands,
variable names, usernames or files.

It also provides a large number of program specific scripted comple-
tions. Most of these completions are simple options like the -l option
for ls, but a lot are more advanced. For example:

• man and whatis show the installed manual pages as completions.

• make uses targets in the Makefile in the current directory as comple-
tions.

• mount uses mount points specified in fstab as completions.

• apt, rpm and yum show installed or installable packages

You can also write your own completions or install some you got from
someone else. For that, see Writing your own completions.

Completion scripts are loaded on demand, just like functions are. The
difference is the $fish_complete_path list is used instead of
$fish_function_path. Typically you can drop new completions in ~/.con-
fig/fish/completions/name-of-command.fish and fish will find them auto-
matically.

Syntax highlighting
Fish interprets the command line as it is typed and uses syntax high-
lighting to provide feedback. The most important feedback is the detec-
tion of potential errors. By default, errors are marked red.

Detected errors include:

• Non-existing commands.

• Reading from or appending to a non-existing file.

• Incorrect use of output redirects

• Mismatched parenthesis

To customize the syntax highlighting, you can set the environment vari-
ables listed in the Variables for changing highlighting colors section.

Fish also provides pre-made color themes you can pick with fish_config.
Running just fish_config opens a browser interface, or you can use
fish_config theme in the terminal.

For example, to disable nearly all coloring:

fish_config theme choose none

Or, to see all themes, right in your terminal:

fish_config theme show

Syntax highlighting variables
The colors used by fish for syntax highlighting can be configured by
changing the values of various variables. The value of these variables
can be one of the colors accepted by the set_color command. The modi-
fier switches accepted by set_color like --bold, --dim, --italics,
--reverse and --underline are also accepted.

Example: to make errors highlighted and red, use:

set fish_color_error red --bold

If a variable isn't set or is empty, fish usually tries
$fish_color_normal, except for:

• $fish_color_keyword, where it tries $fish_color_command first.

• $fish_color_option, where it tries $fish_color_param first.

• For $fish_color_valid_path, if that doesn't have a color, but only
modifiers, it adds those to the color that would otherwise be used,
like $fish_color_param. But if valid paths have a color, it uses that
and adds in modifiers from the other color.

Pager color variables
fish will sometimes present a list of choices in a table, called the
pager.

Example: to set the background of each pager row, use:

set fish_pager_color_background --background=white

To have black text on alternating white and gray backgrounds:

set fish_pager_color_prefix black
set fish_pager_color_completion black
set fish_pager_color_description black
set fish_pager_color_background --background=white
set fish_pager_color_secondary_background --background=brwhite

When the secondary or selected variables aren't set or are empty, the
normal variables are used, except for $fish_pager_color_selected_back-
ground, where the background of $fish_color_search_match is tried
first.

Abbreviations
To avoid needless typing, a frequently-run command like git checkout
can be abbreviated to gco using the abbr command.

abbr -a gco git checkout

After entering gco and pressing Space or Enter, a gco in command posi-
tion will turn into git checkout in the command line. If you want to
use a literal gco sometimes, use Control+Space [1].

This is a lot more powerful, for example you can make going up a number
of directories easier with this:

function multicd
echo cd (string repeat -n (math (string length -- $argv[1]) - 1) ../)
end
abbr --add dotdot --regex '^\.\.+$' --function multicd

Now, .. transforms to cd ../, while ... turns into cd ../../ and ....
expands to cd ../../../.

The advantage over aliases is that you can see the actual command be-
fore using it, add to it or change it, and the actual command will be
stored in history.

[1] Any binding that executes the expand-abbr or execute bind function
will expand abbreviations. By default Control+Space is bound to
just inserting a space.

Programmable title
When using most virtual terminals, it is possible to set the message
displayed in the titlebar of the terminal window. This can be done au-
tomatically in fish by defining the fish_title function. The fish_title
function is executed before and after a new command is executed or put
into the foreground and the output is used as a titlebar message. The
status current-command builtin will always return the name of the job
to be put into the foreground (or fish if control is returning to the
shell) when the fish_prompt function is called. The first argument to
fish_title will contain the most recently executed foreground command
as a string.

The default fish title shows the hostname if connected via ssh, the
currently running command (unless it is fish) and the current working
directory. All of this is shortened to not make the tab too wide.

Examples:

To show the last command and working directory in the title:

function fish_title
# `prompt_pwd` shortens the title. This helps prevent tabs from becoming very wide.
echo $argv[1] (prompt_pwd)
pwd
end

Programmable prompt
When it is fish's turn to ask for input (like after it started or the
command ended), it will show a prompt. It does this by running the
fish_prompt and fish_right_prompt functions.

The output of the former is displayed on the left and the latter's out-
put on the right side of the terminal. The output of fish_mode_prompt
will be prepended on the left, though the default function only does
this when in vi-mode.

Configurable greeting
When it is started interactively, fish tries to run the fish_greeting
function. The default fish_greeting prints a simple greeting. You can
change its text by changing the $fish_greeting variable, for instance
using a universal variable:

set -U fish_greeting

or you can set it globally in config.fish:

set -g fish_greeting 'Hey, stranger!'

or you can script it by changing the function:

function fish_greeting
random choice "Hello!" "Hi" "G'day" "Howdy"
end

save this in config.fish or a function file. You can also use funced
and funcsave to edit it easily.

Private mode
If $fish_private_mode is set to a non-empty value, commands will not be
written to the history file on disk.

You can also launch with fish --private (or fish -P for short). This
both hides old history and prevents writing history to disk. This is
useful to avoid leaking personal information (e.g. for screencasts) or
when dealing with sensitive information.

You can query the variable fish_private_mode (if test -n "$fish_pri-
vate_mode" ...) if you would like to respect the user's wish for pri-
vacy and alter the behavior of your own fish scripts.

Command line editor
The fish editor features copy and paste, a searchable history and many
editor functions that can be bound to special keyboard shortcuts.

Like bash and other shells, fish includes two sets of keyboard short-
cuts (or key bindings): one inspired by the Emacs text editor, and one
by the Vi text editor. The default editing mode is Emacs. You can
switch to Vi mode by running fish_vi_key_bindings and switch back with
fish_default_key_bindings. You can also make your own key bindings by
creating a function and setting the fish_key_bindings variable to its
name. For example:

function fish_hybrid_key_bindings --description \
"Vi-style bindings that inherit emacs-style bindings in all modes"
for mode in default insert visual
fish_default_key_bindings -M $mode
end
fish_vi_key_bindings --no-erase
end
set -g fish_key_bindings fish_hybrid_key_bindings

While the key bindings included with fish include many of the shortcuts
popular from the respective text editors, they are not a complete im-
plementation. They include a shortcut to open the current command line
in your preferred editor (Alt+E by default) if you need the full power
of your editor.

Shared bindings
Some bindings are common across Emacs and Vi mode, because they aren't
text editing bindings, or because what Vi/Vim does for a particular key
doesn't make sense for a shell.

• Tab completes the current token. Shift+Tab completes the current to-
ken and starts the pager's search mode. Tab is the same as Control+I.

• (Left) and (Right) move the cursor left or right by one character.
If the cursor is already at the end of the line, and an autosugges-
tion is available, accepts the autosuggestion.

• Enter executes the current commandline or inserts a newline if it's
not complete yet (e.g. a ) or end is missing).

• Alt+Enter inserts a newline at the cursor position.

• Alt+ and Alt+ move the cursor one word left or right (to the next
space or punctuation mark), or moves forward/backward in the direc-
tory history if the command line is empty. If the cursor is already
at the end of the line, and an autosuggestion is available, Alt+ (or
Alt+F) accepts the first word in the suggestion.

• Control+ and Control+ move the cursor one word left or right. These
accept one word of the autosuggestion - the part they'd move over.

• Shift+ and Shift+ move the cursor one word left or right, without
stopping on punctuation. These accept one big word of the autosugges-
tion.

• (Up) and (Down) (or Control+P and Control+N for emacs aficionados)
search the command history for the previous/next command containing
the string that was specified on the commandline before the search
was started. If the commandline was empty when the search started,
all commands match. See the history section for more information on
history searching.

• Alt+ and Alt+ search the command history for the previous/next token
containing the token under the cursor before the search was started.
If the commandline was not on a token when the search started, all
tokens match. See the history section for more information on history
searching.

• Control+C interrupt/kill whatever is running (SIGINT).

• Control+D delete one character to the right of the cursor. If the
command line is empty, Control+D will exit fish.

• Control+U removes contents from the beginning of line to the cursor
(moving it to the killring).

• Control+L clears and repaints the screen.

• Control+W removes the previous path component (everything up to the
previous "/", ":" or "@") (moving it to the Copy and paste (Kill
Ring)).

• Control+X copies the current buffer to the system's clipboard, Con-
trol+V inserts the clipboard contents. (see fish_clipboard_copy and
fish_clipboard_paste)

• Alt+D moves the next word to the Copy and paste (Kill Ring).

• Alt+H (or F1) shows the manual page for the current command, if one
exists.

• Alt+L lists the contents of the current directory, unless the cursor
is over a directory argument, in which case the contents of that di-
rectory will be listed.

• Alt+O opens the file at the cursor in a pager.

• Alt+P adds the string &| less; to the end of the job under the cur-
sor. The result is that the output of the command will be paged.

• Alt+W prints a short description of the command under the cursor.

• Alt+E edit the current command line in an external editor. The editor
is chosen from the first available of the $VISUAL or $EDITOR vari-
ables.

• Alt+V Same as Alt+E.

• Alt+S Prepends sudo to the current commandline. If the commandline is
empty, prepend sudo to the last commandline.

• Control+Space Inserts a space without expanding an abbreviation. For
vi-mode this only applies to insert-mode.

Emacs mode commands
To enable emacs mode, use fish_default_key_bindings. This is also the
default.

• Home or Control+A moves the cursor to the beginning of the line.

• End or Control+E moves to the end of line. If the cursor is already
at the end of the line, and an autosuggestion is available, End or
Control+E accepts the autosuggestion.

• Control+B, Control+F move the cursor one character left or right or
accept the autosuggestion just like the (Left) and (Right) shared
bindings (which are available as well).

• Control+N, Control+P move the cursor up/down or through history, like
the up and down arrow shared bindings.

• Delete or Backspace removes one character forwards or backwards re-
spectively. This also goes for Control+H, which is indistinguishable
from backspace.

• Alt+Backspace removes one word backwards.

• Alt+< moves to the beginning of the commandline, Alt+> moves to the
end.

• Control+K deletes from the cursor to the end of line (moving it to
the Copy and paste (Kill Ring)).

• Escape and Control+G cancel the current operation. Immediately after
an unambiguous completion this undoes it.

• Alt+C capitalizes the current word.

• Alt+U makes the current word uppercase.

• Control+T transposes the last two characters.

• Alt+T transposes the last two words.

• Control+Z, Control+_ (Control+/ on some terminals) undo the most re-
cent edit of the line.

• Alt+/ reverts the most recent undo.

• Control+R opens the history in a pager. This will show history en-
tries matching the search, a few at a time. Pressing Control+R again
will search older entries, pressing Control+S (that otherwise toggles
pager search) will go to newer entries. The search bar will always be
selected.

You can change these key bindings using the bind builtin.

Vi mode commands
Vi mode allows for the use of Vi-like commands at the prompt. Ini-
tially, insert mode is active. Escape enters command mode. The commands
available in command, insert and visual mode are described below. Vi
mode shares some bindings with Emacs mode.

To enable vi mode, use fish_vi_key_bindings. It is also possible to
add all emacs-mode bindings to vi-mode by using something like:

function fish_user_key_bindings
# Execute this once per mode that emacs bindings should be used in
fish_default_key_bindings -M insert

# Then execute the vi-bindings so they take precedence when there's a conflict.
# Without --no-erase fish_vi_key_bindings will default to
# resetting all bindings.
# The argument specifies the initial mode (insert, "default" or visual).
fish_vi_key_bindings --no-erase insert
end

When in vi-mode, the fish_mode_prompt function will display a mode in-
dicator to the left of the prompt. To disable this feature, override it
with an empty function. To display the mode elsewhere (like in your
right prompt), use the output of the fish_default_mode_prompt function.

When a binding switches the mode, it will repaint the mode-prompt if it
exists, and the rest of the prompt only if it doesn't. So if you want a
mode-indicator in your fish_prompt, you need to erase fish_mode_prompt
e.g. by adding an empty file at ~/.config/fish/func-
tions/fish_mode_prompt.fish. (Bindings that change the mode are sup-
posed to call the repaint-mode bind function, see bind)

The fish_vi_cursor function will be used to change the cursor's shape
depending on the mode in supported terminals. The following snippet can
be used to manually configure cursors after enabling vi-mode:

# Emulates vim's cursor shape behavior
# Set the normal and visual mode cursors to a block
set fish_cursor_default block
# Set the insert mode cursor to a line
set fish_cursor_insert line
# Set the replace mode cursors to an underscore
set fish_cursor_replace_one underscore
set fish_cursor_replace underscore
# Set the external cursor to a line. The external cursor appears when a command is started.
# The cursor shape takes the value of fish_cursor_default when fish_cursor_external is not specified.
set fish_cursor_external line
# The following variable can be used to configure cursor shape in
# visual mode, but due to fish_cursor_default, is redundant here
set fish_cursor_visual block

Additionally, blink can be added after each of the cursor shape parame-
ters to set a blinking cursor in the specified shape.

Fish knows the shapes "block", "line" and "underscore", other values
will be ignored.

If the cursor shape does not appear to be changing after setting the
above variables, it's likely your terminal emulator does not support
the capabilities necessary to do this. It may also be the case, how-
ever, that fish_vi_cursor has not detected your terminal's features
correctly (for example, if you are using tmux). If this is the case,
you can force fish_vi_cursor to set the cursor shape by setting
$fish_vi_force_cursor in config.fish. You'll have to restart fish for
any changes to take effect. If cursor shape setting remains broken af-
ter this, it's almost certainly an issue with your terminal emulator,
and not fish.

Command mode
Command mode is also known as normal mode.

• h moves the cursor left.

• l moves the cursor right.

• k and j search the command history for the previous/next command con-
taining the string that was specified on the commandline before the
search was started. If the commandline was empty when the search
started, all commands match. See the history section for more infor-
mation on history searching. In multi-line commands, they move the
cursor up and down respectively.

• i enters insert mode at the current cursor position.

• Shift+I enters insert mode at the beginning of the line.

• v enters visual mode at the current cursor position.

• a enters insert mode after the current cursor position.

• Shift+A enters insert mode at the end of the line.

• o inserts a new line under the current one and enters insert mode

• O (capital-"o") inserts a new line above the current one and enters
insert mode

• 0 (zero) moves the cursor to beginning of line (remaining in command
mode).

• d+d deletes the current line and moves it to the Copy and paste (Kill
Ring).

• Shift+D deletes text after the current cursor position and moves it
to the Copy and paste (Kill Ring).

• p pastes text from the Copy and paste (Kill Ring).

• u undoes the most recent edit of the command line.

• Control+R redoes the most recent edit.

• [ and ] search the command history for the previous/next token con-
taining the token under the cursor before the search was started. See
the history section for more information on history searching.

• / opens the history in a pager. This will show history entries match-
ing the search, a few at a time. Pressing it again will search older
entries, pressing Control+S (that otherwise toggles pager search)
will go to newer entries. The search bar will always be selected.

• Backspace moves the cursor left.

• g / G moves the cursor to the beginning/end of the commandline, re-
spectively.

• :q exits fish.

Insert mode
• Escape enters command mode.

• Backspace removes one character to the left.

Visual mode
• (Left) and (Right) extend the selection backward/forward by one
character.

• h moves the cursor left.

• l moves the cursor right.

• k moves the cursor up.

• j moves the cursor down.

• b and w extend the selection backward/forward by one word.

• d and x move the selection to the Copy and paste (Kill Ring) and en-
ter command mode.

• Escape and Control+C enter command mode.

• c and s remove the selection and switch to insert mode.

• X moves the entire line to the Copy and paste (Kill Ring), and enters
command mode.

• y copies the selection to the Copy and paste (Kill Ring), and enters
command mode.

• ~ toggles the case (upper/lower) on the selection, and enters command
mode.

• "*y copies the selection to the clipboard, and enters command mode.

Custom bindings
In addition to the standard bindings listed here, you can also define
your own with bind:

# Just clear the commandline on control-c
bind \cc 'commandline -r ""'

Put bind statements into config.fish or a function called
fish_user_key_bindings.

If you change your mind on a binding and want to go back to fish's de-
fault, you can simply erase it again:

bind --erase \cc

Fish remembers its preset bindings and so it will take effect again.
This saves you from having to remember what it was before and add it
again yourself.

If you use vi bindings, note that bind will by default bind keys in
command mode. To bind something in insert mode:

bind --mode insert \cc 'commandline -r ""'

Key sequences
The terminal tells fish which keys you pressed by sending some se-
quences of bytes to describe that key. For some keys, this is easy -
pressing a simply means the terminal sends "a". In others it's more
complicated and terminals disagree on which they send.

In these cases, fish_key_reader can tell you how to write the key se-
quence for your terminal. Just start it and press the keys you are in-
terested in:

> fish_key_reader # pressing control-c
Press a key:
Press [ctrl-C] again to exit
bind \cC 'do something'

> fish_key_reader # pressing the right-arrow
Press a key:
bind \e\[C 'do something'

Note that some key combinations are indistinguishable or unbindable.
For instance control-i is the same as the tab key. This is a terminal
limitation that fish can't do anything about. When fish_key_reader
prints the same sequence for two different keys, then that is because
your terminal sends the same sequence for them.

Also, Escape is the same thing as Alt in a terminal. To distinguish be-
tween pressing Escape and then another key, and pressing Alt and that
key (or an escape sequence the key sends), fish waits for a certain
time after seeing an escape character. This is configurable via the
fish_escape_delay_ms variable.

If you want to be able to press Escape and then a character and have it
count as Alt+that character, set it to a higher value, e.g.:

set -g fish_escape_delay_ms 100

Similarly, to disambiguate other keypresses where you've bound a subse-
quence and a longer sequence, fish has fish_sequence_key_delay_ms:

# This binds "jk" to switch to normal mode in vi-mode.
# If you kept it like that, every time you press "j",
# fish would wait for a "k" or other key to disambiguate
bind -M insert -m default jk cancel repaint-mode

# After setting this, fish only waits 200ms for the "k",
# or decides to treat the "j" as a separate sequence, inserting it.
set -g fish_sequence_key_delay_ms 200

Copy and paste (Kill Ring)
Fish uses an Emacs-style kill ring for copy and paste functionality.
For example, use Control+K (kill-line) to cut from the current cursor
position to the end of the line. The string that is cut (a.k.a. killed
in emacs-ese) is inserted into a list of kills, called the kill ring.
To paste the latest value from the kill ring (emacs calls this "yank-
ing") use Control+Y (the yank input function). After pasting, use Alt+Y
(yank-pop) to rotate to the previous kill.

Copy and paste from outside are also supported, both via the Control+X
/ Control+V bindings (the fish_clipboard_copy and fish_clipboard_paste
functions [2]) and via the terminal's paste function, for which fish
enables "Bracketed Paste Mode", so it can tell a paste from manually
entered text. In addition, when pasting inside single quotes, pasted
single quotes and backslashes are automatically escaped so that the re-
sult can be used as a single token simply by closing the quote after.
Kill ring entries are stored in fish_killring variable.

The commands begin-selection and end-selection (unbound by default;
used for selection in vi visual mode) control text selection together
with cursor movement commands that extend the current selection. The
variable fish_cursor_selection_mode can be used to configure if that
selection should include the character under the cursor (inclusive) or
not (exclusive). The default is exclusive, which works well with any
cursor shape. For vi mode, and particularly for the block or underscore
cursor shapes you may prefer inclusive.

[2] These rely on external tools. Currently xsel, xclip,
wl-copy/wl-paste and pbcopy/pbpaste are supported.

Multiline editing
The fish commandline editor can be used to work on commands that are
several lines long. There are three ways to make a command span more
than a single line:

• Pressing the Enter key while a block of commands is unclosed, such as
when one or more block commands such as for, begin or if do not have
a corresponding end command.

• Pressing Alt+Enter instead of pressing the Enter key.

• By inserting a backslash (\) character before pressing the Enter key,
escaping the newline.

The fish commandline editor works exactly the same in single line mode
and in multiline mode. To move between lines use the left and right ar-
row keys and other such keyboard shortcuts.

Searchable command history
After a command has been executed, it is remembered in the history
list. Any duplicate history items are automatically removed. By press-
ing the up and down keys, you can search forwards and backwards in the
history. If the current command line is not empty when starting a his-
tory search, only the commands containing the string entered into the
command line are shown.

By pressing Alt+ and Alt+, a history search is also performed, but in-
stead of searching for a complete commandline, each commandline is bro-
ken into separate elements just like it would be before execution, and
the history is searched for an element matching that under the cursor.

For more complicated searches, you can press Ctrl+R to open a pager
that allows you to search the history. It shows a limited number of en-
tries in one page, press Ctrl+R [3] again to move to the next page and
Ctrl+S [4] to move to the previous page. You can change the text to re-
fine your search.

History searches are case-insensitive unless the search string contains
an uppercase character. You can stop a search to edit your search
string by pressing Esc or Page Down.

Prefixing the commandline with a space will prevent the entire line
from being stored in the history. It will still be available for recall
until the next command is executed, but will not be stored on disk.
This is to allow you to fix misspellings and such.

The command history is stored in the file ~/.local/share/fish/fish_his-
tory (or $XDG_DATA_HOME/fish/fish_history if that variable is set) by
default. However, you can set the fish_history environment variable to
change the name of the history session (resulting in a <session>_his-
tory file); both before starting the shell and while the shell is run-
ning.

See the history command for other manipulations.

Examples:

To search for previous entries containing the word 'make', type make in
the console and press the up key.

If the commandline reads cd m, place the cursor over the m character
and press Alt+ to search for previously typed words containing 'm'.

[3] Or another binding that triggers the history-pager input function.
See bind for a list.

[4] Or another binding that triggers the pager-toggle-search input
function.

Navigating directories
Navigating directories is usually done with the cd command, but fish
offers some advanced features as well.

The current working directory can be displayed with the pwd command, or
the $PWD special variable. Usually your prompt already does this.

Directory history
Fish automatically keeps a trail of the recent visited directories with
cd by storing this history in the dirprev and dirnext variables.

Several commands are provided to interact with this directory history:

• dirh prints the history

• cdh displays a prompt to quickly navigate the history

• prevd moves backward through the history. It is bound to Alt+

• nextd moves forward through the history. It is bound to Alt+

Directory stack
Another set of commands, usually also available in other shells like
bash, deal with the directory stack. Stack handling is not automatic
and needs explicit calls of the following commands:

• dirs prints the stack

• pushd adds a directory on top of the stack and makes it the current
working directory

• popd removes the directory on top of the stack and changes the cur-
rent working directory

The fish language
This document is a comprehensive overview of fish's scripting language.

For interactive features see Interactive use.

Syntax overview
Shells like fish are used by giving them commands. A command is exe-
cuted by writing the name of the command followed by any arguments. For
example:

echo hello world

echo command writes its arguments to the screen. In this example the
output is hello world.

Everything in fish is done with commands. There are commands for re-
peating 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.

Every program on your computer can be used as a command in fish. If the
program file is located in one of the 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.

Here is a list of some useful commands:

• cd: Change the current directory

• ls: List files and directories

• man: Display a manual page - try man ls to get help on your "ls" com-
mand, or man mv to get information about "mv".

• mv: Move (rename) files

• cp: Copy files

• open: Open files with the default application associated with each
filetype

• less: Display the contents of files

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 sepa-
rating them with semicolons.

A switch is a very common special type of argument. Switches almost al-
ways start with one or more hyphens - and alter the way a command oper-
ates. 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.

Switches differ between commands and are usually documented on a com-
mand'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-com-
mand-here to get information on your command's switches.

So the basic idea of fish is the same as with other unix shells: It
gets a commandline, runs expansions, and the result is then run as a
command.

Terminology
Here we define some of the terms used on this page and throughout the
rest of the fish documentation:

• Argument: A parameter given to a command. In echo foo, the "foo" is
an argument.

• 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 "echo" is a
builtin.

• 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 "echo" is a builtin command, in command echo foo the "echo"
is an external command, provided by a file like /bin/echo.

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

• Job: A running pipeline or command.

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

• Redirection: An operation that changes one of the input or output
streams associated with a job.

• 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 "-n" is an option.

Quotes
Sometimes you want to give a command an argument that contains charac-
ters special to fish, like spaces or $ or *. To do that, you can use
quotes:

rm "my file.txt"

to remove a file called my file.txt instead of trying to remove two
files, my and file.txt.

Fish understands two kinds of quotes: Single (') and double ("), and
both work slightly differently.

Between single quotes, fish performs no expansions. Between double
quotes, fish only performs variable expansion and command substitution
in the $(command). No other kind of expansion (including brace expan-
sion or parameter expansion) is performed, and escape sequences (for
example, \n) are ignored. Within quotes, whitespace is not used to sep-
arate arguments, allowing quoted arguments to contain spaces.

The only meaningful escape sequences in single quotes are \', which es-
capes a single quote and \\, which escapes the backslash symbol. The
only meaningful escapes in double quotes are \", 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.

Single quotes have no special meaning within double quotes and vice
versa.

More examples:

grep 'enabled)$' foo.txt

searches for lines ending in enabled) in foo.txt (the $ is special to
grep: it matches the end of the line).

apt install "postgres-*"

installs all packages with a name starting with "postgres-", instead of
looking through the current directory for files named "postgres-some-
thing".

Escaping Characters
Some characters cannot be written directly on the command line. For
these characters, so-called escape sequences are provided. These are:

• \a represents the alert character.

• \e represents the escape character.

• \f represents the form feed character.

• \n represents a newline character.

• \r represents the carriage return character.

• \t represents the tab character.

• \v represents the vertical tab character.

• \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 in-
valid strings. Typically fish is run with the ASCII or UTF-8 encod-
ing, so anything up to \X7f is an ASCII character.

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

• \uXXXX, where XXXX is a hexadecimal number, represents the 16-bit
Unicode character with the specified value. For example, \u9 is the
tab character.

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

• \cX, where X is a letter of the alphabet, represents the control se-
quence generated by pressing the control key and the specified let-
ter. For example, \ci is the tab character

Some characters have special meaning to the shell. For example, an
apostrophe ' disables expansion (see Quotes). To tell the shell to
treat these characters literally, escape them with a backslash. For ex-
ample, the command:

echo \'hello world\'

outputs 'hello world' (including the apostrophes), while the command:

echo 'hello world'

outputs hello world (without the apostrophes). In the former case the
shell treats the apostrophes as literal ' characters, while in the lat-
ter case it treats them as special expansion modifiers.

The special characters and their escape sequences are:

• \ (backslash space) escapes the space character. This keeps the
shell from splitting arguments on the escaped space.

• \$ escapes the dollar character.

• \\ escapes the backslash character.

• \* escapes the star character.

• \? escapes the question mark character (this is not necessary if the
qmark-noglob feature flag is enabled).

• \~ escapes the tilde character.

• \# escapes the hash character.

• \( escapes the left parenthesis character.

• \) escapes the right parenthesis character.

• \{ escapes the left curly bracket character.

• \} escapes the right curly bracket character.

• \[ escapes the left bracket character.

• \] escapes the right bracket character.

• \< escapes the less than character.

• \> escapes the more than character.

• \& escapes the ampersand character.

• \| escapes the vertical bar character.

• \; escapes the semicolon character.

• \" escapes the quote character.

• \' escapes the apostrophe character.

As a special case, \ immediately followed by a literal new line is a
"continuation" 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).

Input/Output Redirection
Most programs use three input/output (I/O) streams:

• Standard input (stdin) for reading. Defaults to reading from the key-
board.

• Standard output (stdout) for writing output. Defaults to writing to
the screen.

• Standard error (stderr) for writing errors and warnings. Defaults to
writing to the screen.

Each stream has a number called the file descriptor (FD): 0 for stdin,
1 for stdout, and 2 for stderr.

The destination of a stream can be changed using something called redi-
rection. For example, echo hello > output.txt, redirects the standard
output of the echo command to a text file.

• To read standard input from a file, use <SOURCE_FILE.

• To write standard output to a file, use >DESTINATION.

• To write standard error to a file, use 2>DESTINATION. [1]

• To append standard output to a file, use >>DESTINATION_FILE.

• To append standard error to a file, use 2>>DESTINATION_FILE.

• To not overwrite ("clobber") an existing file, use >?DESTINATION or
2>?DESTINATION. This is known as the "noclobber" redirection.

DESTINATION can be one of the following:

• A filename to write the output to. Often >/dev/null to silence output
by writing it to the special "sinkhole" file.

• An ampersand (&) followed by the number of another file descriptor
like &2 for standard error. The output will be written to the desti-
nation descriptor.

• An ampersand followed by a minus sign (&-). The file descriptor will
be closed. Note: This may cause the program to fail because its
writes will be unsuccessful.

As a convenience, the redirection &> can be used to direct both stdout
and stderr to the same destination. For example, echo hello &> all_out-
put.txt redirects both stdout and stderr to the file all_output.txt.
This is equivalent to echo hello > all_output.txt 2>&1.

Any arbitrary file descriptor can be used in a redirection by prefixing
the redirection with the FD number.

• To redirect the input of descriptor N, use N<DESTINATION.

• To redirect the output of descriptor N, use N>DESTINATION.

• To append the output of descriptor N to a file, use N>>DESTINA-
TION_FILE.

For example:

# Write `foo`'s standard error (file descriptor 2)
# to a file called "output.stderr":
foo 2> output.stderr

# if $num doesn't contain a number,
# this test will be false and print an error,
# so by ignoring the error we can be sure that we're dealing
# with a number in the "if" block:
if test "$num" -gt 2 2>/dev/null
# do things with $num as a number greater than 2
else
# do things if $num is <= 2 or not a number
end

# Save `make`s output in a file:
make &>/log

# Redirections stack and can be used with blocks:
begin
echo stdout
echo stderr >&2 # <- this goes to stderr!
end >/dev/null # ignore stdout, so this prints "stderr"

It is an error to redirect a builtin, function, or block to a file de-
scriptor above 2. However this is supported for external commands.

[1] Previous versions of fish also allowed specifying this as ^DESTI-
NATION, but that made another character special so it was depre-
cated and removed. See feature flags.

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

cat foo.txt | head

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.

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:

make fish 2>| less

will attempt to build fish, and any errors will be shown using the less
pager. [2]

As a convenience, the pipe &| redirects both stdout and stderr to the
same process. This is different from bash, which uses |&.

[2] A "pager" here is a program that takes output and "paginates" it.
less doesn't just do pages, it allows arbitrary scrolling (even
back!).

Combining pipes and redirections
It is possible to use multiple redirections and a pipe at the same
time. In that case, they are read in this order:

1. First the pipe is set up.

2. Then the redirections are evaluated from left-to-right.

This is important when any redirections reference other file descrip-
tors with the &N syntax. When you say >&2, that will redirect stdout to
where stderr is pointing to at that time.

Consider this helper function:

# Just make a function that prints something to stdout and stderr
function print
echo out
echo err >&2
end

Now let's see a few cases:

# Redirect both stderr and stdout to less
# (can also be spelt as `&|`)
print 2>&1 | less

# Show the "out" on stderr, silence the "err"
print >&2 2>/dev/null

# Silence both
print >/dev/null 2>&1

Job control
When you start a job in fish, fish itself will pause, and give control
of the terminal to the program 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 & (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 inter-
face.

Example:

emacs &

will start the emacs text editor in the background. fg can be used to
bring it into the foreground again when needed.

Most programs allow you to suspend the program's execution and return
control to fish by pressing Control+Z (also referred to as ^Z). Once
back at the fish commandline, you can start other programs and do any-
thing you want. If you then want you can go back to the suspended com-
mand by using the fg (foreground) command.

If you instead want to put a suspended job into the background, use the
bg command.

To get a listing of all currently started jobs, use the jobs command.
These listed jobs can be removed with the disown command.

At the moment, functions cannot be started in the background. Functions
that are stopped and then restarted in the background using the bg com-
mand will not execute correctly.

If the & character is followed by a non-separating character, it is not
interpreted as background operator. Separating characters are white-
space and the characters ;<>&|.

Functions
Functions are programs written in the fish syntax. They group together
various commands and their arguments using a single name.

For example, here's a simple function to list directories:

function ll
ls -l $argv
end

The first line tells fish to define a function by the name of ll, so it
can be used by simply writing ll on the commandline. The second line
tells fish that the command ls -l $argv should be called when ll is in-
voked. $argv is a list variable, which always contains all arguments
sent to the function. In the example above, these are simply passed on
to the ls command. The end on the third line ends the definition.

Calling this as ll /tmp/ will end up running ls -l /tmp/, which will
list the contents of /tmp.

This is a kind of function known as an alias.

Fish's prompt is also defined in a function, called fish_prompt. It is
run when the prompt is about to be displayed and its output forms the
prompt:

function fish_prompt
# A simple prompt. Displays the current directory
# (which fish stores in the $PWD variable)
# and then a user symbol - a '' for a normal user and a '#' for root.
set -l user_char ''
if fish_is_root_user
set user_char '#'
end

echo (set_color yellow)$PWD (set_color purple)$user_char
end

To edit a function, you can use funced, and to save a function
funcsave. This will store it in a function file that fish will autoload
when needed.

The functions builtin can show a function's current definition (and
type will also do if given a function).

For more information on functions, see the documentation for the
function builtin.

Defining aliases
One of the most common uses for functions is to slightly alter the be-
havior 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:

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

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

• Always take care to add the $argv 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.

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

To easily create a function of this form, you can use the alias com-
mand. Unlike other shells, this just makes functions - fish has no sep-
arate concept of an "alias", we just use the word for a simple wrapping
function like this. alias immediately creates a function. Consider us-
ing alias --save or funcsave to save the created function into an au-
toload file instead of recreating the alias each time.

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

Autoloading functions
Functions can be defined on the commandline or in a configuration file,
but they can also be automatically loaded. This has some advantages:

• An autoloaded function becomes available automatically to all running
shells.

• If the function definition is changed, all running shells will auto-
matically reload the altered version, after a while.

• Startup time and memory usage is improved, etc.

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 con-
sisting 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:

• A directory for users to keep their own functions, usually ~/.con-
fig/fish/functions (controlled by the XDG_CONFIG_HOME environment
variable).

• A directory for functions for all users on the system, usually
/etc/fish/functions (really $__fish_sysconfdir/functions).

• Directories for other software to put their own functions. These are
in the directories under $__fish_user_data_dir (usually ~/.lo-
cal/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/lo-
cal/share/fish/vendor_functions.d.

• The functions shipped with fish, usually installed in
/usr/share/fish/functions (really $__fish_data_dir/functions).

If you are unsure, your functions probably belong in ~/.con-
fig/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 func-
tions 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 in-
stallation system should support a custom path to override the pkgcon-
fig path, as other distributors may need to alter it easily.

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

This is useful to explain what and why you are doing something:

function ls
# The function is called ls,
# so we have to explicitly call `command ls` to avoid calling ourselves.
command ls --color=auto $argv
end

There are no multiline comments. If you want to make a comment span
multiple lines, simply start each line with a #.

Comments can also appear after a line like so:

set -gx EDITOR emacs # I don't like vim.

Conditions
Fish has some builtins that let you execute commands only if a specific
criterion is met: if, switch, and and or, and also the familiar &&/||
syntax.

The if statement
The if statement runs a block of commands if the condition was true.

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 exit status (that's 0), the if-block is run. For example:

if test -e /etc/os-release
cat /etc/os-release
end

This uses the test command to see if the file /etc/os-release exists.
If it does, it runs cat, which prints it on the screen.

Unlike other shells, the condition command just ends after the first
job, there is no then here. Combiners like and and or extend the condi-
tion.

if is commonly used with the test command that can check conditions.:

if test 5 -gt 2
echo "Yes, 5 is greater than 2"
end

if can also take else if clauses with additional conditions and an
else clause that is executed when everything else was false:

if test "$number" -gt 10
echo Your number was greater than 10
else if test "$number" -gt 5
echo Your number was greater than 5
else if test "$number" -gt 1
echo Your number was greater than 1
else
echo Your number was smaller or equal to 1
end

The not keyword can be used to invert the status:

# Just see if the file contains the string "fish" anywhere.
# This executes the `grep` command, which searches for a string,
# and if it finds it returns a status of 0.
# The `not` then turns 0 into 1 or anything else into 0.
# The `-q` switch stops it from printing any matches.
if not grep -q fish myanimals
echo "You don't have fish!"
else
echo "You have fish!"
end

The switch statement
The switch command is used to execute one of possibly many blocks of
commands depending on the value of a string. It can take multiple case
blocks that are executed when the string matches. They can take
wildcards. For example:

switch (uname)
case Linux
echo Hi Tux!
case Darwin
echo Hi Hexley!
case DragonFly '*BSD'
echo Hi Beastie! # this also works for FreeBSD and NetBSD
case '*'
echo Hi, stranger!
end

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.

Combiners (and / or / && / ||)
For simple checks, you can use combiners. and or && run the second com-
mand if the first succeeded, while or or || run it if the first failed.
For example:

# $XDG_CONFIG_HOME is a standard place to store configuration.
# If it's not set applications should use ~/.config.
set -q XDG_CONFIG_HOME; and set -l configdir $XDG_CONFIG_HOME
or set -l configdir ~/.config

Note that combiners are lazy - only the part that is necessary to de-
termine the final status is run.

Compare:

if sleep 2; and false
echo 'How did I get here? This should be impossible'
end

and:

if false; and sleep 2
echo 'How did I get here? This should be impossible'
end

These do essentially the same thing, but the former takes 2 seconds
longer because the sleep always needs to run.

Or you can have a case where it is necessary to stop early:

if command -sq foo; and foo

If this went on after seeing that the command "foo" doesn't exist, it
would try to run foo and error because it wasn't found!

Combiners really just 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:

test -e /etc/my.config
or echo "OH NO WE NEED A CONFIG FILE"
and return 1

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 $sta-
tus is still 0.

So if you have more complex conditions or want to run multiple things
after something failed, consider using an if. Here that would be:

if not test -e /etc/my.config
echo "OH NO WE NEED A CONFIG FILE"
return 1
end

Loops and blocks
Like most programming language, fish also has the familiar while and
for loops.

while works like a repeated if:

while true
echo Still running
sleep 1
end

will print "Still running" once a second. You can abort it with ctrl-c.

for loops work like in other shells, which is more like python's
for-loops than e.g. C's:

for file in *
echo file: $file
end

will print each file in the current directory. The part after the in is
just a list of arguments, so you can use any expansions there:

set moreanimals bird fox
for animal in {cat,}fish dog $moreanimals
echo I like the $animal
end

If you need a list of numbers, you can use the seq command to create
one:

for i in (seq 1 5)
echo $i
end

break is available to break out of a loop, and continue to jump to the
next iteration.

Input and output redirections (including pipes) can also be applied to
loops:

while read -l line
echo line: $line
end < file

In addition there's a begin block that just groups commands together so
you can redirect to a block or use a new variable scope without any
repetition:

begin
set -l foo bar # this variable will only be available in this block!
end

Parameter expansion
When fish is given a commandline, it expands the parameters before
sending them to the command. There are multiple different kinds of ex-
pansions:

• Wildcards, to create filenames from patterns - *.jpg

• Variable expansion, to use the value of a variable - $HOME

• Command substitution, to use the output of another command - $(cat
/path/to/file)

• Brace expansion, to write lists with common pre- or suffixes in a
shorter way {/usr,}/bin

• Tilde expansion, to turn the ~ at the beginning of paths into the
path to the home directory ~/bin

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.

Wildcards ("Globbing")
When a parameter includes an unquoted * star (or "asterisk") or a ?
question mark, fish uses it as a wildcard to match files.

• * matches any number of characters (including zero) in a file name,
not including /.

• ** matches any number of characters (including zero), and also de-
scends into subdirectories. If ** is a segment by itself, that seg-
ment may match zero times, for compatibility with other shells.

• ? can match any single character except /. This is deprecated and can
be disabled via the qmark-noglob feature flag, so ? will just be an
ordinary character.

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:

• a* matches any files beginning with an 'a' in the current directory.

• ** matches any files and directories in the current directory and all
of its subdirectories.

• ~/.* matches all hidden files (also known as "dotfiles") and directo-
ries in your home directory.

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 be-
havior is like what bash does with shopt -s failglob. There are excep-
tions, namely set and path, overriding variables in overrides, count
and for. Their globs will instead expand to zero arguments (so the com-
mand 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

Unlike bash (by default), fish will not pass on the literal glob char-
acter if no match was found, so for a command like apt install that
does the matching itself, you need to add quotes:

apt install "ncurses-*"

Variable expansion
One of the most important expansions in fish is the "variable expan-
sion". This is the replacing of a dollar sign ($) followed by a vari-
able name with the _value_ of that variable.

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 de-
fault 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 "").

For more on shell variables, read the Shell variables section.

Quoting variables
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 [3].

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

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

Unlike other shells, fish doesn't do what is known as "Word Splitting".
Once a variable is set to a particular set of elements, those elements
expand as themselves. They aren't split on spaces or newlines or any-
thing:

> set foo one\nthing
> echo $foo
one
thing
> printf '|%s|\n' $foo
|one
thing|

That means quoting isn't the absolute necessity it is in other shells.
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 test:

set -l foo one two three
test -n $foo
# prints an error that it got too many arguments, because it was executed like
test -n one two three

test -n "$foo"
# works, because it was executed like
test -n "one two three"

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

Dereferencing variables
The $ symbol can also be used multiple times, as a kind of "derefer-
ence" 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..-1][5] (take all elements of $foo, use them as variable names,
then give the fifth element of those).

Command substitution
A command substitution is an expansion that uses the output of a com-
mand as the arguments to another. For example:

echo (pwd)

This executes the pwd command, takes its output (more specifically what
it wrote to the standard output "stdout" stream) and uses it as argu-
ments to echo. So the inner command (the pwd) is run first and has to
complete before the outer command can even be started.

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 [4], fish splits on newlines.

A command substitution can also be spelled with a dollar sign like out-
ercommand $(innercommand). This variant is also allowed inside double
quotes. When using double quotes, the command output is not split up by
lines, but trailing empty lines are still removed.

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

To use only some lines of the output, refer to slices.

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.
set data "$(cat data.txt)"

# 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 in-
put, "process substitution" is useful. Other shells 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.

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

[4] One exception: Setting $IFS to empty will disable line splitting.
This is deprecated, use string split instead.

Brace expansion
Curly braces can be used to write comma-separated lists. They will be
expanded with each element becoming a new parameter, with the surround-
ing string attached. This is useful to save on typing, and to separate
a variable name from surrounding text.

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 in-
terpreted 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)
When lists are expanded with other parts attached, they are expanded
with these parts still attached. Even if two lists are attached to each
other, they are expanded in all combinations. This is referred to as
the "cartesian product" (like in mathematics), and works basically like
brace expansion.

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 disap-
pearing 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 direc-
tories in it. And if there are no directories in PATH, the right answer
here is to expand to no files.

Slices
Sometimes it's necessary to access only some of the elements of a list
(all fish variables are lists), or some of the lines a command substi-
tution outputs. Both are possible in fish by writing a set of indices
in brackets, like:

# 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 in-
dex.

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 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 cur-
rently 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
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:

ls ~/Music # lists my music directory

echo ~root # prints root's home directory, probably "/root"

Combining different expansions
All of the above expansions can be combined. If several expansions re-
sult in more than one parameter, all possible combinations are created.

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

• Command substitutions

• Variable expansions

• Bracket expansion

• Wildcard expansion

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 com-
mand echo a(ls){1,2,3} will output abar1 abar2 abar3 afoo1 afoo2 afoo3.

Shell variables
Variables are a way to save data and pass it around. They can be used
just by the shell, or they can be "exported", so that a copy of the
variable is available to any external command the shell starts. An ex-
ported variable is referred to as an "environment variable".

To set a variable value, use the set 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.

Example:

To set the variable smurf_color to the value blue, use the command set
smurf_color blue.

After a variable has been set, you can use the value of a variable in
the shell through variable expansion.

Example:

set smurf_color blue
echo Smurfs are usually $smurf_color
set pants_color red
echo Papa smurf, who is $smurf_color, wears $pants_color pants

So you set a variable with set, and use it with a $ and the name.

Variable Scope
There are four kinds of variables in fish: universal, global, function
and local variables.

• Universal variables are shared between all fish sessions a user is
running on one computer. They are stored on disk and persist even af-
ter reboot.

• Global variables are specific to the current fish session. They can
be erased by explicitly requesting set -e.

• Function variables are specific to the currently executing function.
They are erased ("go out of scope") when the current function ends.
Outside of a function, they don't go out of scope.

• 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 com-
mands 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.

Variables can be explicitly set to be universal with the -U or --uni-
versal 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:

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

• When no scope is given, but a variable of that name exists, the vari-
able of the smallest scope will be modified. The scope will not be
changed.

• When no scope is given and no variable of that name exists, the vari-
able is created in function scope if inside a function, or global
scope if no function is executing.

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

# or

function something
if test -e /path/to/my/file
set -f file /path/to/my/file
else
set -f 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:

function test-scopes
begin
# This is a nice local scope where all variables will die
set -l pirate 'There be treasure in them thar hills'
set -f captain Space, the final frontier
# If no variable of that name was defined, it is function-local.
set gnu "In the beginning there was nothing, which exploded"
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.
echo $gnu
# Will output Sir Terry's wisdom.
end

When a function calls another, local variables aren't visible:

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
# so phrase remains as we set it here.
shiver
echo $phrase
end
avast

# Outputs "Avast, mateys"

When in doubt, use function-scoped variables. When you need to make a
variable accessible everywhere, make it global. When you need to per-
sistently store configuration, make it universal. When you want to use
a variable only in a short block, make it local.

Overriding variables for a single command
If you want to override a variable for a single command, you can use
"var=val" statements before the 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 simi-
lar). 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.

Universal Variables
Universal variables are variables that are shared between all the
user's fish sessions on the computer. Fish stores many of its configu-
ration options as universal variables. This means that in order to
change fish settings, all you have to do is change the variable value
once, and it will be automatically updated for all sessions, and pre-
served across computer reboots and login/logout.

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

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.

Exporting variables
Variables in fish can be exported, so they will be inherited by any
commands started by fish. In particular, this is necessary for vari-
ables 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 "environment
variables".

This also applies to fish - when it starts up, it receives environment
variables from its parent (usually the terminal). These typically in-
clude 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 export-
ing 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 vari-
able didn't exist yet it is not exported.

As a naming convention, exported variables are in uppercase and unex-
ported 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-ex-
ported 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. Global variables are ac-
cessible to functions whether they are exported or not.

Lists
Fish can store a list (or an "array" if you wish) of multiple strings
inside of a variable:

> 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 in-
valid 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 exam-
ple, 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 slices 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
# blue was found, so it exits with status 0
# (without printing anything)

> echo $status
0

> contains -i blue $smurf
1

A nice thing about lists is that they are passed to commands one ele-
ment 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
An important list is $argv, which contains the arguments to a function
or script. For example:

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

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"git ") as well as a -- separator to signal the
end of options. Handling all of these manually is tricky and er-
ror-prone.

A more robust approach to option 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
# We tell argparse about -h/--help and -s/--second - these are short and long forms of the same option.
# The "--" here is mandatory, it tells it from where to read the arguments.
argparse h/help s/second -- $argv
# exit if argparse failed because it found an option it didn't recognize - it will print an error
or return

# If -h or --help is given, we print a little help text and return
if set -ql _flag_help
echo "mybetterfunction [-h|--help] [-s|--second] [ARGUMENT ...]"
return 0
end

# If -s or --second is given, we print the second argument,
# not the first and third.
# (this is also available as _flag_s because of the short version)
if set -ql _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 posi-
tional argument now:

> mybetterfunction first -s second third
second

For more information on argparse, like how to handle option arguments,
see the argparse documentation.

PATH variables
Path variables are a special kind of variable used to support colon-de-
limited path lists including PATH, CDPATH, MANPATH, PYTHONPATH, etc.
All variables that end in "PATH" (case-sensitive) become PATH variables
by default.

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

Path variables will also be exported in the colon form, so set -x MY-
PATH 1 2 3 will have external commands see it as 1:2:3.

> set -gx MYPATH /bin /usr/bin /sbin
> env | grep MYPATH
MYPATH=/bin:/usr/bin:/sbin

This is for compatibility with other tools. Unix doesn't have variables
with multiple elements, the closest thing it has are colon-lists like
PATH. For obvious reasons this means no element can contain a :.

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

Special variables
You can change the settings of fish by changing the values of certain
variables.

PATH A list of directories in which to search for commands. This is a
common unix variable also used by other tools.

CDPATH A list of directories in which the cd builtin looks for a new
directory.

Locale Variables
The locale variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE,
LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LANG set the language
option for the shell and subprograms. See the section Locale
variables for more information.

Color variables
A number of variable starting with the prefixes fish_color and
fish_pager_color. See Variables for changing highlighting colors
for more information.

fish_term24bit
If this is set to 1, fish will assume the terminal understands
24-bit RGB color sequences, and won't translate them to the 256
or 16 color palette. This is often detected automatically.

fish_term256
If this is set to 1, fish will assume the terminal understands
256 colors, and won't translate matching colors down to the 16
color palette. This is usually autodetected.

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

fish_emoji_width
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 "spe-
cial" characters). It should usually be auto-detected.

fish_autosuggestion_enabled
controls if Autosuggestions are enabled. Set it to 0 to disable,
anything else to enable. By default they are on.

fish_handle_reflow
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 dis-
able.

fish_key_bindings
the name of the function that sets up the keyboard shortcuts for
the command-line editor.

fish_escape_delay_ms
sets how long fish waits for another key after seeing an escape,
to distinguish pressing the escape key from the start of an es-
cape sequence. The default is 30ms. Increasing it increases the
latency but allows pressing escape instead of alt for alt+char-
acter bindings. For more information, see the chapter in the
bind documentation.

fish_sequence_key_delay_ms
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 Key se-
quences.

fish_complete_path
determines where fish looks for completion. When trying to com-
plete for a command, fish looks for files in the directories in
this variable.

fish_cursor_selection_mode
controls whether the selection is inclusive or exclusive of the
character under the cursor (see Copy and Paste).

fish_function_path
determines where fish looks for functions. When fish autoloads a
function, it will look for files in these directories.

fish_greeting
the greeting message printed on startup. This is printed by a
function of the same name that can be overridden for more com-
plicated changes (see funced)

fish_history
the current history session name. If set, all subsequent com-
mands within an interactive fish session will be logged to a
separate file identified by the value of the variable. If unset,
the default session name "fish" is used. If set to an empty
string, history is not saved to disk (but is still available
within the interactive session).

fish_trace
if set and not empty, will cause fish to print commands before
they execute, similar to set -x in bash. The trace is printed to
the path given by the --debug-output option to fish or the
FISH_DEBUG_OUTPUT variable. It goes to stderr by default.

FISH_DEBUG
Controls which debug categories fish enables for output, analo-
gous to the --debug option.

FISH_DEBUG_OUTPUT
Specifies a file to direct debug output to.

fish_user_paths
a list of directories that are prepended to PATH. This can be a
universal variable.

umask the current file creation mask. The preferred way to change the
umask variable is through the umask function. An attempt to set
umask to an invalid value will always fail.

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

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.

_ the name of the currently running command (though this is depre-
cated, and the use of status current-command is preferred).

argv a list of arguments to the shell or function. argv is only de-
fined when inside a function call, or if fish was invoked with a
list of arguments, like fish myscript.fish foo bar. This vari-
able can be changed.

CMD_DURATION
the runtime of the last command in milliseconds.

COLUMNS and LINES
the current size of the terminal in height and width. These val-
ues are only used by fish if the operating system does not re-
port 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.

fish_kill_signal
the signal that terminated the last foreground job, or 0 if the
job exited normally.

fish_killring
a list of entries in fish's kill ring of cut text.

fish_read_limit
how many bytes fish will process with read or in a command sub-
stitution.

fish_pid
the process ID (PID) of the shell.

history
a list containing the last commands that were entered.

HOME the user's home directory. This variable can be changed.

hostname
the machine's hostname.

IFS the internal field separator that is used for word splitting
with the read builtin. Setting this to the empty string will
also disable line splitting in command substitution. This vari-
able can be changed.

last_pid
the process ID (PID) of the last background process.

PWD the current working directory.

pipestatus
a list of exit statuses of all processes that made up the last
executed pipe. See exit status.

SHLVL the level of nesting of shells. Fish increments this in interac-
tive shells, otherwise it simply passes it along.

status the exit status 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.

status_generation
the "generation" count of $status. This will be incremented only
when the previous command produced an explicit status. (For ex-
ample, background jobs will not increment this).

TERM the type of the current terminal. When fish tries to determine
how the terminal works - how many colors it supports, what se-
quences it sends for keys and other things - it looks at this
variable and the corresponding information in the terminfo data-
base (see man terminfo).

Note: Typically this should not be changed as the terminal sets
it to the correct value.

USER the current username. This variable can be changed.

EUID the current effective user id, set by fish at startup. This
variable can be changed.

version
the version of the currently running fish (also available as
FISH_VERSION for backward compatibility).

As a convention, an uppercase name is usually used for exported vari-
ables, 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 ex-
ported 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
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 ex-
ecuted without problem, but a non-zero exit status means there was some
form of problem.

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:

• 0 is generally the exit status of commands if they successfully per-
formed the requested operation.

• 1 is generally the exit status of commands if they failed to perform
the requested operation.

• 121 is generally the exit status of commands if they were supplied
with invalid arguments.

• 123 means that the command was not executed because the command name
contained invalid characters.

• 124 means that the command was not executed because none of the wild-
cards in the command produced any matches.

• 125 means that while an executable with the specified name was lo-
cated, the operating system could not actually execute the command.

• 126 means that while a file with the specified name was located, it
was not executable.

• 127 means that no function, builtin or command with the given name
could be located.

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

It's possible for the first command to fail while the second succeeds.
One common example is when the second program quits early.

For example, if you have a pipeline like:

cat file1 file2 | head -n 50

This will tell cat to print two files, "file1" and "file2", one after
the other, and the head will then only print the first 50 lines. In
this case you might often see this constellation:

> cat file1 file2 | head -n 50
# 50 lines of output
> echo $pipestatus
141 0

Here, the "141" signifies that cat was killed by signal number 13 (128
+ 13 == 141) - a SIGPIPE. You can also use 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.

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 "0 0", de-
pending on the implementation. This is a general unix issue and not
specific to fish. Some shells feature a "pipefail" feature that will
call a pipeline failed if one of the processes in it failed, and this
is a big problem with it.

Locale Variables
The "locale" of a program is its set of language and regional settings
that depend on language and cultural convention. In UNIX, these are
made up of several categories. The categories are:

LANG This is the typical environment variable for specifying a lo-
cale. A user may set this variable to express the language they
speak, their region, and a character encoding. The actual values
are specific to their platform, except for special values like C
or POSIX.

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.

An example value might be en_US.UTF-8 for the american version
of english and the UTF-8 encoding, or de_AT.UTF-8 for the aus-
trian version of german and the UTF-8 encoding. Your operating
system might have a locale command that you can call as locale
-a to see a list of defined locales.

A UTF-8 encoding is recommended.

LC_ALL Overrides the LANG environment variable and the values of the
other LC_* variables. If this is set, none of the other vari-
ables are used for anything.

Usually the other variables should be used instead. Use LC_ALL
only when you need to override something.

LC_COLLATE
This determines the rules about equivalence of cases and alpha-
betical ordering: collation.

LC_CTYPE
This determines classification rules, like if the type of char-
acter is an alpha, digit, and so on. Most importantly, it de-
fines the text encoding - which numbers map to which characters.
On modern systems, this should typically be something ending in
"UTF-8".

LC_MESSAGES
LC_MESSAGES determines the language in which messages are diis-
played.

LC_MONETARY
Determines currency, how it is formated, and the symbols used.

LC_NUMERIC
Sets the locale for formatting numbers.

LC_TIME
Sets the locale for formatting dates and times.

Builtin commands
Fish includes a number of commands in the shell directly. We call these
"builtins". These include:

• Builtins that manipulate the shell state - cd changes directory, set
sets variables

• Builtins for dealing with data, like string for strings and math for
numbers, count for counting lines or arguments, path for dealing with
path

• status for asking about the shell's status

• printf and echo for creating output

• test for checking conditions

• argparse for parsing function arguments

• source to read a script in the current shell (so changes to variables
stay) and eval to execute a string as script

• random to get random numbers or pick a random element from a list

• read for reading from a pipe or the terminal

For a list of all builtins, use builtin -n.

For a list of all builtins, functions and commands shipped with fish,
see the list of commands. The documentation is also available by using
the --help switch.

Command lookup
When fish is told to run something, it goes through multiple steps to
find it.

If it contains a /, fish tries to execute the given file, from the cur-
rent directory on.

If it doesn't contain a /, it could be a function, builtin, or external
command, and so fish goes through the full lookup.

In order:

1. It tries to resolve it as a function.

• If the function is already known, it uses that

• If there is a file of the name with a ".fish" suffix in
fish_function_path, it loads that. (If there is more than one file
only the first is used)

• If the function is now defined it uses that

2. It tries to resolve it as a builtin.

3. It tries to find an executable file in PATH.

• If it finds a file, it tells the kernel to run it.

• If the kernel knows how to run the file (e.g. via a #! line -
#!/bin/sh or #!/usr/bin/python), it does it.

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

If none of these work, fish runs the function fish_command_not_found
and sets status to 127.

You can use type to see how fish resolved something:

> type --short --all echo
echo is a builtin
echo is /usr/bin/echo

Querying for user input
Sometimes, you want to ask the user for input, for instance to confirm
something. This can be done with the read builtin.

Let's make up an example. This function will glob the files in all the
directories it gets as arguments, and if there are more than five it
will ask the user if it is supposed to show them, but only if it is
connected to a terminal:

function show_files
# This will glob on all arguments. Any non-directories will be ignored.
set -l files $argv/*

# If there are more than 5 files
if test (count $files) -gt 5
# and both stdin (for reading input) and stdout (for writing the prompt)
# are terminals
and isatty stdin
and isatty stdout
# Keep asking until we get a valid response
while read --nchars 1 -l response --prompt-str="Are you sure? (y/n)"
or return 1 # if the read was aborted with ctrl-c/ctrl-d
switch $response
case y Y
echo Okay
# We break out of the while and go on with the function
break
case n N
# We return from the function without printing
echo Not showing
return 1
case '*'
# We go through the while loop and ask again
echo Not valid input
continue
end
end
end

# And now we print the files
printf '%s\n' $files
end

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
just print something without asking because there are fewer than five
files.

Shell variable and function names
The names given to variables and functions (so-called "identifiers")
have to follow certain rules:

• A variable name cannot be empty. It can contain only letters, digits,
and underscores. It may begin and end with any of those characters.

• A function name cannot be empty. It may not begin with a hyphen ("-")
and may not contain a slash ("/"). All other characters, including a
space, are valid. A function name also can't be the same as a re-
served keyword or essential builtin like if or set.

• A bind mode name (e.g., bind -m abc ...) must be a valid variable
name.

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 "/" (because that is the path separator) or NULL byte (be-
cause that is how UNIX ends strings).

Configuration files
When fish is started, it reads and runs its configuration files. Where
these are depends on build configuration and environment variables.

The main file is ~/.config/fish/config.fish (or more precisely
$XDG_CONFIG_HOME/fish/config.fish).

Configuration files are run in the following order:

• Configuration snippets (named *.fish) in the directories:

• $__fish_config_dir/conf.d (by default, ~/.config/fish/conf.d/)

• $__fish_sysconf_dir/conf.d (by default, /etc/fish/conf.d/)

• Directories for others to ship configuration snippets for their
software:

• the directories under $__fish_user_data_dir (usually ~/.lo-
cal/share/fish, controlled by the XDG_DATA_HOME environment vari-
able)

• 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)

These directories are also accessible in $__fish_vendor_confdirs.
Note that changing that in a running fish won't do anything as by
that point the directories have already been read.

If there are multiple files with the same name in these directories,
only the first will be executed. They are executed in order of their
filename, sorted (like globs) in a natural order (i.e. "01" sorts be-
fore "2").

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

• User configuration, usually in ~/.config/fish/config.fish (controlled
by the XDG_CONFIG_HOME environment variable, and accessible as
$__fish_config_dir).

~/.config/fish/config.fish is sourced after the snippets. This is so
you can copy snippets and override some of their behavior.

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.

If you are developing another program, you may want to add configura-
tion 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 in-
stall them to the "vendor" configuration directory. As this path may
vary from system to system, pkg-config should be used to discover it:
pkg-config --variable confdir fish.

For system integration, fish also ships a file called
__fish_build_paths.fish. This can be customized during build, for in-
stance because your system requires special paths to be used.

Future feature flags
Feature flags are how fish stages changes that might break scripts.
Breaking changes are introduced as opt-in, in a few releases they be-
come opt-out, and eventually the old behavior is removed.

You can see the current list of features via status features:

> status features
stderr-nocaret on 3.0 ^ no longer redirects stderr
qmark-noglob off 3.0 ? no longer globs
regex-easyesc on 3.1 string replace -r needs fewer \\'s
ampersand-nobg-in-token on 3.4 & only backgrounds if followed by a separating character

Here is what they mean:

• stderr-nocaret was introduced in fish 3.0 (and made the default in
3.3). It makes ^ an ordinary character instead of denoting an stderr
redirection, to make dealing with quoting and such easier. Use 2> in-
stead. This can no longer be turned off since fish 3.5. The flag can
still be tested for compatibility, but a no-stderr-nocaret value will
simply be ignored.

• qmark-noglob was also introduced in fish 3.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.

• regex-easyesc was introduced in 3.1. It makes it so the replacement
expression in string replace -r does one fewer round of escaping. Be-
fore, 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.

• ampersand-nobg-in-token was introduced in fish 3.4. It makes it so a
& i 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 &. This is recommended formatting anyway, and
fish_indent will have done it for you already.

These changes are introduced off by default. They can be enabled on a
per session basis:

> fish --features qmark-noglob,regex-easyesc

or opted into globally for a user:

> set -U fish_features regex-easyesc qmark-noglob

Features will only be set on startup, so this variable will only take
effect if it is universal or exported.

You can also use the version as a group, so 3.0 is equivalent to
"stderr-nocaret" and "qmark-noglob". Instead of a version, the special
group all enables all features.

Prefixing a feature with no- turns it off instead. E.g. to reenable the
? single-character glob:

set -Ua fish_features no-qmark-noglob

Currently, the following features are enabled by default:

• stderr-nocaret - ^ no longer redirects stderr, use 2>. Enabled by de-
fault in fish 3.3.0. No longer changeable since fish 3.5.0.

• regex-easyesc - string replace -r requires fewer backslashes in the
replacement part. Enabled by default in fish 3.5.0.

• ampersand-nobg-in-token - & in the middle of a word is a normal char-
acter instead of backgrounding. Enabled by default in fish 3.5.0.

Event handlers
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 spe-
cific event takes place. Events that can trigger a handler currently
are:

• When a signal is delivered

• When a job exits

• When the value of a variable is updated

• When the prompt is about to be shown

Example:

To specify a signal handler for the WINCH signal, write:

function my_signal_handler --on-signal WINCH
echo Got WINCH signal!
end

Fish already has the following named events for the --on-event switch:

• fish_prompt is emitted whenever a new fish prompt is about to be dis-
played.

• fish_preexec is emitted right before executing an interactive com-
mand. The commandline is passed as the first parameter. Not emitted
if command is empty.

• fish_posterror is emitted right after executing a command with syntax
errors. The commandline is passed as the first parameter.

• fish_postexec is emitted right after executing an interactive com-
mand. The commandline is passed as the first parameter. Not emitted
if command is empty.

• fish_exit is emitted right before fish exits.

• fish_cancel is emitted when a commandline is cleared.

Events can be fired with the emit command, and do not have to be de-
fined before. The names just need to match. For example:

function handler --on-event imdone
echo generator is done $argv
end

function generator
sleep 1
# The "imdone" is the name of the event
# the rest is the arguments to pass to the handler
emit imdone with $argv
end

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.

Please note that event handlers only become active when a function is
loaded, which means you need to otherwise source or execute a function
instead of relying on autoloading. One approach is to put it into your
configuration file.

For more information on how to define new event handlers, see the docu-
mentation for the function command.

Debugging fish scripts
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 printf and set. As another example, you can run status
print-stack-trace to see how the current breakpoint was reached. To re-
sume normal execution of the script, simply type exit or Control+D.

To start a debug session simply insert the builtin command 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 ac-
tively debugged by sending it the TRAP signal (kill -s TRAP <PID>).
There is limited support for interactively setting or modifying break-
points from this debug prompt: it is possible to insert new breakpoints
in (or remove old ones from) other functions by using the funced func-
tion 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.

Another way to debug script issues is to set the fish_trace variable,
e.g. fish_trace=1 fish_prompt to see which commands fish executes when
running the fish_prompt function.

If you specifically want to debug performance issues, 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. See fish for more information.

Commands
This is a list of all the commands fish ships with.

Broadly speaking, these fall into a few categories:

Keywords
Core language keywords that make up the syntax, like

• if for conditions.

• for and while for loops.

• break and continue to control loops.

• function to define functions.

• return to return a status from a function.

• begin to begin a block and end to end any block (including ifs and
loops).

• and, or and not to combine commands logically.

• switch and case to make multiple blocks depending on the value of a
variable.

• command or builtin to tell fish what sort of thing to execute

• time to time execution

• exec tells fish to replace itself with a command.

Tools
Builtins to do a task, like

• cd to change the current directory.

• echo or printf to produce output.

• set_color to colorize output.

• set to set, query or erase variables.

• read to read input.

• string for string manipulation.

• math does arithmetic.

• argparse to make arguments easier to handle.

• count to count arguments.

• type to find out what sort of thing (command, builtin or function)
fish would call, or if it exists at all.

• test checks conditions like if a file exists or a string is empty.

• contains to see if a list contains an entry.

• eval and source to run fish code from a string or file.

• status to get shell information, like whether it's interactive or a
login shell, or which file it is currently running.

• abbr manages Abbreviations.

• bind to change bindings.

• complete manages completions.

• commandline to get or change the commandline contents.

• fish_config to easily change fish's configuration, like the prompt or
colorscheme.

• random to generate random numbers or pick from a list.

Known functions
Known functions are a customization point. You can change them to
change how your fish behaves. This includes:

• fish_prompt and fish_right_prompt and fish_mode_prompt to print your
prompt.

• fish_command_not_found to tell fish what to do when a command is not
found.

• fish_title to change the terminal's title.

• fish_greeting to show a greeting when fish starts.

Helper functions
Some helper functions, often to give you information for use in your
prompt:

• fish_git_prompt and fish_hg_prompt to print information about the
current git or mercurial repository.

• fish_vcs_prompt to print information for either.

• fish_svn_prompt to print information about the current svn reposi-
tory.

• fish_status_to_signal to give a signal name from a return status.

• prompt_pwd to give the current directory in a nicely formatted and
shortened way.

• prompt_login to describe the current login, with user and hostname,
and to explain if you are in a chroot or connected via ssh.

• prompt_hostname to give the hostname, shortened for use in the
prompt.

• fish_is_root_user to check if the current user is an administrator
user like root.

• fish_add_path to easily add a path to $PATH.

• alias to quickly define wrapper functions ("aliases").

• fish_delta to show what you have changed from the default configura-
tion.

Helper commands
fish also ships some things as external commands so they can be easily
called from elsewhere.

This includes fish_indent to format fish code and fish_key_reader to
show you what escape sequence a keypress produces.

The full list
And here is the full list:

_ - call fish's translations
Synopsis
_ STRING

Description
_ translates its arguments into the current language, if possible.

It is equivalent to gettext fish STRING, meaning it can only be used to
look up fish's own translations.

It requires fish to be built with gettext support. If that support is
disabled, or there is no translation it will simply echo the argument
back.

The language depends on the current locale, set with LANG and
LC_MESSAGES.

Options
_ takes no options.

Examples
> _ File
Datei

abbr - manage fish abbreviations
Synopsis
abbr --add NAME [--position command | anywhere] [-r | --regex PATTERN]
[--set-cursor[=MARKER]] ([-f | --function FUNCTION] | EXPANSION)
abbr --erase NAME ...
abbr --rename OLD_WORD NEW_WORD
abbr --show
abbr --list
abbr --query NAME ...

Description
abbr manages abbreviations - user-defined words that are replaced with
longer phrases when entered.

NOTE:
Only typed-in commands use abbreviations. Abbreviations are not ex-
panded in scripts.

For example, a frequently-run command like git checkout can be abbrevi-
ated to gco. After entering gco and pressing Space or Enter, the full
text git checkout will appear in the command line. To avoid expanding
something that looks like an abbreviation, the default Control+Space
binding inserts a space without expanding.

An abbreviation may match a literal word, or it may match a pattern
given by a regular expression. When an abbreviation matches a word,
that word is replaced by new text, called its expansion. This expansion
may be a fixed new phrase, or it can be dynamically created via a fish
function. This expansion occurs after pressing space or enter.

Combining these features, it is possible to create custom syntaxes,
where a regular expression recognizes matching tokens, and the expan-
sion function interprets them. See the Examples section.

Changed in version 3.6.0: Previous versions of this allowed saving ab-
breviations in universal variables. That's no longer possible. Exist-
ing variables will still be imported and abbr --erase will also erase
the variables. We recommend adding abbreviations to config.fish by
just adding the abbr --add command. When you run abbr, you will see
output like this

> abbr
abbr -a -- foo bar # imported from a universal variable, see `help abbr`

In that case you should take the part before the # comment and save it
in config.fish, then you can run abbr --erase to remove the universal
variable:

> abbr >> ~/.config/fish/config.fish
> abbr --erase (abbr --list)

abbr --add creates a new abbreviation. With no other options, the
string NAME is replaced by EXPANSION.

With --position command, the abbreviation will only expand when it is
positioned as a command, not as an argument to another command. With
--position anywhere the abbreviation may expand anywhere in the command
line. The default is command.

With --regex, the abbreviation matches using the regular expression
given by PATTERN, instead of the literal NAME. The pattern is inter-
preted using PCRE2 syntax and must match the entire token. If multiple
abbreviations match the same token, the last abbreviation added is
used.

With --set-cursor=MARKER, the cursor is moved to the first occurrence
of MARKER in the expansion. The MARKER value is erased. The MARKER may
be omitted (i.e. simply --set-cursor), in which case it defaults to %.

With -f FUNCTION or --function FUNCTION, FUNCTION is treated as the
name of a fish function instead of a literal replacement. When the ab-
breviation matches, the function will be called with the matching token
as an argument. If the function's exit status is 0 (success), the token
will be replaced by the function's output; otherwise the token will be
left unchanged. No EXPANSION may be given separately.

Examples
abbr --add gco git checkout

Add a new abbreviation where gco will be replaced with git checkout.

abbr -a --position anywhere -- -C --color

Add a new abbreviation where -C will be replaced with --color. The --
allows -C to be treated as the name of the abbreviation, instead of an
option.

abbr -a L --position anywhere --set-cursor "% | less"

Add a new abbreviation where L will be replaced with | less, placing
the cursor before the pipe.

function last_history_item
echo $history[1]
end
abbr -a !! --position anywhere --function last_history_item

This first creates a function last_history_item which outputs the last
entered command. It then adds an abbreviation which replaces !! with
the result of calling this function. Taken together, this is similar to
the !! history expansion feature of bash.

function vim_edit
echo vim $argv
end
abbr -a vim_edit_texts --position command --regex ".+\.txt" --function vim_edit

This first creates a function vim_edit which prepends vim before its
argument. It then adds an abbreviation which matches commands ending in
.txt, and replaces the command with the result of calling this func-
tion. This allows text files to be "executed" as a command to open them
in vim, similar to the "suffix alias" feature in zsh.

abbr 4DIRS --set-cursor=! "$(string join \n -- 'for dir in */' 'cd $dir' '!' 'cd ..' 'end')"

This creates an abbreviation "4DIRS" which expands to a multi-line loop
"template." The template enters each directory and then leaves it. The
cursor is positioned ready to enter the command to run in each direc-
tory, at the location of the !, which is itself erased.

Other subcommands
abbr --rename OLD_NAME NEW_NAME

Renames an abbreviation, from OLD_NAME to NEW_NAME

abbr [-s | --show]

Show all abbreviations in a manner suitable for import and export

abbr [-l | --list]

Prints the names of all abbreviation

abbr [-e | --erase] NAME

Erases the abbreviation with the given name

abbr -q or --query [NAME...]

Return 0 (true) if one of the NAME is an abbreviation.

abbr -h or --help

Displays help for the abbr command.

alias - create a function
Synopsis
alias
alias [--save] NAME DEFINITION
alias [--save] NAME=DEFINITION

Description
alias is a simple wrapper for the function builtin, which creates a
function wrapping a command. It has similar syntax to POSIX shell
alias. For other uses, it is recommended to define a function.

If you want to ease your interactive use, to save typing, consider us-
ing an abbreviation instead.

fish marks functions that have been created by alias by including the
command used to create them in the function description. You can list
alias-created functions by running alias without arguments. They must
be erased using functions -e.

• NAME is the name of the alias

• DEFINITION is the actual command to execute. alias automatically ap-
pends $argv, so that all parameters used with the alias are passed to
the actual command.

You cannot create an alias to a function with the same name. Note that
spaces need to be escaped in the call to alias just like at the command
line, even inside quoted parts.

The following options are available:

-h or --help
Displays help about using this command.

-s or --save
Saves the function created by the alias into your fish configu-
ration directory using funcsave.

Example
The following code will create rmi, which runs rm with additional argu-
ments on every invocation.

alias rmi="rm -i"

# This is equivalent to entering the following function:
function rmi --wraps rm --description 'alias rmi=rm -i'
rm -i $argv
end

# This needs to have the spaces escaped or "Chrome.app..."
# will be seen as an argument to "/Applications/Google":
alias chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome banana'

See more
1. The function command this builds on.

2. Functions.

3. Defining aliases.

and - conditionally execute a command
Synopsis
PREVIOUS; and COMMAND

Description
and is used to execute a command if the previous command was successful
(returned a status of 0).

and statements may be used as part of the condition in an while or if
block.

and does not change the current exit status itself, but the command it
runs most likely will. The exit status of the last foreground command
to exit can always be accessed using the $status variable.

The -h or --help option displays help about using this command.

Example
The following code runs the make command to build a program. If the
build succeeds, make's exit status is 0, and the program is installed.
If either step fails, the exit status is 1, and make clean is run,
which removes the files created by the build process.

make; and make install; or make clean

See Also
• false command

• $status variable

type - locate a command and describe its type
Synopsis
type [OPTIONS] NAME [...]

Description
With no options, type indicates how each NAME would be interpreted if
used as a command name.

The following options are available:

-a or --all
Prints all of possible definitions of the specified names.

-s or --short
Suppresses function expansion when used with no options or with
-a/--all.

-f or --no-functions
Suppresses function and builtin lookup.

-t or --type
Prints function, builtin, or file if NAME is a shell function,
builtin, or disk file, respectively.

-p or --path
Prints the path to NAME if NAME resolves to an executable file
in PATH, the path to the script containing the definition of the
function NAME if NAME resolves to a function loaded from a file
on disk (i.e. not interactively defined at the prompt), or noth-
ing otherwise.

-P or --force-path
Returns the path to the executable file NAME, presuming NAME is
found in the PATH environment variable, or nothing otherwise.
--force-path explicitly resolves only the path to executable
files in PATH, regardless of whether NAME is shadowed by a
function or builtin with the same name.

-q or --query
Suppresses all output; this is useful when testing the exit sta-
tus. For compatibility with old fish versions this is also
--quiet.

-h or --help
Displays help about using this command.

The -q, -p, -t and -P flags (and their long flag aliases) are mutually
exclusive. Only one can be specified at a time.

type returns 0 if at least one entry was found, 1 otherwise, and 2 for
invalid options or option combinations.

Example
>_ type fg
fg is a builtin

ulimit - set or get resource usage limits
Synopsis
ulimit [OPTIONS] [LIMIT]

Description
ulimit sets or outputs the resource usage limits of the shell and any
processes spawned by it. If a new limit value is omitted, the current
value of the limit of the resource is printed; otherwise, the specified
limit is set to the new value.

Use one of the following switches to specify which resource limit to
set or report:

-b or --socket-buffers
The maximum size of socket buffers.

-c or --core-size
The maximum size of core files created. By setting this limit to
zero, core dumps can be disabled.

-d or --data-size
The maximum size of a process' data segment.

-e or --nice
Controls the maximum nice value; on Linux, this value is sub-
tracted from 20 to give the effective value.

-f or --file-size
The maximum size of files created by a process.

-i or --pending-signals
The maximum number of signals that may be queued.

-l or --lock-size
The maximum size that may be locked into memory.

-m or --resident-set-size
The maximum resident set size.

-n or --file-descriptor-count
The maximum number of open file descriptors.

-q or --queue-size
The maximum size of data in POSIX message queues.

-r or --realtime-priority
The maximum realtime scheduling priority.

-s or --stack-size
The maximum stack size.

-t or --cpu-time
The maximum amount of CPU time in seconds.

-u or --process-count
The maximum number of processes available to the current user.

-w or --swap-size
The maximum swap space available to the current user.

-v or --virtual-memory-size
The maximum amount of virtual memory available to the shell.

-y or --realtime-maxtime
The maximum contiguous realtime CPU time in microseconds.

-K or --kernel-queues
The maximum number of kqueues (kernel queues) for the current
user.

-P or --ptys
The maximum number of pseudo-terminals for the current user.

-T or --threads
The maximum number of simultaneous threads for the current user.

Note that not all these limits are available in all operating systems;
consult the documentation for setrlimit in your operating system.

The value of limit can be a number in the unit specified for the re-
source or one of the special values hard, soft, or unlimited, which
stand for the current hard limit, the current soft limit, and no limit,
respectively.

If limit is given, it is the new value of the specified resource. If no
option is given, then -f is assumed. Values are in kilobytes, except
for -t, which is in seconds and -n and -u, which are unscaled values.
The exit status is 0 unless an invalid option or argument is supplied,
or an error occurs while setting a new limit.

ulimit also accepts the following options that determine what type of
limit to set:

-H or --hard
Sets hard resource limit.

-S or --soft
Sets soft resource limit.

A hard limit can only be decreased. Once it is set it cannot be in-
creased; a soft limit may be increased up to the value of the hard
limit. If neither -H nor -S is specified, both the soft and hard limits
are updated when assigning a new limit value, and the soft limit is
used when reporting the current value.

The following additional options are also understood by ulimit:

-a or --all
Prints all current limits.

-h or --help
Displays help about using this command.

The fish implementation of ulimit should behave identically to the im-
plementation in bash, except for these differences:

• Fish ulimit supports GNU-style long options for all switches.

• Fish ulimit does not support the -p option for getting the pipe size.
The bash implementation consists of a compile-time check that empiri-
cally guesses this number by writing to a pipe and waiting for SIG-
PIPE. Fish does not do this because this method of determining pipe
size is unreliable. Depending on bash version, there may also be fur-
ther additional limits to set in bash that do not exist in fish.

• Fish ulimit does not support getting or setting multiple limits in
one command, except reporting all values using the -a switch.

Example
ulimit -Hs 64 sets the hard stack size limit to 64 kB.

umask - set or get the file creation mode mask
Synopsis
umask [OPTIONS] [MASK]

Description
umask displays and manipulates the "umask", or file creation mode mask,
which is used to restrict the default access to files.

The umask may be expressed either as an octal number, which represents
the rights that will be removed by default, or symbolically, which rep-
resents the only rights that will be granted by default.

Access rights are explained in the manual page for the chmod(1) pro-
gram.

With no parameters, the current file creation mode mask is printed as
an octal number.

-S or --symbolic
Prints the umask in symbolic form instead of octal form.

-p or --as-command
Outputs the umask in a form that may be reused as input.

-h or --help
Displays help about using this command.

If a numeric mask is specified as a parameter, the current shell's
umask will be set to that value, and the rights specified by that mask
will be removed from new files and directories by default.

If a symbolic mask is specified, the desired permission bits, and not
the inverse, should be specified. A symbolic mask is a comma separated
list of rights. Each right consists of three parts:

• The first part specifies to whom this set of right applies, and can
be one of u, g, o or a, where u specifies the user who owns the file,
g specifies the group owner of the file, o specific other users
rights and a specifies all three should be changed.

• The second part of a right specifies the mode, and can be one of =, +
or -, where = specifies that the rights should be set to the new
value, + specifies that the specified right should be added to those
previously specified and - specifies that the specified rights should
be removed from those previously specified.

• The third part of a right specifies what rights should be changed and
can be any combination of r, w and x, representing read, write and
execute rights.

If the first and second parts are skipped, they are assumed to be a and
=, respectively. As an example, r,u+w means all users should have read
access and the file owner should also have write access.

Note that symbolic masks currently do not work as intended.

Example
umask 177 or umask u=rw sets the file creation mask to read and write
for the owner and no permissions at all for any other users.

vared - interactively edit the value of an environment variable
Synopsis
vared VARIABLE_NAME

Description
vared is used to interactively edit the value of an environment vari-
able. Array variables as a whole can not be edited using vared, but in-
dividual list elements can.

The -h or --help option displays help about using this command.

Example
vared PATH[3] edits the third element of the PATH list

wait - wait for jobs to complete
Synopsis
wait [-n | --any] [PID | PROCESS_NAME] ...

Description
wait waits for child jobs to complete.

If a PID is specified, the command waits for the job that the process
with that process ID belongs to.

If a PROCESS_NAME is specified, the command waits for the jobs that the
matched processes belong to.

If neither a pid nor a process name is specified, the command waits for
all background jobs.

If the -n or --any flag is provided, the command returns as soon as the
first job completes. If it is not provided, it returns after all jobs
complete.

The -h or --help option displays help about using this command.

Example
sleep 10 &
wait $last_pid

spawns sleep in the background, and then waits until it finishes.

for i in (seq 1 5); sleep 10 &; end
wait

spawns five jobs in the background, and then waits until all of them
finishes.

for i in (seq 1 5); sleep 10 &; end
hoge &
wait sleep

spawns five jobs and hoge in the background, and then waits until all
sleeps finish, and doesn't wait for hoge finishing.

while - perform a set of commands multiple times
Synopsis
while CONDITION; COMMANDS; end

Description
while repeatedly executes CONDITION, and if the exit status is 0, then
executes COMMANDS.

The exit status of the while loop is the exit status of the last itera-
tion of the COMMANDS executed, or 0 if none were executed. (This
matches other shells and is POSIX-compatible.)

You can use and or or for complex conditions. Even more complex control
can be achieved with while true containing a break.

The -h or --help option displays help about using this command.

Example
while test -f foo.txt; or test -f bar.txt ; echo file exists; sleep 10; end
# outputs 'file exists' at 10 second intervals,
# as long as the file foo.txt or bar.txt exists.

Fish for bash users
This is to give you a quick overview if you come from bash (or to a
lesser extent other shells like zsh or ksh) and want to know how fish
differs. Fish is intentionally not POSIX-compatible and as such some of
the things you are used to work differently.

Many things are similar - they both fundamentally expand commandlines
to execute commands, have pipes, redirections, variables, globs, use
command output in various ways. This document is there to quickly show
you the differences.

Command substitutions
Fish spells command substitutions as $(command) or (command), but not
`command`.

In addition, it only splits them on newlines instead of $IFS. If you
want to split on something else, use string split, string split0 or
string collect. If those are used as the last command in a command sub-
stitution the splits they create are carried over. So:

for i in (find . -print0 | string split0)

will correctly handle all possible filenames.

Variables
Fish sets and erases variables with set instead of VAR=VAL and a vari-
ety of separate builtins like declare and unset and export. set takes
options to determine the scope and exportedness of a variable:

# Define $PAGER *g*lobal and e*x*ported,
# so this is like ``export PAGER=less``
set -gx PAGER less

# Define $alocalvariable only locally,
# like ``local alocalvariable=foo``
set -l alocalvariable foo

or to erase variables:

set -e PAGER

VAR=VAL statements are available as environment overrides:

PAGER=cat git log

Fish does not perform word splitting. Once a variable has been set to a
value, that value stays as it is, so double-quoting variable expansions
isn't the necessity it is in bash. [1]

For instance, here's bash

> foo="bar baz"
> printf '"%s"\n' $foo
# will print two lines, because we didn't double-quote
# this is word splitting
"bar"
"baz"

And here is fish:

> set foo "bar baz"
> printf '"%s"\n' $foo
# foo was set as one element, so it will be passed as one element, so this is one line
"bar baz"

All variables are "arrays" (we use the term "lists"), and expanding a
variable expands to all its elements, with each element as its own ar-
gument (like bash's "${var[@]}":

> set var "foo bar" banana
> printf %s\n $var
foo bar
banana

Specific elements of a list can be selected:

echo $list[5..7]

The arguments to set are ordinary, so you can also set a variable to
the output of a command:

# Set lines to all the lines in file, one element per line
set lines (cat file)

or a mixture of literal values and output:

> set numbers 1 2 3 (seq 5 8) 9
> printf '%s\n' $numbers
1
2
3
5
6
7
8
9

A = is unnecessary and unhelpful with set - set foo = bar will set the
variable "foo" to two values: "=" and "bar". set foo=bar will print an
error.

See Shell variables for more.

[1] zsh also does not perform word splitting by default (the
SH_WORD_SPLIT option controls this)

Wildcards (globs)
Fish only supports the * and ** glob (and the deprecated ? glob) as
syntax. If a glob doesn't match it fails the command (like with bash's
failglob) unless the command is for, set or count or the glob is used
with an environment override (VAR=* command), in which case it expands
to nothing (like with bash's nullglob option).

Globbing doesn't happen on expanded variables, so:

set foo "*"
echo $foo

will not match any files.

There are no options to control globbing so it always behaves like
that.

See Wildcards for more.

Quoting
Fish has two quoting styles: "" and ''. Variables are expanded in dou-
ble-quotes, nothing is expanded in single-quotes.

There is no $'', instead the sequences that would transform are trans-
formed when unquoted:

> echo a\nb
a
b

See Quotes for more.

String manipulation
Fish does not have ${foo%bar}, ${foo#bar} and ${foo/bar/baz}. Instead
string manipulation is done by the string builtin.

For example, to replace "bar" with "baz":

> string replace bar baz "bar luhrmann"
baz luhrmann

It can also split strings:

> string split "," "foo,bar"
foo
bar

Match regular expressions as a replacement for grep:

> echo bababa | string match -r 'aba$'
aba

Pad strings to a given width, with arbitrary characters:

> string pad -c x -w 20 "foo"
xxxxxxxxxxxxxxxxxfoo

Make strings lower/uppercase:

> string lower Foo
foo

> string upper Foo
FOO

repeat strings, trim strings, escape strings or print a string's length
or width (in terminal cells).

Special variables
Some bash variables and their closest fish equivalent:

• $*, $@, $1 and so on: $argv

• $?: $status

• $$: $fish_pid

• $#: No variable, instead use count $argv

• $!: $last_pid

• $0: status filename

• $-: Mostly status is-interactive and status is-login

Process substitution
Instead of <(command) fish uses (command | psub). There is no equiva-
lent to >(command).

Note that both of these are bashisms, and most things can easily be ex-
pressed without. E.g. instead of:

source (command | psub)

just use:

command | source

as fish's source can read from stdin.

Heredocs
Fish does not have <<EOF "heredocs". Instead of

cat <<EOF
some string
some more string
EOF

use:

printf %s\n "some string" "some more string"

or:

echo "some string
some more string"

# or if you want the quotes on separate lines:

echo "\
some string
some more string\
"

Quotes are followed across newlines.

What "heredocs" do is:

1. Read/interpret the string, with special rules, up to the terminator.
[2]

2. Write the resulting string to a temporary file.

3. Start the command the heredoc is attached to with that file as
stdin.

This means it is essentially the same as just reading from a pipe, so:

echo "foo" | cat

is mostly the same as

cat <<EOF
foo
EOF

Just like with heredocs, the command has to be prepared to read from
stdin. Sometimes this requires special options to be used, often giving
a filename of - turns it on.

For example:

echo "xterm
rxvt-unicode" | pacman --remove -

# is the same as (the `-` makes pacman read arguments from stdin)
pacman --remove xterm rxvt-unicode

and could be written in other shells as

# This "-" is still necessary - the heredoc is *also* passed over stdin!
pacman --remove - << EOF
xterm
rxvt-unicode
EOF

So heredocs really are just minor syntactical sugar that introduces a
lot of special rules, which is why fish doesn't have them. Pipes are a
core concept, and are simpler and compose nicer.

[2] For example, the "EOF" is just a convention, the terminator can be
an arbitrary string, something like "THISISTHEEND" also works. And
using <<- trims leading tab characters (but not other whitespace),
so you can indent the lines, but only with tabs. Substitutions
(variables, commands) are done on the heredoc by default, but not
if the terminator is quoted: cat << "EOF".

Test (test, [, [[)
Fish has a POSIX-compatible test or [ builtin. There is no [[ and test
does not accept == as a synonym for =. It can compare floating point
numbers, however.

set -q can be used to determine if a variable exists or has a certain
number of elements (set -q foo[2]).

Arithmetic Expansion
Fish does not have $((i+1)) arithmetic expansion, computation is han-
dled by math:

math $i + 1

Unlike bash's arithmetic, it can handle floating point numbers:

> math 5 / 2
2.5

And also has some functions, like for trigonometry:

> math cos 2 x pi
1

You can pass arguments to math separately like above or in quotes. Be-
cause fish uses () parentheses for command substitutions, quoting is
needed if you want to use them in your expression:

> math '(5 + 2) * 4'

Both * and x are valid ways to spell multiplication, but * needs to be
quoted because it looks like a glob.

Prompts
Fish does not use the $PS1, $PS2 and so on variables. Instead the
prompt is the output of the fish_prompt function, plus the
fish_mode_prompt function if vi-mode is enabled and the
fish_right_prompt function for the right prompt.

As an example, here's a relatively simple bash prompt:

# <$HOSTNAME> <$PWD in blue> <Prompt Sign in Yellow> <Rest in default light white>
PS1='\h\[\e[1;34m\]\w\[\e[m\] \[\e[1;32m\]\$\[\e[m\] '

and a rough fish equivalent:

function fish_prompt
set -l prompt_symbol '$'
fish_is_root_user; and set prompt_symbol '#'

echo -s (prompt_hostname) \
(set_color blue) (prompt_pwd) \
(set_color yellow) $prompt_symbol (set_color normal)
end

This shows a few differences:

• Fish provides set_color to color text. It can use the 16 named colors
and also RGB sequences (so you could also use set_color 5555FF)

• Instead of introducing specific escapes like \h for the hostname, the
prompt is simply a function. To achieve the effect of \h, fish pro-
vides helper functions like prompt_hostname, which prints a shortened
version of the hostname.

• Fish offers other helper functions for adding things to the prompt,
like fish_vcs_prompt for adding a display for common version control
systems (git, mercurial, svn), and prompt_pwd for showing a shortened
$PWD (the user's home directory becomes ~ and any path component is
shortened).

The default prompt is reasonably full-featured and its code can be read
via type fish_prompt.

Fish does not have $PS2 for continuation lines, instead it leaves the
lines indented to show that the commandline isn't complete yet.

Blocks and loops
Fish's blocking constructs look a little different. They all start with
a word, end in end and don't have a second starting word:

for i in 1 2 3; do
echo $i
done

# becomes

for i in 1 2 3
echo $i
end

while true; do
echo Weeee
done

# becomes

while true
echo Weeeeeee
end

{
echo Hello
}

# becomes

begin
echo Hello
end

if true; then
echo Yes I am true
else
echo "How is true not true?"
fi

# becomes

if true
echo Yes I am true
else
echo "How is true not true?"
end

foo() {
echo foo
}

# becomes

function foo
echo foo
end

# (bash allows the word "function",
# but this is an extension)

Fish does not have an until. Use while not or while !.

Subshells
Bash has a feature called "subshells", where it will start another
shell process for certain things. That shell will then be independent
and e.g. any changes it makes to variables won't be visible in the main
shell.

This includes things like:

# A list of commands in `()` parentheses
(foo; bar) | baz

# Both sides of a pipe
foo | while read -r bar; do
# This will not be visible outside of the loop.
VAR=VAL
# This background process will not be, either
baz &
done

() subshells are often confused with {} grouping, which does not use a
subshell. When you just need to group, you can use begin; end in fish:

(foo; bar) | baz
# when it should really have been:
{ foo; bar; } | baz
# becomes
begin; foo; bar; end | baz

The pipe will simply be run in the same process, so while read loops
can set variables outside:

foo | while read bar
set -g VAR VAL
baz &
end

echo $VAR # will print VAL
jobs # will show "baz"

Subshells are also frequently confused with command substitutions,
which bash writes as `command` or $(command) and fish writes as $(com-
mand) or (command). Bash also uses subshells to implement them.

The isolation can usually be achieved by just scoping variables (with
set -l), but if you really do need to run your code in a new shell en-
vironment you can always use fish -c 'your code here' to do so explic-
itly.

Builtins and other commands
By now it has become apparent that fish puts much more of a focus on
its builtins and external commands rather than its syntax. So here are
some helpful builtins and their rough equivalent in bash:

• string - this replaces most of the string transformation (${i%foo} et
al) and can also be used instead of grep and sed and such.

• math - this replaces $((i + 1)) arithmetic and can also do floats and
some simple functions (sine and friends).

• argparse - this can handle a script's option parsing, for which bash
would probably use getopt (zsh provides zparseopts).

• count can be used to count things and therefore replaces $# and can
be used instead of wc.

• status provides information about the shell status, e.g. if it's in-
teractive or what the current linenumber is. This replaces $- and
$BASH_LINENO and other variables.

• seq(1) can be used as a replacement for {1..10} range expansion. If
your OS doesn't ship a seq fish includes a replacement function.

Other facilities
Bash has set -x or set -o xtrace to print all commands that are being
executed. In fish, this would be enabled by setting fish_trace.

Or, if your intention is to profile how long each line of a script
takes, you can use fish --profile - see the page for the fish command.

Tutorial
Why fish?
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.

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 fish might be just what you're looking for!

Getting started
Once installed, just type in fish into your current shell to try it
out!

You will be greeted by the standard fish prompt, which means you are
all set up and can start using fish:

> fish
Welcome to fish, the friendly interactive shell
Type help for instructions on how to use fish
you@hostname ~>

This prompt that you see above is the fish default prompt: it shows
your username, hostname, and working directory. - to change this
prompt see how to change your prompt - to switch to fish permanently
see Default Shell.

From now on, we'll pretend your prompt is just a > to save space.

Learning fish
This tutorial assumes a basic understanding of command line shells and
Unix commands, and that you have a working copy of fish.

If you have a strong understanding of other shells, and want to know
what fish does differently, search for the magic phrase unlike other
shells, which is used to call out important differences.

Or, if you want a quick overview over the differences to other shells
like Bash, see Fish For Bash Users.

For the full, detailed description of how to use fish interactively,
see Interactive Use.

For a comprehensive description of fish's scripting language, see The
Fish Language.

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

> echo hello world
hello world

This runs the command echo with the arguments hello and world. In this
case that's the same as one argument hello world, but in many cases
it's not. If you need to pass an argument that includes a space, you
can escape with a backslash, or quote it using single or double quotes:

> mkdir My\ Files
# Makes a directory called "My Files", with a space in the name
> cp ~/Some\ File 'My Files'
# Copies a file called "Some File" in the home directory to "My Files"
> ls "My Files"
Some File

Getting Help
Run help to open fish's help in a web browser, and man with the page
(like fish-language) 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...

To open this section, use help getting-help.

Fish works by running commands, which are often also installed on your
computer. Usually these commands also provide help in the man system,
so you can get help for them there. Try man ls to get help on your com-
puter's ls command.

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

Valid file paths are underlined 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 color variables directly.

For example, if you want to disable (almost) all coloring:

fish_config theme choose none

This picks the "none" theme. To see all themes:

fish_config theme show

Just running fish_config will open up a browser interface that allows
you to pick from the available themes.

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

The recursive wildcard ** 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.

For more, see Wildcards.

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 >. stderr is
redirected with a 2>.

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

To redirect stdout and stderr into one file, you can use &>:

> make &> make_output.txt

For more, see Input and output redirections and Pipes.

Autosuggestions
As you type fish will suggest commands 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:

> rsync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo

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

If you don't like autosuggestions, you can disable them by setting
$fish_autosuggestion_enabled to 0:

set -g fish_autosuggestion_enabled 0

Tab Completions
A rich set of tab completions work "out of the box".

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

> /priTab => /private/

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

> ~/stuff/sTab
~/stuff/script.sh (command) ~/stuff/sources/ (directory)

Hit tab again to cycle through the possibilities. The part in parenthe-
ses there (that "command" and "directory") is the completion descrip-
tion. It's just a short hint to explain what kind of argument it is.

fish can also complete many commands, like git branches:

> git merge prTab => git merge prompt_designer
> git checkout bTab
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 followed by a variable name is re-
placed with the value of that variable:

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

This is known as variable substitution, and it also happens 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 an ordinary command to set variables:
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 substitu-
tion:

> 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 Noo-
dle", so that is the argument that was passed to mkdir, spaces and all.

You can erase (or "delete") a variable with -e or --erase

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

For more, see Variable expansion.

Exports (Shell Variables)
Sometimes you need to have a variable available to an external command,
often as a setting. For example many programs like git or man read the
$PAGER variable to figure out your preferred pager (the program that
lets you scroll text). Other variables used like this include $BROWSER,
$LANG (to configure your language) and $PATH. You'll note these are
written in ALLCAPS, but that's just a convention.

To give a variable to an external command, it needs to be "exported".
This is done with a flag to set, either --export or just -x.

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

It can also be unexported with --unexport or -u.

This works the other way around as well! If fish is started by some-
thing else, it inherits that parents exported variables. So if your
terminal emulator starts fish, and it exports $LANG set to en_US.UTF-8,
fish will receive that setting. And whatever started your terminal emu-
lator also gave it some variables that it will then pass on unless it
specifically decides not to. This is how fish usually receives the val-
ues for things like $LANG, $PATH and $TERM, without you having to spec-
ify them again.

Exported variables can be local or global or universal - "exported" is
not a scope! Usually you'd make them global via set -gx MyVariable
SomeValue.

For more, see Exporting variables.

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

Variables whose name ends in "PATH" are automatically split on colons
to become lists. They are joined using colons when exported to subcom-
mands. This is for compatibility with other tools, which expect $PATH
to use colons. You can also explicitly add this quirk to a variable
with set --path, or remove it with set --unpath.

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
# Will print:
# 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 a 1 2 3
> set 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.

For more, see Lists.

Command Substitutions
Command substitutions use the output of one command as an argument to
another. Unlike other shells, fish does not use backticks `` for com-
mand substitutions. Instead, it uses parentheses with or without a dol-
lar:

> 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 without a dollar are not expanded within quotes,
so the version with a dollar is simpler:

> 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. Usually this is a big
help because unix commands operate on a line-by-line basis. Sometimes
it 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 -n " ")
-lgio-2.0
-lgobject-2.0
-lglib-2.0

If you need a command substitutions output as one argument, without any
splits, use quoted command substitution:

> echo "first line
second line" > myfile
> set myfile "$(cat myfile)"
> printf '|%s|' $myfile
|first line
second line|

For more, see Command substitution.

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

This is useful interactively to enter multiple commands. In a script
it's easier to read if the commands are on separate lines.

Exit Status
When a command exits, it returns a status code as a non-negative inte-
ger (that's a whole number >= 0).

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

> false
> echo $status
1

This indicates how the command fared - 0 usually means success, while
the others signify kinds of failure. For instance fish's set --query
returns the number of variables it queried that weren't set - set
--query PATH usually returns 0, set --query arglbargl boogagoogoo usu-
ally returns 2.

There is also a $pipestatus list variable for the exit statuses [1] of
processes in a pipe.

For more, see The status variable.

[1] or "stati" if you prefer, or "stats" if you've time-travelled from
ancient Rome or work as a latin teacher

Combiners (And, Or, Not)
fish supports the familiar && and || to combine commands, and ! to
negate them:

> ./configure && make && sudo make install

Here, make is only executed if ./configure succeeds (returns 0), and
sudo make install is only executed if both ./configure and make suc-
ceed.

fish also supports and, or, and not. The first two are job modifiers
and have lower precedence. Example usage:

> cp file1 file1_bak && cp file2 file2_bak; 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 file1_bak && cp file2 file2_bak
and echo "Backup successful"
or echo "Backup failed"

Conditionals (If, Else, Switch)
Use 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

To compare strings or numbers or check file properties (whether a file
exists or is writeable and such), use test, like

if test "$fish" = "flounder"
echo FLOUNDER
end

# or

if test "$number" -gt 5
echo $number is greater than five
else
echo $number is five or less
end

# or

# This test is true if the path /etc/hosts exists
# - it could be a file or directory or symlink (or possibly something else).
if test -e /etc/hosts
echo We most likely have a hosts file
else
echo We do not have a hosts file
end

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

if command -sq fish; and grep fish /etc/shells
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)
case Linux
echo Hi Tux!
case Darwin
echo Hi Hexley!
case FreeBSD NetBSD DragonFly
echo Hi Beastie!
case '*'
echo Hi, stranger!
end

As you see, case does not fall through, and can accept multiple argu-
ments or (quoted) wildcards.

For more, see Conditions.

Functions
A fish function is a list of commands, which may optionally take argu-
ments. Unlike other shells, arguments are not passed in "numbered vari-
ables" like $1, but instead in a single list $argv. To create a func-
tion, use the function builtin:

function say_hello
echo Hello $argv
end
say_hello
# prints: Hello
say_hello everybody!
# prints: Hello everybody!

Unlike other shells, fish does not have aliases or special prompt syn-
tax. Functions take their place. [2]

You can list the names of all functions with the functions builtin
(note the plural!). fish starts out with a number of functions:

> functions
N_, abbr, alias, bg, cd, cdh, contains_seq, dirh, dirs, disown, down-or-search, edit_command_buffer, export, fg, fish_add_path, fish_breakpoint_prompt, fish_clipboard_copy, fish_clipboard_paste, fish_config, fish_default_key_bindings, fish_default_mode_prompt, fish_git_prompt, fish_hg_prompt, fish_hybrid_key_bindings, fish_indent, fish_is_root_user, fish_job_summary, fish_key_reader, fish_md5, fish_mode_prompt, fish_npm_helper, fish_opt, fish_print_git_action, fish_print_hg_root, fish_prompt, fish_sigtrap_handler, fish_svn_prompt, fish_title, fish_update_completions, fish_vcs_prompt, fish_vi_cursor, fish_vi_key_bindings, funced, funcsave, grep, help, history, hostname, isatty, kill, la, ll, ls, man, nextd, open, popd, prevd, prompt_hostname, prompt_pwd, psub, pushd, realpath, seq, setenv, suspend, trap, type, umask, up-or-search, vared, wait

You can see the source for any function by passing its name to func-
tions:

> functions ls
function ls --description 'List contents of directory'
command ls -G $argv
end

For more, see Functions.

[2] There is a function called alias, but it's just a shortcut to make
functions. fish also provides abbreviations, through the abbr com-
mand.

Loops
While loops:

while true
echo "Loop forever"
end
# Prints:
# Loop forever
# Loop forever
# Loop forever
# yes, this really will loop forever. Unless you abort it with ctrl-c.

For loops can be used to iterate over a list. For example, a list of
files:

for file in *.txt
cp $file $file.bak
end

Iterating over a list of numbers can be done with seq:

for x in (seq 5)
touch file_$x.txt
end

For more, see Loops and blocks.

Prompt
Unlike other shells, there is no prompt variable like PS1. To display
your prompt, fish executes the fish_prompt function and uses its output
as the prompt. And if it exists, fish also executes the
fish_right_prompt function and uses its output as the right prompt.

You can define your own prompt from the command line:

> function fish_prompt; echo "New Prompt % "; end
New Prompt % _

Then, if you are happy with it, you can save it to disk by typing func-
save fish_prompt. This saves the prompt in ~/.config/fish/func-
tions/fish_prompt.fish. (Or, if you want, you can create that file man-
ually from the start.)

Multiple lines are OK. Colors can be set via set_color, passing it
named ANSI colors, or hex RGB values:

function fish_prompt
set_color purple
date "+%m/%d/%y"
set_color F00
echo (pwd) '>' (set_color normal)
end

This prompt would look like:

02/06/13
/home/tutorial > _

You can choose among some sample prompts by running fish_config for a
web UI or fish_config prompt for a simpler version inside your termi-
nal.

$PATH
$PATH is an environment variable containing the directories that fish
searches for commands. Unlike other shells, $PATH is a list, not a
colon-delimited string.

Fish takes care to set $PATH to a default, but typically it is just in-
herited from fish's parent process and is set to a value that makes
sense for the system - see Exports.

To prepend /usr/local/bin and /usr/sbin to $PATH, you can write:

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

To remove /usr/local/bin from $PATH, you can write:

> set PATH (string match -v /usr/local/bin $PATH)

For compatibility with other shells and external commands, $PATH is a
path variable, and so will be joined with colons (not spaces) when you
quote it:

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

and it will be exported like that, and when fish starts it splits the
$PATH it receives into a list on colon.

You can do so directly in config.fish, like you might do in other
shells with .profile. See this example.

A faster way is to use the fish_add_path function, which adds given di-
rectories to the path if they aren't already included. It does this by
modifying the $fish_user_paths universal variable, which is automati-
cally prepended to $PATH. For example, to permanently add /usr/lo-
cal/bin to your $PATH, you could write:

> fish_add_path /usr/local/bin

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. You can also add this line to
config.fish, as it only adds the component if necessary.

Or you can modify $fish_user_paths yourself, but you should be careful
not to append to it unconditionally in config.fish, or it will grow
longer and longer.

Startup (Where's .bashrc?)
Fish starts by executing commands in ~/.config/fish/config.fish. You
can create it if it does not exist.

It is possible to directly create functions and variables in con-
fig.fish file, using the commands shown above. For example:

> cat ~/.config/fish/config.fish

set -x PATH $PATH /sbin/

function ll
ls -lh $argv
end

However, it is more common and efficient to use autoloading functions
and universal variables.

If you want to organize your configuration, fish also reads commands in
.fish files in ~/.config/fish/conf.d/. See Configuration Files for the
details.

Autoloading Functions
When fish encounters a command, it attempts to autoload a function for
that command, by looking for a file with the name of that command in
~/.config/fish/functions/.

For example, if you wanted to have a function ll, you would add a text
file ll.fish to ~/.config/fish/functions:

> cat ~/.config/fish/functions/ll.fish
function ll
ls -lh $argv
end

This is the preferred way to define your prompt as well:

> cat ~/.config/fish/functions/fish_prompt.fish
function fish_prompt
echo (pwd) "> "
end

See the documentation for funced and funcsave for ways to create these
files automatically, and $fish_function_path to control their location.

Universal Variables
A universal variable is a variable whose value is shared across all in-
stances of fish, now and in the future even after a reboot. You can
make a variable universal with set -U:

> set -U EDITOR vim

Now in another shell:

> echo $EDITOR
vim

Ready for more?
If you want to learn more about fish, there is lots of detailed docu-
mentation, the official gitter channel, an official mailing list, and
the github page.

Writing your own completions
To specify a completion, use the complete command. complete takes as a
parameter the name of the command to specify a completion for. For ex-
ample, to add a completion for the program myprog, one would start the
completion command with complete -c myprog ...

To provide a list of possible completions for myprog, use the -a
switch. If myprog accepts the arguments start and stop, this can be
specified as complete -c myprog -a 'start stop'. The argument to the -a
switch is always a single string. At completion time, it will be tok-
enized on spaces and tabs, and variable expansion, command substitution
and other forms of parameter expansion will take place.

fish has a special syntax to support specifying switches accepted by a
command. The switches -s, -l and -o are used to specify a short switch
(single character, such as -l), a gnu style long switch (such as
--color) and an old-style long switch (like -shuffle), respectively. If
the command 'myprog' has an option '-o' which can also be written as
--output, and which can take an additional value of either 'yes' or
'no', this can be specified by writing:

complete -c myprog -s o -l output -a "yes no"

In the complete call above, the -a arguments apply when the option
-o/--output has been given, so this offers them for:

> myprog -o<TAB>
> myprog --output=<TAB>

By default, option arguments are optional, so the candidates are only
offered directly attached like that, so they aren't given in this case:

> myprog -o <TAB>

Usually options require a parameter, so you would give --require-para-
meter / -r:

complete -c myprog -s o -l output -ra "yes no"

which offers yes/no in these cases:

> myprog -o<TAB>
> myprog --output=<TAB>
> myprog -o <TAB>
> myprog --output <TAB>

In the latter two cases, files will also be offered because file com-
pletion is enabled by default.

You would either inhibit file completion for a single option:

complete -c myprog -s o -l output --no-files -ra "yes no"

or with a specific condition:

complete -c myprog -f --condition '__fish_seen_subcommand_from somesubcommand'

or you can disable file completions globally for the command:

complete -c myprog -f

If you have disabled them globally, you can enable them just for a spe-
cific condition or option with the --force-files / -F option:

# Disable files by default
complete -c myprog -f
# but reenable them for --config-file
complete -c myprog -l config-file --force-files -r

As a more comprehensive example, here's a commented excerpt of the com-
pletions for systemd's timedatectl:

# All subcommands that timedatectl knows - this is useful for later.
set -l commands status set-time set-timezone list-timezones set-local-rtc set-ntp

# Disable file completions for the entire command
# because it does not take files anywhere
# Note that this can be undone by using "-F".
#
# File completions also need to be disabled
# if you want to have more control over what files are offered
# (e.g. just directories, or just files ending in ".mp3").
complete -c timedatectl -f

# This line offers the subcommands
# -"status",
# -"set-timezone",
# -"set-time"
# -"list-timezones"
# if no subcommand has been given so far.
#
# The `-n`/`--condition` option takes script as a string, which it executes.
# If it returns true, the completion is offered.
# Here the condition is the `__fish_seen_subcommands_from` helper function.
# If returns true if any of the given commands is used on the commandline,
# as determined by a simple heuristic.
# For more complex uses, you can write your own function.
# See e.g. the git completions for an example.
#
complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" \
-a "status set-time set-timezone list-timezones"

# If the "set-timezone" subcommand is used,
# offer the output of `timedatectl list-timezones` as completions.
# Each line of output is used as a separate candidate,
# and anything after a tab is taken as the description.
# It's often useful to transform command output with `string` into that form.
complete -c timedatectl -n "__fish_seen_subcommand_from set-timezone" \
-a "(timedatectl list-timezones)"

# Completion candidates can also be described via `-d`,
# which is useful if the description is constant.
# Try to keep these short, because that means the user gets to see more at once.
complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" \
-a "set-local-rtc" -d "Maintain RTC in local time"

# We can also limit options to certain subcommands by using conditions.
complete -c timedatectl -n "__fish_seen_subcommand_from set-local-rtc" \
-l adjust-system-clock -d 'Synchronize system clock from the RTC'

# These are simple options that can be used everywhere.
complete -c timedatectl -s h -l help -d 'Print a short help text and exit'
complete -c timedatectl -l version -d 'Print a short version string and exit'
complete -c timedatectl -l no-pager -d 'Do not pipe output into a pager'

For examples of how to write your own complex completions, study the
completions in /usr/share/fish/completions. (The exact path depends on
your chosen installation prefix and may be slightly different)

Useful functions for writing completions
fish ships with several functions that may be useful when writing com-
mand-specific completions. Most of these function names begin with the
string __fish_. Such functions are internal to fish and their name and
interface may change in future fish versions. A few of these functions
are described here.

Functions beginning with the string __fish_print_ print a newline sepa-
rated list of strings. For example, __fish_print_filesystems prints a
list of all known file systems. Functions beginning with __fish_com-
plete_ print out a newline separated list of completions with descrip-
tions. The description is separated from the completion by a tab char-
acter.

• __fish_complete_directories STRING DESCRIPTION performs path comple-
tion on STRING, allowing only directories, and giving them the de-
scription DESCRIPTION.

• __fish_complete_path STRING DESCRIPTION performs path completion on
STRING, giving them the description DESCRIPTION.

• __fish_complete_groups prints a list of all user groups with the
groups members as description.

• __fish_complete_pids prints a list of all processes IDs with the com-
mand name as description.

• __fish_complete_suffix SUFFIX performs file completion but sorts
files ending in SUFFIX first. This is useful in conjunction with com-
plete --keep-order.

• __fish_complete_users prints a list of all users with their full name
as description.

• __fish_print_filesystems prints a list of all known file systems.
Currently, this is a static list, and not dependent on what file sys-
tems the host operating system actually understands.

• __fish_print_hostnames prints a list of all known hostnames. This
function searches the fstab for nfs servers, ssh for known hosts and
checks the /etc/hosts file.

• __fish_print_interfaces prints a list of all known network inter-
faces.

• __fish_print_packages prints a list of all installed packages. This
function currently handles Debian, rpm and Gentoo packages.

Where to put completions
Completions can be defined on the commandline or in a configuration
file, but they can also be automatically loaded. Fish automatically
searches through any directories in the list variable $fish_com-
plete_path, and any completions defined are automatically loaded when
needed. A completion file must have a filename consisting of the name
of the command to complete and the suffix .fish.

By default, Fish searches the following for completions, using the
first available file that it finds:

• A directory for end-users to keep their own completions, usually
~/.config/fish/completions (controlled by the XDG_CONFIG_HOME envi-
ronment variable);

• A directory for systems administrators to install completions for all
users on the system, usually /etc/fish/completions;

• A user-specified directory for third-party vendor completions, usu-
ally ~/.local/share/fish/vendor_completions.d (controlled by the
XDG_DATA_HOME environment variable);

• A directory for third-party software vendors to ship their own com-
pletions for their software, usually /usr/share/fish/vendor_comple-
tions.d;

• The completions shipped with fish, usually installed in
/usr/share/fish/completions; and

• Completions automatically generated from the operating system's man-
ual, usually stored in ~/.local/share/fish/generated_completions.

These paths are controlled by parameters set at build, install, or run
time, and may vary from the defaults listed above.

This wide search may be confusing. If you are unsure, your completions
probably belong in ~/.config/fish/completions.

If you have written new completions for a common Unix command, please
consider sharing your work by submitting it via the instructions in
Further help and development.

If you are developing another program and would like to ship comple-
tions with your program, install them to the "vendor" completions di-
rectory. As this path may vary from system to system, the pkgconfig
framework should be used to discover this path with the output of
pkg-config --variable completionsdir fish.

Writing your own prompt
WARNING:
This document uses formatting to show what a prompt would look like.
If you are viewing this in the man page, you probably want to switch
to looking at the html version instead. Run help custom-prompt to
view it in a web browser.

Fish ships a number of prompts that you can view with the fish_config
command, and many users have shared their prompts online.

However, you can also write your own, or adjust an existing prompt.
This is a good way to get used to fish's scripting language.

Unlike other shells, fish's prompt is built by running a function -
fish_prompt. Or, more specifically, three functions:

• fish_prompt, which is the main prompt function

• fish_right_prompt, which is shown on the right side of the terminal.

• fish_mode_prompt, which is shown if vi-mode is used.

These functions are run, and whatever they print is displayed as the
prompt (minus one trailing newline).

Here, we will just be writing a simple fish_prompt.

Our first prompt
Let's look at a very simple example:

function fish_prompt
echo $PWD '>'
end

This prints the current working directory (PWD) and a > symbol to show
where the prompt ends. The > is quoted because otherwise it would sig-
nify a redirection.

Because we've used echo, it adds spaces between the two so it ends up
looking like (assuming _ is your cursor):

/home/tutorial >_

Formatting
echo adds spaces between its arguments. If you don't want those, you
can use string join like this:

function fish_prompt
string join '' -- $PWD '>'
end

The -- indicates to string that no options can come after it, in case
we extend this with something that can start with a -.

There are other ways to remove the space, including echo -s and printf.

Adding colo(u)r
This prompt is functional, but a bit boring. We could add some color.

Fortunately, fish offers the set_color command, so you can do:

echo (set_color red)foo

set_color can also handle RGB colors like set_color 23b455, and other
formatting options including bold and italics.

So, taking our previous prompt and adding some color:

function fish_prompt
string join '' -- (set_color green) $PWD (set_color normal) '>'
end

A "normal" color tells the terminal to go back to its normal formatting
options.

What set_color does internally is to print an escape sequence that
tells the terminal to change color. So if you see something like:

echo \e\[31mfoo

that could just be set_color red.

Shortening the working directory
This is fine, but our PWD can be a bit long, and we are typically only
interested in the last few directories. We can shorten this with the
prompt_pwd helper that will give us a shortened working directory:

function fish_prompt
string join '' -- (set_color green) (prompt_pwd) (set_color normal) '>'
end

prompt_pwd takes options to control how much to shorten. For instance,
if we want to display the last two directories, we'd use prompt_pwd
--full-length-dirs 2:

function fish_prompt
string join '' -- (set_color green) (prompt_pwd --full-length-dirs 2) (set_color normal) '>'
end

With a current directory of "/home/tutorial/Music/Lena Raine/Oneknow-
ing", this would print

~/M/Lena Raine/Oneknowing>_

Status
One important bit of information that every command returns is the
status. This is a whole number from 0 to 255, and usually it is used as
an error code - 0 if the command returned successfully, or a number
from 1 to 255 if not.

It's useful to display this in your prompt, but showing it when it's 0
seems kind of wasteful.

First of all, since every command (except for set) changes the status,
you need to store it for later use as the first thing in your prompt.
Use a local variable so it will be confined to your prompt function:

set -l last_status $status

And after that, you can set a string if it not zero:

# Prompt status only if it's not 0
set -l stat
if test $last_status -ne 0
set stat (set_color red)"[$last_status]"(set_color normal)
end

And to print it, we add it to our string join:

string join '' -- (set_color green) (prompt_pwd) (set_color normal) $stat '>'

If $last_status was 0, $stat is empty, and so it will simply disappear.

So our entire prompt is now:

function fish_prompt
set -l last_status $status
# Prompt status only if it's not 0
set -l stat
if test $last_status -ne 0
set stat (set_color red)"[$last_status]"(set_color normal)
end

string join '' -- (set_color green) (prompt_pwd) (set_color normal) $stat '>'
end

And it looks like:

~/M/L/Oneknowing[1]>_

after we run false (which returns 1).

Where to go from here?
We have now built a simple but working and usable prompt, but of course
more can be done.

• Fish offers more helper functions: - prompt_login to describe the
user/hostname/container or prompt_hostname to describe just the host
- fish_is_root_user to help with changing the symbol for root. -
fish_vcs_prompt to show version control information (or
fish_git_prompt / fish_hg_prompt / fish_svn_prompt to limit it to
specific systems)

• You can add a right prompt by changing fish_right_prompt or a vi-mode
prompt by changing fish_mode_prompt.

• Some prompts have interesting or advanced features - Add the time
when the prompt was printed - Show various integrations like python's
venv - Color the parts differently.

You can look at fish's sample prompts for inspiration. Open up
fish_config, find one you like and pick it. For example:

fish_config prompt show # <- shows all the sample prompts
fish_config prompt choose disco # <- this picks the "disco" prompt for this session
funced fish_prompt # <- opens fish_prompt in your editor, and reloads it once the editor exits

Design
This is a description of the design principles that have been used to
design fish. The fish design has three high level goals. These are:

1. Everything that can be done in other shell languages should be pos-
sible to do in fish, though fish may rely on external commands in
doing so.

2. Fish should be user-friendly, but not at the expense of expressive-
ness. Most tradeoffs between power and ease of use can be avoided
with careful design.

3. Whenever possible without breaking the above goals, fish should fol-
low POSIX.

To achieve these high-level goals, the fish design relies on a number
of more specific design principles. These are presented below, together
with a rationale and a few examples for each.

The law of orthogonality
The shell language should have a small set of orthogonal features. Any
situation where two features are related but not identical, one of them
should be removed, and the other should be made powerful and general
enough to handle all common use cases of either feature.

Rationale: Related features make the language larger, which makes it
harder to learn. It also increases the size of the source code, making
the program harder to maintain and update.

Examples:

• Here documents are too similar to using echo inside of a pipeline.

• Subshells, command substitution and process substitution are strongly
related. fish only supports command substitution, the others can be
achieved either using a block or the psub shellscript function.

• Having both aliases and functions is confusing, especially since both
of them have limitations and problems. fish functions have none of
the drawbacks of either syntax.

• The many Posix quoting styles are silly, especially $.

The law of responsiveness
The shell should attempt to remain responsive to the user at all times,
even in the face of contended or unresponsive filesystems. It is only
acceptable to block in response to a user initiated action, such as
running a command.

Rationale: Bad performance increases user-facing complexity, because it
trains users to recognize and route around slow use cases. It is also
incredibly frustrating.

Examples:

• Features like syntax highlighting and autosuggestions must perform
all of their disk I/O asynchronously.

• Startup should minimize forks and disk I/O, so that fish can be
started even if the system is under load.

Configurability is the root of all evil
Every configuration option in a program is a place where the program is
too stupid to figure out for itself what the user really wants, and
should be considered a failure of both the program and the programmer
who implemented it.

Rationale: Different configuration options are a nightmare to maintain,
since the number of potential bugs caused by specific configuration
combinations quickly becomes an issue. Configuration options often im-
ply assumptions about the code which change when reimplementing the
code, causing issues with backwards compatibility. But mostly, configu-
ration options should be avoided since they simply should not exist, as
the program should be smart enough to do what is best, or at least a
good enough approximation of it.

Examples:

• Fish allows the user to set various syntax highlighting colors. This
is needed because fish does not know what colors the terminal uses by
default, which might make some things unreadable. The proper solution
would be for text color preferences to be defined centrally by the
user for all programs, and for the terminal emulator to send these
color properties to fish.

• Fish does not allow you to set the number of history entries, differ-
ent language substyles or any number of other common shell configura-
tion options.

A special note on the evils of configurability is the long list of very
useful features found in some shells, that are not turned on by de-
fault. Both zsh and bash support command-specific completions, but no
such completions are shipped with bash by default, and they are turned
off by default in zsh. Other features that zsh supports that are dis-
abled by default include tab-completion of strings containing wild-
cards, a sane completion pager and a history file.

The law of user focus
When designing a program, one should first think about how to make an
intuitive and powerful program. Implementation issues should only be
considered once a user interface has been designed.

Rationale: This design rule is different than the others, since it de-
scribes how one should go about designing new features, not what the
features should be. The problem with focusing on what can be done, and
what is easy to do, is that too much of the implementation is exposed.
This means that the user must know a great deal about the underlying
system to be able to guess how the shell works, it also means that the
language will often be rather low-level.

Examples:

• There should only be one type of input to the shell, lists of com-
mands. Loops, conditionals and variable assignments are all performed
through regular commands.

• The differences between built-in commands and shellscript functions
should be made as small as possible. Built-ins and shellscript func-
tions should have exactly the same types of argument expansion as
other commands, should be possible to use in any position in a
pipeline, and should support any I/O redirection.

• Instead of forking when performing command substitution to provide a
fake variable scope, all fish commands are performed from the same
process, and fish instead supports true scoping.

• All blocks end with the end built-in.

The law of discoverability
A program should be designed to make its features as easy as possible
to discover for the user.

Rationale: A program whose features are discoverable turns a new user
into an expert in a shorter span of time, since the user will become an
expert on the program simply by using it.

The main benefit of a graphical program over a command-line-based pro-
gram is discoverability. In a graphical program, one can discover all
the common features by simply looking at the user interface and guess-
ing what the different buttons, menus and other widgets do. The tradi-
tional way to discover features in command-line programs is through
manual pages. This requires both that the user starts to use a differ-
ent program, and then they remember the new information until the next
time they use the same program.

Examples:

• Everything should be tab-completable, and every tab completion should
have a description.

• Every syntax error and error in a built-in command should contain an
error message describing what went wrong and a relevant help page.
Whenever possible, errors should be flagged red by the syntax high-
lighter.

• The help manual should be easy to read, easily available from the
shell, complete and contain many examples

• The language should be uniform, so that once the user understands the
command/argument syntax, they will know the whole language, and be
able to use tab-completion to discover new features.

Release notes
fish 3.7.1 (released March 19, 2024)
This release of fish fixes the following problems identified in fish
3.7.0:

• Deleting the last history entry via history delete works again (-
#10190).

• Wildcards (*) will no longer sometimes generate paths that did not
exist (#10205).

This release also contains some improvements:

• A crash when trying to run an ELF program with a missing interpreter
has been fixed. This crashed in the process after fork, so did not
affect the fish process that tried to start the program (#10199).

• funced will now always source the file after it has written it, even
if the contents did not change. This prevents issues if the file was
otherwise modified (#10318).

• The warning for when a builtin returns a negative exit code was im-
proved, now mentioning the original status (#10187).

• Added completions for

• cobra-cli (#10293)

• dmidecode (#10368)

• mycli (#10309)

• ollama (#10327)

• pstree (#10317)

• Some improvements to documentation and completions.

----

fish 3.7.0 (released January 1, 2024)
This release of fish includes a number of improvements over fish 3.6.4,
detailed below. Although work continues on the porting of fish inter-
nals to the Rust programming language, that work is not included in
this release. fish 3.7.0 and any future releases in the 3.7 series re-
main C++ programs.

Notable improvements and fixes
• Improvements to the history pager, including:

• The history pager will now also attempt subsequence matches (-
#9476), so you can find a command line like git log 3.6.1..Integra-
tion_3.7.0 by searching for gitInt.

• Opening the history pager will now fill the search field with a
search string if you're already in a search (#10005). This makes it
nicer to search something with and then later decide to switch to
the full pager.

• Closing the history pager with enter will now copy the search text
to the commandline if there was no match, so you can continue edit-
ing the command you tried to find right away (#9934).

• Performance improvements for command completions and globbing, where
supported by the operating system, especially on slow filesystems
such as NFS (#9891, #9931, #10032, #10052).

• fish can now be configured to wait a specified amount of time for a
multi-key sequence to be completed, instead of waiting indefinitely.
For example, this makes binding kj to switching modes in vi mode pos-
sible. The timeout can be set via the new fish_sequence_key_delay_ms
variable (#7401), and may be set by default in future versions.

Deprecations and removed features
• LS_COLORS is no longer set automatically by the ls function (#10080).
Users that set .dircolors should manually import it using other
means. Typically this would be set -gx LS_COLORS (dircolors -c .dir-
colors | string split ' ')[3]

Scripting improvements
• Running exit with a negative number no longer crashes fish (#9659).

• fish --command will now return a non-zero status if parsing failed (-
#9888).

• The jobs builtin will now escape the commands it prints (#9808).

• string repeat no longer overflows if the count is a multiple of the
chunk size (#9900).

• The builtin builtin will now properly error out with invalid argu-
ments instead of doing nothing and returning true (#9942).

• command time in a pipeline is allowed again, as is command and and
command or (#9985).

• exec will now also apply variable overrides, so FOO=bar exec will now
set $FOO correctly (#9995).

• umask will now handle empty symbolic modes correctly, like umask
u=,g=rwx,o= (#10177).

• Improved error messages for errors occurring in command substitutions
(#10054).

Interactive improvements
• read no longer enables bracketed paste so it doesn't stay enabled in
combined commandlines like mysql -p(read --silent) (#8285).

• Vi mode now uses fish_cursor_external to set the cursor shape for ex-
ternal commands (#4656).

• Opening the history search in vi mode switches to insert mode cor-
rectly (#10141).

• Vi mode cursor shaping is now enabled in iTerm2 (#9698).

• Working directory reporting is enabled for iTerm2 (#9955).

• Completing commands as root includes commands not owned by root, fix-
ing a regression introduced in fish 3.2.0 (#9699).

• Selection uses fish_color_selection for the foreground and background
colors, as intended, rather than just the background (#9717).

• The completion pager will no longer sometimes skip the last entry
when moving through a long list (#9833).

• The interactive history delete interface now allows specifying index
ranges like "1..5" (#9736), and history delete --exact now properly
saves the history (#10066).

• Command completion will now call the stock manpath on macOS, instead
of a potential Homebrew version. This prevents awkward error messages
(#9817).

• A new bind function history-pager-delete, bound to Shift + Delete by
default, will delete the currently-selected history pager item from
history (#9454).

• fish_key_reader will now use printable characters as-is, so pressing
"" no longer leads to it telling you to bind \u00F6 (#9986).

• open can be used to launch terminal programs again, as an xdg-open
bug has been fixed and a workaround has been removed (#10045).

• The repaint-mode binding will now only move the cursor if there is
repainting to be done. This fixes Alt combination bindings in vi mode
(#7910).

• A new clear-screen bind function is used for Ctrl + l by default.
This clears the screen and repaints the existing prompt at first, so
it eliminates visible flicker unless the terminal is very slow (-
#10044).

• The alias convenience function has better support for commands with
unusual characters, like + (#8720).

• A longstanding issue where items in the pager would sometimes display
without proper formatting has been fixed (#9617).

• The Alt + l binding, which lists the directory of the token under the
cursor, correctly expands tilde (~) to the home directory (#9954).

• Various fish utilities that use an external pager will now try a se-
lection of common pagers if the PAGER environment variable is not
set, or write the output to the screen without a pager if there is
not one available (#10074).

• Command-specific tab completions may now offer results whose first
character is a period. For example, it is now possible to tab-com-
plete git add for files with leading periods. The default file com-
pletions hide these files, unless the token itself has a leading pe-
riod (#3707).

Improved prompts
• The default theme now only uses named colors, so it will track the
terminal's palette (#9913).

• The Dracula theme has now been synced with upstream (#9807); use
fish_config to re-apply it to pick up the changes.

• fish_vcs_prompt now also supports fossil (#9497).

• Prompts which display the working directory using the prompt_pwd
function correctly display directories beginning with dashes (-
#10169).

Completions
• Added completions for:

• age and age-keygen (#9813)

• airmon-ng (#10116)

• ar (#9720)

• blender (#9905)

• bws (#10165)

• calendar (#10138)

• checkinstall (#10106)

• crc (#10034)

• doctl

• gimp (#9904)

• gojq (#9740)

• horcrux (#9922)

• ibmcloud (#10004)

• iwctl (#6884)

• java_home (#9998)

• krita (#9903)

• oc (#10034)

• qjs (#9723)

• qjsc (#9731)

• rename (#10136)

• rpm-ostool (#9669)

• smerge (#10135)

• userdel (#10056)

• watchexec (#10027)

• wpctl (#10043)

• xxd (#10137)

• zabbix (#9647)

• The zfs completions no longer print errors about setting a read-only
variable (#9705).

• The kitty completions have been removed in favor of keeping them up-
stream (#9750).

• git completions now support aliases that reference other aliases (-
#9992).

• The gw and gradlew completions are loaded properly (#10127).

• Improvements to many other completions.

• Improvements to the manual page completion generator (#9787, #9814,
#9961).

Other improvements
• Improvements and corrections to the documentation.

• The Web-based configuration now uses a more readable style when
printed, such as for a keybinding reference (#9828).

• Updates to the German translations (#9824).

• The colors of the Nord theme better match their official style (-
#10168).

For distributors
• The licensing information for some of the derived code distributed
with fish was incomplete. Though the license information was present
in the source distribution, it was not present in the documentation.
This has been corrected (#10162).

• The CMake configure step will now also look for libterminfo as an al-
ternative name for libtinfo, as used in NetBSD curses (#9794).

----

fish 3.6.4 (released December 5, 2023)
This release contains a complete fix for the test suite failure in fish
3.6.2 and 3.6.3.

----

fish 3.6.3 (released December 4, 2023)
This release contains a fix for a test suite failure in fish 3.6.2.

----

fish 3.6.2 (released December 4, 2023)
This release of fish contains a security fix for CVE-2023-49284, a mi-
nor security problem identified in fish 3.6.1 and previous versions
(thought to affect all released versions of fish).

fish uses certain Unicode non-characters internally for marking wild-
cards and expansions. It incorrectly allowed these markers to be read
on command substitution output, rather than transforming them into a
safe internal representation.

For example, echo \UFDD2HOME has the same output as echo $HOME.

While this may cause unexpected behavior with direct input, this may
become a minor security problem if the output is being fed from an ex-
ternal program into a command substitution where this output may not be
expected.

----

fish 3.6.1 (released March 25, 2023)
This release of fish contains a number of fixes for problems identified
in fish 3.6.1, as well as some enhancements.

Notable improvements and fixes
•

abbr --erase now also erases the universal variables used by the old
abbr function. That means::
abbr --erase (abbr --list)

can now be used to clean out all old abbreviations (#9468).

• abbr --add --universal now warns about --universal being non-func-
tional, to make it easier to detect old-style abbr calls (#9475).

Deprecations and removed features
• The Web-based configuration for abbreviations has been removed, as it
was not functional with the changes abbreviations introduced in 3.6.0
(#9460).

Scripting improvements
• abbr --list no longer escapes the abbr name, which is necessary to be
able to pass it to abbr --erase (#9470).

• read will now print an error if told to set a read-only variable, in-
stead of silently doing nothing (#9346).

• set_color -v no longer crashes fish (#9640).

Interactive improvements
• Using fish_vi_key_bindings in combination with fish's --no-config
mode works without locking up the shell (#9443).

• The history pager now uses more screen space, usually half the screen
(#9458)

• Variables that were set while the locale was C (the default
ASCII-only locale) will now properly be encoded if the locale is
switched (#2613, #9473).

• Escape during history search restores the original command line again
(fixing a regression in 3.6.0).

• Using --help on builtins now respects the $MANPAGER variable, in
preference to $PAGER (#9488).

• Control-G closes the history pager, like other shells (#9484).

• The documentation for the :, [ and . builtin commands can now be
looked up with man (#9552).

• fish no longer crashes when searching history for non-ASCII code-
points case-insensitively (#9628).

• The Alt-S binding will now also use please if available (#9635).

• Themes that don't specify every color option can be installed cor-
rectly in the Web-based configuration (#9590).

• Compatibility with Midnight Commander's prompt integration has been
improved (#9540).

• A spurious error, noted when using fish in Google Drive directories
under WSL 2, has been silenced (#9550).

• Using read in fish_greeting or similar functions will not trigger an
infinite loop (#9564).

• Compatibility when upgrading from old versions of fish (before 3.4.0)
has been improved (#9569).

Improved prompts
• The git prompt will compute the stash count to be used independently
of the informative status (#9572).

Completions
• Added completions for:

• apkanalyzer (#9558)

• neovim (#9543)

• otool

• pre-commit (#9521)

• proxychains (#9486)

• scrypt (#9583)

• stow (#9571)

• trash and helper utilities trash-empty, trash-list, trash-put,
trash-restore (#9560)

• ssh-copy-id (#9675)

• Improvements to many completions, including the speed of completing
directories in WSL 2 (#9574).

• Completions using __fish_complete_suffix are now offered in the cor-
rect order, fixing a regression in 3.6.0 (#8924).

• git completions for git-foo-style commands was restored, fixing a re-
gression in 3.6.0 (#9457).

• File completion now offers ../ and ./ again, fixing a regression in
3.6.0 (#9477).

• The behaviour of completions using __fish_complete_path matches stan-
dard path completions (#9285).

Other improvements
• Improvements and corrections to the documentation.

For distributors
• fish 3.6.1 builds correctly on Cygwin (#9502).

----

fish 3.6.0 (released January 7, 2023)
Notable improvements and fixes
• By default, Control-R now opens the command history in the pager (-
#602). This is fully searchable and syntax-highlighted, as an alter-
native to the incremental search seen in other shells. The new spe-
cial input function history-pager has been added for custom bindings.

• Abbrevations are more flexible (#9313, #5003, #2287):

• They may optionally replace tokens anywhere on the command line,
instead of only commands

• Matching tokens may be described using a regular expression instead
of a literal word

• The replacement text may be produced by a fish function, instead of
a literal word

• They may position the cursor anywhere in the expansion, instead of
at the end

For example:

function multicd
echo cd (string repeat -n (math (string length -- $argv[1]) - 1) ../)
end

abbr --add dotdot --regex '^\.\.+$' --function multicd

This expands .. to cd ../, ... to cd ../../ and .... to cd ../../../
and so on.

Or:

function last_history_item; echo $history[1]; end
abbr -a !! --position anywhere --function last_history_item

which expands !! to the last history item, anywhere on the command
line, mimicking other shells' history expansion.

See the documentation for more.

• path gained a new mtime subcommand to print the modification time
stamp for files. For example, this can be used to handle cache file
ages (#9057):

> touch foo
> sleep 10
> path mtime --relative foo
10

• string gained a new shorten subcommand to shorten strings to a given
visible width (#9156):

> string shorten --max 10 "Hello this is a long string"
Hello thi

• test (aka [) gained -ot (older than) and -nt (newer than) operators
to compare file modification times, and -ef to compare whether the
arguments are the same file (#3589).

• fish will now mark the extent of many errors with a squiggly line,
instead of just a caret (^) at the beginning (#9130). For example:

checks/set.fish (line 471): for: a,b: invalid variable name. See `help identifiers`
for a,b in y 1 z 3
^~^

• A new function, fish_delta, shows changes that have been made in
fish's configuration from the defaults (#9255).

• set --erase can now be used with multiple scopes at once, like set
-efglU foo (#7711, #9280).

• status gained a new subcommand, current-commandline, which retrieves
the entirety of the currently-executing command line when called from
a function during execution. This allows easier job introspection (-
#8905, #9296).

Deprecations and removed features
• The \x and \X escape syntax is now equivalent. \xAB previously be-
haved the same as \XAB, except that it would error if the value "AB"
was larger than "7f" (127 in decimal, the highest ASCII value) (-
#9247, #9245, #1352).

• The fish_git_prompt will now only turn on features if the appropriate
variable has been set to a true value (of "1", "yes" or "true") in-
stead of just checking if it is defined. This allows specifically
turning features off without having to erase variables, such as via
universal variables. If you have defined a variable to a different
value and expect it to count as true, you need to change it (#9274).
For example, set -g __fish_git_prompt_show_informative_status 0 pre-
viously would have enabled informative status (because any value
would have done so), but now it turns it off.

• Abbreviations are no longer stored in universal variables. Existing
universal abbreviations are still imported, but new abbreviations
should be added to config.fish.

• The short option -r for abbreviations has changed from rename to
regex, for consistency with string.

Scripting improvements
• argparse can now be used without option specifications, to allow us-
ing --min-args, --max-args or for commands that take no options (but
might in future) (#9006):

function my_copy
argparse --min-args 2 -- $argv
or return

cp $argv
end

• set --show now shows when a variable was inherited from fish's parent
process, which should help with debugging (#9029):

> set --show XDG_DATA_DIRS
$XDG_DATA_DIRS: set in global scope, exported, a path variable with 4 elements
$XDG_DATA_DIRS[1]: |/home/alfa/.local/share/flatpak/exports/share|
$XDG_DATA_DIRS[2]: |/var/lib/flatpak/exports/share|
$XDG_DATA_DIRS[3]: |/usr/local/share|
$XDG_DATA_DIRS[4]: |/usr/share|
$XDG_DATA_DIRS: originally inherited as |/home/alfa/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share/:/usr/share/|

• The read limit is now restored to the default when fish_read_limit is
unset (#9129).

• math produces an error for division-by-zero, as well as augmenting
some errors with their extent (#9190). This changes behavior in some
limited cases, such as:

math min 1 / 0, 5

which would previously print "5" (because in floating point division
"1 / 0" yields infinite, and 5 is smaller than infinite) but will now
return an error.

• fish_clipboard_copy and fish_clipboard_paste can now be used in pipes
(#9271):

git rev-list 3.5.1 | fish_clipboard_copy

fish_clipboard_paste | string join + | math

• status fish-path returns a fully-normalised path, particularly no-
ticeable on NetBSD (#9085).

Interactive improvements
• If the terminal definition for TERM can't be found, fish now tries
using the "xterm-256color" and "xterm" definitions before "ansi" and
"dumb". As the majority of terminal emulators in common use are now
more or less xterm-compatible (often even explicitly claiming the
xterm-256color entry), this should often result in a fully or almost
fully usable terminal (#9026).

• A new variable, fish_cursor_selection_mode, can be used to configure
whether the command line selection includes the character under the
cursor (inclusive) or not (exclusive). The new default is exclusive;
use set fish_cursor_selection_mode inclusive to get the previous be-
havior back (#7762).

• fish's completion pager now fills half the terminal on first tab
press instead of only 4 rows, which should make results visible more
often and save key presses, without constantly snapping fish to the
top of the terminal (#9105, #2698).

• The complete-and-search binding, used with Shift-Tab by default, se-
lects the first item in the results immediately (#9080).

• bind output is now syntax-highlighted when used interacively.

• Alt-H (the default __fish_man_page binding) does a better job of
showing the manual page of the command under cursor (#9020).

• If fish_color_valid_path contains an actual color instead of just
modifiers, those will be used for valid paths even if the underlying
color isn't "normal" (#9159).

• The key combination for the QUIT terminal sequence, often Con-
trol-Backslash (\x1c), can now be sused as a binding (#9234).

• fish's vi mode uses normal xterm-style sequences to signal cursor
change, instead of using the iTerm's proprietary escape sequences.
This allows for a blinking cursor and makes it work in complicated
scenarios with nested terminals. (#3741, #9172)

• When running fish on a remote system (such as inside SSH or a con-
tainer), Control-X now copies to the local client system's clipboard
if the terminal supports OSC 52.

• commandline gained two new options, --selection-start and --selec-
tion-end, to set the start/end of the current selection (#9197,
#9215).

• fish's builtins now handle keyboard interrupts (Control-C) correctly
(#9266).

Completions
• Added completions for:

• ark

• asciinema (#9257)

• clojure (#9272)

• csh

• direnv (#9268)

• dive (#9082)

• dolphin

• dua (#9277)

• efivar (#9318)

• eg

• es (#9388)

• firefox-developer-edition and firefox (#9090)

• fortune (#9177)

• kb

• kind (#9110)

• konsole

• ksh

• loadkeys (#9312)

• okular

• op (#9300)

• ouch (#9405)

• pix

• readelf (#8746, #9386)

• qshell

• rc

• sad (#9145)

• tcsh

• toot

• tox (#9078)

• wish

• xed

• xonsh (#9389)

• xplayer

• xreader

• xviewer

• yash (#9391)

• zig (#9083)

• Improvements to many completions, including making cd completion much
faster (#9220).

• Completion of tilde (~) works properly even when the file name con-
tains an escaped character (#9073).

• fish no longer loads completions if the command is used via a rela-
tive path and is not in PATH (#9133).

• fish no longer completes inside of comments (#9320).

Improved terminal support
• Opening help on WSL now uses PowerShell to open the browser if avail-
able, removing some awkward UNC path errors (#9119).

Other improvements
• The Web-based configuration tool now works on systems with IPv6 dis-
abled (#3857).

• Aliases can ignore arguments by ending them with # (#9199).

• string is now faster when reading large strings from stdin (#9139).

• string repeat uses less memory and is faster. (#9124)

• Builtins are much faster when writing to a pipe or file. (#9229).

• Performance improvements to highlighting (#9180) should make using
fish more pleasant on slow systems.

• On 32-bit systems, globs like * will no longer fail to return some
files, as large file support has been enabled.

Fixed bugs
• The history search text for a token search is now highlighted cor-
rectly if the line contains multiple instances of that text (#9066).

• process-exit and job-exit events are now generated for all background
jobs, including those launched from event handlers (#9096).

• A crash when completing a token that contained both a potential glob
and a quoted variable expansion was fixed (#9137).

• prompt_pwd no longer accidentally overwrites a global or universal
$fish_prompt_pwd_full_dirs when called with the -d or
--full-length-dirs option (#9123).

• A bug which caused fish to freeze or exit after running a command
which does not preserve the foreground process group was fixed (-
#9181).

• The "Disco" sample prompt no longer prints an error in some working
directories (#9164). If you saved this prompt, you should run
fish_config prompt save disco again.

• fish launches external commands via the given path again, rather than
always using an absolute path. This behaviour was inadvertently
changed in 3.5.0 and is visible, for example, when launching a bash
script which checks $0 (#9143).

• printf no longer tries to interpret the first argument as an option
(#9132).

• Interactive read in scripts will now have the correct keybindings
again (#9227).

• A possible stack overflow when recursively evaluating substitutions
has been fixed (#9302).

• A crash with relative $CDPATH has been fixed (#9407).

• printf now properly fills extra %d specifiers with 0 even on macOS
and BSD (#9321).

• fish_key_reader now correctly exits when receiving a SIGHUP (like af-
ter closing the terminal) (#9309).

• fish_config theme save now works as documented instead of erroring
out (#9088, #9273).

• fish no longer triggers prompts to install command line tools when
first run on macOS (#9343).

• fish_git_prompt now quietly fails on macOS if the xcrun cache is not
yet populated (#6625), working around a potential hang.

For distributors
• The vendored PCRE2 sources have been removed. It is recommended to
declare PCRE2 as a dependency when packaging fish. If the CMake vari-
able FISH_USE_SYSTEM_PCRE2 is false, fish will now download and build
PCRE2 from the official repo (#8355, #8363). Note this variable de-
faults to true if PCRE2 is found installed on the system.

----

fish 3.5.1 (released July 20, 2022)
This release of fish introduces the following small enhancements:

• Cursor shaping for Vi mode is enabled by default in tmux, and will be
used if the outer terminal is capable (#8981).

• printf returns a better error when used with arguments interpreted as
octal numbers (#9035).

• history merge when in private mode is now an error, rather than wip-
ing out other sessions' history (#9050).

• The error message when launching a command that is built for the
wrong architecture on macOS is more helpful (#9052).

• Added completions for:

• choose (#9065)

• expect (#9060)

• navi (#9064)

• qdbus (#9031)

• reflector (#9027)

• Improvements to some completions.

This release also fixes a number of problems identified in fish 3.5.0.

• Completing git blame or git -C works correctly (#9053).

• On terminals that emit a CSI u sequence for Shift-Space, fish inserts
a space instead of printing an error. (#9054).

• status fish-path on Linux-based platforms could print the path with a
" (deleted)" suffix (such as /usr/bin/fish (deleted)), which is now
removed (#9019).

• Cancelling an initial command (from fish's --init-command option)
with Control-C no longer prevents configuration scripts from running
(#9024).

• The job summary contained extra blank lines if the prompt used multi-
ple lines, which is now fixed (#9044).

• Using special input functions in bindings, in combination with and/or
conditionals, no longer crashes (#9051).

----

fish 3.5.0 (released June 16, 2022)
Notable improvements and fixes
• A new path builtin command to filter and transform paths (#7659,
#8958). For example, to list all the separate extensions used on
files in /usr/share/man (after removing one extension, commonly a
".gz"):

path filter -f /usr/share/man/** | path change-extension '' | path extension | path sort -u

• Tab (or any key bound to complete) now expands wildcards instead of
invoking completions, if there is a wildcard in the path component
under the cursor (#954, #8593).

• Scripts can now catch and handle the SIGINT and SIGTERM signals, ei-
ther via function --on-signal or with trap (#6649).

Deprecations and removed features
• The stderr-nocaret feature flag, introduced in fish 3.0 and enabled
by default in fish 3.1, has been made read-only. That means it is no
longer possible to disable it, and code supporting the ^ redirection
has been removed (#8857, #8865).

To recap: fish used to support ^ to redirect stderr, so you could use
commands like:

test "$foo" -gt 8 ^/dev/null

to ignore error messages. This made the ^ symbol require escaping and
quoting, and was a bit of a weird shortcut considering 2> already
worked, which is only one character longer.

So the above can simply become:

test "$foo" -gt 8 2>/dev/null

• The following feature flags have been enabled by default:

• regex-easyesc, which makes string replace -r not do a superfluous
round of unescaping in the replacement expression. That means e.g.
to escape any "a" or "b" in an argument you can use string replace
-ra '([ab])' '\\\\$1' foobar instead of needing 8 backslashes.

This only affects the replacement expression, not the match expres-
sion (the '([ab])' part in the example). A survey of plugins on
GitHub did not turn up any affected code, so we do not expect this
to affect many users.

This flag was introduced in fish 3.1.

• ampersand-nobg-in-token, which means that & will not create a back-
ground job if it occurs in the middle of a word. For example, echo
foo&bar will print "foo&bar" instead of running echo foo in the
background and then starting bar as a second job.

Reformatting with fish_indent would already introduce spaces, turn-
ing echo foo&bar into echo foo & bar.

This flag was introduced in fish 3.4.

To turn off these flags, add no-regex-easyesc or no-amper-
sand-nobg-in-token to fish_features and restart fish:

set -Ua fish_features no-regex-easyesc

Like stderr-nocaret, they will eventually be made read-only.

• Most string subcommands no longer append a newline to their input if
the input didn't have one (#8473, #3847)

• Fish's escape sequence removal (like for string length --visible or
to figure out how wide the prompt is) no longer has special support
for non-standard color sequences like from Data General terminals,
e.g. the Data General Dasher D220 from 1984. This removes a bunch of
work in the common case, allowing string length --visible to be much
faster with unknown escape sequences. We don't expect anyone to have
ever used fish with such a terminal (#8769).

• Code to upgrade universal variables from fish before 3.0 has been re-
moved. Users who upgrade directly from fish versions 2.7.1 or before
will have to set their universal variables & abbreviations again. (-
#8781)

• The meaning of an empty color variable has changed (#8793). Previ-
ously, when a variable was set but empty, it would be interpreted as
the "normal" color. Now, empty color variables cause the same effect
as unset variables - the general highlighting variable for that type
is used instead. For example:

set -g fish_color_command blue
set -g fish_color_keyword

would previously make keywords "normal" (usually white in a dark ter-
minal). Now it'll make them blue. To achieve the previous behavior,
use the normal color explicitly: set -g fish_color_keyword normal.

This makes it easier to make self-contained color schemes that don't
accidentally use color that was set before. fish_config has been ad-
justed to set known color variables that a theme doesn't explicitly
set to empty.

• eval is now a reserved keyword, so it can't be used as a function
name. This follows set and read, and is necessary because it can't be
cleanly shadowed by a function - at the very least eval set -l argv
foo breaks. Fish will ignore autoload files for it, so left over
eval.fish from previous fish versions won't be loaded.

• The git prompt in informative mode now defaults to skipping counting
untracked files, as this was extremely slow. To turn it on, set
__fish_git_prompt_showuntrackedfiles or set the git config value
"bash.showuntrackedfiles" to true explicitly (which can be done for
individual repositories). The "informative+vcs" sample prompt already
skipped display of untracked files, but didn't do so in a way that
skipped the computation, so it should be quite a bit faster in many
cases (#8980).

• The __terlar_git_prompt function, used by the "Terlar" sample prompt,
has been rebuilt as a configuration of the normal fish_git_prompt to
ease maintenance, improve performance and add features (like reading
per-repo git configuration). Some slight changes remain; users who
absolutely must have the same behavior are encouraged to copy the old
function (#9011, #7918, #8979).

Scripting improvements
• Quoted command substitution that directly follow a variable expansion
(like echo "$var$(echo x)") no longer affect the variable expansion
(#8849).

• Fish now correctly expands command substitutions that are preceded by
an escaped dollar (like echo \$(echo)). This regressed in version
3.4.0.

• math can now handle underscores (_) as visual separators in numbers
(#8611, #8496):

math 5 + 2_123_252

• math's min and max functions now take a variable number of arguments
instead of always requiring 2 (#8644, #8646):

> math min 8,2,4
2

• read is now faster as the last process in a pipeline (#8552).

• string join gained a new --no-empty flag to skip empty arguments (-
#8774, #8351).

• read now only triggers the fish_read event, not the fish_prompt event
(#8797). It was supposed to work this way in fish 3.2.0 and later,
but both events were emitted.

• The TTY modes are no longer restored when non-interactive shells
exit. This fixes wrong tty modes in pipelines with interactive com-
mands. (#8705).

• Some functions shipped with fish printed error messages to standard
output, but they now they rightly go to standard error (#8855).

• jobs now correctly reports CPU usage as a percentage, instead of as a
number of clock ticks (#8919).

• process-exit events now fire when the process exits even if the job
has not yet exited, fixing a regression in 3.4.1 (#8914).

Interactive improvements
• Fish now reports a special error if a command wasn't found and there
is a non-executable file by that name in PATH (#8804).

• less and other interactive commands would occasionally be stopped
when run in a pipeline with fish functions; this has been fixed (-
#8699).

• Case-changing autosuggestions generated mid-token now correctly ap-
pend only the suffix, instead of duplicating the token (#8820).

• ulimit learned a number of new options for the resource limits avail-
able on Linux, FreeBSD ande NetBSD, and returns a specific warning if
the limit specified is not available on the active operating system
(#8823, #8786).

• The vared command can now successfully edit variables named "tmp" or
"prompt" (#8836, #8837).

• time now emits an error if used after the first command in a pipeline
(#8841).

• fish_add_path now prints a message for skipped non-existent paths
when using the -v flag (#8884).

• Since fish 3.2.0, pressing Control-D while a command is running would
end up inserting a space into the next commandline, which has been
fixed (#8871).

• A bug that caused multi-line prompts to be moved down a line when
pasting or switching modes has been fixed (#3481).

• The Web-based configuration system no longer strips too many quotes
in the abbreviation display (#8917, #8918).

• Fish started with --no-config will now use the default keybindings (-
#8493)

• When fish inherits a USER environment variable value that doesn't
correspond to the current effective user ID, it will now correct it
in all cases (#8879, #8583).

• Fish sets a new EUID variable containing the current effective user
id (#8866).

• history search no longer interprets the search term as an option (-
#8853)

• The status message when a job terminates should no longer be erased
by a multiline prompt (#8817)

New or improved bindings
• The Alt-S binding will now insert doas instead of sudo if necessary
(#8942).

• The kill-whole-line special input function now kills the newline pre-
ceeding the last line. This makes dd in vi-mode clear the last line
properly.

• The new kill-inner-line special input function kills the line without
any newlines, allowing cc in vi-mode to clear the line while preserv-
ing newlines (#8983).

• On terminals that emit special sequences for these combinations,
Shift-Space is bound like Space, and Ctrl-Return is bound like Return
(#8874).

Improved prompts
• A new Astronaut prompt (#8775), a multi-line prompt using plain text
reminiscent of the Starship.rs prompt.

Completions
• Added completions for:

• archlinux-java (#8911)

• apk (#8951)

• brightnessctl (#8758)

• efibootmgr (#9010)

• fastboot (#8904)

• optimus-manager (#8913)

• rclone (#8819)

• sops (#8821)

• tuned-adm (#8760)

• wg-quick (#8687)

• complete can now be given multiple --condition options. They will be
attempted in the order they were given, and only if all succeed will
the completion be made available (as if they were connected with &&).
This helps with caching - fish's complete system stores the return
value of each condition as long as the commandline doesn't change, so
this can reduce the number of conditions that need to be evaluated (-
#8536, #8967).

Improved terminal support
• Working directory reporting is enabled for kitty (#8806).

• Changing the cursor shape is now enabled by default in iTerm2 (-
#3696).

For distributors
• libatomic is now correctly detected as necessary when building on
RISC-V (#8850, #8851).

• In some cases, the build process found the wrong libintl on macOS.
This has been corrected (#5244).

• The paths for completions, functions, and configuration snippets now
include subdirectories fish/vendor_completions.d, fish/vendor_func-
tions.d, and fish/vendor_conf.d (respectively) within XDG_DATA_HOME
(or ~/.local/share if not defined) (#8887, #7816).

----

fish 3.4.1 (released March 25, 2022)
This release of fish fixes the following problems identified in fish
3.4.0:

• An error printed after upgrading, where old instances could pick up a
newer version of the fish_title function, has been fixed (#8778)

• fish builds correctly on NetBSD (#8788) and OpenIndiana (#8780).

• nextd-or-forward-word, bound to Alt-Right Arrow by default, was inad-
vertently changed to move like forward-bigword. This has been cor-
rected (#8790).

• funcsave -q and funcsave --quiet now work correctly (#8830).

• Issues with the csharp and nmcli completions were corrected.

If you are upgrading from version 3.3.1 or before, please also review
the release notes for 3.4.0 (included below).

----

fish 3.4.0 (released March 12, 2022)
Notable improvements and fixes
• fish's command substitution syntax has been extended: $(cmd) now has
the same meaning as (cmd) but it can be used inside double quotes, to
prevent line splitting of the results (#159):

foo (bar | string collect)
# can now be written as
foo "$(bar)"

# and

foo (bar)
# can now be written as
foo $(bar)
# this will still split on newlines only.

• Complementing the prompt command in 3.3.0, fish_config gained a theme
subcommand to show and pick from the sample themes (meaning color
schemes) directly in the terminal, instead of having to open a Web
browser. For example fish_config theme choose Nord loads the Nord
theme in the current session (#8132). The current theme can be saved
with fish_config theme dump, and custom themes can be added by saving
them in ~/.config/fish/themes/.

• set and read learned a new option, --function, to set a variable in
the function's top scope. This should be a more familiar way of scop-
ing variables and avoids issues with --local, which is actually
block-scoped (#565, #8145):

function demonstration
if true
set --function foo bar
set --local baz banana
end
echo $foo # prints "bar" because $foo is still valid
echo $baz # prints nothing because $baz went out of scope
end

• string pad now excludes escape sequences like colors that fish knows
about, and a new --visible flag to string length makes it use that
kind of visible width. This is useful to get the number of terminal
cells an already colored string would occupy, like in a prompt. (-
#8182, #7784, #4012):

> string length --visible (set_color red)foo
3

• Performance improvements to globbing, especially on systems using
glibc. In some cases (large directories with files with many numbers
in the names) this almost halves the time taken to expand the glob.

• Autosuggestions can now be turned off by setting $fish_autosugges-
tion_enabled to 0, and (almost) all highlighting can be turned off by
choosing the new "None" theme. The exception is necessary colors,
like those which distinguish autosuggestions from the actual command
line. (#8376)

• The fish_git_prompt function, which is included in the default
prompts, now overrides git to avoid running commands set by
per-repository configuration. This avoids a potential security issue
in some circumstances, and has been assigned CVE-2022-20001 (#8589).

Deprecations and removed features
• A new feature flag, ampersand-nobg-in-token makes & only act as back-
ground operator if followed by a separator. In combination with
qmark-noglob, this allows entering most URLs at the command line
without quoting or escaping (#7991). For example:

> echo foo&bar # will print "foo&bar", instead of running "echo foo" in the background and executing "bar"
> echo foo & bar # will still run "echo foo" in the background and then run "bar"
# with both ampersand-nobg-in-token and qmark-noglob, this argument has no special characters anymore
> open https://www.youtube.com/watch?v=dQw4w9WgXcQ&feature=youtu.be

As a reminder, feature flags can be set on startup with fish --fea-
tures ampersand-nobg-in-token,qmark-noglob or with a universal vari-
able called fish_features:

> set -Ua fish_features ampersand-nobg-in-token

• $status is now forbidden as a command, to prevent a surprisingly com-
mon error among new users: Running if $status (#8171). This applies
only to $status, other variables are still allowed.

• set --query now returns an exit status of 255 if given no variable
names. This means if set -q $foo will not enter the if-block if $foo
is empty or unset. To restore the previous behavior, use if not set
-q foo; or set -q $foo - but this is unlikely to be desireable (-
#8214).

• _ is now a reserved keyword (#8342).

• The special input functions delete-or-exit, nextd-or-forward-word and
prevd-or-backward-word replace fish functions of the same names (-
#8538).

• Mac OS X 10.9 is no longer supported. The minimum Mac version is now
10.10 "Yosemite."

Scripting improvements
• string collect supports a new --allow-empty option, which will output
one empty argument in a command substitution that has no output (-
#8054). This allows commands like test -n (echo -n | string collect
--allow-empty) to work more reliably. Note this can also be written
as test -n "$(echo -n)" (see above).

• string match gained a --groups-only option, which makes it only out-
put capturing groups, excluding the full match. This allows string
match to do simple transformations (#6056):

> string match -r --groups-only '(.*)fish' 'catfish' 'twofish' 'blue fish' | string escape
cat
two
'blue '

• $fish_user_paths is now automatically deduplicated to fix a common
user error of appending to it in config.fish when it is universal (-
#8117). fish_add_path remains the recommended way to add to $PATH.

• return can now be used outside functions. In scripts, it does the
same thing as exit. In interactive mode,it sets $status without exit-
ing (#8148).

• An oversight prevented all syntax checks from running on commands
given to fish -c (#8171). This includes checks such as exec not being
allowed in a pipeline, and $$ not being a valid variable. Generally,
another error was generated anyway.

• fish_indent now correctly reformats tokens that end with a backslash
followed by a newline (#8197).

• commandline gained an --is-valid option to check if the command line
is syntactically valid and complete. This allows basic implementation
of transient prompts (#8142).

• commandline gained a --paging-full-mode option to check if the pager
is showing all the possible lines (no "7 more rows" message) (#8485).

• List expansion correctly reports an error when used with all zero in-
dexes (#8213).

• Running fish with a directory instead of a script as argument (eg
fish .) no longer leads to an infinite loop. Instead it errors out
immediately (#8258)

• Some error messages occuring after fork, like "text file busy" have
been replaced by bespoke error messages for fish (like "File is cur-
rently open for writing"). This also restores error messages with
current glibc versions that removed sys_errlist (#8234, #4183).

• The realpath builtin now also squashes leading slashes with the
--no-symlinks option (#8281).

• When trying to cd to a dangling (broken) symbolic link, fish will
print an error noting that the target is a broken link (#8264).

• On MacOS terminals that are not granted permissions to access a
folder, cd would print a spurious "rotten symlink" error, which has
been corrected to "permission denied" (#8264).

• Since fish 3.0, for loops would trigger a variable handler function
before the loop was entered. As the variable had not actually changed
or been set, this was a spurious event and has been removed (#8384).

• math now correctly prints negative values and values larger than
2**31 when in hex or octal bases (#8417).

• dirs always produces an exit status of 0, instead of sometimes re-
turning 1 (#8211).

• cd "" no longer crashes fish (#8147).

• set --query can now query whether a variable is a path variable via
--path or --unpath (#8494).

• Tilde characters (~) produced by custom completions are no longer es-
caped when applied to the command line, making it easier to use the
output of a recursive complete -C in completion scripts (#4570).

• set --show reports when a variable is read-only (#8179).

• Erasing $fish_emoji_width will reset fish to the default guessed
emoji width (#8274).

• The la function no longer lists entries for "." and "..", matching
other systems defaults (#8519).

• abbr -q returns the correct exit status when given multiple abbrevia-
tion names as arguments (#8431).

• command -v returns an exit status of 127 instead of 1 if no command
was found (#8547).

• argparse with --ignore-unknown no longer breaks with multiple unknown
options in a short option group (#8637).

• Comments inside command substitutions or brackets now correctly ig-
nore parentheses, quotes, and brackets (#7866, #8022, #8695).

• complete -C supports a new --escape option, which turns on escaping
in returned completion strings (#3469).

• Invalid byte or unicode escapes like \Utest or \xNotHex are now a to-
kenizer error instead of causing the token to be truncated (#8545).

Interactive improvements
• Vi mode cursors are now set properly after Control-C (#8125).

• funced will try to edit the whole file containing a function defini-
tion, if there is one (#391).

• Running a command line consisting of just spaces now deletes an
ephemeral (starting with space) history item again (#8232).

• Command substitutions no longer respect job control, instead running
inside fish's own process group (#8172). This more closely matches
other shells, and improves Control-C reliability inside a command
substitution.

• history and __fish_print_help now properly support less before ver-
sion 530, including the version that ships with macOS. (#8157).

• help now knows which section is in which document again (#8245).

• fish's highlighter will now color options (starting with - or --)
with the color given in the new $fish_color_option, up to the first
--. It falls back on $fish_color_param, so nothing changes for exist-
ing setups (#8292).

• When executing a command, abbreviations are no longer expanded when
the cursor is separated from the command by spaces, making it easier
to suppress abbreviation expansion of commands without arguments. (-
#8423).

• fish_key_reader's output was simplified. By default, it now only
prints a bind statement. The previous per-character timing informa-
tion can be seen with a new --verbose switch (#8467).

• Custom completions are now also loaded for commands that contain
tildes or variables like ~/bin/fish or $PWD/fish (#8442).

• Command lines spanning multiple lines will not be overwritten by the
completion pager when it fills the entire terminal (#8509, #8405).

• When redrawing a multiline prompt, the old prompt is now properly
cleared (#8163).

• Interactive completion would occasionally ignore the last word on the
command line due to a race condition. This has been fixed (#8175).

• Propagation of universal variables from a fish process that is clos-
ing is faster (#8209).

• The command line is drawn in the correct place if the prompt ends
with a newline (#8298).

• history learned a new subcommand clear-session to erase all history
from the current session (#5791).

• Pressing Control-C in fish_key_reader will no longer print the incor-
rect "Press [ctrl-C] again to exit" message (#8510).

• The default command-not-found handler for Fedora/PackageKit now
passes the whole command line, allowing for functionality such as
running the suggested command directly (#8579).

• When looking for locale information, the Debian configuration is now
used when available (#8557).

• Pasting text containing quotes from the clipboard trims spaces more
appropriately (#8550).

• The clipboard bindings ignore X-based clipboard programs if the DIS-
PLAY environment variable is not set, which helps prefer the Windows
clipboard when it is available (such as on WSL).

• funcsave will remove a saved copy of a function that has been erased
with functions --erase.

• The Web-based configuration tool gained a number of improvements, in-
cluding the ability to set pager colors.

• The default fish_title prints a shorter title with shortened $PWD and
no more redundant "fish" (#8641).

• Holding down an arrow key won't freeze the terminal with long periods
of flashing (#8610).

• Multi-char bindings are no longer interrupted if a signal handler en-
queues an event. (#8628).

New or improved bindings
• Escape can now bound without breaking arrow key bindings (#8428).

• The Alt-H binding (to open a commands manual page) now also ignores
command (#8447).

Improved prompts
• The fish_status_to_signal helper function returns the correct signal
names for the current platform, rather than Linux (#8530).

• The prompt_pwd helper function learned a --full-length-dirs N option
to keep the last N directory components unshortened. In addition the
number of characters to shorten each component should be shortened to
can now be given as -d N or --dir-length N. (#8208):

> prompt_pwd --full-length-dirs 2 -d 1 ~/dev/fish-shell/share/tools/web_config
~/d/f/s/tools/web_config

Completions
• Added completions for:

• Apple's shortcuts

• argparse (#8434)

• asd (#8759)

• az (#8141)

• black (#8123)

• clasp (#8373)

• cpupower (#8302)

• dart (#8315)

• dscacheutil

• elvish (#8416)

• ethtool (#8283)

• exif (#8246)

• findstr (#8481)

• git-sizer (#8156)

• gnome-extensions (#8732)

• gping (#8181)

• isatty (#8609)

• istioctl (#8343)

• kmutil

• kubectl (#8734)

• matlab (#8505)

• mono (#8415) and related tools csharp, gacutil, gendarme, ikdasm,
ilasm, mkbundle, monodis, monop, sqlsharp and xsp (#8452)

• Angular's ng (#8111)

• nodeenv (#8533)

• octave (#8505)

• pabcnet_clear (#8421)

• qmk (#8180)

• rakudo (#8113)

• rc-status (#8757)

• roswell (#8330)

• sbcl (#8330)

• starship (#8520)

• topgrade (#8651)

• wine, wineboot and winemaker (#8411)

• Windows Subsystem for Linux (WSL)'s wslpath (#8364)

• Windows' color (#8483), attrib, attributes, choice, clean, clean-
mgr, cmd, cmdkey, comp, forfiles, powershell, reg, schtasks, setx
(#8486)

• zef (#8114)

• Improvements to many completions, especially for git aliases (#8129),
subcommands (#8134) and submodules (#8716).

• Many adjustments to complete correct options for system utilities on
BSD and macOS.

• When evaluating custom completions, the command line state no longer
includes variable overrides (var=val). This unbreaks completions that
read commandline -op.

Improved terminal support
• Dynamic terminal titles are enabled on WezTerm (#8121).

• Directory history navigation works out of the box with Apple Termi-
nal's default key settings (#2330).

• fish now assumes Unicode 9+ widths for emoji under iTerm 2 (#8200).

• Skin-tone emoji modifiers (U+1F3FB through U+1F3FF) are now measured
as width 0 (#8275).

• fish's escape sequence removal now also knows Tmux's wrapped escapes.

• Vi mode cursors are enabled in Apple Terminal.app (#8167).

• Vi cursor shaping and $PWD reporting is now also enabled on foot (-
#8422).

• ls will use colors also on newer versions of Apple Terminal.app (-
#8309).

• The Delete and Shift-Tab keys work more reliably under st (#8352,
#8354).

Other improvements
• Fish's test suite now uses ctest, and has become much faster to run.
It is now also possible to run only specific tests with targets named
test_$filename - make test_set.fish only runs the set.fish test. (-
#7851)

• The HTML version of the documentation now includes copy buttons for
code examples (#8218).

• The HTML version of the documentation and the web-based configuration
tool now pick more modern system fonts instead of falling back to Ar-
ial and something like Courier New most of the time (#8632).

• The Debian & Ubuntu package linked from fishshell.com is now a single
package, rather than split into fish and fish-common (#7845).

• The macOS installer does not assert that Rosetta is required to in-
stall fish on machines with Apple Silicon (#8566).

• The macOS installer now cleans up previous .pkg installations when
upgrading. (#2963).

For distributors
• The minimum version of CMake required to build fish is now 3.5.0.

• The CMake installation supports absolute paths for CMAKE_IN-
STALL_DATADIR (#8150).

• Building using NetBSD curses works on any platform (#8087).

• The build system now uses the default linker instead of forcing use
of the gold or lld linker (#8152).

----

fish 3.3.1 (released July 6, 2021)
This release of fish fixes the following problems identified in fish
3.3.0:

• The prompt and command line are redrawn correctly in response to uni-
versal variable changes (#8088).

• A superfluous error that was produced when setting the PATH or CDPATH
environment variables to include colon-delimited components that do
not exist was removed (#8095).

• The Vi mode indicator in the prompt is repainted correctly after
Ctrl-C cancels the current command (#8103).

• fish builds correctly on platforms that do not have a spawn.h header,
such as old versions of OS X (#8097).

A number of improvements to the documentation, and fixes for comple-
tions, are included as well.

If you are upgrading from version 3.2.2 or before, please also review
the release notes for 3.3.0 (included below).

----

fish 3.3.0 (released June 28, 2021)
Notable improvements and fixes
• fish_config gained a prompt subcommand to show and pick from the sam-
ple prompts directly in the terminal, instead of having to open a
webbrowser. For example fish_config prompt choose default loads the
default prompt in the current session (#7958).

• The documentation has been reorganized to be easier to understand (-
#7773).

Deprecations and removed features
• The $fish_history value "default" is no longer special. It used to be
treated the same as "fish" (#7650).

• Redirection to standard error with the ^ character has been disabled
by default. It can be turned back on using the stderr-nocaret feature
flag, but will eventually be disabled completely (#7105).

• Specifying an initial tab to fish_config now only works with
fish_config browse (eg fish_config browse variables), otherwise it
would interfere with the new prompt subcommand (see below) (#7958).

Scripting improvements
• math gained new functions log2 (like the documentation claimed), max
and min (#7856). math functions can be used without the parentheses
(eg math sin 2 + 6), and functions have the lowest precedence in the
order of operations (#7877).

• Shebang (#!) lines are no longer required within shell scripts, im-
proving support for scripts with concatenated binary contents. If a
file fails to execute and passes a (rudimentary) binary safety check,
fish will re-invoke it using /bin/sh (#7802).

• Exit codes are better aligned with bash. A failed execution now re-
ports $status of 127 if the file is not found, and 126 if it is not
executable.

• echo no longer writes its output one byte at a time, improving per-
formance and allowing use with Linux's special API files (/proc, /sys
and such) (#7836).

• fish should now better handle cd on filesystems with broken stat(3)
responses (#7577).

• Builtins now properly report a $status of 1 upon unsuccessful writes
(#7857).

• string match with unmatched capture groups and without the --all flag
now sets an empty variable instead of a variable containing the empty
string. It also correctly imports the first match if multiple argu-
ments are provided, matching the documentation. (#7938).

• fish produces more specific errors when a command in a command sub-
stitution wasn't found or is not allowed. This now prints something
like "Unknown command" instead of "Unknown error while evaluating
command substitution".

• fish_indent allows inline variable assignments (FOO=BAR command) to
use line continuation, instead of joining them into one line (#7955).

• fish gained a --no-config option to disable configuration files. This
applies to user-specific and the systemwide config.fish (typically in
/etc/fish/config.fish), and configuration snippets (typically in
conf.d directories). It also disables universal variables, history,
and loading of functions from system or user configuration directo-
ries (#7921, #1256).

• When universal variables are unavailable for some reason, setting a
universal variable now sets a global variable instead (#7921).

• $last_pid now contains the process ID of the last process in the
pipeline, allowing it to be used in scripts (#5036, #5832, #7721).
Previously, this value contained the process group ID, but in scripts
this was the same as the running fish's process ID.

• process-exit event handlers now receive the same value as $status in
all cases, instead of receiving -1 when the exit was due to a signal.

• process-exit event handlers for PID 0 also received JOB_EXIT events;
this has been fixed.

• job-exit event handlers may now be created with any of the PIDs from
the job. The handler is passed the last PID in the job as its second
argument, instead of the process group.

• Trying to set an empty variable name with set no longer works (these
variables could not be used in expansions anyway).

• fish_add_path handles an undefined PATH environment variable cor-
rectly (#8082).

Interactive improvements
• Commands entered before the previous command finishes will now be
properly syntax highlighted.

• fish now automatically creates config.fish and the configuration di-
rectories in $XDG_CONFIG_HOME/fish (by default ~/.config/fish) if
they do not already exist (#7402).

• $SHLVL is no longer incremented in non-interactive shells. This means
it won't be set to values larger than 1 just because your environment
happens to run some scripts in $SHELL in its startup path (#7864).

• fish no longer rings the bell when flashing the command line. The
flashing should already be enough notification and the bell can be
annoying (#7875).

• fish --help is more helpful if the documentation isn't installed (-
#7824).

• funced won't include an entry on where a function is defined, thanks
to the new functions --no-details option (#7879).

• A new variable, fish_killring, containing entries from the killring,
is now available (#7445).

• fish --private prints a note on private mode on startup even if
$fish_greeting is an empty list (#7974).

• fish no longer attempts to lock history or universal variable files
on remote filesystems, including NFS and Samba mounts. In rare cases,
updates to these files may be dropped if separate fish instances mod-
ify them simultaneously. (#7968).

• wait and on-process-exit work correctly with jobs that have already
exited (#7210).

• __fish_print_help (used for --help output for fish's builtins) now
respects the LESS environment variable, and if not set, uses better
default pager settings (#7997).

• Errors from alias are now printed to standard error, matching other
builtins and functions (#7925).

• ls output is colorized on OpenBSD if colorls utility is installed (-
#8035)

• The default pager color looks better in terminals with light back-
grounds (#3412).

• Further robustness improvements to the bash history import (#7874).

• fish now tries to find a Unicode-aware locale for encoding (LC_CTYPE)
if started without any locale information, improving the display of
emoji and other non-ASCII text on misconfigured systems (#8031). To
allow a C locale, set the variable fish_allow_singlebyte_locale to 1.

• The Web-based configuration and documentation now feature a dark mode
if the browser requests it (#8043).

• Color variables can now also be given like --background red and -b
red, not just --background=red (#8053).

• exit run within fish_prompt now exits properly (#8033).

• When attempting to execute the unsupported POSIX-style brace command
group ({ ... }) fish will suggest its equivalent begin; ...; end com-
mands (#6415).

New or improved bindings
• Pasting in Vi mode puts text in the right place in normal mode (-
#7847).

• Vi mode's u is bound to undo instead of history-search-backward, fol-
lowing GNU readline's behavior. Similarly, Control-R is bound to redo
instead of history-search-backward, following Vim (#7908).

• s in Vi visual mode now does the same thing as c (#8039).

• The binding for "*y now uses fish_clipboard_copy, allowing it to sup-
port more than just xsel.

• The Control-Space binding can be correctly customised (#7922).

• exit works correctly in bindings (#7967).

• The F1 binding, which opens the manual page for the current command,
now works around a bug in certain less versions that fail to clear
the screen (#7863).

• The binding for Alt-S now toggles whether sudo is prepended, even
when it took the commandline from history instead of only adding it.

• The new functions fish_commandline_prepend and fish_commandline_ap-
pend allow toggling the presence of a prefix/suffix on the current
commandline. (#7905).

• backward-kill-path-component Control-W) no longer erases parts of two
tokens when the cursor is positioned immediately after /. (#6258).

Improved prompts
• The default Vi mode prompt now uses foreground instead of background
colors, making it less obtrusive (#7880).

• Performance of the "informative" git prompt is improved somewhat (-
#7871). This is still slower than the non-informative version by its
very nature. In particular it is IO-bound, so it will be very slow on
slow disks or network mounts.

• The sample prompts were updated. Some duplicated prompts, like the
various classic variants, or less useful ones, like the "justadollar"
prompt were removed, some prompts were cleaned up, and in some cases
renamed. A new "simple" and "disco" prompt were added (#7884, #7897,
#7930). The new prompts will only take effect when selected and ex-
isting installed prompts will remain unchanged.

• A new prompt_login helper function to describe the kind of "login"
(user, host and chroot status) for use in prompts. This replaces the
old "debian chroot" prompt and has been added to the default and ter-
lar prompts (#7932).

• The Web-based configuration's prompt picker now shows and installs
right prompts (#7930).

• The git prompt now has the same symbol order in normal and "informa-
tive" mode, and it's customizable via $__fish_git_prompt_status_order
(#7926).

Completions
• Added completions for:

• firewall-cmd (#7900)

• sv (#8069)

• Improvements to plenty of completions!

• Commands that wrap cd (using complete --wraps cd) get the same com-
pletions as cd (#4693).

• The --force-files option to complete works for bare arguments, not
just options (#7920).

• Completion descriptions for functions don't include the function def-
inition, making them more concise (#7911).

• The kill completions no longer error on MSYS2 (#8046).

• Completion scripts are now loaded when calling a command via a rela-
tive path (like ./git) (#6001, #7992).

• When there are multiple completion candidates, fish inserts their
shared prefix. This prefix was computed in a case-insensitive way,
resulting in wrong case in the completion pager. This was fixed by
only inserting prefixes with matching case (#7744).

Improved terminal support
• fish no longer tries to detect a missing new line during startup,
preventing an erroneous from appearing if the terminal is resized at
the wrong time, which can happen in tiling window managers (#7893).

• fish behaves better when it disagrees with the terminal on the width
of characters. In particular, staircase effects with right prompts
should be gone in most cases (#8011).

• If the prompt takes up the entire line, the last character should no
longer be chopped off in certain terminals (#8002).

• fish's reflow handling has been disabled by default for kitty (-
#7961).

• The default prompt no longer produces errors when used with a dumb
terminal (#7904).

• Terminal size variables are updated for window size change signal
handlers (SIGWINCH).

• Pasting within a multi-line command using a terminal that supports
bracketed paste works correctly, instead of producing an error (-
#7782).

• set_color produces an error when used with invalid arguments, rather
than empty output which interacts badly with Cartesian product expan-
sion.

For distributors
• fish runs correctly on platforms without the O_CLOEXEC flag for
open(2) (#8023).

----

fish 3.2.2 (released April 7, 2021)
This release of fish fixes a number of additional issues identified in
the fish 3.2 series:

• The command-not-found handler used suggestions from pacman on Arch
Linux, but this caused major slowdowns on some systems and has been
disabled (#7841).

• fish will no longer hang on exit if another process is in the fore-
ground on macOS (#7901).

• Certain programs (such as lazygit) could create situations where fish
would not receive keystrokes correctly, but it is now more robust in
these situations (#7853).

• Arguments longer than 1024 characters no longer trigger excessive CPU
usage on macOS (#7837).

• fish builds correctly on macOS when using new versions of Xcode (-
#7838).

• Completions for aura (#7865) and tshark (#7858) should no longer pro-
duce errors.

• Background jobs no longer interfere with syntax highlighting (a re-
gression introduced in fish 3.2.1, #7842).

If you are upgrading from version 3.1.2 or before, please also review
the release notes for 3.2.1 and 3.2.0 (included below).

----

fish 3.2.1 (released March 18, 2021)
This release of fish fixes the following problems identified in fish
3.2.0:

• Commands in key bindings are run with fish's internal terminal modes,
instead of the terminal modes typically used for commands. This fixes
a bug introduced in 3.2.0, where text would unexpectedly appear on
the terminal, especially when pasting (#7770).

• Prompts which use the internal __fish_print_pipestatus function will
display correctly rather than carrying certain modifiers (such as
bold) further than intended (#7771).

• Redirections to internal file descriptors is allowed again, reversing
the changes in 3.2.0. This fixes a problem with Midnight Commander (-
#7769).

• Universal variables should be fully reliable regardless of operating
system again (#7774).

• fish_git_prompt no longer causes screen flickering in certain termi-
nals (#7775).

• fish_add_path manipulates the fish_user_paths variable correctly when
moving multiple paths (#7776).

• Pasting with a multi-line command no longer causes a __fish_tok-
enizer_state error (#7782).

• psub inside event handlers cleans up temporary files properly (-
#7792).

• Event handlers declared with --on-job-exit $fish_pid no longer run
constantly (#7721), although these functions should use --on-event
fish_exit instead.

• Changing terminal modes inside config.fish works (#7783).

• set_color --print-colors no longer prints all colors in bold (#7805)

• Completing commands starting with a - no longer prints an error (-
#7809).

• Running fish_command_not_found directly no longer produces an error
on macOS or other OSes which do not have a handler available (#7777).

• The new type builtin now has the (deprecated) --quiet long form of -q
(#7766).

It also includes some small enhancements:

• help and fish_config work correctly when fish is running in a Chrome
OS Crostini Linux VM (#7789).

• The history file can be made a symbolic link without it being over-
written (#7754), matching a similar improvement for the universal
variable file in 3.2.0.

• An unhelpful error ("access: No error"), seen on Cygwin, is no longer
produced (#7785).

• Improvements to the rsync completions (#7763), some completion de-
scriptions (#7788), and completions that use IP address (#7787).

• Improvements to the appearance of fish_config (#7811).

If you are upgrading from version 3.1.2 or before, please also review
the release notes for 3.2.0 (included below).

----

fish 3.2.0 (released March 1, 2021)
Notable improvements and fixes
• Undo and redo support for the command-line editor and pager search (-
#1367). By default, undo is bound to Control+Z, and redo to Alt+/.

• Builtins can now output before all data is read. For example, string
replace no longer has to read all of stdin before it can begin to
output. This makes it usable also for pipes where the previous com-
mand hasn't finished yet, like:

# Show all dmesg lines related to "usb"
dmesg -w | string match '*usb*'

• Prompts will now be truncated instead of replaced with "> " if they
are wider than the terminal (#904). For example:

~/dev/build/fish-shell-git/src/fish-shell/build (makepkg)>

will turn into:

h-shell/build (makepkg)>

It is still possible to react to the COLUMNS variable inside the
prompt to implement smarter behavior.

• fish completes ambiguous completions after pressing Tab even when
they have a common prefix, without the user having to press Tab again
(#6924).

• fish is less aggressive about resetting terminal modes, such as flow
control, after every command. Although flow control remains off by
default, enterprising users can now enable it with stty (#2315,
#7704).

• A new "fish_add_path" helper function to add paths to $PATH without
producing duplicates, to be used interactively or in config.fish (-
#6960, #7028). For example:

fish_add_path /opt/mycoolthing/bin

will add /opt/mycoolthing/bin to the beginning of $fish_user_path
without creating duplicates, so it can be called safely from con-
fig.fish or interactively, and the path will just be there, once.

• Better errors with "test" (#6030):

> test 1 = 2 and echo true or false
test: Expected a combining operator like '-a' at index 4
1 = 2 and echo true or echo false
^

This includes numbering the index from 1 instead of 0, like fish
lists.

• A new theme for the documentation and Web-based configuration (#6500,
#7371, #7523), matching the design on fishshell.com.

• fish --no-execute will no longer complain about unknown commands or
non-matching wildcards, as these could be defined differently at run-
time (especially for functions). This makes it usable as a static
syntax checker (#977).

• string match --regex now integrates named PCRE2 capture groups as
fish variables, allowing variables to be set directly from string
match (#7459). To support this functionality, string is now a re-
served word and can no longer be wrapped in a function.

• Globs and other expansions are limited to 512,288 results (#7226).
Because operating systems limit the number of arguments to commands,
larger values are unlikely to work anyway, and this helps to avoid
hangs.

• A new "fish for bash users" documentation page gives a quick overview
of the scripting differences between bash and fish (#2382), and the
completion tutorial has also been moved out into its own document (-
#6709).

Syntax changes and new commands
• Range limits in index range expansions like $x[$start..$end] may be
omitted: $start and $end default to 1 and -1 (the last item) respec-
tively (#6574):

echo $var[1..]
echo $var[..-1]
echo $var[..]

All print the full list $var.

• When globbing, a segment which is exactly ** may now match zero di-
rectories. For example **/foo may match foo in the current directory
(#7222).

Scripting improvements
• The type, _ (gettext), . (source) and : (no-op) functions are now im-
plemented builtins for performance purposes (#7342, #7036, #6854).

• set and backgrounded jobs no longer overwrite $pipestatus (#6820),
improving its use in command substitutions (#6998).

• Computed ("electric") variables such as status are now only global in
scope, so set -Uq status returns false (#7032).

• The output for set --show has been shortened, only mentioning the
scopes in which a variable exists (#6944). In addition, it now shows
if a variable is a path variable.

• A new variable, fish_kill_signal, is set to the signal that termi-
nated the last foreground job, or 0 if the job exited normally (-
#6824, #6822).

• A new subcommand, string pad, allows extending strings to a given
width (#7340, #7102).

• string sub has a new --end option to specify the end index of a sub-
string (#6765, #5974).

• string split has a new --fields option to specify fields to output,
similar to cut -f (#6770).

• string trim now also trims vertical tabs by default (#6795).

• string replace no longer prints an error if a capturing group wasn't
matched, instead treating it as empty (#7343).

• string subcommands now quit early when used with --quiet (#7495).

• string repeat now handles multiple arguments, repeating each one (-
#5988).

• printf no longer prints an error if not given an argument (not even a
format string).

• The true and false builtins ignore any arguments, like other shells
(#7030).

• fish_indent now removes unnecessary quotes in simple cases (#6722)
and gained a --check option to just check if a file is indented cor-
rectly (#7251).

• fish_indent indents continuation lines that follow a line ending in a
backslash, |, && or ||.

• pushd only adds a directory to the stack if changing to it was suc-
cessful (#6947).

• A new fish_job_summary function is called whenever a background job
stops or ends, or any job terminates from a signal (#6959, #2727,
#4319). The default behaviour can now be customized by redefining
it.

• status gained new dirname and basename convenience subcommands to get
just the directory to the running script or the name of it, to sim-
plify common tasks such as running (dirname (status filename)) (-
#7076, #1818).

• Broken pipelines are now handled more smoothly; in particular, bad
redirection mid-pipeline results in the job continuing to run but
with the broken file descriptor replaced with a closed file descrip-
tor. This allows better error recovery and is more in line with other
shells' behaviour (#7038).

• jobs --quiet PID no longer prints "no suitable job" if the job for
PID does not exist (eg because it has finished) (#6809, #6812).

• jobs now shows continued child processes correctly (#6818)

• disown should no longer create zombie processes when job control is
off, such as in config.fish (#7183).

• command, jobs and type builtins support --query as the long form of
-q, matching other builtins. The long form --quiet is deprecated (-
#7276).

• argparse no longer requires a short flag letter for long-only options
(#7585) and only prints a backtrace with invalid options to argparse
itself (#6703).

• argparse now passes the validation variables (e.g. $_flag_value) as
local-exported variables, avoiding the need for --no-scope-shadowing
in validation functions.

• complete takes the first argument as the name of the command if the
--command/-c option is not used, so complete git is treated like com-
plete --command git, and it can show the loaded completions for spe-
cific commands with complete COMMANDNAME (#7321).

• set_color -b (without an argument) no longer prints an error message,
matching other invalid invocations of this command (#7154).

• exec no longer produces a syntax error when the command cannot be
found (#6098).

• set --erase and abbr --erase can now erase multiple things in one go,
matching functions --erase (#7377).

• abbr --erase no longer prints errors when used with no arguments or
on an unset abbreviation (#7376, #7732).

• test -t, for testing whether file descriptors are connected to a ter-
minal, works for file descriptors 0, 1, and 2 (#4766). It can still
return incorrect results in other cases (#1228).

• Trying to execute scripts with Windows line endings (CRLF) produces a
sensible error (#2783).

• Trying to execute commands with arguments that exceed the operating
system limit now produces a specific error (#6800).

• An alias that delegates to a command with the same name no longer
triggers an error about recursive completion (#7389).

• math now has a --base option to output the result in hexadecimal or
octal (#7496) and produces more specific error messages (#7508).

• math learned bitwise functions bitand, bitor and bitxor, used like
math "bitand(0xFE, 5)" (#7281).

• math learned tau for those who don't like typing "2 * pi".

• Failed redirections will now set $status (#7540).

• fish sets exit status in a more consistent manner after errors, in-
cluding invalid expansions like $foo[.

• Using read --silent while fish is in private mode was adding these
potentially-sensitive entries to the history; this has been fixed (-
#7230).

• read can now read interactively from other files, and can be used to
read from the terminal via read </dev/tty (if the operating system
provides /dev/tty) (#7358).

• A new fish_status_to_signal function for transforming exit statuses
to signal names has been added (#7597, #7595).

• The fallback realpath builtin supports the -s/--no-symlinks option,
like GNU realpath (#7574).

• functions and type now explain when a function was defined via source
instead of just saying Defined in -.

• Significant performance improvements when globbing, appending to
variables or in math.

• echo no longer interprets options at the beginning of an argument (eg
echo "-n foo") (#7614).

• fish now finds user configuration even if the HOME environment vari-
able is not set (#7620).

• fish no longer crashes when started from a Windows-style working di-
rectory (eg F:\path) (#7636).

• fish -c now reads the remaining arguments into $argv (#2314).

• The pwd command supports the long options --logical and --physical,
matching other implementations (#6787).

• fish --profile now only starts profiling after fish is ready to exe-
cute commands (all configuration is completed). There is a new --pro-
file-startup option that only profiles the startup and configuration
process (#7648).

• Builtins return a maximum exit status of 255, rather than potentially
overflowing. In particular, this affects exit, return, functions
--query, and set --query (#7698, #7702).

• It is no longer an error to run builtin with closed stdin. For exam-
ple count <&- now prints 0, instead of failing.

• Blocks, functions, and builtins no longer permit redirecting to file
descriptors other than 0 (standard input), 1 (standard output) and 2
(standard error). For example, echo hello >&5 is now an error. This
prevents corruption of internal state (#3303).

Interactive improvements
• fish will now always attempt to become process group leader in inter-
active mode (#7060). This helps avoid hangs in certain circumstances,
and allows tmux's current directory introspection to work (#5699).

• The interactive reader now allows ending a line in a logical opera-
tors (&& and ||) instead of complaining about a missing command.
(This was already syntactically valid, but interactive sessions
didn't know about it yet).

• The prompt is reprinted after a background job exits (#1018).

• fish no longer inserts a space after a completion ending in ., , or -
is accepted, improving completions for tools that provide dynamic
completions (#6928).

• If a filename is invalid when first pressing Tab, but becomes valid,
it will be completed properly on the next attempt (#6863).

• help string match/replace/<subcommand> will show the help for string
subcommands (#6786).

• fish_key_reader sets the exit status to 0 when used with --help or
--version (#6964).

• fish_key_reader and fish_indent send output from --version to stan-
dard output, matching other fish binaries (#6964).

• A new variable $status_generation is incremented only when the previ-
ous command produces an exit status (#6815). This can be used, for
example, to check whether a failure status is a holdover due to a
background job, or actually produced by the last run command.

• fish_greeting is now a function that reads a variable of the same
name, and defaults to setting it globally. This removes a universal
variable by default and helps with updating the greeting. However,
to disable the greeting it is now necessary to explicitly specify
universal scope (set -U fish_greeting) or to disable it in con-
fig.fish (#7265).

• Events are properly emitted after a job is cancelled (#2356).

• fish_preexec and fish_postexec events are no longer triggered for
empty commands (#4829, #7085).

• Functions triggered by the fish_exit event are correctly run when the
terminal is closed or the shell receives SIGHUP (#7014).

• The fish_prompt event no longer fires when read is used. If you need
a function to run any time read is invoked by a script, use the new
fish_read event instead (#7039).

• A new fish_posterror event is emitted when attempting to execute a
command with syntax errors (#6880, #6816).

• The debugging system has now fully switched from the old numbered
level to the new named category system introduced in 3.1. A number of
new debugging categories have been added, including config, path,
reader and screen (#6511). See the output of fish --print-debug-cate-
gories for the full list.

• The warning about read-only filesystems has been moved to a new
"warning-path" debug category and can be disabled by setting a debug
category of -warning-path (#6630):

fish --debug=-warning-path

• The enabled debug categories are now printed on shell startup (-
#7007).

• The -o short option to fish, for --debug-output, works correctly in-
stead of producing an invalid option error (#7254).

• fish's debugging can now also be enabled via FISH_DEBUG and FISH_DE-
BUG_OUTPUT environment variables. This helps with debugging when no
commandline options can be passed, like when fish is called in a she-
bang (#7359).

• Abbreviations are now expanded after all command terminators (eg ; or
|), not just space, as in fish 2.7.1 and before (#6970), and after
closing a command substitution (#6658).

• The history file is now created with user-private permissions, match-
ing other shells (#6926). The directory containing the history file
was already private, so there should not have been any private data
revealed.

• The output of time is now properly aligned in all cases (#6726,
#6714) and no longer depends on locale (#6757).

• The command-not-found handling has been simplified. When it can't
find a command, fish now just executes a function called fish_com-
mand_not_found instead of firing an event, making it easier to re-
place and reason about. Previously-defined __fish_com-
mand_not_found_handler functions with an appropriate event listener
will still work (#7293).

• Control-C handling has been reimplemented in C++ and is therefore
quicker (#5259), no longer occasionally prints an "unknown command"
error (#7145) or overwrites multiline prompts (#3537).

• Control-C no longer kills background jobs for which job control is
disabled, matching POSIX semantics (#6828, #6861).

• Autosuggestions work properly after Control-C cancels the current
commmand line (#6937).

• History search is now case-insensitive unless the search string con-
tains an uppercase character (#7273).

• fish_update_completions gained a new --keep option, which improves
speed by skipping completions that already exist (#6775, #6796).

• Aliases containing an embedded backslash appear properly in the out-
put of alias (#6910).

• open no longer hangs indefinitely on certain systems, as a bug in
xdg-open has been worked around (#7215).

• Long command lines no longer add a blank line after execution (#6826)
and behave better with Backspace (#6951).

• functions -t works like the long option --handlers-type, as docu-
mented, instead of producing an error (#6985).

• History search now flashes when it found no more results (#7362)

• fish now creates the path in the environment variable XDG_RUNTIME_DIR
if it does not exist, before using it for runtime data storage (-
#7335).

• set_color --print-colors now also respects the bold, dim, underline,
reverse, italic and background modifiers, to better show their effect
(#7314).

• The fish Web configuration tool (fish_config) shows prompts correctly
on Termux for Android (#7298) and detects Windows Services for Linux
2 properly (#7027). It no longer shows the history variable as it may
be too large (one can use the History tab instead). It also starts
the browser in another thread, avoiding hangs in some circumstances,
especially with Firefox's Developer Edition (#7158). Finally, a bug
in the Source Code Pro font may cause browsers to hang, so this font
is no longer chosen by default (#7714).

• funcsave gained a new --directory option to specify the location of
the saved function (#7041).

• help works properly on MSYS2 (#7113) and only uses cmd.exe if running
on WSL (#6797).

• Resuming a piped job by its number, like fg %1, works correctly (-
#7406). Resumed jobs show the correct title in the terminal emulator
(#7444).

• Commands run from key bindings now use the same TTY modes as normal
commands (#7483).

• Autosuggestions from history are now case-sensitive (#3978).

• $status from completion scripts is no longer passed outside the com-
pletion, which keeps the status display in the prompt as the last
command's status (#7555).

• Updated localisations for pt_BR (#7480).

• fish_trace output now starts with -> (like fish --profile), making
the depth more visible (#7538).

• Resizing the terminal window no longer produces a corrupted prompt (-
#6532, #7404).

• functions produces an error rather than crashing on certain invalid
arguments (#7515).

• A crash in completions with inline variable assignment (eg A= b) has
been fixed (#7344).

• fish_private_mode may now be changed dynamically using set (#7589),
and history is kept in memory in private mode (but not stored perma-
nently) (#7590).

• Commands with leading spaces may be retrieved from history with
up-arrow until a new command is run, matching zsh's HIST_IGNORE_SPACE
(#1383).

• Importing bash history or reporting errors with recursive globs (**)
no longer hangs (#7407, #7497).

• bind now shows \x7f for the del key instead of a literal DEL charac-
ter (#7631)

• Paths containing variables or tilde expansion are only suggested when
they are still valid (#7582).

• Syntax highlighting can now color a command as invalid even if exe-
cuted quickly (#5912).

• Redirection targets are no longer highlighted as error if they con-
tain variables which will likely be defined by the current command-
line (#6654).

• fish is now more resilient against broken terminal modes (#7133,
#4873).

• fish handles being in control of the TTY without owning its own
process group better, avoiding some hangs in special configurations
(#7388).

• Keywords can now be colored differently by setting the
fish_color_keyword variable (fish_color_command is used as a fall-
back) (#7678).

• Just like fish_indent, the interactive reader will indent continua-
tion lines that follow a line ending in a backslash, |, && or || (-
#7694).

• Commands with a trailing escaped space are saved in history correctly
(#7661).

• fish_prompt no longer mangles Unicode characters in the private-use
range U+F600-U+F700. (#7723).

• The universal variable file, fish_variables, can be made a symbolic
link without it being overwritten (#7466).

• fish is now more resilient against mktemp failing (#7482).

New or improved bindings
• As mentioned above, new special input functions undo (Control+_ or
Control+Z) and redo (Alt-/) can be used to revert changes to the com-
mand line or the pager search field (#6570).

• Control-Z is now available for binding (#7152).

• Additionally, using the cancel special input function (bound to Es-
cape by default) right after fish picked an unambiguous completion
will undo that (#7433).

• fish_clipboard_paste (Control+V) trims indentation from multiline
commands, because fish already indents (#7662).

• Vi mode bindings now support dh, dl, c0, cf, ct, cF, cT, ch, cl, y0,
ci, ca, yi, ya, di, da, d;, d,, o, O and Control+left/right keys to
navigate by word (#6648, #6755, #6769, #7442, #7516).

• Vi mode bindings support ~ (tilde) to toggle the case of the selected
character (#6908).

• Functions up-or-search and down-or-search (Up and Down) can cross
empty lines, and don't activate search mode if the search fails,
which makes them easier to use to move between lines in some situa-
tions.

• If history search fails to find a match, the cursor is no longer
moved. This is useful when accidentally starting a history search on
a multi-line commandline.

• The special input function beginning-of-history (Page Up) now moves
to the oldest search instead of the youngest - that's end-of-history
(Page Down).

• A new special input function forward-single-char moves one character
to the right, and if an autosuggestion is available, only take a sin-
gle character from it (#7217, #4984).

• Special input functions can now be joined with or as a modifier
(adding to and), though only some commands set an exit status (-
#7217). This includes suppress-autosuggestion to reflect whether an
autosuggestion was suppressed (#1419)

• A new function __fish_preview_current_file, bound to Alt+O, opens the
current file at the cursor in a pager (#6838, #6855).

• edit_command_buffer (Alt-E and Alt-V) passes the cursor position to
the external editor if the editor is recognized (#6138, #6954).

• __fish_prepend_sudo (Alt-S) now toggles a sudo prefix (#7012) and
avoids shifting the cursor (#6542).

• __fish_prepend_sudo (Alt-S) now uses the previous commandline if the
current one is empty, to simplify rerunning the previous command with
sudo (#7079).

• __fish_toggle_comment_commandline (Alt-#) now uncomments and presents
the last comment from history if the commandline is empty (#7137).

• __fish_whatis_current_token (Alt-W) prints descriptions for functions
and builtins (#7191, #2083).

• The definition of "word" and "bigword" for movements was refined,
fixing (eg) vi mode's behavior with e on the second-to-last char, and
bigword's behavior with single-character words and non-blank
non-graphical characters (#7353, #7354, #4025, #7328, #7325)

• fish's clipboard bindings now also support Windows Subsystem for
Linux via PowerShell and clip.exe (#7455, #7458) and will properly
copy newlines in multi-line commands.

• Using the *-jump special input functions before typing anything else
no longer crashes fish.

• Completing variable overrides (foo=bar) could replace the entire
thing with just the completion in some circumstances. This has been
fixed (#7398).

Improved prompts
• The default and example prompts print the correct exit status for
commands prefixed with not (#6566).

• git prompts include all untracked files in the repository, not just
those in the current directory (#6086).

• The git prompts correctly show stash states (#6876, #7136) and clean
states (#7471).

• The Mercurial prompt correctly shows untracked status (#6906), and by
default only shows the branch for performance reasons. A new vari-
able $fish_prompt_hg_show_informative_status can be set to enable
more information.

• The fish_vcs_prompt passes its arguments to the various VCS prompts
that it calls (#7033).

• The Subversion prompt was broken in a number of ways in 3.1.0 and has
been restored (#6715, #7278).

• A new helper function fish_is_root_user simplifies checking for supe-
ruser privilege (#7031, #7123).

• New colorschemes - ayu Light, ayu Dark and ayu Mirage (#7596).

• Bugs related to multiline prompts, including repainting (#5860) or
navigating directory history (#3550) leading to graphical glitches
have been fixed.

• The nim prompt now handles vi mode better (#6802)

Improved terminal support
• A new variable, fish_vi_force_cursor, can be set to force
fish_vi_cursor to attempt changing the cursor shape in vi mode, re-
gardless of terminal (#6968). The fish_vi_cursor option --force-iterm
has been deprecated.

• diff will now colourize output, if supported (#7308).

• Autosuggestions appear when the cursor passes the right prompt (-
#6948) or wraps to the next line (#7213).

• The cursor shape in Vi mode changes properly in Windows Terminal (-
#6999, #6478).

• The spurious warning about terminal size in small terminals has been
removed (#6980).

• Dynamic titles are now enabled in Alacritty (#7073) and emacs' vterm
(#7122).

• Current working directory updates are enabled in foot (#7099) and
WezTerm (#7649).

• The width computation for certain emoji agrees better with terminals
(especially flags). (#7237).

• Long command lines are wrapped in all cases, instead of sometimes be-
ing put on a new line (#5118).

• The pager is properly rendered with long command lines selected (-
#2557).

• Sessions with right prompts can be resized correctly in terminals
that handle reflow, like GNOME Terminal (and other VTE-based termi-
nals), upcoming Konsole releases and Alacritty. This detection can be
overridden with the new fish_handle_reflow variable (#7491).

• fish now sets terminal modes sooner, which stops output from appear-
ing before the greeting and prompt are ready (#7489).

• Better detection of new Konsole versions for true color support and
cursor shape changing.

• fish no longer attempts to modify the terminal size via TIOCSWINSZ,
improving compatibility with Kitty (#6994).

Completions
• Added completions for

• 7z, 7za and 7zr (#7220)

• alias (#7035)

• alternatives (#7616)

• apk (#7108)

• asciidoctor (#7000)

• avifdec and avifenc (#7674)

• bluetoothctl (#7438)

• cjxl and djxl (#7673)

• cmark (#7000)

• create_ap (#7096)

• deno (#7138)

• dhclient (#6684)

• Postgres-related commands dropdb, createdb, pg_restore, pg_dump and
pg_dumpall (#6620)

• dotnet (#7558)

• downgrade (#6751)

• gapplication, gdbus, gio and gresource (#7300)

• gh (#7112)

• gitk

• groups (#6889)

• hashcat (#7746)

• hikari (#7083)

• icdiff (#7503)

• imv (#6675)

• john (#7746)

• julia (#7468)

• k3d (#7202)

• ldapsearch (#7578)

• lightdm and dm-tool (#7624)

• losetup (#7621)

• micro (#7339)

• mpc (#7169)

• Metasploit's msfconsole, msfdb and msfvenom (#6930)

• mtr (#7638)

• mysql (#6819)

• ncat, nc.openbsd, nc.traditional and nmap (#6873)

• openssl (#6845)

• prime-run (#7241)

• ps2pdf{12,13,14,wr} (#6673)

• pyenv (#6551)

• rst2html, rst2html4, rst2html5, rst2latex, rst2man, rst2odt,
rst2pseudoxml, rst2s5, rst2xetex, rst2xml and rstpep2html (#7019)

• spago (#7381)

• sphinx-apidoc, sphinx-autogen, sphinx-build and sphinx-quickstart
(#7000)

• strace (#6656)

• systemd's bootctl, coredumpctl, hostnamectl (#7428), homectl (-
#7435), networkctl (#7668) and userdbctl (#7667)

• tcpdump (#6690)

• tig

• traceroute and tracepath (#6803)

• windscribe (#6788)

• wireshark, tshark, and dumpcap

• xbps-* (#7239)

• xxhsum, xxh32sum, xxh64sum and xxh128sum (#7103)

• yadm (#7100)

• zopfli and zopflipng (#6872)

• Lots of improvements to completions, including:

• git completions can complete the right and left parts of a commit
range like from..to or left...right.

• Completion scripts for custom Git subcommands like git-xyz are now
loaded with Git completions. The completions can now be defined di-
rectly on the subcommand (using complete git-xyz), and completion
for git xyz will work. (#7075, #7652, #4358)

• make completions no longer second-guess make's file detection, fix-
ing target completion in some cases (#7535).

• Command completions now correctly print the description even if the
command was fully matched (like in ls<TAB>).

• set completions no longer hide variables starting with __, they are
sorted last instead.

• Improvements to the manual page completion generator (#7086, #6879,
#7187).

• Significant performance improvements to completion of the available
commands (#7153), especially on macOS Big Sur where there was a sig-
nificant regression (#7365, #7511).

• Suffix completion using __fish_complete_suffix uses the same fuzzy
matching logic as normal file completion, and completes any file but
sorts files with matching suffix first (#7040, #7547). Previously, it
only completed files with matching suffix.

For distributors
• fish has a new interactive test driver based on pexpect, removing the
optional dependency on expect (and adding an optional dependency on
pexpect) (#5451, #6825).

• The CHANGELOG was moved to restructured text, allowing it to be in-
cluded in the documentation (#7057).

• fish handles ncurses installed in a non-standard prefix better (-
#6600, #7219), and uses variadic tparm on NetBSD curses (#6626).

• The Web-based configuration tool no longer uses an obsolete Angular
version (#7147).

• The fish project has adopted the Contributor Covenant code of conduct
(#7151).

Deprecations and removed features
• The fish_color_match variable is no longer used. (Previously this
controlled the color of matching quotes and parens when using read).

• fish 3.2.0 will be the last release in which the redirection to stan-
dard error with the ^ character is enabled. The stderr-nocaret fea-
ture flag will be changed to "on" in future releases.

• string is now a reserved word and cannot be used for function names
(see above).

• fish_vi_cursor's option --force-iterm has been deprecated (see
above).

• command, jobs and type long-form option --quiet is deprecated in fa-
vor of --query (see above).

• The fish_command_not_found event is no longer emitted, instead there
is a function of that name. By default it will call a previously-de-
fined __fish_command_not_found_handler. To emit the event manually
use emit fish_command_not_found.

• The fish_prompt event no longer fires when read is used. If you need
a function to run any time read is invoked by a script, use the new
fish_read event instead (#7039).

• To disable the greeting message permanently it is no longer enough to
just run set fish_greeting interactively as it is no longer implic-
itly a universal variable. Use set -U fish_greeting or disable it in
config.fish with set -g fish_greeting.

• The long-deprecated and non-functional -m/--read-mode options to read
were removed in 3.1b1. Using the short form, or a never-implemented
-B option, no longer crashes fish (#7659).

• With the addition of new categories for debug options, the old num-
bered debugging levels have been removed.

For distributors and developers
• fish source tarballs are now distributed using the XZ compression
method (#5460).

• The fish source tarball contains an example FreeDesktop entry and
icon.

• The CMake variable MAC_CODESIGN_ID can now be set to "off" to disable
code-signing (#6952, #6792).

• Building on on macOS earlier than 10.13.6 succeeds, instead of fail-
ing on code-signing (#6791).

• The pkg-config file now uses variables to ensure paths used are
portable across prefixes.

• The default values for the extra_completionsdir, extra_functionsdir
and extra_confdir options now use the installation prefix rather than
/usr/local (#6778).

• A new CMake variable FISH_USE_SYSTEM_PCRE2 controls whether fish
builds with the system-installed PCRE2, or the version it bundles. By
default it prefers the system library if available, unless Mac code-
signing is enabled (#6952).

• Running the full interactive test suite now requires Python 3.5+ and
the pexpect package (#6825); the expect package is no longer re-
quired.

• Support for Python 2 in fish's tools (fish_config and the manual page
completion generator) is no longer guaranteed. Please use Python 3.5
or later (#6537).

• The Web-based configuration tool is compatible with Python 3.10 (-
#7600) and no longer requires Python's distutils package (#7514).

• fish 3.2 is the last release to support Red Hat Enterprise Linux &
CentOS version 6.

----

fish 3.1.2 (released April 29, 2020)
This release of fish fixes a major issue discovered in fish 3.1.1:

• Commands such as fzf and enhancd, when used with eval, would hang.
eval buffered output too aggressively, which has been fixed (#6955).

If you are upgrading from version 3.0.0 or before, please also review
the release notes for 3.1.1, 3.1.0 and 3.1b1 (included below).

----

fish 3.1.1 (released April 27, 2020)
This release of fish fixes a number of major issues discovered in fish
3.1.0.

• Commands which involve . ( ... | psub) now work correctly, as a bug
in the function --on-job-exit option has been fixed (#6613).

• Conflicts between upstream packages for ripgrep and bat, and the fish
packages, have been resolved (#5822).

• Starting fish in a directory without read access, such as via su, no
longer crashes (#6597).

• Glob ordering changes which were introduced in 3.1.0 have been re-
verted, returning the order of globs to the previous state (#6593).

• Redirections using the deprecated caret syntax to a file descriptor
(eg ^&2) work correctly (#6591).

• Redirections that append to a file descriptor (eg 2>>&1) work cor-
rectly (#6614).

• Building fish on macOS (#6602) or with new versions of GCC (#6604,
#6609) is now successful.

• time is now correctly listed in the output of builtin -n, and time
--help works correctly (#6598).

• Exported universal variables now update properly (#6612).

• status current-command gives the expected output when used with an
environment override - that is, F=B status current-command returns
status instead of F=B (#6635).

• test no longer crashes when used with nan or inf arguments, erroring
out instead (#6655).

• Copying from the end of the command line no longer crashes fish (-
#6680).

• read no longer removes multiple separators when splitting a variable
into a list, restoring the previous behaviour from fish 3.0 and be-
fore (#6650).

• Functions using --on-job-exit and --on-process-exit work reliably
again (#6679).

• Functions using --on-signal INT work reliably in interactive ses-
sions, as they did in fish 2.7 and before (#6649). These handlers
have never worked in non-interactive sessions, and making them work
is an ongoing process.

• Functions using --on-variable work reliably with variables which are
set implicitly (rather than with set), such as fish_bind_mode and PWD
(#6653).

• 256 colors are properly enabled under certain conditions that were
incorrectly detected in fish 3.1.0 ($TERM begins with xterm, does not
include 256color, and $TERM_PROGRAM is not set) (#6701).

• The Mercurial (hg) prompt no longer produces an error when the cur-
rent working directory is removed (#6699). Also, for performance rea-
sons it shows only basic information by default; to restore the de-
tailed status, set $fish_prompt_hg_show_informative_status.

• The VCS prompt, fish_vcs_prompt, no longer displays Subversion (svn)
status by default, due to the potential slowness of this operation (-
#6681).

• Pasting of commands has been sped up (#6713).

• Using extended Unicode characters, such as emoji, in a non-Unicode
capable locale (such as the C or POSIX locale) no longer renders all
output blank (#6736).

• help prefers to use xdg-open, avoiding the use of open on Debian sys-
tems where this command is actually openvt (#6739).

• Command lines starting with a space, which are not saved in history,
now do not get autosuggestions. This fixes an issue with Midnight
Commander integration (#6763), but may be changed in a future ver-
sion.

• Copying to the clipboard no longer inserts a newline at the end of
the content, matching fish 2.7 and earlier (#6927).

• fzf in complex pipes no longer hangs. More generally, code run as
part of command substitutions or eval will no longer have separate
process groups. (#6624, #6806).

This release also includes:

• several changes to improve macOS compatibility with code signing and
notarization;

• several improvements to completions; and

• several content and formatting improvements to the documentation.

If you are upgrading from version 3.0.0 or before, please also review
the release notes for 3.1.0 and 3.1b1 (included below).

Errata for fish 3.1
A new builtin, time, was introduced in the fish 3.1 releases. This
builtin is a reserved word (like test, function, and others) because of
the way it is implemented, and functions can no longer be named time.
This was not clear in the fish 3.1b1 changelog.

----

fish 3.1.0 (released February 12, 2020)
Compared to the beta release of fish 3.1b1, fish version 3.1.0:

• Fixes a regression where spaces after a brace were removed despite
brace expansion not occurring (#6564).

• Fixes a number of problems in compiling and testing on Cygwin (#6549)
and Solaris-derived systems such as Illumos (#6553, #6554, #6555,
#6556, and #6558).

• Fixes the process for building macOS packages.

• Fixes a regression where excessive error messages are printed if Uni-
code characters are emitted in non-Unicode-capable locales (#6584).

• Contains some improvements to the documentation and a small number of
completions.

If you are upgrading from version 3.0.0 or before, please also review
the release notes for 3.1b1 (included below).

----

fish 3.1b1 (released January 26, 2020)
Notable improvements and fixes
• A new $pipestatus variable contains a list of exit statuses of the
previous job, for each of the separate commands in a pipeline (-
#5632).

• fish no longer buffers pipes to the last function in a pipeline, im-
proving many cases where pipes appeared to block or hang (#1396).

• An overhaul of error messages for builtin commands, including a re-
moval of the overwhelming usage summary, more readable stack traces
(#3404, #5434), and stack traces for test (aka [) (#5771).

• fishs debugging arguments have been significantly improved. The --de-
bug-level option has been removed, and a new --debug option replaces
it. This option accepts various categories, which may be listed via
fish --print-debug-categories (#5879). A new --debug-output option
allows for redirection of debug output.

• string has a new collect subcommand for use in command substitutions,
producing a single output instead of splitting on new lines (similar
to "$(cmd)" in other shells) (#159).

• The fish manual, tutorial and FAQ are now available in man format as
fish-doc, fish-tutorial and fish-faq respectively (#5521).

• Like other shells, cd now always looks for its argument in the cur-
rent directory as a last resort, even if the CDPATH variable does not
include it or . (#4484).

• fish now correctly handles CDPATH entries that start with .. (#6220)
or contain ./ (#5887).

• The fish_trace variable may be set to trace execution (#3427). This
performs a similar role as set -x in other shells.

• fish uses the temporary directory determined by the system, rather
than relying on /tmp (#3845).

• The fish Web configuration tool (fish_config) prints a list of com-
mands it is executing, to help understanding and debugging (#5584).

• Major performance improvements when pasting (#5866), executing lots
of commands (#5905), importing history from bash (#6295), and when
completing variables that might match $history (#6288).

Syntax changes and new commands
• A new builtin command, time, which allows timing of fish functions
and builtins as well as external commands (#117).

• Brace expansion now only takes place if the braces include a , or a
variable expansion, meaning common commands such as git reset
HEAD@{0} do not require escaping (#5869).

• New redirections &> and &| may be used to redirect or pipe stdout,
and also redirect stderr to stdout (#6192).

• switch now allows arguments that expand to nothing, like empty vari-
ables (#5677).

• The VAR=val cmd syntax can now be used to run a command in a modified
environment (#6287).

• and is no longer recognised as a command, so that nonsensical con-
structs like and and and produce a syntax error (#6089).

• maths exponent operator,^, was previously left-associative, but now
uses the more commonly-used right-associative behaviour (#6280). This
means that math '3^0.5^2' was previously calculated as(30.5)2, but is
now calculated as 3(0.52).

• In fish 3.0, the variable used with for loops inside command substi-
tutions could leak into enclosing scopes; this was an inadvertent be-
haviour change and has been reverted (#6480).

Scripting improvements
• string split0 now returns 0 if it split something (#5701).

• In the interest of consistency, builtin -q and command -q can now be
used to query if a builtin or command exists (#5631).

• math now accepts --scale=max for the maximum scale (#5579).

• builtin $var now works correctly, allowing a variable as the builtin
name (#5639).

• cd understands the -- argument to make it possible to change to di-
rectories starting with a hyphen (#6071).

• complete --do-complete now also does fuzzy matches (#5467).

• complete --do-complete can be used inside completions, allowing lim-
ited recursion (#3474).

• count now also counts lines fed on standard input (#5744).

• eval produces an exit status of 0 when given no arguments, like other
shells (#5692).

• printf prints what it can when input hasnt been fully converted to a
number, but still prints an error (#5532).

• complete -C foo now works as expected, rather than requiring complete
-Cfoo.

• complete has a new --force-files option, to re-enable file comple-
tions. This allows sudo -E and pacman -Qo to complete correctly (-
#5646).

• argparse now defaults to showing the current function name (instead
of argparse) in its errors, making --name often superfluous (#5835).

• argparse has a new --ignore-unknown option to keep unrecognized op-
tions, allowing multiple argparse passes to parse options (#5367).

• argparse correctly handles flag value validation of options that only
have short names (#5864).

• read -S (short option of --shell) is recognised correctly (#5660).

• read understands --list, which acts like --array in reading all argu-
ments into a list inside a single variable, but is better named (-
#5846).

• read has a new option, --tokenize, which splits a string into vari-
ables according to the shells tokenization rules, considering quot-
ing, escaping, and so on (#3823).

• read interacts more correctly with the deprecated $IFS variable, in
particular removing multiple separators when splitting a variable
into a list (#6406), matching other shells.

• fish_indent now handles semicolons better, including leaving them in
place for ; and and ; or instead of breaking the line (#5859).

• fish_indent --write now supports multiple file arguments, indenting
them in turn.

• The default read limit has been increased to 100MiB (#5267).

• math now also understands x for multiplication, provided it is fol-
lowed by whitespace (#5906).

• math reports the right error when incorrect syntax is used inside
parentheses (#6063), and warns when unsupported logical operations
are used (#6096).

• functions --erase now also prevents fish from autoloading a function
for the first time (#5951).

• jobs --last returns 0 to indicate success when a job is found (-
#6104).

• commandline -p and commandline -j now split on && and || in addition
to ; and & (#6214).

• A bug where string split would drop empty strings if the output was
only empty strings has been fixed (#5987).

• eval no long creates a new local variable scope, but affects vari-
ables in the scope it is called from (#4443). source still creates a
new local scope.

• abbr has a new --query option to check for the existence of an abbre-
viation.

• Local values for fish_complete_path and fish_function_path are now
ignored; only their global values are respected.

• Syntax error reports now display a marker in the correct position (-
#5812).

• Empty universal variables may now be exported (#5992).

• Exported universal variables are no longer imported into the global
scope, preventing shadowing. This makes it easier to change such
variables for all fish sessions and avoids breakage when the value is
a list of multiple elements (#5258).

• A bug where for could use invalid variable names has been fixed (-
#5800).

• A bug where local variables would not be exported to functions has
been fixed (#6153).

• The null command (:) now always exits successfully, rather than pass-
ing through the previous exit status (#6022).

• The output of functions FUNCTION matches the declaration of the func-
tion, correctly including comments or blank lines (#5285), and cor-
rectly includes any --wraps flags (#1625).

• type supports a new option, --short, which suppress function expan-
sion (#6403).

• type --path with a function argument will now output the path to the
file containing the definition of that function, if it exists.

• type --force-path with an argument that cannot be found now correctly
outputs nothing, as documented (#6411).

• The $hostname variable is no longer truncated to 32 characters (-
#5758).

• Line numbers in function backtraces are calculated correctly (#6350).

• A new fish_cancel event is emitted when the command line is can-
celled, which is useful for terminal integration (#5973).

Interactive improvements
• New Base16 color options are available through the Web-based configu-
ration (#6504).

• fish only parses /etc/paths on macOS in login shells, matching the
bash implementation (#5637) and avoiding changes to path ordering in
child shells (#5456). It now ignores blank lines like the bash imple-
mentation (#5809).

• The locale is now reloaded when the LOCPATH variable is changed (-
#5815).

• read no longer keeps a history, making it suitable for operations
that shouldnt end up there, like password entry (#5904).

• dirh outputs its stack in the correct order (#5477), and behaves as
documented when universal variables are used for its stack (#5797).

• funced and the edit-commandline-in-buffer bindings did not work in
fish 3.0 when the $EDITOR variable contained spaces; this has been
corrected (#5625).

• Builtins now pipe their help output to a pager automatically (#6227).

• set_color now colors the --print-colors output in the matching colors
if it is going to a terminal.

• fish now underlines every valid entered path instead of just the last
one (#5872).

• When syntax highlighting a string with an unclosed quote, only the
quote itself will be shown as an error, instead of the whole argu-
ment.

• Syntax highlighting works correctly with variables as commands (-
#5658) and redirections to close file descriptors (#6092).

• help works properly on Windows Subsytem for Linux (#5759, #6338).

• A bug where disown could crash the shell has been fixed (#5720).

• fish will not autosuggest files ending with ~ unless there are no
other candidates, as these are generally backup files (#985).

• Escape in the pager works correctly (#5818).

• Key bindings that call fg no longer leave the terminal in a broken
state (#2114).

• Brackets (#5831) and filenames containing $ (#6060) are completed
with appropriate escaping.

• The output of complete and functions is now colorized in interactive
terminals.

• The Web-based configuration handles aliases that include single
quotes correctly (#6120), and launches correctly under Termux (#6248)
and OpenBSD (#6522).

• function now correctly validates parameters for --argument-names as
valid variable names (#6147) and correctly parses options following
--argument-names, as in --argument-names foo --description bar (-
#6186).

• History newly imported from bash includes command lines using && or
||.

• The automatic generation of completions from manual pages is better
described in job and process listings, and no longer produces a warn-
ing when exiting fish (#6269).

• In private mode, setting $fish_greeting to an empty string before
starting the private session will prevent the warning about history
not being saved from being printed (#6299).

• In the interactive editor, a line break (Enter) inside unclosed
brackets will insert a new line, rather than executing the command
and producing an error (#6316).

• Ctrl-C always repaints the prompt (#6394).

• When run interactively from another program (such as Python), fish
will correctly start a new process group, like other shells (#5909).

• Job identifiers (for example, for background jobs) are assigned more
logically (#6053).

• A bug where history would appear truncated if an empty command was
executed was fixed (#6032).

New or improved bindings
• Pasting strips leading spaces to avoid pasted commands being omitted
from the history (#4327).

• Shift-Left and Shift-Right now default to moving backwards and for-
wards by one bigword (words separated by whitespace) (#1505).

• The default escape delay (to differentiate between the escape key and
an alt-combination) has been reduced to 30ms, down from 300ms for the
default mode and 100ms for Vi mode (#3904).

• The forward-bigword binding now interacts correctly with autosugges-
tions (#5336).

• The fish_clipboard_* functions support Wayland by using wl-clipboard
(#5450).

• The nextd and prevd functions no longer print Hit end of history, in-
stead using a bell. They correctly store working directories contain-
ing symbolic links (#6395).

• If a fish_mode_prompt function exists, Vi mode will only execute it
on mode-switch instead of the entire prompt. This should make it much
more responsive with slow prompts (#5783).

• The path-component bindings (like Ctrl-w) now also stop at : and @,
because those are used to denote user and host in commands such as
ssh (#5841).

• The NULL character can now be bound via bind -k nul. Terminals often
generate this character via control-space. (#3189).

• A new readline command expand-abbr can be used to trigger abbrevia-
tion expansion (#5762).

• A new readline command, delete-or-exit, removes a character to the
right of the cursor or exits the shell if the command line is empty
(moving this functionality out of the delete-or-exit function).

• The self-insert readline command will now insert the binding se-
quence, if not empty.

• A new binding to prepend sudo, bound to Alt-S by default (#6140).

• The Alt-W binding to describe a command should now work better with
multiline prompts (#6110)

• The Alt-H binding to open a commands man page now tries to ignore
sudo (#6122).

• A new pair of bind functions, history-prefix-search-backward (and
forward), was introduced (#6143).

• Vi mode now supports R to enter replace mode (#6342), and d0 to
delete the current line (#6292).

• In Vi mode, hitting Enter in replace-one mode no longer erases the
prompt (#6298).

• Selections in Vi mode are inclusive, matching the actual behaviour of
Vi (#5770).

Improved prompts
• The Git prompt in informative mode now shows the number of stashes if
enabled.

• The Git prompt now has an option ($__fish_git_prompt_use_informa-
tive_chars) to use the (more modern) informative characters without
enabling informative mode.

• The default prompt now also features VCS integration and will color
the host if running via SSH (#6375).

• The default and example prompts print the pipe status if an earlier
command in the pipe fails.

• The default and example prompts try to resolve exit statuses to sig-
nal names when appropriate.

Improved terminal output
• New fish_pager_color_ options have been added to control more ele-
ments of the pagers colors (#5524).

• Better detection and support for using fish from various system con-
soles, where limited colors and special characters are supported (-
#5552).

• fish now tries to guess if the system supports Unicode 9 (and dis-
plays emoji as wide), eliminating the need to set $fish_emoji_width
in most cases (#5722).

• Improvements to the display of wide characters, particularly Korean
characters and emoji (#5583, #5729).

• The Vi mode cursor is correctly redrawn when regaining focus under
terminals that report focus (eg tmux) (#4788).

• Variables that control background colors (such as
fish_pager_color_search_match) can now use --reverse.

Completions
• Added completions for

• aws

• bat (#6052)

• bosh (#5700)

• btrfs

• camcontrol

• cf (#5700)

• chronyc (#6496)

• code (#6205)

• cryptsetup (#6488)

• csc and csi (#6016)

• cwebp (#6034)

• cygpath and cygstart (#6239)

• epkginfo (#5829)

• ffmpeg, ffplay, and ffprobe (#5922)

• fsharpc and fsharpi (#6016)

• fzf (#6178)

• g++ (#6217)

• gpg1 (#6139)

• gpg2 (#6062)

• grub-mkrescue (#6182)

• hledger (#6043)

• hwinfo (#6496)

• irb (#6260)

• iw (#6232)

• kak

• keepassxc-cli (#6505)

• keybase (#6410)

• loginctl (#6501)

• lz4, lz4c and lz4cat (#6364)

• mariner (#5718)

• nethack (#6240)

• patool (#6083)

• phpunit (#6197)

• plutil (#6301)

• pzstd (#6364)

• qubes-gpg-client (#6067)

• resolvectl (#6501)

• rg

• rustup

• sfdx (#6149)

• speedtest and speedtest-cli (#5840)

• src (#6026)

• tokei (#6085)

• tsc (#6016)

• unlz4 (#6364)

• unzstd (#6364)

• vbc (#6016)

• zpaq (#6245)

• zstd, zstdcat, zstdgrep, zstdless and zstdmt (#6364)

• Lots of improvements to completions.

• Selecting short options which also have a long name from the comple-
tion pager is possible (#5634).

• Tab completion will no longer add trailing spaces if they already ex-
ist (#6107).

• Completion of subcommands to builtins like and or not now works cor-
rectly (#6249).

• Completion of arguments to short options works correctly when multi-
ple short options are used together (#332).

• Activating completion in the middle of an invalid completion does not
move the cursor any more, making it easier to fix a mistake (#4124).

• Completion in empty commandlines now lists all available commands.

• Functions listed as completions could previously leak parts of the
function as other completions; this has been fixed.

Deprecations and removed features
• The vcs-prompt functions have been promoted to names without dou-
ble-underscore, so __fish_git_prompt is now fish_git_prompt,
__fish_vcs_prompt is now fish_vcs_prompt, __fish_hg_prompt is now
fish_hg_prompt and __fish_svn_prompt is now fish_svn_prompt. Shims at
the old names have been added, and the variables have kept their old
names (#5586).

• string replace has an additional round of escaping in the replacement
expression, so escaping backslashes requires many escapes (eg string
replace -ra '([ab])' '\\\\\\\$1' a). The new feature flag
regex-easyesc can be used to disable this, so that the same effect
can be achieved with string replace -ra '([ab])' '\\\\$1' a (#5556).
As a reminder, the intention behind feature flags is that this will
eventually become the default and then only option, so scripts should
be updated.

• The fish_vi_mode function, deprecated in fish 2.3, has been removed.
Use fish_vi_key_bindings instead (#6372).

For distributors and developers
• fish 3.0 introduced a CMake-based build system. In fish 3.1, both the
Autotools-based build and legacy Xcode build system have been re-
moved, leaving only the CMake build system. All distributors and de-
velopers must install CMake.

• fish now depends on the common tee external command, for the psub
process substitution function.

• The documentation is now built with Sphinx. The old Doxygen-based
documentation system has been removed. Developers, and distributors
who wish to rebuild the documentation, must install Sphinx.

• The INTERNAL_WCWIDTH build option has been removed, as fish now al-
ways uses an internal wcwidth function. It has a number of configura-
tion options that make it more suitable for general use (#5777).

• mandoc can now be used to format the output from --help if nroff is
not installed, reducing the number of external dependencies on sys-
tems with mandoc installed (#5489).

• Some bugs preventing building on Solaris-derived systems such as Il-
lumos were fixed (#5458, #5461, #5611).

• Completions for npm, bower and yarn no longer require the jq utility
for full functionality, but will use Python instead if it is avail-
able.

• The paths for completions, functions and configuration snippets have
been extended. On systems that define XDG_DATA_DIRS, each of the di-
rectories in this variable are searched in the subdirectories
fish/vendor_completions.d, fish/vendor_functions.d, and fish/ven-
dor_conf.d respectively. On systems that do not define this variable
in the environment, the vendor directories are searched for in both
the installation prefix and the default extra directory, which now
defaults to /usr/local (#5029).

----

fish 3.0.2 (released February 19, 2019)
This release of fish fixes an issue discovered in fish 3.0.1.

Fixes and improvements
• The PWD environment variable is now ignored if it does not resolve to
the true working directory, fixing strange behaviour in terminals
started by editors and IDEs (#5647).

If you are upgrading from version 2.7.1 or before, please also review
the release notes for 3.0.1, 3.0.0 and 3.0b1 (included below).

fish 3.0.1 (released February 11, 2019)
This release of fish fixes a number of major issues discovered in fish
3.0.0.

Fixes and improvements
• exec does not complain about running foreground jobs when called (-
#5449).

• while loops now evaluate to the last executed command in the loop
body (or zero if the body was empty), matching POSIX semantics (-
#4982).

• read --silent no longer echoes to the tty when run from a non-inter-
active script (#5519).

• On macOS, path entries with spaces in /etc/paths and /etc/paths.d now
correctly set path entries with spaces. Likewise, MANPATH is cor-
rectly set from /etc/manpaths and /etc/manpaths.d (#5481).

• fish starts correctly under Cygwin/MSYS2 (#5426).

• The pager-toggle-search binding (Ctrl-S by default) will now activate
the search field, even when the pager is not focused.

• The error when a command is not found is now printed a single time,
instead of once per argument (#5588).

• Fixes and improvements to the git completions, including printing
correct paths with older git versions, fuzzy matching again, reducing
unnecessary offers of root paths (starting with :/) (#5578, #5574,
#5476), and ignoring shell aliases, so enterprising users can set up
the wrapping command (via set -g __fish_git_alias_$command
$whatitwraps) (#5412).

• Significant performance improvements to core shell functions (#5447)
and to the kill completions (#5541).

• Starting in symbolically-linked working directories works correctly
(#5525).

• The default fish_title function no longer contains extra spaces (-
#5517).

• The nim prompt now works correctly when chosen in the Web-based con-
figuration (#5490).

• string now prints help to stdout, like other builtins (#5495).

• Killing the terminal while fish is in vi normal mode will no longer
send it spinning and eating CPU. (#5528)

• A number of crashes have been fixed (#5550, #5548, #5479, #5453).

• Improvements to the documentation and certain completions.

Known issues
There is one significant known issue that was not corrected before the
release:

• fish does not run correctly under Windows Services for Linux before
Windows 10 version 1809/17763, and the message warning of this may
not be displayed (#5619).

If you are upgrading from version 2.7.1 or before, please also review
the release notes for 3.0.0 and 3.0b1 (included below).

----

fish 3.0.0 (released December 28, 2018)
fish 3 is a major release, which introduces some breaking changes
alongside improved functionality. Although most existing scripts will
continue to work, they should be reviewed against the list contained in
the 3.0b1 release notes below.

Compared to the beta release of fish 3.0b1, fish version 3.0.0:

• builds correctly against musl libc (#5407)

• handles huge numeric arguments to test correctly (#5414)

• removes the history colouring introduced in 3.0b1, which did not al-
ways work correctly

There is one significant known issue which was not able to be corrected
before the release:

• fish 3.0.0 builds on Cygwin (#5423), but does not run correctly (-
#5426) and will result in a hanging terminal when started. Cygwin
users are encouraged to continue using 2.7.1 until a release which
corrects this is available.

If you are upgrading from version 2.7.1 or before, please also review
the release notes for 3.0b1 (included below).

----

fish 3.0b1 (released December 11, 2018)
fish 3 is a major release, which introduces some breaking changes
alongside improved functionality. Although most existing scripts will
continue to work, they should be reviewed against the list below.

Notable non-backward compatible changes
• Process and job expansion has largely been removed. % will no longer
perform these expansions, except for %self for the PID of the current
shell. Additionally, job management commands (disown, wait, bg, fg
and kill) will expand job specifiers starting with % (#4230, #1202).

• set x[1] x[2] a b, to set multiple elements of an array at once, is
no longer valid syntax (#4236).

• A literal {} now expands to itself, rather than nothing. This makes
working with find -exec easier (#1109, #4632).

• Literally accessing a zero-index is now illegal syntax and is caught
by the parser (#4862). (fish indices start at 1)

• Successive commas in brace expansions are handled in less surprising
manner. For example, {,,,} expands to four empty strings rather than
an empty string, a comma and an empty string again (#3002, #4632).

• for loop control variables are no longer local to the for block (-
#1935).

• Variables set in if and while conditions are available outside the
block (#4820).

• Local exported (set -lx) vars are now visible to functions (#1091).

• The new math builtin (see below) does not support logical expres-
sions; test should be used instead (#4777).

• Range expansion will now behave sensibly when given a single positive
and negative index ($foo[5..-1] or $foo[-1..5]), clamping to the last
valid index without changing direction if the list has fewer elements
than expected.

• read now uses -s as short for --silent ( la bash); --shells abbrevi-
ation (formerly -s) is now -S instead (#4490).

• cd no longer resolves symlinks. fish now maintains a virtual path,
matching other shells (#3350).

• source now requires an explicit - as the filename to read from the
terminal (#2633).

• Arguments to end are now errors, instead of being silently ignored.

• The names argparse, read, set, status, test and [ are now reserved
and not allowed as function names. This prevents users unintention-
ally breaking stuff (#3000).

• The fish_user_abbreviations variable is no longer used; abbreviations
will be migrated to the new storage format automatically.

• The FISH_READ_BYTE_LIMIT variable is now called fish_byte_limit (-
#4414).

• Environment variables are no longer split into arrays based on the
record separator character on startup. Instead, variables are not
split, unless their name ends in PATH, in which case they are split
on colons (#436).

• The history builtins --with-time option has been removed; this has
been deprecated in favor of --show-time since 2.7.0 (#4403).

• The internal variables __fish_datadir and __fish_sysconfdir are now
known as __fish_data_dir and __fish_sysconf_dir respectively.

Deprecations
With the release of fish 3, a number of features have been marked for
removal in the future. All users are encouraged to explore alterna-
tives. A small number of these features are currently behind feature
flags, which are turned on at present but may be turned off by default
in the future.

A new feature flags mechanism is added for staging deprecations and
breaking changes. Feature flags may be specified at launch with fish
--features ... or by setting the universal fish_features variable. (-
#4940)

• The use of the IFS variable for read is deprecated; IFS will be ig-
nored in the future (#4156). Use the read --delimiter option instead.

• The function --on-process-exit switch will be removed in future (-
#4700). Use the fish_exit event instead: function --on-event
fish_exit.

• $_ is deprecated and will removed in the future (#813). Use status
current-command in a command substitution instead.

• ^ as a redirection deprecated and will be removed in the future. (-
#4394). Use 2> to redirect stderr. This is controlled by the
stderr-nocaret feature flag.

• ? as a glob (wildcard) is deprecated and will be removed in the fu-
ture (#4520). This is controlled by the qmark-noglob feature flag.

Notable fixes and improvements
Syntax changes and new commands
• fish now supports && (like and), || (like or), and ! (like not), for
better migration from POSIX-compliant shells (#4620).

• Variables may be used as commands (#154).

• fish may be started in private mode via fish --private. Private mode
fish sessions do not have access to the history file and any commands
evaluated in private mode are not persisted for future sessions. A
session variable $fish_private_mode can be queried to detect private
mode and adjust the behavior of scripts accordingly to respect the
users wish for privacy.

• A new wait command for waiting on backgrounded processes (#4498).

• math is now a builtin rather than a wrapper around bc (#3157). Float-
ing point computations is now used by default, and can be controlled
with the new --scale option (#4478).

• Setting $PATH no longer warns on non-existent directories, allowing
for a single $PATH to be shared across machines (eg via dotfiles) (-
#2969).

• while sets $status to a non-zero value if the loop is not executed (-
#4982).

• Command substitution output is now limited to 10 MB by default, con-
trolled by the fish_read_limit variable (#3822). Notably, this is
larger than most operating systems argument size limit, so trying to
pass argument lists this size to external commands has never worked.

• The machine hostname, where available, is now exposed as the $host-
name reserved variable. This removes the dependency on the hostname
executable (#4422).

• Bare bind invocations in config.fish now work. The
fish_user_key_bindings function is no longer necessary, but will
still be executed if it exists (#5191).

• $fish_pid and $last_pid are available as replacements for %self and
%last.

New features in commands
• alias has a new --save option to save the generated function immedi-
ately (#4878).

• bind has a new --silent option to ignore bind requests for named keys
not available under the current terminal (#4188, #4431).

• complete has a new --keep-order option to show the provided or dynam-
ically-generated argument list in the same order as specified, rather
than alphabetically (#361).

• exec prompts for confirmation if background jobs are running.

• funced has a new --save option to automatically save the edited func-
tion after successfully editing (#4668).

• functions has a new --handlers option to show functions registered as
event handlers (#4694).

• history search supports globs for wildcard searching (#3136) and has
a new --reverse option to show entries from oldest to newest (#4375).

• jobs has a new --quiet option to silence the output.

• read has a new --delimiter option for splitting input into arrays (-
#4256).

• read writes directly to stdout if called without arguments (#4407).

• read can now read individual lines into separate variables without
consuming the input in its entirety via the new /--line option.

• set has new --append and --prepend options (#1326).

• string match with an empty pattern and --entire in glob mode now
matches everything instead of nothing (#4971).

• string split supports a new --no-empty option to exclude empty
strings from the result (#4779).

• string has new subcommands split0 and join0 for working with NUL-de-
limited output.

• string no longer stops processing text after NUL characters (#4605)

• string escape has a new --style regex option for escaping strings to
be matched literally in string regex operations.

• test now supports floating point values in numeric comparisons.

Interactive improvements
• A pipe at the end of a line now allows the job to continue on the
next line (#1285).

• Italics and dim support out of the box on macOS for Terminal.app and
iTerm (#4436).

• cd tab completions no longer descend into the deepest unambiguous
path (#4649).

• Pager navigation has been improved. Most notably, moving down now
wraps around, moving up from the commandline now jumps to the last
element and moving right and left now reverse each other even when
wrapping around (#4680).

• Typing normal characters while the completion pager is active no
longer shows the search field. Instead it enters them into the com-
mand line, and ends paging (#2249).

• A new input binding pager-toggle-search toggles the search field in
the completions pager on and off. By default, this is bound to
Ctrl-S.

• Searching in the pager now does a full fuzzy search (#5213).

• The pager will now show the full command instead of just its last
line if the number of completions is large (#4702).

• Abbreviations can be tab-completed (#3233).

• Tildes in file names are now properly escaped in completions (#2274).

• Wrapping completions (from complete --wraps or function --wraps) can
now inject arguments. For example, complete gco --wraps 'git check-
out' now works properly (#1976). The alias function has been updated
to respect this behavior.

• Path completions now support expansions, meaning expressions like
python ~/<TAB> now provides file suggestions just like any other rel-
ative or absolute path. (This includes support for other expansions,
too.)

• Autosuggestions try to avoid arguments that are already present in
the command line.

• Notifications about crashed processes are now always shown, even in
command substitutions (#4962).

• The screen is no longer reset after a BEL, fixing graphical glitches
(#3693).

• vi-mode now supports ; and , motions. This introduces new {for-
ward,backward}-jump-till and repeat-jump{,-reverse} bind functions (-
#5140).

• The *y vi-mode binding now works (#5100).

• True color is now enabled in neovim by default (#2792).

• Terminal size variables ($COLUMNS/$LINES) are now updated before
fish_prompt is called, allowing the prompt to react (#904).

• Multi-line prompts no longer repeat when the terminal is resized (-
#2320).

• xclip support has been added to the clipboard integration (#5020).

• The Alt-P keybinding paginates the last command if the command line
is empty.

• $cmd_duration is no longer reset when no command is executed (#5011).

• Deleting a one-character word no longer erases the next word as well
(#4747).

• Token history search (Alt-Up) omits duplicate entries (#4795).

• The fish_escape_delay_ms timeout, allowing the use of the escape key
both on its own and as part of a control sequence, was applied to all
control characters; this has been reduced to just the escape key.

• Completing a function shows the description properly (#5206).

• commandline can now be used to set the commandline for the next com-
mand, restoring a behavior in 3.4.1 (#8807).

• Added completions for

• ansible, including ansible-galaxy, ansible-playbook and ansi-
ble-vault (#4697)

• bb-power (#4800)

• bd (#4472)

• bower

• clang and clang++ (#4174)

• conda (#4837)

• configure (for autoconf-generated files only)

• curl

• doas (#5196)

• ebuild (#4911)

• emaint (#4758)

• eopkg (#4600)

• exercism (#4495)

• hjson

• hugo (#4529)

• j (from autojump #4344)

• jbake (#4814)

• jhipster (#4472)

• kitty

• kldload

• kldunload

• makensis (#5242)

• meson

• mkdocs (#4906)

• ngrok (#4642)

• OpenBSDs pkg_add, pkg_delete, pkg_info, pfctl, rcctl, signify, and
vmctl (#4584)

• openocd

• optipng

• opkg (#5168)

• pandoc (#2937)

• port (#4737)

• powerpill (#4800)

• pstack (#5135)

• serve (#5026)

• ttx

• unzip

• virsh (#5113)

• xclip (#5126)

• xsv

• zfs and zpool (#4608)

• Lots of improvements to completions (especially darcs (#5112), git,
hg and sudo).

• Completions for yarn and npm now require the all-the-package-names
NPM package for full functionality.

• Completions for bower and yarn now require the jq utility for full
functionality.

• Improved French translations.

Other fixes and improvements
• Significant performance improvements to abbr (#4048), setting vari-
ables (#4200, #4341), executing functions, globs (#4579), string
reading from standard input (#4610), and slicing history (in particu-
lar, $history[1] for the last executed command).

• Fishs internal wcwidth function has been updated to deal with newer
Unicode, and the width of some characters can be configured via the
fish_ambiguous_width (#5149) and fish_emoji_width (#2652) variables.
Alternatively, a new build-time option INTERNAL_WCWIDTH can be used
to use the systems wcwidth instead (#4816).

• functions correctly supports -d as the short form of --description.
(#5105)

• /etc/paths is now parsed like macOS bash path_helper, fixing $PATH
order (#4336, #4852) on macOS.

• Using a read-only variable in a for loop produces an error, rather
than silently producing incorrect results (#4342).

• The universal variables filename no longer contains the hostname or
MAC address. It is now at the fixed location .config/fish/fish_vari-
ables (#1912).

• Exported variables in the global or universal scope no longer have
their exported status affected by local variables (#2611).

• Major rework of terminal and job handling to eliminate bugs (#3805,
#3952, #4178, #4235, #4238, #4540, #4929, #5210).

• Improvements to the manual page completion generator (#2937, #4313).

• suspend --force now works correctly (#4672).

• Pressing Ctrl-C while running a script now reliably terminates fish
(#5253).

For distributors and developers
• fish ships with a new build system based on CMake. CMake 3.2 is the
minimum required version. Although the autotools-based Makefile and
the Xcode project are still shipped with this release, they will be
removed in the near future. All distributors and developers are en-
couraged to migrate to the CMake build.

• Build scripts for most platforms no longer require bash, using the
standard sh instead.

• The hostname command is no longer required for fish to operate.

fish 2.7.1 (released December 23, 2017)
This release of fish fixes an issue where iTerm 2 on macOS would dis-
play a warning about paste bracketing being left on when starting a new
fish session (#4521).

If you are upgrading from version 2.6.0 or before, please also review
the release notes for 2.7.0 and 2.7b1 (included below).

fish 2.7.0 (released November 23, 2017)
There are no major changes between 2.7b1 and 2.7.0. If you are upgrad-
ing from version 2.6.0 or before, please also review the release notes
for 2.7b1 (included below).

Xcode builds and macOS packages could not be produced with 2.7b1, but
this is fixed in 2.7.0.

fish 2.7b1 (released October 31, 2017)
Notable improvements
• A new cdh (change directory using recent history) command provides a
more friendly alternative to prevd/nextd and pushd/popd (#2847).

• A new argparse command is available to allow fish script to parse ar-
guments with the same behavior as builtin commands. This also in-
cludes the fish_opt helper command. (#4190).

• Invalid array indexes are now silently ignored (#826, #4127).

• Improvements to the debugging facility, including a prompt specific
to the debugger (fish_breakpoint_prompt) and a status is-breakpoint
subcommand (#1310).

• string supports new lower and upper subcommands, for altering the
case of strings (#4080). The case changing is not locale-aware yet.-
string escape has a new --style=xxx flag where xxx can be script,
var, or url (#4150), and can be reversed with string unescape (-
#3543).

• History can now be split into sessions with the fish_history vari-
able, or not saved to disk at all (#102).

• Read history is now controlled by the fish_history variable rather
than the --mode-name flag (#1504).

• command now supports an --all flag to report all directories with the
command. which is no longer a runtime dependency (#2778).

• fish can run commands before starting an interactive session using
the new --init-command/-C options (#4164).

• set has a new --show option to show lots of information about vari-
ables (#4265).

Other significant changes
• The COLUMNS and LINES environment variables are now correctly set the
first time fish_prompt is run (#4141).

• completes --no-files option works as intended (#112).

• echo -h now correctly echoes -h in line with other shells (#4120).

• The export compatibility function now returns zero on success, rather
than always returning 1 (#4435).

• Stop converting empty elements in MANPATH to . (#4158). The behavior
being changed was introduced in fish 2.6.0.

• count -h and count --help now return 1 rather than produce command
help output (#4189).

• An attempt to read which stops because too much data is available
still defines the variables given as parameters (#4180).

• A regression in fish 2.4.0 which prevented pushd +1 from working has
been fixed (#4091).

• A regression in fish 2.6.0 where multiple read commands in non-inter-
active scripts were broken has been fixed (#4206).

• A regression in fish 2.6.0 involving universal variables with
side-effects at startup such as set -U fish_escape_delay_ms 10 has
been fixed (#4196).

• Added completions for:

• as (#4130)

• cdh (#2847)

• dhcpd (#4115)

• ezjail-admin (#4324)

• Fabrics fab (#4153)

• grub-file (#4119)

• grub-install (#4119)

• jest (#4142)

• kdeconnect-cli

• magneto (#4043, #4108)

• mdadm (#4198)

• passwd (#4209)

• pip and pipenv (#4448)

• s3cmd (#4332)

• sbt (#4347)

• snap (#4215)

• Sublime Text 3s subl (#4277)

• Lots of improvements to completions.

• Updated Chinese and French translations.

• Improved completions for:

• apt

• cd (#4061)

• composer (#4295)

• eopkg

• flatpak (#4456)

• git (#4117, #4147, #4329, #4368)

• gphoto2

• killall (#4052)

• ln

• npm (#4241)

• ssh (#4377)

• tail

• xdg-mime (#4333)

• zypper (#4325)

fish 2.6.0 (released June 3, 2017)
Since the beta release of fish 2.6b1, fish version 2.6.0 contains a
number of minor fixes, new completions for magneto (#4043), and im-
provements to the documentation.

Known issues
• Apple macOS Sierra 10.12.5 introduced a problem with launching web
browsers from other programs using AppleScript. This affects the fish
Web configuration (fish_config); users on these platforms will need
to manually open the address displayed in the terminal, such as by
copying and pasting it into a browser. This problem will be fixed
with macOS 10.12.6.

If you are upgrading from version 2.5.0 or before, please also review
the release notes for 2.6b1 (included below).

----

fish 2.6b1 (released May 14, 2017)
Notable fixes and improvements
• Jobs running in the background can now be removed from the list of
jobs with the new disown builtin, which behaves like the same command
in other shells (#2810).

• Command substitutions now have access to the terminal, like in other
shells. This allows tools like fzf to work properly (#1362, #3922).

• In cases where the operating system does not report the size of the
terminal, the COLUMNS and LINES environment variables are used; if
they are unset, a default of 80x24 is assumed.

• New French (#3772 & #3788) and improved German (#3834) translations.

• fish no longer depends on the which external command.

Other significant changes
• Performance improvements in launching processes, including major re-
ductions in signal blocking. Although this has been heavily tested,
it may cause problems in some circumstances; set the FISH_NO_SIG-
NAL_BLOCK variable to 0 in your fish configuration file to return to
the old behaviour (#2007).

• Performance improvements in prompts and functions that set lots of
colours (#3793).

• The Delete key no longer deletes backwards (a regression in 2.5.0).

• functions supports a new --details option, which identifies where the
function was loaded from (#3295), and a --details --verbose option
which includes the function description (#597).

• read will read up to 10 MiB by default, leaving the target variable
empty and exiting with status 122 if the line is too long. You can
set a different limit with the FISH_READ_BYTE_LIMIT variable.

• read supports a new --silent option to hide the characters typed (-
#838), for when reading sensitive data from the terminal. read also
now accepts simple strings for the prompt (rather than scripts) with
the new -P and --prompt-str options (#802).

• export and setenv now understand colon-separated PATH, CDPATH and
MANPATH variables.

• setenv is no longer a simple alias for set -gx and will complain,
just like the csh version, if given more than one value (#4103).

• bind supports a new --list-modes option (#3872).

• bg will check all of its arguments before backgrounding any jobs; any
invalid arguments will cause a failure, but non-existent (eg recently
exited) jobs are ignored (#3909).

• funced warns if the function being edited has not been modified (-
#3961).

• printf correctly outputs long long integers (#3352).

• status supports a new current-function subcommand to print the cur-
rent function name (#1743).

• string supports a new repeat subcommand (#3864). string match sup-
ports a new --entire option to emit the entire line matched by a pat-
tern (#3957). string replace supports a new --filter option to only
emit lines which underwent a replacement (#3348).

• test supports the -k option to test for sticky bits (#733).

• umask understands symbolic modes (#738).

• Empty components in the CDPATH, MANPATH and PATH variables are now
converted to . (#2106, #3914).

• New versions of ncurses (6.0 and up) wipe terminal scrollback buffers
with certain commands; the C-l binding tries to avoid this (#2855).

• Some systems su implementations do not set the USER environment vari-
able; it is now reset for root users (#3916).

• Under terminals which support it, bracketed paste is enabled, escap-
ing problematic characters for security and convience (#3871). In-
side single quotes ('), single quotes and backslashes in pasted text
are escaped (#967). The fish_clipboard_paste function (bound to C-v
by default) is still the recommended pasting method where possible as
it includes this functionality and more.

• Processes in pipelines are no longer signalled as soon as one command
in the pipeline has completed (#1926). This behaviour matches other
shells mre closely.

• All functions requiring Python work with whichever version of Python
is installed (#3970). Python 3 is preferred, but Python 2.6 remains
the minimum version required.

• The color of the cancellation character can be controlled by the
fish_color_cancel variable (#3963).

• Added completions for:

• caddy (#4008)

• castnow (#3744)

• climate (#3760)

• flatpak

• gradle (#3859)

• gsettings (#4001)

• helm (#3829)

• i3-msg (#3787)

• ipset (#3924)

• jq (#3804)

• light (#3752)

• minikube (#3778)

• mocha (#3828)

• mkdosfs (#4017)

• pv (#3773)

• setsid (#3791)

• terraform (#3960)

• usermod (#3775)

• xinput

• yarn (#3816)

• Improved completions for adb (#3853), apt (#3771), bzr (#3769),
dconf, git (including #3743), grep (#3789), go (#3789), help (#3789),
hg (#3975), htop (#3789), killall (#3996), lua, man (#3762), mount (-
#3764 & #3841), obnam (#3924), perl (#3856), portmaster (#3950),
python (#3840), ssh (#3781), scp (#3781), systemctl (#3757) and ud-
isks (#3764).

----

fish 2.5.0 (released February 3, 2017)
There are no major changes between 2.5b1 and 2.5.0. If you are upgrad-
ing from version 2.4.0 or before, please also review the release notes
for 2.5b1 (included below).

Notable fixes and improvements
• The Home, End, Insert, Delete, Page Up and Page Down keys work in
Vi-style key bindings (#3731).

----

fish 2.5b1 (released January 14, 2017)
Platform Changes
Starting with version 2.5, fish requires a more up-to-date version of
C++, specifically C++11 (from 2011). This affects some older platforms:

Linux
For users building from source, GCCs g++ 4.8 or later, or LLVMs clang
3.3 or later, are known to work. Older platforms may require a newer
compiler installed.

Unfortunately, because of the complexity of the toolchain, binary pack-
ages are no longer published by the fish-shell developers for the fol-
lowing platforms:

• Red Hat Enterprise Linux and CentOS 5 & 6 for 64-bit builds

• Ubuntu 12.04 (EoLTS April 2017)

• Debian 7 (EoLTS May 2018)

Installing newer version of fish on these systems will require building
from source.

OS X SnowLeopard
Starting with version 2.5, fish requires a C++11 standard library on OS
X 10.6 (SnowLeopard). If this library is not installed, you will see
this error: dyld: Library not loaded: /usr/lib/libc++.1.dylib

MacPorts is the easiest way to obtain this library. After installing
the SnowLeopard MacPorts release from the install page, run:

sudo port -v install libcxx

Now fish should launch successfully. (Please open an issue if it does
not.)

This is only necessary on 10.6. OS X 10.7 and later include the re-
quired library by default.

Other significant changes
• Attempting to exit with running processes in the background produces
a warning, then signals them to terminate if a second attempt to exit
is made. This brings the behaviour for running background processes
into line with stopped processes. (#3497)

• random can now have start, stop and step values specified, or the new
choice subcommand can be used to pick an argument from a list (-
#3619).

• A new key bindings preset, fish_hybrid_key_bindings, including all
the Emacs-style and Vi-style bindings, which behaves like
fish_vi_key_bindings in fish 2.3.0 (#3556).

• function now returns an error when called with invalid options,
rather than defining the function anyway (#3574). This was a regres-
sion present in fish 2.3 and 2.4.0.

• fish no longer prints a warning when it identifies a running instance
of an old version (2.1.0 and earlier). Changes to universal variables
may not propagate between these old versions and 2.5b1.

• Improved compatiblity with Android (#3585), MSYS/mingw (#2360), and
Solaris (#3456, #3340).

• Like other shells, the test builting now returns an error for numeric
operations on invalid integers (#3346, #3581).

• complete no longer recognises --authoritative and --unauthoritative
options, and they are marked as obsolete.

• status accepts subcommands, and should be used like status is-inter-
active. The old options continue to be supported for the foreseeable
future (#3526), although only one subcommand or option can be speci-
fied at a time.

• Selection mode (used with begin-selection) no longer selects a char-
acter the cursor does not move over (#3684).

• List indexes are handled better, and a bit more liberally in some
cases (echo $PATH[1 .. 3] is now valid) (#3579).

• The fish_mode_prompt function is now simply a stub around fish_de-
fault_mode_prompt, which allows the mode prompt to be included more
easily in customised prompt functions (#3641).

Notable fixes and improvements
• alias, run without options or arguments, lists all defined aliases,
and aliases now include a description in the function signature that
identifies them.

• complete accepts empty strings as descriptions (#3557).

• command accepts -q/--quiet in combination with --search (#3591), pro-
viding a simple way of checking whether a command exists in scripts.

• Abbreviations can now be renamed with abbr --rename OLD_KEY NEW_KEY
(#3610).

• The command synopses printed by --help options work better with copy-
ing and pasting (#2673).

• help launches the browser specified by the $fish_help_browser vari-
able if it is set (#3131).

• History merging could lose items under certain circumstances and is
now fixed (#3496).

• The $status variable is now set to 123 when a syntactically invalid
command is entered (#3616).

• Exiting fish now signals all background processes to terminate, not
just stopped jobs (#3497).

• A new prompt_hostname function which prints a hostname suitable for
use in prompts (#3482).

• The __fish_man_page function (bound to Alt-h by default) now tries to
recognize subcommands (e.g. git add will now open the git-add man
page) (#3678).

• A new function edit_command_buffer (bound to Alt-e & Alt-v by de-
fault) to edit the command buffer in an external editor (#1215,
#3627).

• set_color now supports italics (--italics), dim (--dim) and reverse
(--reverse) modes (#3650).

• Filesystems with very slow locking (eg incorrectly-configured NFS)
will no longer slow fish down (#685).

• Improved completions for apt (#3695), fusermount (#3642), make (-
#3628), netctl-auto (#3378), nmcli (#3648), pygmentize (#3378), and
tar (#3719).

• Added completions for:

• VBoxHeadless (#3378)

• VBoxSDL (#3378)

• base64 (#3378)

• caffeinate (#3524)

• dconf (#3638)

• dig (#3495)

• dpkg-reconfigure (#3521 & #3522)

• feh (#3378)

• launchctl (#3682)

• lxc (#3554 & #3564),

• mddiagnose (#3524)

• mdfind (#3524)

• mdimport (#3524)

• mdls (#3524)

• mdutil (#3524)

• mkvextract (#3492)

• nvram (#3524)

• objdump (#3378)

• sysbench (#3491)

• tmutil (#3524)

----

fish 2.4.0 (released November 8, 2016)
There are no major changes between 2.4b1 and 2.4.0.

Notable fixes and improvements
• The documentation is now generated properly and with the correct ver-
sion identifier.

• Automatic cursor changes are now only enabled on the subset of XTerm
versions known to support them, resolving a problem where older ver-
sions printed garbage to the terminal before and after every prompt
(#3499).

• Improved the title set in Apple Terminal.app.

• Added completions for defaults and improved completions for diskutil
(#3478).

----

fish 2.4b1 (released October 18, 2016)
Significant changes
• The clipboard integration has been revamped with explicit bindings.
The killring commands no longer copy from, or paste to, the X11 clip-
board - use the new copy (C-x) and paste (C-v) bindings instead. The
clipboard is now available on OS X as well as systems using X11
(e.g. Linux). (#3061)

• history uses subcommands (history delete) rather than options (his-
tory --delete) for its actions (#3367). You can no longer specify
multiple actions via flags (e.g., history --delete --save something).

• New history options have been added, including --max=n to limit the
number of history entries, --show-time option to show timestamps (-
#3175, #3244), and --null to null terminate history entries in the
search output.

• history search is now case-insensitive by default (which also affects
history delete) (#3236).

• history delete now correctly handles multiline commands (#31).

• Vi-style bindings no longer include all of the default emacs-style
bindings; instead, they share some definitions (#3068).

• If there is no locale set in the environment, various known system
configuration files will be checked for a default. If no locale can
be found, en_US-UTF.8 will be used (#277).

• A number followed by a caret (e.g. 5^) is no longer treated as a
redirection (#1873).

• The $version special variable can be overwritten, so that it can be
used for other purposes if required.

Notable fixes and improvements
• The fish_realpath builtin has been renamed to realpath and made com-
patible with GNU realpath when run without arguments (#3400). It is
used only for systems without a realpath or grealpath utility (-
#3374).

• Improved color handling on terminals/consoles with 8-16 colors, par-
ticularly the use of bright named color (#3176, #3260).

• fish_indent can now read from files given as arguments, rather than
just standard input (#3037).

• Fuzzy tab completions behave in a less surprising manner (#3090,
#3211).

• jobs should only print its header line once (#3127).

• Wildcards in redirections are highlighted appropriately (#2789).

• Suggestions will be offered more often, like after removing charac-
ters (#3069).

• history --merge now correctly interleaves items in chronological or-
der (#2312).

• Options for fish_indent have been aligned with the other binaries -
in particular, -d now means --debug. The --dump option has been re-
named to --dump-parse-tree (#3191).

• The display of bindings in the Web-based configuration has been
greatly improved (#3325), as has the rendering of prompts (#2924).

• fish should no longer hang using 100% CPU in the C locale (#3214).

• A bug in FreeBSD 11 & 12, Dragonfly BSD & illumos prevented fish from
working correctly on these platforms under UTF-8 locales; fish now
avoids the buggy behaviour (#3050).

• Prompts which show git repository information (via __fish_git_prompt)
are faster in large repositories (#3294) and slow filesystems (-
#3083).

• fish 2.3.0 reintroduced a problem where the greeting was printed even
when using read; this has been corrected again (#3261).

• Vi mode changes the cursor depending on the current mode (#3215).

• Command lines with escaped space characters at the end tab-complete
correctly (#2447).

• Added completions for:

• arcanist (#3256)

• connmanctl (#3419)

• figlet (#3378)

• mdbook (#3378)

• ninja (#3415)

• p4, the Perforce client (#3314)

• pygmentize (#3378)

• ranger (#3378)

• Improved completions for aura (#3297), abbr (#3267), brew (#3309),
chown (#3380, #3383),cygport (#3392), git (#3274, #3226, #3225,
#3094, #3087, #3035, #3021, #2982, #3230), kill & pkill (#3200),
screen (#3271), wget (#3470), and xz (#3378).

• Distributors, packagers and developers will notice that the build
process produces more succinct output by default; use make V=1 to get
verbose output (#3248).

• Improved compatibility with minor platforms including musl (#2988),
Cygwin (#2993), Android (#3441, #3442), Haiku (#3322) and Solaris .

----

fish 2.3.1 (released July 3, 2016)
This is a functionality and bugfix release. This release does not con-
tain all the changes to fish since the last release, but fixes a number
of issues directly affecting users at present and includes a small num-
ber of new features.

Significant changes
• A new fish_key_reader binary for decoding interactive keypresses (-
#2991).

• fish_mode_prompt has been updated to reflect the changes in the way
the Vi input mode is set up (#3067), making this more reliable.

• fish_config can now properly be launched from the OS X app bundle (-
#3140).

Notable fixes and improvements
• Extra lines were sometimes inserted into the output under Windows
(Cygwin and Microsoft Windows Subsystem for Linux) due to TTY time-
stamps not being updated (#2859).

• The string builtins match mode now handles the combination of -rnv
(match, invert and count) correctly (#3098).

• Improvements to TTY special character handling (#3064), locale han-
dling (#3124) and terminal environment variable handling (#3060).

• Work towards handling the terminal modes for external commands
launched from initialisation files (#2980).

• Ease the upgrade path from fish 2.2.0 and before by warning users to
restart fish if the string builtin is not available (#3057).

• type -a now syntax-colorizes function source output.

• Added completions for alsamixer, godoc, gofmt, goimports, gorename,
lscpu, mkdir, modinfo, netctl-auto, poweroff, termite, udisksctl and
xz (#3123).

• Improved completions for apt (#3097), aura (#3102),git (#3114), npm
(#3158), string and suspend (#3154).

----

fish 2.3.0 (released May 20, 2016)
There are no significant changes between 2.3.0 and 2.3b2.

Other notable fixes and improvements
• abbr now allows non-letter keys (#2996).

• Define a few extra colours on first start (#2987).

• Multiple documentation updates.

• Added completions for rmmod (#3007).

• Improved completions for git (#2998).

Known issues
• Interactive commands started from fish configuration files or from
the -c option may, under certain circumstances, be started with in-
correct terminal modes and fail to behave as expected. A fix is
planned but requires further testing (#2619).

----

fish 2.3b2 (released May 5, 2016)
Significant changes
• A new fish_realpath builtin and associated function to allow the use
of realpath even on those platforms that dont ship an appropriate
command (#2932).

• Alt-# toggles the current command line between commented and uncom-
mented states, making it easy to save a command in history without
executing it.

• The fish_vi_mode function is now deprecated in favour of
fish_vi_key_bindings.

Other notable fixes and improvements
• Fix the build on Cygwin (#2952) and RedHat Enterprise Linux/CentOS 5
(#2955).

• Avoid confusing the terminal line driver with non-printing characters
in fish_title (#2453).

• Improved completions for busctl, git (#2585, #2879, #2984), and
netctl.

----

fish 2.3b1 (released April 19, 2016)
Significant Changes
• A new string builtin to handle strings! This builtin will measure,
split, search and replace text strings, including using regular ex-
pressions. It can also be used to turn lists into plain strings using
join. string can be used in place of sed, grep, tr, cut, and awk in
many situations. (#2296)

• Allow using escape as the Meta modifier key, by waiting after seeing
an escape character wait up to 300ms for an additional character.
This is consistent with readline (e.g. bash) and can be configured
via the fish_escape_delay_ms variable. This allows using escape as
the Meta modifier. (#1356)

• Add new directories for vendor functions and configuration snippets
(#2500)

• A new fish_realpath builtin and associated realpath function should
allow scripts to resolve path names via realpath regardless of
whether there is an external command of that name; albeit with some
limitations. See the associated documentation.

Backward-incompatible changes
• Unmatched globs will now cause an error, except when used with for,
set or count (#2719)

• and and or will now bind to the closest if or while, allowing com-
pound conditions without begin and end (#1428)

• set -ql now searches up to function scope for variables (#2502)

• status -f will now behave the same when run as the main script or us-
ing source (#2643)

• source no longer puts the file name in $argv if no arguments are
given (#139)

• History files are stored under the XDG_DATA_HOME hierarchy (by de-
fault, in ~/.local/share), and existing history will be moved on
first use (#744)

Other notable fixes and improvements
• Fish no longer silences errors in config.fish (#2702)

• Directory autosuggestions will now descend as far as possible if
there is only one child directory (#2531)

• Add support for bright colors (#1464)

• Allow Ctrl-J (cj) to be bound separately from Ctrl-M (cm) (#217)

• psub now has a -s/suffix option to name the temporary file with that
suffix

• Enable 24-bit colors on select terminals (#2495)

• Support for SVN status in the prompt (#2582)

• Mercurial and SVN support have been added to the Classic + Git (now
Classic + VCS) prompt (via the new __fish_vcs_prompt function) (-
#2592)

• export now handles variables with a = in the value (#2403)

• New completions for:

• alsactl

• Archlinuxs asp, makepkg

• Atoms apm (#2390)

• entr - the Event Notify Test Runner (#2265)

• Fedoras dnf (#2638)

• OSX diskutil (#2738)

• pkgng (#2395)

• pulseaudios pacmd and pactl

• rusts rustc and cargo (#2409)

• sysctl (#2214)

• systemds machinectl (#2158), busctl (#2144), systemd-nspawn, sys-
temd-analyze, localectl, timedatectl

• and more

• Fish no longer has a function called sgrep, freeing it for user cus-
tomization (#2245)

• A rewrite of the completions for cd, fixing a few bugs (#2299, #2300,
#562)

• Linux VTs now run in a simplified mode to avoid issues (#2311)

• The vi-bindings now inherit from the emacs bindings

• Fish will also execute fish_user_key_bindings when in vi-mode

• funced will now also check $VISUAL (#2268)

• A new suspend function (#2269)

• Subcommand completion now works better with split /usr (#2141)

• The command-not-found-handler can now be overridden by defining a
function called __fish_command_not_found_handler in config.fish (-
#2332)

• A few fixes to the Sorin theme

• PWD shortening in the prompt can now be configured via the
fish_prompt_pwd_dir_length variable, set to the length per path com-
ponent (#2473)

• fish no longer requires /etc/fish/config.fish to correctly start, and
now ships a skeleton file that only contains some documentation (-
#2799)

----

fish 2.2.0 (released July 12, 2015)
Significant changes
• Abbreviations: the new abbr command allows for interactively-expanded
abbreviations, allowing quick access to frequently-used commands (-
#731).

• Vi mode: run fish_vi_mode to switch fish into the key bindings and
prompt familiar to users of the Vi editor (#65).

• New inline and interactive pager, which will be familiar to users of
zsh (#291).

• Underlying architectural changes: the fishd universal variable server
has been removed as it was a source of many bugs and security prob-
lems. Notably, old fish sessions will not be able to communicate uni-
versal variable changes with new fish sessions. For best results,
restart all running instances of fish.

• The web-based configuration tool has been redesigned, featuring a
prompt theme chooser and other improvements.

• New German, Brazilian Portuguese, and Chinese translations.

Backward-incompatible changes
These are kept to a minimum, but either change undocumented features or
are too hard to use in their existing forms. These changes may break
existing scripts.

• commandline no longer interprets functions in reverse, instead behav-
ing as expected (#1567).

• The previously-undocumented CMD_DURATION variable is now set for all
commands and contains the execution time of the last command in mil-
liseconds (#1585). It is no longer exported to other commands (-
#1896).

• if / else conditional statements now return values consistent with
the Single Unix Specification, like other shells (#1443).

• A new top-level local scope has been added, allowing local variables
declared on the commandline to be visible to subsequent commands. (-
#1908)

Other notable fixes and improvements
• New documentation design (#1662), which requires a Doxygen version
1.8.7 or newer to build.

• Fish now defines a default directory for other packages to provide
completions. By default this is /usr/share/fish/vendor-completions.d;
on systems with pkgconfig installed this path is discoverable with
pkg-config --variable completionsdir fish.

• A new parser removes many bugs; all existing syntax should keep work-
ing.

• New fish_preexec and fish_postexec events are fired before and after
job execution respectively (#1549).

• Unmatched wildcards no longer prevent a job from running. Wildcards
used interactively will still print an error, but the job will pro-
ceed and the wildcard will expand to zero arguments (#1482).

• The . command is deprecated and the source command is preferred (-
#310).

• bind supports bind modes, which allows bindings to be set for a par-
ticular named mode, to support the implementation of Vi mode.

• A new export alias, which behaves like other shells (#1833).

• command has a new --search option to print the name of the disk file
that would be executed, like other shells command -v (#1540).

• commandline has a new --paging-mode option to support the new pager.

• complete has a new --wraps option, which allows a command to (recur-
sively) inherit the completions of a wrapped command (#393), and com-
plete -e now correctly erases completions (#380).

• Completions are now generated from manual pages by default on the
first run of fish (#997).

• fish_indent can now produce colorized (--ansi) and HTML (--html) out-
put (#1827).

• functions --erase now prevents autoloaded functions from being re-
loaded in the current session.

• history has a new --merge option, to incorporate history from other
sessions into the current session (#825).

• jobs returns 1 if there are no active jobs (#1484).

• read has several new options:

• --array to break input into an array (#1540)

• --null to break lines on NUL characters rather than newlines (#1694)

• --nchars to read a specific number of characters (#1616)

• --right-prompt to display a right-hand-side prompt during interactive
read (#1698).

• type has a new -q option to suppress output (#1540 and, like other
shells, type -a now prints all matches for a command (#261).

• Pressing F1 now shows the manual page for the current command (-
#1063).

• fish_title functions have access to the arguments of the currently
running argument as $argv[1] (#1542).

• The OS command-not-found handler is used on Arch Linux (#1925), nixOS
(#1852), openSUSE and Fedora (#1280).

• Alt+. searches backwards in the token history, mapping to the same
behavior as inserting the last argument of the previous command, like
other shells (#89).

• The SHLVL environment variable is incremented correctly (#1634 &
#1693).

• Added completions for adb (#1165 & #1211), apt (#2018), aura (#1292),
composer (#1607), cygport (#1841), dropbox (#1533), elixir (#1167),
fossil, heroku (#1790), iex (#1167), kitchen (#2000), nix (#1167),
node/npm (#1566), opam (#1615), setfacl (#1752), tmuxinator (#1863),
and yast2 (#1739).

• Improved completions for brew (#1090 & #1810), bundler (#1779), cd (-
#1135), emerge (#1840),git (#1680, #1834 & #1951), man (#960), mod-
probe (#1124), pacman (#1292), rpm (#1236), rsync (#1872), scp (-
#1145), ssh (#1234), sshfs (#1268), systemctl (#1462, #1950 & #1972),
tmux (#1853), vagrant (#1748), yum (#1269), and zypper (#1787).

----

fish 2.1.2 (released Feb 24, 2015)
fish 2.1.2 contains a workaround for a filesystem bug in Mac OS X
Yosemite. #1859

Specifically, after installing fish 2.1.1 and then rebooting, Verify
Disk in Disk Utility will report Invalid number of hard links. We dont
have any reports of data loss or other adverse consequences. fish 2.1.2
avoids triggering the bug, but does not repair an already affected
filesystem. To repair the filesystem, you can boot into Recovery Mode
and use Repair Disk from Disk Utility. Linux and versions of OS X prior
to Yosemite are believed to be unaffected.

There are no other changes in this release.

----

fish 2.1.1 (released September 26, 2014)
Important: if you are upgrading, stop all running instances of fishd as
soon as possible after installing this release; it will be restarted
automatically. On most systems, there will be no further action re-
quired. Note that some environments (where XDG_RUNTIME_DIR is set),
such as Fedora 20, will require a restart of all running fish processes
before universal variables work as intended.

Distributors are highly encouraged to call killall fishd, pkill fishd
or similar in installation scripts, or to warn their users to do so.

Security fixes
• The fish_config web interface now uses an authentication token to
protect requests and only responds to requests from the local machine
with this token, preventing a remote code execution attack. (closing
CVE-2014-2914). #1438

• psub and funced are no longer vulnerable to attacks which allow local
privilege escalation and data tampering (closing CVE-2014-2906 and
CVE-2014-3856). #1437

• fishd uses a secure path for its socket, preventing a local privilege
escalation attack (closing CVE-2014-2905). #1436

• __fish_print_packages is no longer vulnerable to attacks which would
allow local privilege escalation and data tampering (closing
CVE-2014-3219). #1440

Other fixes
• fishd now ignores SIGPIPE, fixing crashes using tools like GNU Paral-
lel and which occurred more often as a result of the other fishd
changes. #1084 & #1690

----

fish 2.1.0
Significant Changes
• Tab completions will fuzzy-match files. #568

When tab-completing a file, fish will first attempt prefix matches
(foo matches foobar), then substring matches (ooba matches foobar),
and lastly subsequence matches (fbr matches foobar). For example, in
a directory with files foo1.txt, foo2.txt, foo3.txt, you can type
only the numeric part and hit tab to fill in the rest.

This feature is implemented for files and executables. It is not yet
implemented for options (like --foobar), and not yet implemented
across path components (like /u/l/b to match /usr/local/bin).

• Redirections now work better across pipelines. #110, #877

In particular, you can pipe stderr and stdout together, for example,
with cmd ^&1 | tee log.txt, or the more familiar cmd 2>&1 | tee
log.txt.

• A single ``%`` now expands to the last job backgrounded. #1008

Previously, a single % would pid-expand to either all backgrounded
jobs, or all jobs owned by your user. Now it expands to the last job
backgrounded. If no job is in the background, it will fail to expand.
In particular, fg % can be used to put the most recent background job
in the foreground.

Other Notable Fixes
• alt-U and alt+C now uppercase and capitalize words, respectively.
#995

• VTE based terminals should now know the working directory. #906

• The autotools build now works on Mavericks. #968

• The end-of-line binding (ctrl+E) now accepts autosuggestions. #932

• Directories in /etc/paths (used on OS X) are now prepended instead of
appended, similar to other shells. #927

• Option-right-arrow (used for partial autosuggestion completion) now
works on iTerm2. #920

• Tab completions now work properly within nested subcommands. #913

• printf supports \e, the escape character. #910

• fish_config history no longer shows duplicate items. #900

• $fish_user_paths is now prepended to $PATH instead of appended. #888

• Jobs complete when all processes complete. #876

For example, in previous versions of fish, sleep 10 | echo Done re-
turns control immediately, because echo does not read from stdin.
Now it does not complete until sleep exits (presumably after 10 sec-
onds).

• Better error reporting for square brackets. #875

• fish no longer tries to add /bin to $PATH unless PATH is totally
empty. #852

• History token substitution (alt-up) now works correctly inside sub-
shells. #833

• Flow control is now disabled, freeing up ctrl-S and ctrl-Q for other
uses. #814

• sh-style variable setting like foo=bar now produces better error mes-
sages. #809

• Commands with wildcards no longer produce autosuggestions. #785

• funced no longer freaks out when supplied with no arguments. #780

• fish.app now works correctly in a directory containing spaces. #774

• Tab completion cycling no longer occasionally fails to repaint. #765

• Comments now work in evald strings. #684

• History search (up-arrow) now shows the item matching the autosugges-
tion, if that autosuggestion was truncated. #650

• Ctrl-T now transposes characters, as in other shells. #128

----

fish 2.0.0
Significant Changes
• Command substitutions now modify ``$status`` :issue:`547`. Previously
the exit status of command substitutions (like (pwd)) was ignored;
however now it modifies $status. Furthermore, the set command now
only sets $status on failure; it is untouched on success. This allows
for the following pattern:

if set python_path (which python)
...
end

Because set does not modify $status on success, the if branch effec-
tively tests whether which succeeded, and if so, whether the set also
succeeded.

• Improvements to PATH handling. There is a new variable,
fish_user_paths, which can be set universally, and whose contents are
appended to $PATH #527

• /etc/paths and /etc/paths.d are now respected on OS X

• fish no longer modifies $PATH to find its own binaries

• Long lines no longer use ellipsis for line breaks, and copy and paste
should no longer include a newline even if the line was broken #300

• New syntax for index ranges (sometimes known as slices) #212

• fish now supports an ``else if`` statement #134

• Process and pid completion now works on OS X #129

• fish is now relocatable, and no longer depends on compiled-in paths
#125

• fish now supports a right prompt (RPROMPT) through the
fish_right_prompt function #80

• fish now uses posix_spawn instead of fork when possible, which is
much faster on BSD and OS X #11

Other Notable Fixes
• Updated VCS completions (darcs, cvs, svn, etc.)

• Avoid calling getcwd on the main thread, as it can hang #696

• Control-D (forward delete) no longer stops at a period #667

• Completions for many new commands

• fish now respects rxvts unique keybindings #657

• xsel is no longer built as part of fish. It will still be invoked if
installed separately #633

• __fish_filter_mime no longer spews #628

• The no-execute option to fish no longer falls over when reaching the
end of a block #624

• fish_config knows how to find fish even if its not in the $PATH #621

• A leading space now prevents writing to history, as is done in bash
and zsh #615

• Hitting enter after a backslash only goes to a new line if it is fol-
lowed by whitespace or the end of the line #613

• printf is now a builtin #611

• Event handlers should no longer fire if signals are blocked #608

• set_color is now a builtin #578

• man page completions are now located in a new generated_completions
directory, instead of your completions directory #576

• tab now clears autosuggestions #561

• tab completion from within a pair of quotes now attempts to appropri-
ate the closing quote #552

• $EDITOR can now be a list: for example, set EDITOR gvim -f) #541

• case bodies are now indented #530

• The profile switch -p no longer crashes #517

• You can now control-C out of read #516

• umask is now functional on OS X #515

• Avoid calling getpwnam on the main thread, as it can hang #512

• Alt-F or Alt-right-arrow (Option-F or option-right-arrow) now accepts
one word of an autosuggestion #435

• Setting fish as your login shell no longer kills OpenSUSE #367

• Backslashes now join lines, instead of creating multiple commands
#347

• echo now implements the -e flag to interpret escapes #337

• When the last token in the users input contains capital letters, use
its case in preference to that of the autosuggestion #335

• Descriptions now have their own muted color #279

• Wildcards beginning with a . (for example, ls .*) no longer match .
and .. #270

• Recursive wildcards now handle symlink loops #268

• You can now delete history items from the fish_config web interface
#250

• The OS X build now weak links wcsdup and wcscasecmp #240

• fish now saves and restores the process group, which prevents certain
processes from being erroneously reported as stopped #197

• funced now takes an editor option #187

• Alternating row colors are available in fish pager through
fish_pager_color_secondary #186

• Universal variable values are now stored based on your MAC address,
not your hostname #183

• The caret ^ now only does a stderr redirection if it is the first
character of a token, making git users happy #168

• Autosuggestions will no longer cause line wrapping #167

• Better handling of Unicode combining characters #155

• fish SIGHUPs processes more often #138

• fish no longer causes sudo to ask for a password every time

• fish behaves better under Midnight Commander #121

• set -e no longer crashes #100

• fish now will automatically import history from bash, if there is no
fish history #66

• Backslashed-newlines inside quoted strings now behave more intu-
itively #52

• Tab titles should be shown correctly in iTerm2 #47

• scp remote path completion now sometimes works #42

• The read builtin no longer shows autosuggestions #29

• Custom key bindings can now be set via the fish_user_key_bindings
function #21

• All Python scripts now run correctly under both Python 2 and Python 3
#14

• The accept autosuggestion key can now be configured #19

• Autosuggestions will no longer suggest invalid commands #6

----

fishfish Beta r2
Bug Fixes
• Implicit cd is back, for paths that start with one or two dots, a
slash, or a tilde.

• Overrides of default functions should be fixed. The internalized
scripts feature is disabled for now.

• Disabled delayed suspend. This is a strange job-control feature of
BSD systems, including OS X. Disabling it frees up Control Y for
other purposes; in particular, for yank, which now works on OS X.

• fish_indent is fixed. In particular, the funced and funcsave func-
tions work again.

• A SIGTERM now ends the whole execution stack again (resolving #13).

• Bumped the __fish_config_interactive version number so the default
fish_color_autosuggestion kicks in.

• fish_config better handles combined term256 and classic colors like
555 yellow.

New Features
• A history builtin, and associated interactive function that enables
deleting history items. Example usage: * Print all history items be-
ginning with echo: history --prefix echo * Print all history items
containing foo: history --contains foo * Interactively delete some
items containing foo: history --delete --contains foo

Credit to @siteshwar for implementation. Thanks @siteshwar!

----

fishfish Beta r1
Scripting
• No changes! All existing fish scripts, config files, completions,
etc. from trunk should continue to work.

New Features
• Autosuggestions. Think URL fields in browsers. When you type a com-
mand, fish will suggest the rest of the command after the cursor, in
a muted gray when possible. You can accept the suggestion with the
right arrow key or Ctrl-F. Suggestions come from command history,
completions, and some custom code for cd; theres a lot of potential
for improvement here. The suggestions are computed on a background
pthread, so they never slow down your typing. The autosuggestion fea-
ture is incredible. I miss it dearly every time I use anything else.

• term256 support where available, specifically modern xterms and OS X
Lion. You can specify colors the old way (set_color cyan) or by spec-
ifying RGB hex values (set_color FF3333); fish will pick the closest
supported color. Some xterms do not advertise term256 support either
in the $TERM or terminfo max_colors field, but nevertheless support
it. For that reason, fish will default into using it on any xterm
(but it can be disabled with an environment variable).

• Web-based configuration page. There is a new function fish_config.
This spins up a simple Python web server and opens a browser window
to it. From this web page, you can set your shell colors and view
your functions, variables, and history; all changes apply immediately
to all running shells. Eventually all configuration ought to be sup-
ported via this mechanism (but in addition to, not instead of, com-
mand line mechanisms).

• Man page completions. There is a new function fish_update_comple-
tions. This function reads all the man1 files from your manpath, re-
moves the roff formatting, parses them to find the commands and op-
tions, and outputs fish completions into ~/.config/fish/completions.
It wont overwrite existing completion files (except ones that it gen-
erated itself).

Programmatic Changes
• fish is now entirely in C++. I have no particular love for C++, but
it provides a ready memory-model to replace halloc. Weve made an ef-
fort to keep it to a sane and portable subset (no C++11, no boost, no
going crazy with templates or smart pointers), but we do use the STL
and a little tr1.

• halloc is entirely gone, replaced by normal C++ ownership semantics.
If you dont know what halloc is, well, now you have two reasons to be
happy.

• All the crufty C data structures are entirely gone. array_list_t,
priority_queue_t, hash_table_t, string_buffer_t have been removed and
replaced by STL equivalents like std::vector, std::map, and
std::wstring. A lot of the string handling now uses std::wstring in-
stead of wchar_t *

• fish now spawns pthreads for tasks like syntax highlighting that re-
quire blocking I/O.

• History has been completely rewritten. History files now use an ex-
tensible YAML-style syntax. History merging (multiple shells writing
to the same history file) now works better. There is now a maximum
history length of about 250k items (256 * 1024).

• The parser has been instanced, so you can now create more than one.

• Total #LoC has shrunk slightly even with the new features.

Performance
• fish now runs syntax highlighting in a background thread, so typing
commands is always responsive even on slow filesystems.

• echo, test, and pwd are now builtins, which eliminates many forks.

• The files in share/functions and share/completions now get internal-
ized into C strings that get compiled in with fish. This substan-
tially reduces the number of files touched at startup. A consequence
is that you cannot change these functions without recompiling, but
often other functions depend on these standard functions, so changing
them is perhaps not a good idea anyways.

Here are some system call counts for launching and then exiting fish
with the default configuration, on OS X. The first column is fish
trunk, the next column is with our changes, and the last column is bash
for comparison. This data was collected via dtrace.

before

after

bash

open

fork

stat

131

lstat

670

read

332

write

172

149

The large number of forks relative to bash are due to fishs insanely
expensive default prompt, which is unchanged in my version. If we
switch to a prompt comparable to bashs (lame) default, the forks drop
to 16 with trunk, 4 after our changes.

The large reduction in lstat() numbers is due to fish no longer needing
to call ttyname() on OS X.

Weve got some work to do to be as lean as bash, but were on the right
track.

License
License for fish
fish Copyright 2005-2009 Axel Liljencrantz, 2009-2023 fish-shell con-
tributors. fish is released under the GNU General Public License, ver-
sion 2.

fish includes other code licensed under the GNU General Public License,
version 2, including GNU printf.

Copyright 1990-2007 Free Software Foundation, Inc. Printf (from GNU
Coreutils 6.9) is released under the GNU General Public License, ver-
sion 2.

The GNU General Public License agreement follows.

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc. 51 Franklin
Street, Fifth Floor, Boston, MA 02110-1301, USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom
to share and change it. By contrast, the GNU General Public License is
intended to guarantee your freedom to share and change free software -
to make sure the software is free for all its users. This General Pub-
lic License applies to most of the Free Software Foundation's software
and to any other program whose authors commit to using it. (Some other
Free Software Foundation software is covered by the GNU Library General
Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price.
Our General Public Licenses are designed to make sure that you have the
freedom to distribute copies of free software (and charge for this ser-
vice if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone
to deny you these rights or to ask you to surrender the rights. These
restrictions translate to certain responsibilities for you if you dis-
tribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis
or for a fee, you must give the recipients all the rights that you
have. You must make sure that they, too, receive or can get the source
code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free soft-
ware. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

Finally, any free program is threatened constantly by software patents.
We wish to avoid the danger that redistributors of a free program will
individually obtain patent licenses, in effect making the program pro-
prietary. To prevent this, we have made it clear that any patent must
be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modifi-
cation follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

• This License applies to any program or other work which contains a
notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", be-
low, refers to any such program or work, and a "work based on the
Program" means either the Program or any derivative work under copy-
right law: that is to say, a work containing the Program or a portion
of it, either verbatim or with modifications and/or translated into
another language. (Hereinafter, translation is included without lim-
itation in the term "modification".) Each licensee is addressed as
"you".
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Pro-
gram is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source
code as you receive it, in any medium, provided that you conspicu-
ously and appropriately publish on each copy an appropriate copy-
right notice and disclaimer of warranty; keep intact all the notices
that refer to this License and to the absence of any warranty; and
give any other recipients of the Program a copy of this License
along with the Program.
You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for
a fee.

2. You may modify your copy or copies of the Program or any portion of
it, thus forming a work based on the Program, and copy and distrib-
ute such modifications or work under the terms of Section 1 above,
provided that you also meet all of these conditions:

• You must cause the modified files to carry prominent notices stat-
ing that you changed the files and the date of any change.

• You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

• If the modified program normally reads commands interactively when
run, you must cause it, when started running for such interactive
use in the most ordinary way, to print or display an announcement
including an appropriate copyright notice and a notice that there
is no warranty (or else, saying that you provide a warranty) and
that users may redistribute the program under these conditions,
and telling the user how to view a copy of this License. (Excep-
tion: if the Program itself is interactive but does not normally
print such an announcement, your work based on the Program is not
required to print an announcement.)

These requirements apply to the modified work as a whole. If iden-
tifiable sections of that work are not derived from the Program, and
can be reasonably considered independent and separate works in them-
selves, then this License, and its terms, do not apply to those sec-
tions when you distribute them as separate works. But when you dis-
tribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms
of this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who
wrote it.

Thus, it is not the intent of this section to claim rights or con-
test your rights to work written entirely by you; rather, the intent
is to exercise the right to control the distribution of derivative
or collective works based on the Program.

In addition, mere aggregation of another work not based on the Pro-
gram with the Program (or with a work based on the Program) on a
volume of a storage or distribution medium does not bring the other
work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it, un-
der Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the follow-
ing:

• Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software inter-
change; or,

• Accompany it with a written offer, valid for at least three years,
to give any third party, for a charge no more than your cost of
physically performing source distribution, a complete ma-
chine-readable copy of the corresponding source code, to be dis-
tributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,

• Accompany it with the information you received as to the offer to
distribute corresponding source code. (This alternative is al-
lowed only for noncommercial distribution and only if you received
the program in object code or executable form with such an offer,
in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to con-
trol compilation and installation of the executable. However, as a
special exception, the source code distributed need not include any-
thing that is normally distributed (in either source or binary form)
with the major components (compiler, kernel, and so on) of the oper-
ating system on which the executable runs, unless that component it-
self accompanies the executable.

If distribution of executable or object code is made by offering ac-
cess to copy from a designated place, then offering equivalent ac-
cess to copy the source code from the same place counts as distribu-
tion of the source code, even though third parties are not compelled
to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program ex-
cept as expressly provided under this License. Any attempt otherwise
to copy, modify, sublicense or distribute the Program is void, and
will automatically terminate your rights under this License. How-
ever, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the Pro-
gram), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject
to these terms and conditions. You may not impose any further re-
strictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

7. If, as a consequence of a court judgment or allegation of patent in-
fringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do
not excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under
this License and any other pertinent obligations, then as a conse-
quence you may not distribute the Program at all. For example, if a
patent license would not permit royalty-free redistribution of the
Program by all those who receive copies directly or indirectly
through you, then the only way you could satisfy both it and this
License would be to refrain entirely from distribution of the Pro-
gram.
If any portion of this section is held invalid or unenforceable un-
der any particular circumstance, the balance of the section is in-
tended to apply and the section as a whole is intended to apply in
other circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the in-
tegrity of the free software distribution system, which is imple-
mented by public license practices. Many people have made generous
contributions to the wide range of software distributed through that
system in reliance on consistent application of that system; it is
up to the author/donor to decide if he or she is willing to distrib-
ute software through any other system and a licensee cannot impose
that choice.

This section is intended to make thoroughly clear what is believed
to be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in cer-
tain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorpo-
rates the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions
will be similar in spirit to the present version, but may differ in
detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Pro-
gram specifies a version number of this License which applies to it
and "any later version", you have the option of following the terms
and conditions either of that version or of any later version pub-
lished by the Free Software Foundation. If the Program does not
specify a version number of this License, you may choose any version
ever published by the Free Software Foundation.

10.
If you wish to incorporate parts of the Program into other free pro-
grams whose distribution conditions are different, write to the au-
thor to ask for permission. For software which is copyrighted by
the Free Software Foundation, write to the Free Software Foundation;
we sometimes make exceptions for this. Our decision will be guided
by the two goals of preserving the free status of all derivatives of
our free software and of promoting the sharing and reuse of software
generally.
NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WAR-
RANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS
AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIM-
ITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PER-
FORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DE-
FECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRIT-
ING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO
YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CON-
SEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR
A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN
IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.

License for PCRE2
fish contains code from the [PCRE2](http://www.pcre.org) library to
support regular expressions. This code, created by Philip Hazel, is
distributed under the terms of the BSD license. Copyright 1997-2015
University of Cambridge.

The BSD license follows.

Redistribution and use in source and binary forms, with or without mod-
ification, are permitted provided that the following conditions are
met:

• Redistributions of source code must retain the above copyright no-
tice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the distri-
bution.

• Neither the name of the University of Cambridge nor the names of
any contributors may be used to endorse or promote products de-
rived from this software without specific prior written permis-
sion.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC-
ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

License for the Python docs theme
In doc_src/python_docs_theme/, taken from
https://pypi.org/project/python-docs-theme/2020.1/.

PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2

1. This LICENSE AGREEMENT is between the Python Software Foundation
("PSF"), and the Individual or Organization ("Licensee") accessing and
otherwise using this software ("Python") in source or binary form and
its associated documentation.

2. Subject to the terms and conditions of this License Agreement, PSF
hereby grants Licensee a nonexclusive, royalty-free, world-wide license
to reproduce, analyze, test, perform and/or display publicly, prepare
derivative works, distribute, and otherwise use Python alone or in any
derivative version, provided, however, that PSF's License Agreement and
PSF's notice of copyright, i.e., "Copyright (c) 2001, 2002, 2003, 2004,
2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016,
2017 Python Software Foundation; All Rights Reserved" are retained in
Python alone or in any derivative version prepared by Licensee.

3. In the event Licensee prepares a derivative work that is based on or
incorporates Python or any part thereof, and wants to make the deriva-
tive work available to others as provided herein, then Licensee hereby
agrees to include in any such work a brief summary of the changes made
to Python.

4. PSF is making Python available to Licensee on an "AS IS" basis. PSF
MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF
EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTA-
TION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PUR-
POSE OR THAT THE USE OF PYTHON WILL NOT INFRINGE ANY THIRD PARTY
RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON FOR
ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT
OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON, OR ANY DERIVA-
TIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.

7. Nothing in this License Agreement shall be deemed to create any re-
lationship of agency, partnership, or joint venture between PSF and Li-
censee. This License Agreement does not grant permission to use PSF
trademarks or trade name in a trademark sense to endorse or promote
products or services of Licensee, or any third party.

8. By copying, installing or otherwise using Python, Licensee agrees to
be bound by the terms and conditions of this License Agreement.

License for CMake
The fish source code contains files from [CMake](https://cmake.org) to
support the build system. This code is distributed under the terms of
a BSD-style license. Copyright 2000-2017 Kitware, Inc. and Contribu-
tors.

The BSD license for CMake follows.

Redistribution and use in source and binary forms, with or without mod-
ification, are permitted provided that the following conditions are
met:

• Redistributions of source code must retain the above copyright no-
tice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright no-
tice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

• Neither the name of Kitware, Inc. nor the names of Contributors may
be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC-
ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

License for code derived from tmux
fish contains code from [tmux](http://tmux.sourceforge.net), copy-
righted by Nicholas Marriott <nicm@users.sourceforge.net> (2007), and
made available under the OpenBSD license.

The OpenBSD license is included below.

Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WAR-
RANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAM-
AGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

License for UTF8
fish also contains small amounts of code under the ISC license, namely
the UTF-8 conversion functions. This code is copyright 2007 Alexey
Vatchenko <av@bsdua.org>.

The ISC license agreement follows.

Permission to use, copy, modify, and/or distribute this software for
any purpose with or without fee is hereby granted, provided that the
above copyright notice and this permission notice appear in all copies.

License for flock
fish also contains small amounts of code from NetBSD, namely the flock
fallback function. This code is copyright 2001 The NetBSD Foundation,
Inc., and derived from software contributed to The NetBSD Foundation by
Todd Vierling.

The NetBSD license follows.

Redistribution and use in source and binary forms, with or without mod-
ification, are permitted provided that the following conditions are
met:

1. Redistributions of source code must retain the above copyright no-
tice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBU-
TORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MIT License
fish includes a copy of AngularJS, which is copyright 2010-2012 Google,
Inc. and licensed under the MIT License. It also includes the Dracula
theme, which is copyright 2018 Dracula Team, and the Nord theme, which
is copyright 2016-present Sven Greb. These themes are also used under
the MIT license.

The MIT license follows.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Soft-
ware"), to deal in the Software without restriction, including without
limitation the rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or sell copies of the Software, and to permit persons
to whom the Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MER-
CHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFT-
WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

AUTHOR
fish-shell developers

3.7 Apr 14, 2025 FISH-DOC(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=fish-doc&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages