FreeBSD Manual Pages
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 pro-
grams. fish offers a command-line interface focused on usability and interactive
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 immediately,
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 in-
formation.
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 an overview of fish's scripting language, see The Fish Language. If it
would be useful in a script file, it's here.
For information on using fish interactively, see Interactive use. If it's
about key presses, syntax highlighting or anything else that needs an in-
teractive terminal session, look here.
If you need to install fish first, read on, the rest of this document will
tell you how to get, install and configure fish.
SETUP
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 <https://fishshell.com/>.
To install the development version of fish, see the instructions on the -
project's GitHub page <https://github.com/fish-shell/fish-shell>.
Starting and Exiting
Once fish has been installed, open a terminal. If fish is not the default
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 de-
fault.
The simplest method is to set your terminal emulator (e.g. GNOME Terminal,
Apple's Terminal.app, or Konsole) to start fish directly. See its configu-
ration and set the program to start to /usr/local/bin/fish (the exact path
depends on how you installed fish).
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 incorrect
PATH. Some operating systems, including a number of Linux distributions,
require the login shell to be Bourne-compatible and to read configura-
tion 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:
> command -v fish | sudo tee -a /etc/shells
2. Change your default shell with:
> chsh -s "$(command -v fish)"
To change it back to another shell, substitute fish with bash, tcsh or zsh
as appropriate in the above command.
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 execute them.
For this, they are expected to have a first line, the shebang 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 inter-
preter /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 specifying
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 be-
fore 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 easier.
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 <https://github.com/fish-shell/fish-shell/>
* The official Matrix room <https://matrix.to/#/#fish-shell:matrix.org>
* The official mailing list at fish-users@lists.sourceforge.net
<https://lists.sourceforge.net/lists/listinfo/fish-users>
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 one command using
the key=value some command syntax, like in other shells. The two lines be-
low 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 universal
and exported. Typically it makes sense to make an exported variable 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 mul-
tiple 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 before 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 inherits.
If this is not possible, add a statement to your configuration file (usu-
ally ~/.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-interac-
tive 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 --reset
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 acti-
vated 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 started by fish_config, or alter the
fish_color family of environment variables, or use the fish_config theme
subcommand, like:
> fish_config theme show
# to demonstrate all the colorschemes
> fish_config theme choose coolbeans
# to load the "coolbeans" theme
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 (^a) or down (^a) arrow
keys to navigate through history matches, or press ctrl-r to open the his-
tory in a searchable pager. In this pager you can press ctrl-r or ctrl-s to
move to older or younger history respectively.
Additional default key bindings include ctrl-p (up) and ctrl-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 be-
fore 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 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, up recalls whole lines, starting from
the last executed line. So instead of typing !!, you would hit the up-ar-
row.
* 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 recalled
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. If you
want to see more context, you can press ctrl-r to open the history in the
pager.
* alt-up recalls individual arguments, starting from the last argument in
the last executed line. This can be used instead of "!$".
See documentation for more details about line editing in fish.
That being said, you can use Abbreviations to implement history substitu-
tion. Here's !! only:
function last_history_item; echo $history[1]; end
abbr -a !! --position anywhere --function last_history_item
Run this and !! will be replaced with the last history entry, anywhere on
the commandline. Put it into config.fish to keep it.
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 newlines,
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" sepa-
rately.
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, splitting
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 only interested in success or failure, you can run the command
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 informa-
tion.
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-*
or
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 receiving pro-
gram.
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.
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 "Connection
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 lo-
gin or non-interactive or non-login shell.
This simplifies matters, but it also means when config.fish generates out-
put, 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 itself
need to agree on the width of characters in order to handle cursor move-
ment.
This is more important to fish than other shells because features like syn-
tax 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 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_ambiguous_width to the
correct value.
* The character is an emoji and your system only supports Unicode 8. In
this case set $fish_emoji_width to 1.
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 terminal's font ren-
dering.
* Different widths for multiple ambiguous width characters - there is no
way for fish to know which width you assign to each character.
fish does not work in a specific terminal
The terminal might not meet all of fish's requirements. Please report this
to your terminal's and to fish's issue tracker.
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, use that package manager's
uninstall function. If you built fish yourself, assuming you installed 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
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 Language
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-tutorial.
Autosuggestions
fish suggests commands as you type, based on command history, completions,
and valid file paths. As you type commands, you will see a suggestion of-
fered 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
right (^a) or ctrl-f. To accept the first suggested word, press alt-right
(^a) or alt-f. If the autosuggestion is not what you want, 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 efficient
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
exactly one possibility, it inserts it. If it finds more, it inserts 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, pageup / pagedown, tab or
shift-tab. Pressing ctrl-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 completions.
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 some-
one else. For that, see Writing your own completions.
Completion scripts are loaded on demand, 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 ~/.config/fish/comple-
tions/name-of-command.fish and fish will find them automatically.
Syntax highlighting
Fish interprets the command line as it is typed and uses syntax highlight-
ing to provide feedback. The most important feedback is the detection 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 variables
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 from fish:
# disable nearly all coloring
fish_config theme choose none
# restore fish's default theme
fish_config theme choose default
Or, to see all themes, right in your terminal:
fish_config theme show
To update the theme of all shell sessions without restarting them, first
have those sessions define an event handler by adding the following to your
config.fish and restarting them:
function apply-my-theme --on-variable=my_theme
fish_config theme choose $my_theme
end
Then, set the corresponding universal variable from any session:
> set -U my_theme lava
> set -U my_theme snow-day
Syntax highlighting variables
The colors used by fish for syntax highlighting can be configured by chang-
ing the values of various variables. The value of these variables can be
one of the colors accepted by the set_color command. Options accepted by
set_color like --foreground=, --background=, --bold, --dim, --italics,
--reverse, --strikethrough, --underline and --underline-color= are also ac-
cepted.
Example: to make errors highlighted and red, use:
set fish_color_error red --bold
The following variables are available to change the highlighting colors in
fish:
+------------------------------+-----------------------------+
| Variable | Meaning |
+------------------------------+-----------------------------+
| | default color |
| fish_color_normal | |
+------------------------------+-----------------------------+
| | commands like echo |
| fish_color_command | |
+------------------------------+-----------------------------+
| | keywords like if - this |
| fish_color_keyword | falls back on the command |
| | color if unset |
+------------------------------+-----------------------------+
| | quoted text like "abc" |
| fish_color_quote | |
+------------------------------+-----------------------------+
| | IO redirections like |
| fish_color_redirection | >/dev/null |
+------------------------------+-----------------------------+
| | process separators like ; |
| fish_color_end | and & |
+------------------------------+-----------------------------+
| | syntax errors |
| fish_color_error | |
+------------------------------+-----------------------------+
| | ordinary command parameters |
| fish_color_param | |
+------------------------------+-----------------------------+
| | parameters and redirection |
| fish_color_valid_path | targets that are filenames |
| | (if the file exists) |
+------------------------------+-----------------------------+
| | options starting with "-", |
| fish_color_option | up to the first "--" para- |
| | meter |
+------------------------------+-----------------------------+
| | comments like '# important' |
| fish_color_comment | |
+------------------------------+-----------------------------+
| | selected text in vi visual |
| fish_color_selection | mode |
+------------------------------+-----------------------------+
| | parameter expansion opera- |
| fish_color_operator | tors like * and ~ |
+------------------------------+-----------------------------+
| | character escapes like \n |
| fish_color_escape | and \x70 |
+------------------------------+-----------------------------+
| | autosuggestions (the pro- |
| fish_color_autosugges- | posed rest of a command) |
| tion | |
+------------------------------+-----------------------------+
| | the current working direc- |
| fish_color_cwd | tory in the default prompt |
+------------------------------+-----------------------------+
| | the current working direc- |
| fish_color_cwd_root | tory in the default prompt |
| | for the root user |
+------------------------------+-----------------------------+
| | the username in the default |
| fish_color_user | prompt |
+------------------------------+-----------------------------+
| | the hostname in the default |
| fish_color_host | prompt |
+------------------------------+-----------------------------+
| | the hostname in the default |
| fish_color_host_remote | prompt for remote sessions |
| | (like ssh) |
+------------------------------+-----------------------------+
| | the last command's nonzero |
| fish_color_status | exit code in the default |
| | prompt |
+------------------------------+-----------------------------+
| | the '^C' indicator on a |
| fish_color_cancel | canceled command |
+------------------------------+-----------------------------+
| | history search matches and |
| fish_color_search_match | selected pager items (back- |
| | ground only) |
+------------------------------+-----------------------------+
| | the current position in the |
| fish_color_history_cur- | history for commands like |
| rent | dirh and cdh |
+------------------------------+-----------------------------+
If a variable isn't set or is empty after subtracting any --theme=THEME op-
tions, 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 modi-
fiers, 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
Variables affecting the pager colors:
+--------------------------------+-----------------------------+
| Variable | Meaning |
+--------------------------------+-----------------------------+
| | the progress bar at the |
| fish_pager_color_progress | bottom left corner |
+--------------------------------+-----------------------------+
| | the background color of a |
| fish_pager_color_back- | line |
| ground | |
+--------------------------------+-----------------------------+
| | the prefix string, i.e. the |
| fish_pager_color_prefix | string that is to be com- |
| | pleted |
+--------------------------------+-----------------------------+
| | the completion itself, i.e. |
| fish_pager_color_comple- | the proposed rest of the |
| tion | string |
+--------------------------------+-----------------------------+
| | the completion description |
| fish_pager_color_descrip- | |
| tion | |
+--------------------------------+-----------------------------+
| | background of the selected |
| fish_pager_color_se- | completion |
| lected_background | |
+--------------------------------+-----------------------------+
| | prefix of the selected com- |
| fish_pager_color_se- | pletion |
| lected_prefix | |
+--------------------------------+-----------------------------+
| | suffix of the selected com- |
| fish_pager_color_se- | pletion |
| lected_completion | |
+--------------------------------+-----------------------------+
| | description of the selected |
| fish_pager_color_se- | completion |
| lected_description | |
+--------------------------------+-----------------------------+
| | background of every second |
| fish_pager_color_sec- | unselected completion |
| ondary_background | |
+--------------------------------+-----------------------------+
| | prefix of every second uns- |
| fish_pager_color_sec- | elected completion |
| ondary_prefix | |
+--------------------------------+-----------------------------+
| | suffix of every second uns- |
| fish_pager_color_sec- | elected completion |
| ondary_completion | |
+--------------------------------+-----------------------------+
| | description of every second |
| fish_pager_color_sec- | unselected completion |
| ondary_description | |
+--------------------------------+-----------------------------+
When the secondary or selected variables aren't set or are empty, the nor-
mal variables are used, except for $fish_pager_color_selected_background,
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 position
will turn into git checkout in the command line. If you want to use a lit-
eral gco sometimes, use ctrl-space [1].
Abbreviations are a lot more powerful than just replacing literal strings.
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 .... ex-
pands to cd ../../../.
The advantage over aliases is that you can see the actual command before
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 ctrl-space is bound to just in-
serting a space.
Programmable prompt
When it is fish's turn to ask for input (like after it started or the com-
mand ended), it will show a prompt. Often this looks something like:
you@hostname ~>
This prompt is determined by running the fish_prompt and fish_right_prompt
functions.
The output of the former is displayed on the left and the latter's output
on the right side of the terminal. For vi mode, the output of
fish_mode_prompt will be prepended on the left.
If fish_transient_prompt is set to 1, fish will redraw the prompt with a
--final-rendering argument before running a commandline, allowing you to
change it before pushing it to the scrollback.
Fish ships with a few prompts which you can see with fish_config. If you
run just fish_config it will open a web interface [2] where you'll be shown
the prompts and can pick which one you want. fish_config prompt show will
show you the prompts right in your terminal.
For example fish_config prompt choose disco will temporarily select the
"disco" prompt. If you like it and decide to keep it, run fish_config
prompt save.
You can also change these functions yourself by running funced fish_prompt
and funcsave fish_prompt once you are happy with the result (or
fish_right_prompt if you want to change that).
[2] The web interface runs purely locally on your computer and requires
python to be installed.
Configurable greeting
When it is started interactively, fish tries to run the fish_greeting func-
tion. The default fish_greeting prints a simple message. 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.
Programmable title
Most terminals allow setting the text displayed in the titlebar of the ter-
minal window. Fish does this by running the fish_title function. It is
executed before and after a command 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_title function is called. The first argument will con-
tain the most recently executed foreground command as a string.
The default 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
Command line editor
The fish editor features copy and paste, a searchable history and many edi-
tor functions that can be bound to special keyboard shortcuts.
Like bash and other shells, fish includes two sets of keyboard shortcuts
(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 cre-
ating 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 implemen-
tation. 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 edi-
tor.
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 token
and starts the pager's search mode. tab is the same as ctrl-i.
* left (^a) and right (^a) move the cursor left or right by one character. If
the cursor is already at the end of the line, and an autosuggestion is
available, right (^a) 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. This is useful to add
a line to a commandline that's already complete.
* alt-left (^a) and alt-right (^a) move the cursor left or right by one argu-
ment (or one word on macOS). If the command line is empty, they move
forward/backward in the directory history. If the cursor is already at
the end of the line, and an autosuggestion is available, alt-right (^a)
(or alt-f) accepts the first argument (or word on macOS) in the sugges-
tion.
* ctrl-left (^a) and ctrl-right (^a) move the cursor left or right by one
word. These accept one word of the autosuggestion - the part they'd move
over.
* shift-left (^a) and shift-right (^a) move the cursor one word left or
right, without stopping on punctuation. These accept one big word of the
autosuggestion.
* up (^a) and down (^a) (or ctrl-p and ctrl-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-up (^a) and alt-down (^a) search the command history for the previ-
ous/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.
* ctrl-c interrupts/kills whatever is running (SIGINT).
* ctrl-d deletes one character to the right of the cursor. If the command
line is empty, ctrl-d will exit fish.
* ctrl-u removes contents from the beginning of line to the cursor (moving
it to the killring).
* ctrl-l pushes any text above the prompt to the terminal's scrollback,
then clears and repaints the screen.
* ctrl-w removes the previous path component (everything up to the previous
"/", ":" or "@") (moving it to the Copy and paste (Kill Ring)).
* ctrl-x copies the current buffer to the system's clipboard, ctrl-v in-
serts the clipboard contents. (see fish_clipboard_copy and
fish_clipboard_paste)
* alt-d moves the next word to the Copy and paste (Kill Ring).
* ctrl-delete moves the next word (or next argument on macOS) to the Copy
and paste (Kill Ring).
* alt-d lists the directory history if the command line is empty.
* alt-delete moves the next argument (or word on macOS) to the Copy and
paste (Kill Ring).
* shift-delete removes the current history item or autosuggestion from the
command history.
* alt-h (or f1) shows the manual page for the current command, if one ex-
ists.
* alt-l lists the contents of the current directory, unless the cursor is
over a directory argument, in which case the contents of that directory
will be listed.
* alt-o opens the file at the cursor in a pager. If the cursor is in com-
mand position and the command is a script, it will instead open that
script in your editor. The editor is chosen from the first available of
the $VISUAL or $EDITOR variables.
* alt-p adds the string &| less; to the end of the job under the cursor.
The result is that the output of the command will be paged. If you set
the PAGER variable, its value is used instead of less.
* alt-w prints a short description of the command under the cursor.
* alt-e edits the current command line in an external editor. The editor is
chosen from the first available of the $VISUAL or $EDITOR variables.
* 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. If sudo is not installed,
various similar commands are tried: doas, please, and run0.
* ctrl-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 de-
fault.
* home or ctrl-a moves the cursor to the beginning of the line.
* end or ctrl-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 ctrl-e ac-
cepts the autosuggestion.
* ctrl-b, ctrl-f move the cursor one character left or right or accept the
autosuggestion just like the left (^a) and right (^a) shared bindings
(which are available as well).
* alt-b, alt-f move the cursor one word left or right, or accept one word
of the autosuggestion. If the command line is empty, moves forward/back-
ward in the directory history instead.
* ctrl-n, ctrl-p move the cursor up/down or through history, like the up
and down arrow shared bindings.
* delete or backspace or ctrl-h removes one character forwards or backwards
respectively.
* ctrl-backspace removes one word backwards and alt-backspace removes one
argument backwards. On macOS, it's the other way round.
* alt-< moves to the beginning of the commandline, alt-> moves to the end.
* ctrl-k deletes from the cursor to the end of line (moving it to the Copy
and paste (Kill Ring)).
* escape and ctrl-g cancel the current operation. Immediately after an un-
ambiguous completion this undoes it.
* alt-c capitalizes the current word.
* alt-u makes the current word uppercase.
* ctrl-t transposes the last two characters.
* alt-t transposes the last two words.
* ctrl-z, ctrl-_ (ctrl-/ on some terminals) undo the most recent edit of
the line.
* alt-/ or ctrl-shift-z reverts the most recent undo.
* ctrl-r opens the history in a pager. This will show history entries
matching the search, a few at a time. Pressing ctrl-r again will search
older entries, pressing ctrl-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. Initially,
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 indica-
tor 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 ex-
ists, 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/functions/fish_mode_prompt.fish.
(Bindings that change the mode are supposed to call the repaint-mode bind
function, see bind)
The fish_vi_cursor function will be used to change the cursor's shape de-
pending 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 parameters
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 capabil-
ities necessary to do this.
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 contain-
ing 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. In multi-line commands, they move the cursor up and down re-
spectively.
* i enters insert mode at the current cursor position.
* 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.
* 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).
* 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.
* ctrl-r redoes the most recent edit.
* [ and ] search the command history for the previous/next token containing
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 matching
the search, a few at a time. Pressing it again will search older entries,
pressing ctrl-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 / G moves the cursor to the beginning/end of the commandline, respec-
tively.
* ~ toggles the case (upper/lower) of the character and moves to the next
character.
* g,u lowercases to the end of the word.
* g,U uppercases to the end of the word.
* :,q exits fish.
Insert mode
* escape enters command mode.
* backspace removes one character to the left.
* ctrl-n accepts the autosuggestion.
Visual mode
* left (``^a`) and right`(``^a`) 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 enter
command mode.
* escape and ctrl-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.
* g,u lowercases the selection, and enters command mode.
* g,U uppercases 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:
# Prints ``^C`` and a new prompt
bind ctrl-c cancel-commandline
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 default,
you can erase it again:
bind --erase ctrl-c
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 your-
self.
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 ctrl-c 'commandline -r ""'
Key sequences
To find out the name of a key, you can use fish_key_reader.
> fish_key_reader # Press Alt + right-arrow
Press a key:
bind alt-right 'do something'
Note that the historical way the terminal encodes keys and sends them to
the application (fish, in this case) makes a lot of combinations indistin-
guishable or unbindable. In the usual encoding, ctrl-i is the same as the
tab key, and shift cannot be detected when ctrl is also pressed.
There are more powerful encoding schemes, and fish tries to tell the termi-
nal to turn them on, but there are still many terminals that do not support
them. When fish_key_reader prints the same sequence for two different keys,
then that is because your terminal sends the same sequence for them, and
there isn't anything fish can do about it. It is our hope that these
schemes will become more widespread, making input more flexible.
In the historical scheme, escape is the same thing as alt in a terminal. To
distinguish between pressing escape and then another key, and pressing alt
and that key (or an escape sequence the key sends), fish waits for a cer-
tain 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 the sequence j,k 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 j,k 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 ctrl-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 "yanking") use ctrl-y (the yank
input function). After pasting, use alt-y (yank-pop) to rotate to the pre-
vious kill.
Copy and paste from outside are also supported, both via the ctrl-x /
ctrl-v bindings (the fish_clipboard_copy and fish_clipboard_paste functions
[3]) and via the terminal's paste function, for which fish enables "Brack-
eted Paste Mode", so it can tell a paste from manually entered text. In
addition, when pasting inside single quotes, pasted single quotes and back-
slashes are automatically escaped so that the result can be used as a sin-
gle token 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 cur-
sor 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 (exclu-
sive). 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.
[3] 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 sev-
eral 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, es-
caping 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 arrow 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 pressing 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 history search, only the
commands containing the string entered into the command line are shown.
By pressing alt-up (^a) and alt-down (^a), a history search is also per-
formed, but instead of searching for a complete commandline, each command-
line is broken into separate elements 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 entries in
one page, press ctrl-r [4] again to move to the next page and ctrl-s [5] to
move to the previous page. You can change the text to refine 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 escape or pagedown.
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_history
(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>_history file); both
before starting the shell and while the shell is running.
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-up (^a) to search for previously typed words containing 'm'.
[4] Or another binding that triggers the history-pager input function. See
bind for a list.
[5] Or another binding that triggers the pager-toggle-search input func-
tion.
Private mode
Fish has a private mode, in which command history will not be written to
the history file on disk. To enable it, either set $fish_private_mode to a
non-empty value, or launch with fish --private (or fish -P for short).
If you launch fish with -P, it 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 privacy
and alter the behavior of your own fish scripts.
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-left (^a)
* nextd moves forward through the history. It is bound to alt-right (^a)
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 work-
ing directory
* popd removes the directory on top of the stack and changes the current
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 executed 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 repeating
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 re-
quired.
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" command,
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 file-
type
* less: Display the contents of files
Commands and arguments are separated by the space character ' '. Every com-
mand ends with either a newline (by pressing the return key) or a semicolon
;. Multiple commands can be written on the same line by separating them
with semicolons.
A switch is a very common special type of argument. Switches almost always
start with one or more hyphens - and alter the way a command operates. For
example, the ls command usually lists the names of all files and directo-
ries 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, per-
missions, owner, and modification time of each file.
Switches differ between commands and are usually documented on a command's
manual page. There are some switches, however, that are common to most com-
mands. 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-command-here to get informa-
tion 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 im-
plement them as external commands. In echo foo, the "echo" is a builtin.
* Command: A program that the shell can run, or more specifically an exter-
nal 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 characters
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 expansion or para-
meter expansion) is performed, and escape sequences (for example, \n) are
ignored. Within quotes, whitespace is not used to separate arguments, al-
lowing quoted arguments to contain spaces.
The only meaningful escape sequences in single quotes are \', which escapes
a single quote and \\, which escapes the backslash symbol. The only mean-
ingful 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-something".
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 invalid
strings. Typically fish is run with the ASCII or UTF-8 encoding, so any-
thing 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 charac-
ter.
* \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 sequence
generated by pressing the control key and the specified letter. For exam-
ple, \ci is the tab character
Some characters have special meaning to the shell. For example, an apostro-
phe ' disables expansion (see Quotes). To tell the shell to treat these
characters literally, escape them with a backslash. For example, the com-
mand:
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 latter 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 "con-
tinuation" 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 redirec-
tion. 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 read standard input from a file or /dev/null if it can't be read, 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 destination de-
scriptor.
* 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_output.txt
redirects both stdout and stderr to the file all_output.txt. This is equiv-
alent to echo hello > all_output.txt 2>&1. You can also use &>> to append
both stdout and stderr to the same destination.
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>>DESTINATION_FILE.
File descriptors cannot be used with a <? input redirection, only a regular
< one.
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"
# print all lines that include "foo" from myfile, or nothing if it doesn't exist.
string match '*foo*' <?myfile
It is an error to redirect a builtin, function, or block to a file descrip-
tor above 2. However this is supported for external commands.
[1] Previous versions of fish also allowed specifying this as ^DESTINA-
TION, but that made another character special so it was deprecated 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 out-
put 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 &| (as well as the |& alias which is also sup-
ported by Bash) both redirect stdout and stderr to the same process.
[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 descriptors
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:
# 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
print 2>&1 | less
# or
print &| 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 it just started. Sometimes, you want to con-
tinue 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 interface.
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 con-
trol to fish by pressing ctrl-z (also referred to as ^Z). Once back at the
fish commandline, you can start other programs and do anything you want. If
you then want you can go back to the suspended command 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 command
will not execute correctly.
If the & character is followed by a non-separating character, it is not in-
terpreted as background operator. Separating characters are whitespace and
the characters ;<>&|.
Functions
Functions are programs written in the fish syntax. They group together var-
ious 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 writing ll on the commandline. The second line tells fish that
the command ls -l $argv should be called when ll is invoked. $argv is a
list variable, which always contains all arguments sent to the function. In
the example above, these are 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 'ao' for a normal user and a '#' for root.
set -l user_char 'ao'
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 behavior
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 sys-
tems 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 addi-
tional 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 do-
ing so (which is hopefully in your interest).
To easily create a function of this form, you can use the alias command.
Unlike other shells, this just makes functions - fish has no separate con-
cept of an "alias", we just use the word for a simple wrapping function
like this. alias immediately creates a function. Consider using alias
--save or funcsave to save the created function into an autoload file in-
stead of recreating the alias each time.
For an alternative, try abbreviations. These are words that are expanded
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 automati-
cally 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 consisting of
the name of the function plus the suffix .fish and loads the first it
finds.
For example if you try to execute something called banana, fish will go
through all directories in $fish_function_path looking for a file called
banana.fish and load the first one it finds.
By default $fish_function_path contains the following:
* A directory for users to keep their own functions, usually ~/.con-
fig/fish/functions (controlled by the XDG_CONFIG_HOME environment vari-
able).
* 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 ~/.local/share/fish,
controlled by the XDG_DATA_HOME environment variable) and in the
XDG_DATA_DIRS environment variable, in a subdirectory called fish/ven-
dor_functions.d. The default value for XDG_DATA_DIRS is usually
/usr/share/fish/vendor_functions.d and /usr/local/share/fish/vendor_func-
tions.d.
If you are unsure, your functions probably belong in ~/.config/fish/func-
tions.
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 automat-
ically 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 informa-
tion.
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_func-
tion_path, e.g. if your administrator has put something into
/etc/fish/functions that you want to skip.
If you are developing another program and want to install fish functions
for it, install them to the "vendor" functions directory. As this path
varies from system to system, you can use pkgconfig to discover it with the
output of pkg-config --variable functionsdir fish. Your installation system
should support a custom path to override the pkgconfig path, as other dis-
tributors 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 multi-
ple lines, 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 &&/|| syn-
tax.
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 ends after the first job, there
is no then here. Combiners like and and or extend the condition.
A more complicated example with a command substitution:
if test "$(uname)" = Linux
echo I like penguins
end
Because test can be used for many different tests, it is important to quote
variables and command substitutions. If the $(uname) was not quoted, and
uname printed nothing it would run test = Linux, which is an error.
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:
# Check 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
Other things commonly used in if-conditions:
* contains - to see if a list contains a specific element (if contains --
/usr/bin $PATH)
* string - to e.g. match strings (if string match -q -- '*-' $arg)
* path - to check if paths of some criteria exist (if path is -rf --
~/.config/fish/config.fish)
* type - to see if a command, function or builtin exists (if type -q git)
The switch statement
The switch command is used to execute one of possibly many blocks of com-
mands 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 ex-
ample:
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 command
if the first succeeded, while or or || run it if the first failed. For ex-
ample:
# $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 determine
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 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 $status 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 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 expansions:
* 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 use-
less computation.
Wildcards ("Globbing")
When a parameter includes an unquoted * star (or "asterisk") or a ? ques-
tion 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 descends
into subdirectories. If ** is a segment by itself, that segment 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 be an ordinary
character.
Wildcard matches are sorted case insensitively. When sorting matches con-
taining 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 directories
in your home directory.
For most commands, if any wildcard fails to expand, the command is not exe-
cuted, $status is set to nonzero, and a warning is printed. This behavior
is like what bash does with shopt -s failglob. There are exceptions, namely
set and path, overriding variables in overrides, count and for. Their globs
will instead expand to zero arguments (so the command won't see them at
all), like with shopt -s nullglob in bash.
Examples:
# List the .foo files, or warns if there aren't any.
ls *.foo
# List the .foo files, if any.
set foos *.foo
if count $foos >/dev/null
ls $foos
end
Unlike bash (by default), fish will not pass on the literal glob character
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 expansion".
This is the replacing of a dollar sign ($) followed by a variable name with
the _value_ of that variable.
A simple example:
echo $HOME
which will replace $HOME with the home directory of the current user, and
pass it to echo, which will then print it.
Some variables like $HOME are already set because fish sets them by default
or because fish's parent process passed them to fish when it started it.
You can define your own variables by setting them with set:
set my_directory /home/cooluser/mystuff
ls $my_directory
# shows the contents of /home/cooluser/mystuff
For more on how setting variables works, see Shell variables and the fol-
lowing 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. How-
ever, 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
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].
Fish variables are all lists, and they are split into elements when they
are set - that means it is important to decide whether to use quotes or not
with set:
set foo 1 2 3 # a variable with three elements
rm $foo # runs the equivalent of `rm 1 2 3` - trying to delete three files: 1, 2 and 3.
rm "$foo" # runs `rm '1 2 3'` - trying to delete one file called '1 2 3'
set foo # an empty variable
rm $foo # runs `rm` without arguments
rm "$foo" # runs the equivalent of `rm ''`
set foo "1 2 3"
rm $foo # runs the equivalent of `rm '1 2 3'` - trying to delete one file
rm "$foo" # same thing
This is unlike other shells, which do what is known as "Word Splitting",
where they split the variable when it is used in an expansion. E.g. in
bash:
foo="1 2 3"
rm $foo # runs the equivalent of `rm 1 2 3`
rm "$foo" # runs the equivalent of `rm '1 2 3'`
This is the cause of very common problems with filenames with spaces in
bash scripts.
In fish, unquoted 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 ele-
ments will expand to each of those elements separately.
If a variable expands to nothing, it will cancel out any other strings at-
tached to it. See the Combining Lists section for more information.
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 "dereference"
operator (the * in C or C++), like in the following code:
set foo a b c
set a 10; set b 20; set c 30
for i in (seq (count $$foo))
echo $$foo[$i]
end
# Output is:
# 10
# 20
# 30
$$foo[$i] is "the value of the variable named by $foo[$i]".
This can also be used to give a variable name to a function:
function print_var
for arg in $argv
echo Variable $arg is $$arg
end
end
set -g foo 1 2 3
set -g bar a b c
print_var foo bar
# prints "Variable foo is 1 2 3" and "Variable bar is a b c"
Of course the variable will have to be accessible from the function, so it
needs to be global/universal or exported. It also can't clash with a vari-
able name used inside the function. So if we had made $foo there a local
variable, or if we had named it "arg" instead, it would not have worked.
When using this feature together with slices, the slices 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).
Some more examples:
set listone 1 2 3
set listtwo 4 5 6
set var listone listtwo
echo $$var
# Output is 1 2 3 4 5 6
echo $$var[1]
# Output is 1 2 3
echo $$var[2][3]
# $var[2] is listtwo, third element of that is 6, output is 6
echo $$var[..][2]
# The second element of every variable, so output is 2 5
Variables as command
Like other shells, you can run the value of a variable as a command.
> set -g EDITOR emacs
> $EDITOR foo # opens emacs, possibly the GUI version
If you want to give the command an argument inside the variable it needs to
be a separate element:
> set EDITOR emacs -nw
> $EDITOR foo # opens emacs in the terminal even if the GUI is installed
> set EDITOR "emacs -nw"
> $EDITOR foo # tries to find a command called "emacs -nw"
Also like other shells, this only works with commands, builtins and func-
tions - it will not work with keywords because they have syntactical impor-
tance.
For instance set if $if won't allow you to make an if-block, and set cmd
command won't allow you to use the command decorator, but only uses like
$cmd -q foo.
Command substitution
A command substitution is an expansion that uses the output of a command 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 arguments to
echo. So the inner command (the pwd) is run first and has to complete be-
fore 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.
Command substitutions can also be double-quoted:
echo "$(pwd)"
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.
Fish also allows spelling command substitutions without the dollar, like
echo (pwd). This variant will not be expanded in double-quotes (echo
"(pwd)" will print (pwd)).
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 pass it via a
pipe, like:
grep fish myanimallist1 | wc -l
but if you need multiple or the command doesn't read from standard input,
"process substitution" is useful. Other shells allow this via foo <(bar)
<(baz), and fish uses the psub command:
# Compare only 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 1 GiB on the data it will read in a command
substitution. If that limit is reached the command (all of it, not just the
command substitution - the outer command won't be executed at all) fails
and $status is set to 122. This is so command substitutions can't cause the
system to go out of memory, because typically your operating system has a
much lower limit, so reading more than that would be useless and harmful.
This limit can be adjusted with the fish_read_limit variable (0 meaning no
limit). This limit also affects the read command.
[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 ex-
panded with each element becoming a new parameter, with the surrounding
string attached. This is useful to save on typing, and to separate a vari-
able 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 Combining Lists section):
> echo foo-{$undefinedvar}
# Output is an empty line, like a bare `echo`.
If there is nothing between a brace and a comma or two commas, it's inter-
preted as an empty element:
> echo {,,/usr}/bin
/bin /bin /usr/bin
To use a "," as an element, quote or escape it.
The very first character of a command token is never interpreted as expand-
ing brace, because it's the beginning of a compound statement:
> {echo hello, && echo world}
hello,
world
Combining lists
Fish expands lists like brace expansions:
>_ set -l foo x y z
>_ echo 1$foo
# Any element of $foo is combined with the "1":
1x 1y 1z
>_ echo {good,bad}" apples"
# Any element of the {} is combined with the " apples":
good apples bad apples
# Or we can mix the two:
>_ echo {good,bad}" "$foo
good x bad x good y bad y good z bad z
Any string attached to a list will be concatenated to each element.
Two lists will be expanded in all combinations - every element of the
first with every element of the second:
>_ set -l a x y z; set -l b 1 2 3
>_ echo $a$b # same as {x,y,z}{1,2,3}
x1 y1 z1 x2 y2 z2 x3 y3 z3
A result of this is that, if a list has no elements, this combines the
string with no elements, which means the entire token is removed!
>_ set -l c # <- this list is empty!
>_ echo {$c}word
# Output is an empty line - the "word" part is gone
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 directo-
ries in it. And if there are no directories in PATH, the right answer here
is to expand to no files.
Sometimes this may be unwanted, especially that tokens can disappear after
expansion. In those cases, you should double-quote variables - echo
"$c"word.
This also happens after command substitution. To avoid tokens disappearing
there, make the inner command return a trailing newline, or double-quote
it:
>_ 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
>_ echo "$(printf '%s' '')"banana
# quotes mean this is one argument, the banana stays
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 substitution out-
puts. 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 index.
If a list has 5 elements the indices go from 1 to 5, so a range of 2..16
will only go from element 2 to element 5.
If the end is negative the range always goes up, so 2..-2 will go from ele-
ment 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 se-
quence.
Multiple ranges are also possible, separated with a space.
Some examples:
echo (seq 10)[1 2 3]
# Prints: 1 2 3
# Limit the command substitution output
echo (seq 10)[2..5]
# Uses elements from 2 to 5
# Output is: 2 3 4 5
echo (seq 10)[7..]
# Prints: 7 8 9 10
# Use overlapping ranges:
echo (seq 10)[2..5 1..3]
# Takes elements from 2 to 5 and then elements from 1 to 3
# Output is: 2 3 4 5 1 2 3
# Reverse output
echo (seq 10)[-1..1]
# Uses elements from the last output line to
# the first one in reverse direction
# Output is: 10 9 8 7 6 5 4 3 2 1
# The command substitution has only one line,
# so these will result in empty output:
echo (echo one)[2..-1]
echo (echo one)[-3..1]
The same works when setting or expanding variables:
# Reverse path variable
set PATH $PATH[-1..1]
# or
set PATH[-1..1] $PATH
# Use only n last items of the PATH
set n -3
echo $PATH[$n..-1]
Variables can be used as indices for expansion of variables, like so:
set index 2
set letters a b c d
echo $letters[$index] # returns 'b'
However using variables as indices for command substitution is currently
not supported, so:
echo (seq 5)[$index] # This won't work
set sequence (seq 5) # It needs to be written on two lines like this.
echo $sequence[$index] # returns '2'
When using indirect variable expansion with multiple $ ($$name), you have
to give all indices up to the variable you want to slice:
> set -l list 1 2 3 4 5
> set -l name list
> echo $$name[1]
1 2 3 4 5
> echo $$name[1..-1][1..3] # or $$name[1][1..3], since $name only has one element.
1 2 3
Home directory expansion
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 result
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 and
command substitutions are performed from the inside and out.
Example:
If the current directory contains the files 'foo' and 'bar', the command
echo a(ls){1,2,3} will output abar1 abar2 abar3 afoo1 afoo2 afoo3.
Table Of Operators
Putting it together, here is a quick reference to fish's operators, all of
the special symbols it uses:
+------------+----------------------+----------------------+
| Symbol | Meaning | Example |
+------------+----------------------+----------------------+
| $ | Variable expansion | echo $foo |
+------------+----------------------+----------------------+
| $() and () | Command substitution | cat (grep foo bar) |
| | | or cat $(grep foo |
| | | bar) |
+------------+----------------------+----------------------+
| < and > | Redirection, like | git shortlog -nse . |
| | command > file | > authors |
+------------+----------------------+----------------------+
| | | Pipe, connect two or | foo | grep bar | |
| | more commands | grep baz |
+------------+----------------------+----------------------+
| ; | End of the command, | command1; command2 |
| | instead of a newline | |
+------------+----------------------+----------------------+
| & | Backgrounding | sleep 5m & |
+------------+----------------------+----------------------+
| {} | Brace expansion | ls {/usr,}/bin |
+------------+----------------------+----------------------+
| && and || | Combiners | mkdir foo && cd foo |
| | | or rm foo || exit |
+------------+----------------------+----------------------+
| * and ** | Wildcards | cat *.fish or count |
| | | **.jpg |
+------------+----------------------+----------------------+
| \\ | Escaping | echo foo\nbar or |
| | | echo \$foo |
+------------+----------------------+----------------------+
| '' and "" | Quoting | rm "file with |
| | | spaces" or echo |
| | | '$foo' |
+------------+----------------------+----------------------+
| ~ | Home directory ex- | ls ~/ or ls ~root/ |
| | pansion | |
+------------+----------------------+----------------------+
| # | Comments | echo Hello # this |
| | | isn't printed |
+------------+----------------------+----------------------+
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 exported 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
All variables in fish have a scope. For example they can be global or local
to a function or block:
# This variable is global, we can use it everywhere.
set --global name Patrick
# This variable is local, it will not be visible in a function we call from here.
set --local place "at the Krusty Krab"
function local
# This can find $name, but not $place
echo Hello this is $name $place
# This variable is local, it will not be available
# outside of this function
set --local instrument mayonnaise
echo My favorite instrument is $instrument
# This creates a local $name, and won't touch the global one
set --local name Spongebob
echo My best friend is $name
end
local
# Will print:
# Hello this is Patrick
# My favorite instrument is mayonnaise
# My best friend is Spongebob
echo $name, I am $place and my instrument is $instrument
# Will print:
# Patrick, I am at the Krusty Krab and my instrument is
There are four kinds of variable scopes in fish: universal, global, func-
tion and local variables.
* Universal variables are shared between all fish sessions a user is run-
ning on one computer. They are stored on disk and persist even after re-
boot.
* 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 auto-
matically erased when a specific block goes out of scope. A block of com-
mands is a series of commands that begins with one of the commands 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 --universal
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 variable
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 variable
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 uni-
versal 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
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
# This will not output anything, since the pirate was local
echo $pirate
# This will output the good Captain's speech
# since $captain had function-scope.
echo $captain
# This will output Sir Terry's wisdom.
echo $gnu
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 vari-
able accessible everywhere, make it global. When you need to persistently
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 similar).
Calling a command after setting a variable override will result in the ex-
act 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. All changes to universal variables are per-
sistent and instantly propagated across fish sessions.
Universal variables are stored in the file .config/fish/fish_variables. Do
not edit this file directly, as your edits may be overwritten. Edit the
variables through fish scripts or by using fish interactively instead.
Do not append to universal variables in config.fish, because these vari-
ables will then get longer with each new shell instance. Instead, set them
once at the command line.
Exporting variables
Variables in fish can be exported, so they will be inherited by any com-
mands started by fish. In particular, this is necessary for variables 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 vari-
ables 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 include
system configuration like PATH and locale variables.
Variables can be explicitly set to be exported with the -x or --export
switch, or not exported with the -u or --unexport switch. The exporting
rules when setting a variable are similar to the scoping rules for vari-
ables - when an option is passed it is respected, otherwise the variable's
existing state is used. If no option is passed and the variable didn't ex-
ist yet it is not exported.
As a naming convention, exported variables are in uppercase and unexported
variables are in lowercase.
For example:
set -gx ANDROID_HOME ~/.android # /opt/android-sdk
set -gx CDPATH . ~ (test -e ~/Videos; and echo ~/Videos)
set -gx EDITOR emacs -nw
set -gx GOPATH ~/dev/go
set -gx GTK2_RC_FILES "$XDG_CONFIG_HOME/gtk-2.0/gtkrc"
set -gx LESSHISTFILE "-"
Note: Exporting is not a scope, but an additional state. It typically makes
sense to make exported variables global as well, but local-exported vari-
ables 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 accessible to functions
whether they are exported or not.
Lists
Fish can store a list (or an "array" if you wish) of multiple strings in-
side 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 be-
cause it requires less subtracting of 1 and many common Unix tools like seq
work better with it (seq 5 prints 1 to 5, not 0 to 5). An invalid index is
silently ignored resulting in no value (not even an empty string, no argu-
ment 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, 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 vari-
able, the index will be taken from the end of the list. For example, the
index -1 is the last element of the list:
> set fruit apple orange banana
> echo $fruit[-1]
banana
> echo $fruit[-2..-1]
orange
banana
> echo $fruit[-1..1] # reverses the list
banana
orange
apple
As you see, you can use a range of indices, see 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 element as
one argument, so once you've set your list, you can 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 vari-
ous 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 error-prone.
A more robust approach to option handling is argparse, which checks the de-
fined options and puts them into various variables, leaving only the posi-
tional 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-delim-
ited path lists including PATH, CDPATH, MANPATH, PYTHONPATH, LANGUAGE (for
localization) 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 MYPATH 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 vari-
ables.
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 direc-
tory.
Locale Variables
Locale variables such as LANG, LC_ALL, LC_MESSAGES, LC_NUMERIC and
LC_TIME set the language option for the shell and subprograms. See
the section Locale variables and status language for more informa-
tion.
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 0, fish will not output 24-bit RGB true-color se-
quences but the nearest color on the 256 color palette (or the 16
color palette, if fish_term256 is 0). See also set_color. The de-
fault is 1 but for historical reasons, fish defaults to behaving as
if it was 0 on some terminals that are known to not support
true-color sequences.
fish_term256
If this is set to 0 and fish_term24bit is 0, translate RGB colors
down to the 16 color palette. Also, if this is set to 0, set_color
commands such as set_color ff0000 red will prefer the named color.
fish_ambiguous_width
controls the computed width of ambiguous-width characters. This
should be set to 1 if your terminal renders these characters as sin-
gle-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 "special" charac-
ters). It defaults to 2.
fish_autosuggestion_enabled
controls if Autosuggestions are enabled. Set it to 0 to disable,
anything else to enable. By default they are on.
fish_transient_prompt
If this is set to 1, fish will redraw prompts with a --final-render-
ing argument before running a commandline, allowing you to change it
before pushing it to the scrollback. This enables transient prompts.
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 disable.
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 escape se-
quence. The default is 30ms. Increasing it increases the latency but
allows pressing escape instead of alt for alt+character 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 sequences.
fish_complete_path
determines where fish looks for completion. When trying to complete
for a command, fish looks for files in the directories in this vari-
able.
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 func-
tion of the same name that can be overridden for more complicated
changes (see funced)
fish_history
the current history session name. If set, all subsequent commands
within an interactive fish session will be logged to a separate file
identified by the value of the variable. If unset, the default ses-
sion name "fish" is used. If set to an empty string, history is not
saved to disk (but is still available within the interactive ses-
sion).
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. Set it
to all to also trace execution of key bindings, event handlers as
well as prompt and title functions.
FISH_DEBUG
Controls which debug categories fish enables for output, analogous
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 uni-
versal 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.
SHELL_PROMPT_PREFIX
if set, this string is automatically prepended to the left prompt.
This is a standard environment variable that may be set by tools
like systemd's run0 to indicate special shell sessions.
SHELL_PROMPT_SUFFIX
if set, this string is automatically appended to the left prompt.
This is a standard environment variable that may be set by tools
like systemd's run0 to indicate special shell sessions.
SHELL_WELCOME
if set, this string is displayed when an interactive shell starts,
after the greeting. This is a standard environment variable that may
be set by tools like systemd's run0 to display session information.
BROWSER
your preferred web browser. If this variable is set, fish will use
the specified browser instead of the system default browser to dis-
play the fish documentation.
Fish also provides additional information through the values of certain en-
vironment 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 defined
when inside a function call, or if fish was invoked with a list of
arguments, like fish myscript.fish foo bar. This variable can be
changed.
argv_opts
argparse sets this to the list of successfully parsed options, in-
cluding option-arguments. This variable 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 values
are only used by fish if the operating system does not report the
size of the terminal. Both variables must be set in that case other-
wise a default of 80x24 will be used. They are updated when the win-
dow 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 substitu-
tion.
fish_pid
the process ID (PID) of the shell.
fish_terminal_color_theme
a read-only variable; set to light or dark when the terminal uses a
light or dark color theme respectively; set to unknown if the termi-
nal does not report its colors. Like status terminal, this is only
populated once the first interactive prompt is shown. This is used
in an --on-variable event handler to update syntax highlighting
variables whenever the terminal's color theme changes. See here for
how to specify light and dark variants in your theme.
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 variable 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 exe-
cuted pipe. See exit status.
SHLVL the level of nesting of shells. Fish increments this in interactive
shells, otherwise it only 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 example,
background jobs will not increment this).
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 variables,
while lowercase variables are not exported. (CMD_DURATION is an exception
for historical reasons). This rule is not enforced by fish, but it is good
coding practice to use casing to distinguish between exported and unex-
ported 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 executed 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 performed
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 con-
tained invalid characters.
* 124 means that the command was not executed because none of the wildcards
in the command produced any matches.
* 125 means that while an executable with the specified name was located,
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 some-
thing, negated with not (so 1 if it found something, 0 otherwise). $pipes-
tatus reflects the status of cat (which returns non-zero for example when
it couldn't find the file) and grep, without the negation.
So if both cat and grep succeeded, $status would be 1 because of the not,
and $pipestatus would be 0 and 0.
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", depending
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. In
UNIX, these are made up of several categories. The categories used by fish
are:
LANG This is the typical environment variable for specifying a locale. A
user may set this variable to express the language they speak, their
region, and a character encoding. The encoding part is ignored,
fish always assumes UTF-8. 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.
Example values are en_US.UTF-8 for the American English or
de_AT.UTF-8 for Austrian German. Your operating system might have a
locale command that you can call as locale -a to see a list of de-
fined locales.
LANGUAGE
This is treated like LC_MESSAGES except that it can hold multiple
values, which allows to specify a priority list of languages for
translation. It's a PATH variable, like in GNU gettext
<https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-
variable.html>.
Language identifiers without a region specified (e.g. zh) result in
all available variants of this language being tried in arbitrary or-
der. In this example, we might first look for messages in the zh_CN
catalog, followed by zh_TW, or the other way around. This is dif-
ferent from GNU gettext, which uses a "default" variant of the lan-
guage instead. If you prefer a certain variant, specify it earlier
in the list, e.g. zh_TW:zh if your preferred language is zh_TW, and
you prefer any other variants of zh over the English default. If
zh_TW is the only variant of zh you want, specifying zh_TW in the
LANGUAGE variable will result in messages which are not available in
zh_TW being displayed in English.
See also builtin _ (underscore).
LC_ALL
Overrides the LANG and all other LC_* variables. Please use LC_ALL
only as a temporary override.
LC_MESSAGES
Determines the language in which messages are displayed, see builtin
_ (underscore).
LC_NUMERIC
Sets the locale for formatting numbers.
LC_TIME
Determines how date and time are displayed. Used in the history
builtin.
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 num-
bers, 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 current
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 in-
terpreter, 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 di-
rectories 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 print some-
thing 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 reserved 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 (because 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_CON-
FIG_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 soft-
ware:
* the directories under $__fish_user_data_dir (usually ~/.lo-
cal/share/fish, controlled by the XDG_DATA_HOME environment variable)
* a fish/vendor_conf.d directory in the directories listed in
$XDG_DATA_DIRS (default /usr/share/fish/vendor_conf.d and /usr/lo-
cal/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 file-
name, sorted (like globs) in a natural order (i.e. "01" sorts before
"2").
* System-wide configuration files, where administrators can include ini-
tialization for all users on the system - similar to /etc/profile for
POSIX-style shells - in $__fish_sysconf_dir (usually /etc/fish/con-
fig.fish).
* User configuration, usually in ~/.config/fish/config.fish (controlled by
the XDG_CONFIG_HOME environment variable, and accessible as $__fish_con-
fig_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 interac-
tive. If you want to run a command only when using a login shell, use sta-
tus --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 configuration
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. Addi-
tionally, users of other shells won't benefit from the fish-specific con-
figuration. However, if they are required, you can install them to the
"vendor" configuration directory. As this path may vary from system to sys-
tem, 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 instance
because your system requires special paths to be used.
Future feature flags
Feature flags are how fish stages changes that might break scripts. Break-
ing changes are introduced as opt-in, in a few releases they become
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 on 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
remove-percent-self off 4.0 %self is no longer expanded (use $fish_pid)
test-require-arg off 4.0 builtin test requires an argument
mark-prompt on 4.0 write OSC 133 prompt markers to the terminal
ignore-terminfo on 4.1 do not look up $TERM in terminfo database
query-term on 4.1 query the TTY to enable extra functionality
omit-term-workarounds off 4.3 skip workarounds for incompatible terminals
Here is what they mean:
* stderr-nocaret was introduced in fish 3.0 and cannot be turned off since
fish 3.5. It can still be tested for compatibility, but a no-stderr-no-
caret value will be ignored. The flag made ^ an ordinary character in-
stead of denoting an stderr redirection. Use 2> instead.
* qmark-noglob was also introduced in fish 3.0 (and made the default in
4.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 (and made the default in 3.5). It
makes it so the replacement expression in string replace -r does one
fewer round of escaping. Before, 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 (and made the default
in 3.5). It makes it so a & is 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 format-
ting anyway, and fish_indent will have done it for you already.
* remove-percent-self turns off the special %self expansion. It was intro-
duced in 4.0. To get fish's pid, you can use the fish_pid variable.
* test-require-arg removes builtin test's one-argument form (test "string".
It was introduced in 4.0. To test if a string is non-empty, use test -n
"string". If disabled, any call to test that would change sends a debug
message of category "deprecated-test", so starting fish with fish --de-
bug=deprecated-test can be used to find offending calls.
* mark-prompt makes fish report to the terminal the beginning and end of
both shell prompts and command output.
* ignore-terminfo was introduced in fish 4.1 and cannot be turned off since
fish 4.5. It can still be tested for compatibility, but a no-ignore-ter-
minfo value will be ignored. The flag disabled lookup of $TERM in the
terminfo database.
* query-term allows fish to query the terminal by writing escape sequences
and reading the terminal's response. This enables features such as
scrolling. If you use an incompatible terminal, you can -- for the time
being -- work around it by running (once) set -Ua fish_features
no-query-term.
* omit-term-workarounds prevents fish from trying to work around incompati-
ble terminals.
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 ef-
fect 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
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 specific
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 command.
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 er-
rors. The commandline is passed as the first parameter.
* fish_postexec is emitted right after executing an interactive command.
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.
* fish_focus_in is emitted when fish's terminal gains focus.
* fish_focus_out is emitted when fish's terminal loses focus.
Events can be fired with the emit command, and do not have to be defined
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 in-
stead 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 documen-
tation 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 pre-
sented 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 cur-
rent breakpoint was reached. To resume normal execution of the script, type
exit or ctrl-d.
To start a debug session insert the builtin command breakpoint at the point
in a function or script where you wish to gain control, then run the func-
tion or script. Also, the default action of the TRAP signal is to call this
builtin, meaning a running script can be actively debugged by sending it
the TRAP signal (kill -s TRAP <PID>). There is limited support for interac-
tively setting or modifying breakpoints from this debug prompt: it is pos-
sible to insert new breakpoints in (or remove old ones from) other func-
tions by using the funced function to edit the definition of a function,
but it is not possible to add or remove a breakpoint from the func-
tion/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.
Profiling fish scripts
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 speci-
fied path. This profile log includes a breakdown of how long each step in
the execution took.
For example:
> fish --profile /tmp/sleep.prof -ic 'sleep 3s'
> cat /tmp/sleep.prof
Time Sum Command
3003419 3003419 > sleep 3s
This will show the time for each command itself in the first column, the
time for the command and every subcommand (like any commands inside of a
function or command substitutions) in the second and the command itself in
the third, separated with tabs.
The time is given in microseconds.
To see the slowest commands last, sort -nk2 /path/to/logfile is useful.
For profiling fish's startup there is also --profile-startup /path/to/log-
file.
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 and else 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 vari-
able.
* 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.
* end to end a block
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.
* path for filtering paths and handling their components.
* 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_tab_title to change the terminal tab's title.
* fish_greeting to show a greeting when fish starts.
* fish_should_add_to_history to determine if a command should be added to
history
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 repository.
* 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 short-
ened 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 configuration.
* export as a compatibility function for other shells.
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.
This only works with messages which are translated as part of fish's own
sources, so using it as part of your own fish scripts which are not up-
streamed into the fish repo will not work unless the exact same message
also exists upstream.
It requires fish to be built with gettext support. If that support is dis-
abled or there is no translation it will echo the argument back.
The language depends on the current locale, set with LANG, LC_MESSAGES,
LC_ALL, and LANGUAGE. These variables do not have to be exported for fish
to use them, and fish's variable scopes are supported. If other programs
launched via fish should respect these locale variables they have to be ex-
ported to make them available outside of fish.
For LANGUAGE you can use a list, or use colons to separate multiple lan-
guages.
If the status language set command was used, its arguments specify the lan-
guage precedence, and the environment variables are ignored.
Options
_ takes no options.
Examples
Use German translations:
> set LANG de_DE.UTF-8
> _ file
Datei
Specify a precedence of languages (only works with LANGUAGE):
> set LANGUAGE pt de
> _ file # This message has a Portuguese translation.
arquivo
> _ "Invalid arguments" # This message does not have a Portuguese translation, but a German one.
UngA1/4ltige Argumente
> _ untranslatable # No translation in Portuguese, nor in German.
untranslatable
Note that the specific examples may change if translations are added/modi-
fied.
abbr - manage fish abbreviations
Synopsis
abbr --add NAME [--position command | anywhere] [-r | --regex PATTERN] [-c | --command COMMAND]
[--set-cursor[=MARKER]] ([-f | --function FUNCTION] | EXPANSION)
abbr --erase [ [-c | --command COMMAND]... ] NAME ...
abbr --rename [ [-c | --command COMMAND]... ] OLD_WORD NEW_WORD
abbr [--show] [--color WHEN]
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 expanded
in scripts.
For example, a frequently-run command like git checkout can be abbreviated
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 ctrl-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 ex-
pansion 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 expansion function
interprets them. See the Examples section.
Changed in version 3.6.0: Previous versions of this allowed saving abbrevi-
ations in universal variables. That's no longer possible. Existing vari-
ables will still be imported and abbr --erase will also erase the vari-
ables. 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 vari-
able:
> abbr >> ~/.config/fish/config.fish
> abbr --erase (abbr --list)
Alternatively you can keep them in a separate configuration file by doing
something like the following:
> abbr > ~/.config/fish/conf.d/myabbrs.fish
This will save all your abbreviations in "myabbrs.fish", overwriting the
whole file so it doesn't leave any duplicates, or restore abbreviations you
had erased. Of course any functions will have to be saved separately, see
funcsave.
"add" subcommand
abbr [-a | --add] NAME [--position command | anywhere] [-r | --regex PATTERN]
[-c | --command COMMAND] [--set-cursor[=MARKER]] ([-f | --function FUNCTION] | EXPANSION)
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 posi-
tioned as a command, not as an argument to another command. With --position
anywhere the abbreviation may expand anywhere in the command line. The de-
fault is command.
With --command COMMAND, the abbreviation will only expand when it is used
as an argument to the given COMMAND. Multiple --command can be used to-
gether, and the abbreviation will expand for each. An empty COMMAND means
it will expand only when there is no command. --command implies --position
anywhere and disallows --position command. Even with different COMMANDS,
the NAME of the abbreviation needs to be unique. Consider using --regex if
you want to expand the same word differently for multiple commands.
With --regex, the abbreviation matches using the regular expression given
by PATTERN, instead of the literal NAME. The pattern is interpreted 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 abbreviation
matches, the function will be called with the matching token as an argu-
ment. If the function's exit status is 0 (success), the token will be re-
placed by the function's output; otherwise the token will be left un-
changed. 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 -- al-
lows -C to be treated as the name of the abbreviation, instead of an op-
tion.
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 en-
tered command. It then adds an abbreviation which replaces !! with the re-
sult 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 argu-
ment. It then adds an abbreviation which matches commands ending in .txt,
and replaces the command with the result of calling this function. This al-
lows 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 cur-
sor is positioned ready to enter the command to run in each directory, at
the location of the !, which is itself erased.
abbr --command git co checkout
Turns "co" as an argument to "git" into "checkout". Multiple commands are
possible, --command={git,hg} would expand "co" to "checkout" for both git
and hg.
Other subcommands
abbr --rename [ [-c | --command COMMAND]... ] OLD_NAME NEW_NAME
Renames an abbreviation, from OLD_NAME to NEW_NAME. For command-specific
abbreviations, the --command options must be provided to disambiguate which
abbreviation to rename.
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] [ [-c | --command COMMAND]... ] NAME ...
Erases the abbreviation with the given name. For command-specific abbrevi-
ations, the --command options must be provided to disambiguate which abbre-
viation to rename.
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
NOTE: This page documents the fish builtin alias. To see the documentation
on any non-fish versions, use command man alias.
alias is a simple wrapper for the function builtin, which creates a func-
tion 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 using an
abbreviation instead.
fish marks functions that have been created by alias by including the com-
mand 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 appends
$argv, so that all parameters used with the alias are passed to the ac-
tual 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 configuration
directory using funcsave.
Example
The following code will create rmi, which runs rm with additional arguments
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
alias sometimes requires escaping, as you can see here:
# 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'
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
* or command
* not command
argparse - parse options passed to a fish script or function
Synopsis
argparse [OPTIONS] OPTION_SPEC ... -- [ARG ...]
Description
This command makes it easy for fish scripts and functions to handle argu-
ments. You pass arguments that define the known options, followed by a lit-
eral --, then the arguments to be parsed (which might also include a lit-
eral --). argparse then sets variables to indicate the passed options with
their values, sets $argv_opts to the options and their values, and sets
$argv to the remaining arguments. See the usage section below.
Each option specification (OPTION_SPEC) is written in the domain specific
language described below. All OPTION_SPECs must appear after any argparse
flags and before the -- that separates them from the arguments to be
parsed.
Each option that is seen in the ARG list will result in variables named
_flag_X, where X is the short flag letter and the long flag name (if they
are defined). For example a --help option could cause argparse to define
one variable called _flag_h and another called _flag_help.
The variables will be set with local scope (i.e., as if the script had done
set -l _flag_X). If the flag is a boolean (that is, it is passed or not, it
doesn't have a value) the values are the short and long flags seen. If the
option is not a boolean the values will be zero or more values correspond-
ing to the values collected when the ARG list is processed. If the flag was
not seen the flag variable will not be set.
Options
The following argparse options are available. They must appear before all
OPTION_SPECs:
-n or --name NAME
Use NAME in error messages. By default the current function name
will be used, or argparse if run outside of a function.
-x or --exclusive OPTIONS
A comma separated list of options that are mutually exclusive. You
can use this more than once to define multiple sets of mutually ex-
clusive options. You give either the short or long version of each
option, and you still need to otherwise define the options.
-N or --min-args NUMBER
The minimum number of acceptable non-option arguments. The default
is zero.
-X or --max-args NUMBER
The maximum number of acceptable non-option arguments. The default
is infinity.
-u or --move-unknown
Allow unknown options, and move them from $argv to $argv_opts. By
default, Unknown options are treated as if they take optional argu-
ments (i.e. have option spec =?).
The above means that if a group of short options contains an unknown
short option followed by a known short option, the known short op-
tion is treated as an argument to the unknown one (e.g. --move-un-
known h -- -oh will treat h as the argument to -o, and so _flag_h
will not be set). In contrast, if the known option comes first (and
does not take any arguments), the known option will be recognised
(e.g. argparse --move-unknown h -- -ho will set $_flag_h to -h)
-i or --ignore-unknown
Deprecated. This is like --move-unknown, except that unknown options
and their arguments are kept in $argv and not moved to $argv_opts.
Unlike --move-unknown, this option makes it impossible to distin-
guish between an unknown option and non-option argument that starts
with a - (since any -- separator in $argv will be removed).
-S or --strict-longopts
This makes the parsing of long options more strict. In particular,
without this flag, if long is a known long option flag, --long and
--long=<value> can be abbreviated as:
* -long and -long=<value>, but only if there is no short flag l.
* --lo and --lo=<value>, but only if there is no other long flag
that starts with lo. Similarly with any other non-empty prefix of
long.
* -lo and -lo=<value> (i.e. combining the above two).
With the --strict-longopts flag, the above three are parse errors:
one must use the syntax --long or --long=<value> to use a long op-
tion called long.
This flag has no effect on the parsing of unknown options (which are
parsed as if this flag is on).
This option may be on all the time in the future, so do not rely on
the behaviour without it.
--unknown-arguments KIND
This option implies --move-unknown, unless --ignore-unknown is also
given. This will modify the parsing behaviour of unknown options
depending on the value of KIND:
* optional (the default), allows each unknown option to take an
optional argument (i.e. as if it had =? or =* in its option
specification). For example, argparse --ignore-unknown --un-
known-arguments=optional ab -- -u -a -ub will set _flag_a but
not _flag_b, as the b is treated as an argument to the second
use of -u.
* required requires each unknown option to take an argument (i.e.
as if it had = or =+ in its option specification). If the above
example was changed to use --unknown-arguments=required, nei-
ther _flag_a nor _flag_b would be set: the -a will be treated
as an argument to the first use of -u, and the b as an argument
to the second.
* none forbids each unknown option from taking an argument (i.e.
as if it had no = in its option specification). If the above
example was changed to use --unknown-arguments=none, both
_flag_a and _flag_b would be set, as neither use of -u will be
passed as taking an argument.
Note that the above assumes that unknown long flags use the --
"GNU-style" (e.g. if KIND is none, and there is no bar long op-
tion, -bar is interpreted as three short flags, b, a, and r; but
if bar is known, -bar is treated the same as --bar).
When using --unknown-arguments=required, you will get an error if
the provided arguments end in an unknown option, since it has no
argument. Similarly, with --unknown-arguments=none, you will get
an error if you use the --flag=value syntax and flag is an un-
known option.
-s or --stop-nonopt
Causes scanning the arguments to stop as soon as the first non-op-
tion argument is seen. Among other things, this is useful to imple-
ment subcommands that have their own options.
-h or --help
Displays help about using this command.
Usage
To use this command, pass the option specifications (OPTION_SPEC), a manda-
tory --, and then the arguments to be parsed.
A simple example:
argparse 'h/help' 'n/name=' -- $argv
or return
If $argv is empty then there is nothing to parse and argparse returns zero
to indicate success. If $argv is not empty then it is checked for flags -h,
--help, -n and --name. If they are found they are removed from the argu-
ments and local variables called _flag_OPTION are set so the script can de-
termine which options were seen. If $argv doesn't have any errors, like an
unknown option or a missing mandatory value for an option, then argparse
exits with a status of zero. Otherwise it writes appropriate error messages
to stderr and exits with a status of one.
The or return means that the function returns argparse's status if it
failed, so if it goes on argparse succeeded.
To use the flags argparse has extracted:
# Checking for _flag_h and _flag_help is equivalent
# We check if it has been given at least once
if set -ql _flag_h
echo "Usage: my_function [-h | --help] [-n | --name=NAME]" >&2
return 1
end
set -l myname somedefault
set -ql _flag_name[1]
and set myname $_flag_name[-1] # here we use the *last* --name=
Any characters in the flag name that are not valid in a variable name (like
- dashes) will be replaced with underscores.
The -- argument is required. You do not have to include any option specifi-
cations or arguments after the -- but you must include the --. For example,
this is acceptable:
set -l argv foo
argparse 'h/help' 'n/name' -- $argv
argparse --min-args=1 -- $argv
But this is not:
set -l argv
argparse 'h/help' 'n/name' $argv
The first -- seen is what allows the argparse command to reliably separate
the option specifications and options to argparse itself (like --move-un-
known) from the command arguments, so it is required.
Option Specifications
Each option specification consists of:
* An optional alphanumeric short flag character.
* An optional long flag name preceded by a /. If neither a short flag nor
long flag are present, an error is reported.
* If there is no short flag, and the long flag name is more than one
character, the / can be omitted.
* For backwards compatibility, if there is a short and a long flag, a
- can be used in place of the /, if the short flag is not to be us-
able by users (in which case it will also not be exposed as a flag
variable).
* Nothing if the flag is a boolean that takes no argument or is an integer
flag, or
* = if it requires a value and only the last instance of the flag is
saved, or
* =? if it takes an optional value and only the last instance of the
flag is saved, or
* =+ if it requires a value and each instance of the flag is saved, or
* =* if it takes an optional value and each instance of the flag is
saved, storing the empty string when the flag was not given a value.
* Optionally a &, indicating that the option and any attached values are
not to be saved in $argv or $argv_opts. This does not affect the the
_flag_ variables.
* Nothing if the flag is a boolean that takes no argument, or
* ! followed by fish script to validate the value. Typically this will
be a function to run. If the exit status is zero the value for the
flag is valid. If non-zero the value is invalid. Any error messages
should be written to stdout (not stderr). See the section on Flag
Value Validation for more information.
See the fish_opt command for a friendlier but more verbose way to create
option specifications.
If a flag is not seen when parsing the arguments then the corresponding
_flag_X var(s) will not be set.
Integer flag
Sometimes commands take numbers directly as options, like foo -55. To allow
this one option spec can have the # modifier so that any integer will be
understood as this flag, and the last number will be given as its value (as
if = was used).
The # must follow the short flag letter (if any), and other modifiers like
= are not allowed, except for - (for backwards compatibility):
m#maximum
This does not read numbers given as +NNN, only those that look like flags -
-NNN.
Note: Optional arguments
An option defined with =? or =* can take optional arguments. Optional argu-
ments have to be directly attached to the option they belong to.
That means the argument will only be used for the option if you use it
like:
cmd --flag=value
# or
cmd -fvalue
but not if used like:
cmd --flag value
# "value" here will be used as a positional argument
# and "--flag" won't have an argument.
If this weren't the case, using an option without an optional argument
would be difficult if you also wanted to use positional arguments.
For example:
grep --color auto
# Here "auto" will be used as the search string,
# "color" will not have an argument and will fall back to the default,
# which also *happens to be* auto.
grep --color always
# Here grep will still only use color "auto"matically
# and search for the string "always".
This isn't specific to argparse but common to all things using getopt(3)
(if they have optional arguments at all). That grep example is how GNU grep
actually behaves.
Flag Value Validation
Sometimes you need to validate the option values. For example, that it is a
valid integer within a specific range, or an ip address, or something en-
tirely different. You can always do this after argparse returns but you can
also request that argparse perform the validation by executing arbitrary
fish script. To do so append an ! (exclamation-mark) then the fish script
to be run. When that code is executed three vars will be defined:
* _argparse_cmd will be set to the value of the value of the argparse
--name value.
* _flag_name will be set to the short or long flag that being processed.
* _flag_value will be set to the value associated with the flag being
processed.
These variables are passed to the function as local exported variables.
The script should write any error messages to stdout, not stderr. It should
return a status of zero if the flag value is valid otherwise a non-zero
status to indicate it is invalid.
Fish ships with a _validate_int function that accepts a --min and --max
flag. Let's say your command accepts a -m or --max flag and the minimum al-
lowable value is zero and the maximum is 5. You would define the option
like this: m/max=!_validate_int --min 0 --max 5. The default if you call
_validate_int without those flags is to check that the value is a valid in-
teger with no limits on the min or max value allowed.
Here are some examples of flag validations:
# validate that a path is a directory
argparse 'p/path=!test -d "$_flag_value"' -- --path $__fish_config_dir
# validate that a function does not exist
argparse 'f/func=!not functions -q "$_flag_value"' -- -f alias
# validate that a string matches a regex
argparse 'c/color=!string match -rq \'^#?[0-9a-fA-F]{6}$\' "$_flag_value"' -- -c 'c0ffee'
# validate with a validator function
argparse 'n/num=!_validate_int --min 0 --max 99' -- --num 42
Example OPTION_SPECs
Some OPTION_SPEC examples:
* h/help means that both -h and --help are valid. The flag is a boolean and
can be used more than once. If either flag is used then _flag_h and
_flag_help will be set to however either flag was seen, as many times as
it was seen. So it could be set to -h, -h and --help, and count $_flag_h
would yield "3".
* help means that only --help is valid. The flag is a boolean and can be
used more than once. If it is used then _flag_help will be set as above.
Also h-help (with an arbitrary short letter) for backwards compatibility.
* help& is similar (it will remove --help from $argv), the difference is
that --help` will not placed in $argv_opts.
* longonly= is a flag --longonly that requires an option, there is no short
flag or even short flag variable.
* n/name= means that both -n and --name are valid. It requires a value and
can be used at most once. If the flag is seen then _flag_n and _flag_name
will be set with the single mandatory value associated with the flag.
* n/name=? means that both -n and --name are valid. It accepts an optional
value and can be used at most once. If the flag is seen then _flag_n and
_flag_name will be set with the value associated with the flag if one was
provided else it will be set with no values.
* n/name=* is similar, but the flag can be used more than once. If the flag
is seen then _flag_n and _flag_name will be set with the values associ-
ated with each occurence. Each value will be the value given to the op-
tion, or the empty string if no value was given.
* name=+ means that only --name is valid. It requires a value and can be
used more than once. If the flag is seen then _flag_name will be set with
the values associated with each occurrence.
* x means that only -x is valid. It is a boolean that can be used more than
once. If it is seen then _flag_x will be set as above.
* /x is similar, but only --x is valid (instead of -x).
* x=, x=?, and x=+ are similar to the n/name examples above but there is no
long flag alternative to the short flag -x.
* #max (or #-max) means that flags matching the regex "^--?\d+$" are valid.
When seen they are assigned to the variable _flag_max. This allows any
valid positive or negative integer to be specified by prefixing it with a
single "-". Many commands support this idiom. For example head -3 /a/file
to emit only the first three lines of /a/file.
* n#max means that flags matching the regex "^--?\d+$" are valid. When seen
they are assigned to the variables _flag_n and _flag_max. This allows any
valid positive or negative integer to be specified by prefixing it with a
single "-". Many commands support this idiom. For example head -3 /a/file
to emit only the first three lines of /a/file. You can also specify the
value using either flag: -n NNN or --max NNN in this example.
* #longonly causes the last integer option to be stored in _flag_longonly.
After parsing the arguments the argv variable is set with local scope to
any values not already consumed during flag processing. If there are no un-
bound values the variable is set but count $argv will be zero. Similarly,
the argv_opts variable is set with local scope to the arguments that were
consumed during flag processing. This allows forwarding $argv_opts to an-
other command, together with additional arguments.
If an error occurs during argparse processing it will exit with a non-zero
status and print error messages to stderr.
Examples
A simple use:
argparse h/help -- $argv
or return
if set -q _flag_help
# TODO: Print help here
return 0
end
This supports one option - -h / --help. Any other option is an error. If it
is given it prints help and exits.
How fish_add_path - add to the path parses its args:
argparse -x g,U -x P,U -x a,p g/global U/universal P/path p/prepend a/append h/help m/move v/verbose n/dry-run -- $argv
There are a variety of boolean flags, all with long and short versions. A
few of these cannot be used together, and that is what the -x flag is used
for. -x g,U means that --global and --universal or their short equivalents
conflict, and if they are used together you get an error. In this case you
only need to give the short or long flag, not the full option specifica-
tion.
After this it figures out which variable it should operate on according to
the --path flag:
set -l var fish_user_paths
set -q _flag_path
and set var PATH
# ...
# Check for --dry-run.
# The "-" has been replaced with a "_" because
# it is not valid in a variable name
not set -ql _flag_dry_run
and set $var $result
An example of using $argv_opts to forward known options to another command,
whilst adding new options:
function my-head
# The following option is the only existing one to head that takes arguments
# (we will forward it verbatim).
set -l opt_spec n/lines=
# --qwords is a new option, but --bytes is an existing one which we will modify below
set -a opt_spec "qwords=&" "c/bytes=&"
argparse --strict-longopts --move-unknown --unknown-arguments=none $opt_spec -- $argv || return
if set -q _flag_qwords
# --qwords allows specifying the size in multiples of 8 bytes
set -a argv_opts --bytes=(math -- $_flag_qwords \* 8 || return)
else if set -q _flag_bytes
# Allows using a 'q' suffix, e.g. --bytes=4q to mean 4*8 bytes.
if string match -qr 'q$' -- $_flag_bytes
set -a argv_opts --bytes=(math -- (string replace -r 'q$' '*8' -- $_flag_bytes) || return)
else
# Keep the users setting
set -a argv_opts --bytes=$_flag_bytes
end
end
if test (count $argv) -eq 0
# Default to heading /dev/kmsg (whereas head defaults to stdin)
set -l argv /dev/kmsg
end
# Call the real head with our modified options and arguments.
head $argv_opts -- $argv
end
The argparse call above saves all the options we do not want to process in
$argv_opts. (The --qwords and --bytes options are not saved there as their
option spec's end in a ~). The code then processes the --qwords and --byt-
ess options using the the $_flag_OPTION variables, and puts the transformed
options in $argv_opts (which already contains all the original options,
other than --qwords and --bytes).
Note that because the argparse call above uses --move-unknown and --un-
known-arguments=none, we only need to tell it the arguments to head that
take a value. This allows the wrapper script to accurately work out the
non-option arguments (i.e. $argv, the filenames that head is to operate
on). Using --unknown-arguments=optional and explicitly listing all the
known options to head however would have the advantage that if head were to
add new options, they could still be used with the wrapper script using the
"stuck" form for arguments (e.g. -o<arg>, or --opt=<arg>).
Note that the --strict-longopts is required to be able to correctly pass
short options, e.g. without it my-head -q --bytes 10q, will actually parse
the -q as shorthand for --qwords.
begin - start a new block of code
Synopsis
begin; [COMMANDS ...]; end
{ [COMMANDS ...] }
Description
begin is used to create a new block of code.
A block allows the introduction of a new variable scope, redirection of the
input or output of a set of commands as a group, or to specify precedence
when using the conditional commands like and.
The block is unconditionally executed. begin; ...; end is equivalent to if
true; ...; end.
begin does not change the current exit status itself. After the block has
completed, $status will be set to the status returned by the most recent
command.
Some other shells only support the { [COMMANDS ...] ; } notation.
The -h or --help option displays help about using this command.
Example
The following code sets a number of variables inside of a block scope.
Since the variables are set inside the block and have local scope, they
will be automatically deleted when the block ends.
begin
set -l PIRATE Yarrr
...
end
echo $PIRATE
# This will not output anything, since the PIRATE variable
# went out of scope at the end of the block
In the following code, all output is redirected to the file out.html.
begin
echo $xml_header
echo $html_header
if test -e $file
...
end
...
end > out.html
bg - send jobs to background
Synopsis
bg [PID ...]
Description
bg sends jobs to the background, resuming them if they are stopped.
A background job is executed simultaneously with fish, and does not have
access to the keyboard. If no job is specified, the last job to be used is
put in the background. If PID is specified, the jobs containing the speci-
fied process IDs are put in the background.
A PID of the format %n, where n is an integer, will be interpreted as the
PID of job number n. Job numbers can be seen in the output of jobs.
When at least one of the arguments isn't a valid job specifier, bg will
print an error without backgrounding anything.
When all arguments are valid job specifiers, bg will background all match-
ing jobs that exist.
The -h or --help option displays help about using this command.
Example
The typical use is to run something, stop it with ctrl-z, and then continue
it in the background with bg:
> find / -name "*.js" >/tmp/jsfiles 2>/dev/null # oh no, this takes too long, let's press Ctrl-z!
fish: Job 1, 'find / -name "*.js" >/tmp/jsfila|' has stopped
> bg
Send job 1 'find / -name "*.js" >/tmp/jsfiles 2>/dev/null' to background
> # I can continue using this shell!
> # Eventually:
fish: Job 1, 'find / -name "*.js" >/tmp/jsfila|' has ended
bg 123 456 789 will background the jobs that contain processes 123, 456 and
789.
If only 123 and 789 exist, it will still background them and print an error
about 456.
bg 123 banana or bg banana 123 will complain that "banana" is not a valid
process ID.
bg %2 will background job 2.
bind - handle fish key bindings
Synopsis
bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [--preset | --user] [-s | --silent] KEYS COMMAND ...
bind [(-M | --mode) MODE] [--preset] [--user] [--color WHEN] [KEYS]
bind [-a | --all] [--preset] [--user] [--color WHEN]
bind (-f | --function-names)
bind (-K | --key-names)
bind (-L | --list-modes)
bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] [-a | --all] | KEYS ...
Description
bind manages key bindings.
If both KEYS and COMMAND are given, bind adds (or replaces) a binding in
MODE. If only KEYS is given, bind lists any existing bindings for those
keys in MODE or in all modes. If no KEYS argument is provided, bind lists
all bindings in MODE or in all modes.
KEYS is a comma-separated list of key names. Modifier keys can be speci-
fied by prefixing a key name with a combination of ctrl-, alt-, shift- and
super- (i.e. the "windows" or "command" key). For example, pressing w
while holding the Alt modifier is written as alt-w. Key names are
case-sensitive; for example alt-W is the same as alt-shift-w.
ctrl-x,ctrl-e would mean pressing ctrl-x followed by ctrl-e.
Some keys have names, usually because they don't have an obvious printable
character representation. They are:
* the arrow keys up, down, left and right,
* backspace,
* comma (,),
* delete,
* end,
* enter,
* escape,
* f1 through f12.
* home,
* insert,
* menu,
* minus (-),
* pageup,
* pagedown,
* printscreen,
* space and
* tab,
These names are case-sensitive.
An empty value ('') for KEYS designates the generic binding that will be
used if nothing else matches. For most bind modes, it makes sense to bind
this to the self-insert function (i.e. bind '' self-insert). This will in-
sert any keystrokes that have no bindings otherwise. Non-printable charac-
ters are ignored by the editor, so this will not result in control se-
quences being inserted.
To find the name of a key combination you can use fish_key_reader.
COMMAND can be any fish command, but it can also be one of a set of special
input functions. These include functions for moving the cursor, operating
on the kill-ring, performing tab completion, etc. Use bind --function-names
or see below for a list of these input functions.
NOTE:
If a script changes the commandline, it should finish by calling the re-
paint special input function.
Key bindings may use "modes", which mimics vi's modal input behavior. The
default mode is "default" (in vi-mode, that's vi's "normal" mode). Every
key binding applies to a single mode; you can specify which one with -M
MODE. If the key binding should change the mode, you can specify the new
mode with -m NEW_MODE. The mode can be viewed and changed via the
$fish_bind_mode variable. If you want to change the mode from inside a fish
function, use set fish_bind_mode MODE.
To save custom key bindings, put the bind statements into config.fish. Al-
ternatively, fish also automatically executes a function called
fish_user_key_bindings if it exists.
Options
The following options are available:
-f or --function-names
Display a list of available input functions
-K or --key-names
Display a list of available named keys such as backspace.
-L or --list-modes
Display a list of defined bind modes
-M MODE or --mode MODE
Specify a bind mode that the bind is used in. Defaults to "default".
If you use vi bindings, that's the command mode, what vi calls "nor-
mal" mode.
-m NEW_MODE or --sets-mode NEW_MODE
Change the current mode to NEW_MODE after this binding is executed
-e or --erase
Erase the binding with the given sequence and mode instead of defin-
ing a new one. Multiple sequences can be specified with this flag.
Specifying -a or --all with -M or --mode erases all binds in the
given mode regardless of sequence. Specifying -a or --all without
-M or --mode erases all binds in all modes regardless of sequence.
-a or --all
See --erase
--preset and --user
Specify if bind should operate on user or preset bindings. User
bindings take precedence over preset bindings when fish looks up
mappings. By default, all bind invocations work on the "user" level
except for listing, which will show both levels. All invocations
except for inserting new bindings can operate on both levels at the
same time (if both --preset and --user are given). --preset should
only be used in full binding sets (like when working on
fish_vi_key_bindings).
-s or --silent
Silences error message for unbound sequences.
--color WHEN
Controls when to use syntax highlighting colors when listing bind-
ings. WHEN can be auto (the default, colorize if the output is a
terminal), always, or never.
-h or --help
Displays help about using this command.
Special input functions
The following special input functions are available:
and only execute the next function if the previous succeeded (note: only
some functions report success)
accept-autosuggestion
accept the current autosuggestion. Returns false when there was
nothing to accept.
backward-char
move one character to the left. If the completion pager is active,
select the previous completion instead.
backward-char-passive
move one character to the left, but do not trigger any non-move-
ment-related operations. If the cursor is at the start of the com-
mandline, does nothing. Does not change the selected item in the
completion pager UI when shown.
backward-token
move one argument to the left
backward-delete-char
deletes one character of input to the left of the cursor
backward-kill-token
move the argument to the left of the cursor to the killring
backward-kill-line
move everything from the beginning of the line to the cursor to the
killring
backward-kill-path-component
move one path component to the left of the cursor to the killring. A
path component is everything likely to belong to a path component,
i.e. not any of the following: /={,}'":@ |;<>&, plus newlines and
tabs.
backward-kill-word
move the word to the left of the cursor to the killring, until the
start of the current word (like vim's db)
backward-kill-bigword
move the whitespace-delimited word to the left of the cursor to the
killring, until the start of the current word (like vim's dB)
backward-path-component
move one path component to the left
backward-word
move one word to the left, stopping at the start of the previous
word (like vim's b, or Emacs' M-b but differs slightly in word divi-
sion rules)
backward-bigword
move one whitespace-delimited word to the left, stopping at the
start of the previous word (like vim's B)
backward-word-end
move to the end of the previous word (like vim's ge)
backward-bigword-end
move to the end of the previous whitespace-delimited word (like
vim's gE)
beginning-of-buffer
moves to the beginning of the buffer, i.e. the start of the first
line
beginning-of-history
move to the beginning of the history
beginning-of-line
move to the beginning of the line
begin-selection
start selecting text
cancel
close the pager if it is open, or undo the most recent completion if
one was just inserted
cancel-commandline
cancel the current commandline and replace it with a new empty one,
leaving the old one in place with a marker to show that it was can-
celled
capitalize-word
make the current word begin with a capital letter
clear-commandline
empty the entire commandline
clear-screen
clears the screen and redraws the prompt.
scrollback-push
pushes earlier output to the terminal scrollback, positioning the
prompt at the top. This requires the terminal to implement the
ECMA-48 SCROLL UP command and cursor position reporting.
complete
guess the remainder of the current token
complete-and-search
invoke the searchable pager on completion options (for convenience,
this also moves backwards in the completion pager)
delete-char
delete one character to the right of the cursor
delete-or-exit
delete one character to the right of the cursor, or exit the shell
if the commandline is empty
down-line
move down one line
downcase-word
make the current word lowercase
end-of-buffer
moves to the end of the buffer, i.e. the end of the last line; or if
already at the end of the commandline, accept the current autosug-
gestion.
end-of-history
move to the end of the history
end-of-line
move to the end of the line
end-selection
end selecting text
expand-abbr
expands any abbreviation currently under the cursor
execute
run the current commandline
exit exit the shell
forward-token
move one argument to the right
forward-char
move one character to the right; or if at the end of the command-
line, accept the current autosuggestion. If the completion pager is
active, select the next completion instead.
forward-char-passive
move one character to the right, but do not trigger any non-move-
ment-related operations. If the cursor is at the end of the command-
line, does not accept the current autosuggestion (if any). Does not
change the selected item in the completion pager, if shown.
forward-path-component
move one path component to the right; or if at the end of the com-
mandline, accept a path component from the current autosuggestion.
forward-single-char
move one character to the right; or if at the end of the command-
line, accept a single char from the current autosuggestion.
forward-word
move one word to the right, stopping after the end of the current
word; or if at the end of the commandline, accept one word from the
current autosuggestion.
forward-word-vi
like forward-word, but stops at the start of the next word (like
vim's w)
forward-word-end
like forward-word, but stops at the end of the next word (like vim's
e)
forward-bigword
move one whitespace-delimited word to the right, stopping after the
end of the current word; or if at the end of the commandline, accept
one word from the current autosuggestion.
forward-bigword-vi
like forward-bigword, but stops at the start of the next word (like
vim's W)
forward-bigword-end
like forward-bigword, but stops at the end of the next word (like
vim's E)
history-pager
invoke the searchable pager on history (incremental search); or if
the history pager is already active, search further backwards in
time.
history-delete
permanently delete the current history item, either from the history
pager or from an active up-arrow history search
history-search-backward
search the history for the previous match
history-search-forward
search the history for the next match
history-prefix-search-backward
search the history for the previous prefix match
history-prefix-search-forward
search the history for the next prefix match
history-token-search-backward
search the history for the previous matching argument
history-token-search-forward
search the history for the next matching argument
history-last-token-search-backward
search the history for the previous matching last argument
history-last-token-search-forward
search the history for the next matching last argument
forward-jump and backward-jump
read another character and jump to its next occurrence after/before
the cursor
forward-jump-till and backward-jump-till
jump to right before the next occurrence
repeat-jump and repeat-jump-reverse
redo the last jump in the same/opposite direction
jump-to-matching-bracket
jump to matching bracket if the character under the cursor is
bracket; otherwise, jump to the next occurrence of any right bracket
after the cursor. The following brackets are considered: ([{}])
jump-till-matching-bracket
the same as jump-to-matching-bracket but offset cursor to the right
for left bracket, and offset cursor to the left for right bracket.
The offset is applied for both the position we jump from and posi-
tion we jump to. In other words, the cursor will continuously jump
inside the brackets but won't reach them by 1 character. The input
function is useful to emulate ib vi text object. The following
brackets are considered: ([{}])
kill-token
move the next argument to the killring
kill-line
move everything from the cursor to the end of the line to the kill-
ring
kill-path-component
move one path component to the killring.
kill-selection
move the selected text to the killring
kill-whole-line
move the line (including the following newline) to the killring. If
the line is the last line, its preceding newline is also removed
kill-inner-line
move the line (without the following newline) to the killring
kill-word
move the next word to the killring, stopping after the end of the
killed word
kill-word-vi
move the next word to the killring, stopping at the start of the
next word (like vim's dw)
kill-bigword
move the next whitespace-delimited word to the killring, stopping
after the end of the current word
kill-bigword-vi
move the next whitespace-delimited word to the killring, stopping at
the start of the next word (like vim's dW)
kill-inner-word
delete the word under the cursor (like vim's diw)
kill-inner-bigword
delete the whitespace-delimited word under the cursor (like vim's
diW)
kill-a-word
delete the word under the cursor plus surrounding whitespace (like
vim's daw)
kill-a-bigword
delete the whitespace-delimited word under the cursor plus surround-
ing whitespace (like vim's daW)
nextd-or-forward-word
if the commandline is empty, then move forward in the directory his-
tory, otherwise move one word to the right; or if at the end of the
commandline, accept one word from the current autosuggestion.
or only execute the next function if the previous did not succeed
(note: only some functions report failure)
pager-toggle-search
toggles the search field if the completions pager is visible; or if
used after history-pager, search forwards in time.
prevd-or-backward-word
if the commandline is empty, then move backward in the directory
history, otherwise move one word to the left
repaint
reexecutes the prompt functions and redraws the prompt (also
force-repaint for backwards-compatibility)
repaint-mode
reexecutes the fish_mode_prompt and redraws the prompt. This is use-
ful for vi mode. If no fish_mode_prompt exists or it prints nothing,
it acts like a normal repaint.
self-insert
inserts the matching sequence into the command line
self-insert-notfirst
inserts the matching sequence into the command line, unless the cur-
sor is at the beginning
get-key
sets fish_key to the key that was pressed to trigger this binding.
Example use:
for i in (seq 0 9)
bind $i get-key 'commandline -i "#$fish_key"' 'set -eg fish_key'
end
suppress-autosuggestion
remove the current autosuggestion. Returns true if there was a sug-
gestion to remove.
swap-selection-start-stop
go to the other end of the highlighted text without changing the se-
lection
transpose-chars
transpose two characters to the left of the cursor
transpose-words
transpose two words to the left of the cursor
togglecase-char
toggle the capitalisation (case) of the character under the cursor
togglecase-selection
toggle the capitalisation (case) of the selection
insert-line-under
add a new line under the current line
insert-line-over
add a new line over the current line
up-line
move up one line
undo and redo
revert or redo the most recent edits on the command line
upcase-word
make the current word uppercase
yank insert the latest entry of the killring into the buffer
yank-pop
rotate to the previous entry of the killring
Additional functions
The following functions are included as normal functions, but are particu-
larly useful for input editing:
up-or-search and down-or-search
move the cursor or search the history depending on the cursor posi-
tion and current mode
edit_command_buffer
open the visual editor (controlled by the VISUAL or EDITOR environ-
ment variables) with the current command-line contents
fish_clipboard_copy
copy the current selection to the system clipboard
fish_clipboard_paste
paste the current selection from the system clipboard before the
cursor
fish_commandline_append
append the argument to the command-line. If the command-line already
ends with the argument, this removes the suffix instead. Starts with
the last command from history if the command-line is empty.
fish_commandline_prepend
prepend the argument to the command-line. If the command-line al-
ready starts with the argument, this removes the prefix instead.
Starts with the last command from history if the command-line is
empty.
Examples
Exit the shell when ctrl-d is pressed:
bind ctrl-d 'exit'
Perform a history search when pageup is pressed:
bind pageup history-search-backward
Turn on vi key bindings and rebind ctrl-c to clear the input line:
set -g fish_key_bindings fish_vi_key_bindings
bind -M insert ctrl-c kill-whole-line repaint
Launch git diff and repaint the commandline afterwards when ctrl-g is
pressed:
bind ctrl-g 'git diff' repaint
Swap tab and shift-tab, making tab focus the search field. But if the
search field is already active, keep the behavior (tab cycles forward,
shift-tab backward).:
bind tab '
if commandline --search-field >/dev/null
commandline -f complete
else
commandline -f complete-and-search
end
'
bind shift-tab '
if commandline --search-field >/dev/null
commandline -f complete-and-search
else
commandline -f complete
end
'
Terminal Limitations
Unix terminals, like the ones fish operates in, are at heart 70s technol-
ogy. They have some limitations that applications running inside them can't
workaround.
For instance, historically the control key modifies a character by setting
the top three bits to 0. This means:
* Many characters + control are indistinguishable from other keys: ctrl-i
is tab, ctrl-j is newline (\n).
* Control and shift don't work simultaneously - ctrl-X is the same as
ctrl-x.
Other keys don't have a direct encoding, and are sent as escape sequences.
For example right (^a) usually sends \e\[C.
Some modern terminals support newer encodings for keys, that allow distin-
guishing more characters and modifiers, and fish enables as many of these
as it can, automatically.
When in doubt, run fish_key_reader - explore what characters keyboard keys
send. If that tells you that pressing ctrl-i sends tab, your terminal does
not support these better encodings, and so fish is limited to what it
sends.
Key timeout
When you've bound a sequence of multiple characters, there is always the
possibility that fish has only seen a part of it, and then it needs to dis-
ambiguate between the full sequence and part of it.
For example:
bind j,k 'commandline -i foo'
# or `bind jk`
will bind the sequence jk to insert "foo" into the commandline. When you've
only pressed "j", fish doesn't know if it should insert the "j" (because of
the default self-insert), or wait for the "k".
You can enable a timeout for this, by setting the
fish_sequence_key_delay_ms variable to the timeout in milliseconds. If the
timeout elapses, fish will no longer wait for the sequence to be completed,
and do what it can with the characters it already has.
The escape key is a special case, because it can be used standalone as a
real key or as part of a longer escape sequence, like function or arrow
keys. Holding alt and something else also typically sends escape, for exam-
ple holding alt+a will send an escape character and then an "a". So the es-
cape character has its own timeout configured with fish_escape_delay_ms.
See also Key sequences.
block - temporarily block delivery of events
Synopsis
block [(--local | --global)]
block --erase
Description
block delays delivery of all events triggered by fish or the emit, thus de-
laying the execution of any function registered --on-event,
--on-process-exit, --on-job-exit, --on-variable and --on-signal until after
the block is removed.
Event blocks should not be confused with code blocks, which are created
with begin, if, while or for
Without options, block sets up a block that is released automatically at
the end of the current function scope.
The following options are available:
-l or --local
Release the block automatically at the end of the current innermost
code block scope.
-g or --global
Never automatically release the lock.
-e or --erase
Release global block.
-h or --help
Display help about using this command.
Example
# Create a function that listens for events
function --on-event foo foo; echo 'foo fired'; end
# Block the delivery of events
block -g
emit foo
# No output will be produced
block -e
# 'foo fired' will now be printed
Notes
Events are only received from the current fish process as there is no way
to send events from one fish process to another.
break - stop the current inner loop
Synopsis
LOOP_CONSTRUCT
[COMMANDS ...]
break
[COMMANDS ...]
end
Description
break halts a currently running loop (LOOP_CONSTRUCT), such as a for or
while loop. It is usually added inside of a conditional block such as an if
block.
The -h or --help option displays help about using this command.
Example
The following code searches all .c files for "smurf", and halts at the
first occurrence.
for i in *.c
if grep smurf $i
echo Smurfs are present in $i
break
end
end
See Also
* the continue command, to skip the remainder of the current iteration of
the current inner loop
breakpoint - launch debug mode
Synopsis
breakpoint
Description
breakpoint is used to halt a running script and launch an interactive de-
bugging prompt.
For more details, see Debugging fish scripts in the fish manual.
There are no parameters for breakpoint.
builtin - run a builtin command
Synopsis
builtin [OPTIONS] BUILTINNAME
builtin --query BUILTINNAME ...
builtin --names
Description
builtin forces the shell to use a builtin command named BUILTIN, rather
than a function or external program.
The following options are available:
-n or --names
Lists the names of all defined builtins.
-q or --query BUILTIN
Tests if any of the specified builtins exist. If any exist, it re-
turns 0, 1 otherwise.
-h or --help
Displays help about using this command.
Example
builtin jobs
# executes the jobs builtin, even if a function named jobs exists
case - conditionally execute a block of commands
Synopsis
switch VALUE
[case [GLOB ...]
[COMMAND ...]]
end
Description
switch executes one of several blocks of commands, depending on whether a
specified value matches one of several values. case is used together with
the switch statement in order to determine which block should be executed.
Each case command is given one or more parameters. The first case command
with a parameter that matches the string specified in the switch command
will be evaluated. case parameters may contain wildcards. These need to be
escaped or quoted in order to avoid regular wildcard expansion using file-
names.
Note that fish does not fall through on case statements. Only the first
matching case is executed.
Note that command substitutions in a case statement will be evaluated even
if its body is not taken. All substitutions, including command substitu-
tions, must be performed before the value can be compared against the para-
meter.
Example
Say $animal contains the name of an animal. Then this code would classify
it:
switch $animal
case cat
echo evil
case wolf dog human moose dolphin whale
echo mammal
case duck goose albatross
echo bird
case shark trout stingray
echo fish
# Note that the next case has a wildcard which is quoted
case '*'
echo I have no idea what a $animal is
end
If the above code was run with $animal set to whale, the output would be
mammal.
If $animal was set to "banana", it would print "I have no idea what a ba-
nana is".
cd - change directory
Synopsis
cd [DIRECTORY]
Description
NOTE: This page documents the fish builtin cd. To see the documentation on
any non-fish versions, use command man cd.
cd changes the current working directory.
If DIRECTORY is given, it will become the new directory. If no parameter is
given, the HOME environment variable will be used.
If DIRECTORY is a relative path, all the paths in the CDPATH will be tried
as prefixes for it, in addition to PWD. It is recommended to keep . as the
first element of CDPATH, or PWD will be tried last.
Fish will also try to change directory if given a command that looks like a
directory (starting with ., / or ~, or ending with /), without explicitly
requiring cd.
Fish also ships a wrapper function around the builtin cd that understands
cd - as changing to the previous directory. See also prevd. This wrapper
function maintains a history of the 25 most recently visited directories in
the $dirprev and $dirnext global variables. If you make those universal
variables your cd history is shared among all fish instances.
As a special case, cd . is equivalent to cd $PWD, which is useful in cases
where a mountpoint has been recycled or a directory has been removed and
recreated.
The --help or -h option displays help about using this command, and does
not change the directory.
Examples
cd
# changes the working directory to your home directory.
cd /usr/src/fish-shell
# changes the working directory to /usr/src/fish-shell
See Also
Navigate directories using the directory history or the directory stack
cdh - change to a recently visited directory
Synopsis
cdh [DIRECTORY]
Description
cdh with no arguments presents a list of recently visited directories. You
can then select one of the entries by letter or number. You can also press
tab to use the completion pager to select an item from the list. If you
give it a single argument it is equivalent to cd DIRECTORY.
Note that the cd command limits directory history to the 25 most recently
visited directories. The history is stored in the dirprev and dirnext
variables, which this command manipulates. If you make those universal
variables, your cd history is shared among all fish instances.
See Also
* the dirh command to print the directory history
* the prevd command to move backward
* the nextd command to move forward
command - run a program
Synopsis
command [OPTIONS] [COMMANDNAME [ARG ...]]
Description
NOTE: This page documents the fish builtin command. To see the documenta-
tion on any non-fish versions, use command man command.
command forces the shell to execute the program COMMANDNAME and ignore any
functions or builtins with the same name.
In command foo, command is a keyword.
The following options are available:
-a or --all
Prints all COMMAND found in PATH, in the order found.
-q or --query
Return 0 if any of the given commands could be found, 127 otherwise.
Don't print anything. For compatibility, this is also --quiet (dep-
recated).
-s or --search (or -v)
Prints the external command that would be executed, or prints noth-
ing if no file with the specified name could be found in PATH.
-h or --help
Displays help about using this command.
Examples
command ls executes the ls program, even if an ls function also exists.
command -s ls prints the path to the ls program.
command -q git; and command git log runs git log only if git exists.
command -sq git and command -q git and command -vq git return true (0) if a git command could be found and don't print anything.
commandline - set or get the current command line buffer
Synopsis
commandline [OPTIONS] [CMD]
Description
commandline can be used to set or get the current contents of the command
line buffer.
With no parameters, commandline returns the current value of the command
line.
With CMD specified, the command line buffer is erased and replaced with the
contents of CMD.
The following options are available:
-C or --cursor
Set or get the current cursor position, not the contents of the
buffer. If no argument is given, the current cursor position is
printed, otherwise the argument is interpreted as the new cursor po-
sition. If one of the options -j, -p or -t is given, the position
is relative to the respective substring instead of the entire com-
mand line buffer.
-B or --selection-start
Get current position of the selection start in the buffer.
-E or --selection-end
Get current position of the selection end in the buffer.
-f or --function
Causes any additional arguments to be interpreted as input func-
tions, and puts them into the queue, so that they will be read be-
fore any additional actual key presses are. This option cannot be
combined with any other option. See bind for a list of input func-
tions.
-h or --help
Displays help about using this command.
The following options change the way commandline updates the command line
buffer:
-a or --append
Do not remove the current commandline, append the specified string
at the end of it.
-i, --insert or --insert-smart
Do not remove the current commandline, insert the specified string
at the current cursor position. The --insert-smart option turns on
a Do-What-I-Mean (DWIM) mode: it strips any $ prefix from the first
command on each line.
-r or --replace
Remove the current commandline and replace it with the specified
string (default)
The following options change what part of the commandline is printed or up-
dated:
-b or --current-buffer
Select the entire commandline, not including any displayed autosug-
gestion (default).
-j or --current-job
Select the current job - a job here is one pipeline. Stops at logi-
cal operators or terminators (;, &, and newlines).
-p or --current-process
Select the current process - a process here is one command. Stops
at logical operators, terminators, and pipes.
-s or --current-selection
Selects the current selection
-t or --current-token
Selects the current token
--search-field
Use the pager search field instead of the command line. Returns
false if the search field is not shown.
--input=INPUT
Operate on this string instead of the commandline. Useful for using
options like --tokens-expanded.
The following options change the way commandline prints the current comman-
dline buffer:
-c or --cut-at-cursor
Only print selection up until the current cursor position. If com-
bined with --tokens-expanded, this will print up until the last com-
pleted token - excluding the token the cursor is in. This is typi-
cally what you would want for instance in completions. To get both,
use both commandline --cut-at-cursor --tokens-expanded; commandline
--cut-at-cursor --current-token, or commandline -cx; commandline -ct
for short.
-x or --tokens-expanded
Perform argument expansion on the selection and print one argument
per line. Command substitutions are not expanded but forwarded
as-is.
-o, tokenize, --tokens-raw
Deprecated; do not use.
If commandline is called during a call to complete a given string using
complete -C STRING, commandline will consider the specified string to be
the current contents of the command line.
The following options output metadata about the commandline state:
-L or --line
If no argument is given, print the line that the cursor is on, with
the topmost line starting at 1. Otherwise, set the cursor to the
given line.
--column
If no argument is given, print the 1-based offset from the start of
the line to the cursor position in Unicode code points. Otherwise,
set the cursor to the given code point offset.
-S or --search-mode
Evaluates to true if the commandline is performing a history search.
-P or --paging-mode
Evaluates to true if the commandline is showing pager contents, such
as tab completions.
--paging-full-mode
Evaluates to true if the commandline is showing pager contents, such
as tab completions and all lines are shown (no "<n> more rows" mes-
sage).
--is-valid
Returns true when the commandline is syntactically valid and com-
plete. If it is, it would be executed when the execute bind func-
tion is called. If the commandline is incomplete, return 2, if er-
roneous, return 1.
--showing-suggestion
Evaluates to true (i.e. returns 0) when the shell is currently show-
ing an automatic history completion/suggestion, available to be con-
sumed via one of the forward- bindings. For example, can be used to
determine if moving the cursor to the right when already at the end
of the line would have no effect or if it would cause a completion
to be accepted (note that forward-char-passive does this automati-
cally).
Example
commandline -j $history[3] replaces the job under the cursor with the third
item from the command line history.
If the commandline contains
>_ echo $flounder >&2 | less; and echo $catfish
(with the cursor on the "o" of "flounder")
The echo $flounder >& is the first process, less the second and and echo
$catfish the third.
echo $flounder >&2 | less is the first job, and echo $catfish the second.
$flounder is the current token.
The most common use for something like completions is
set -l tokens (commandline -xpc)
which gives the current process (what is being completed), tokenized into
separate entries, up to but excluding the currently being completed token
If you are then also interested in the in-progress token, add
set -l current (commandline -ct)
Note that this makes it easy to render fish's infix matching moot - if pos-
sible it's best if the completions just print all possibilities and leave
the matching to the current token up to fish's logic.
More examples:
>_ commandline -t
$flounder
>_ commandline -ct
$fl
>_ commandline -b # or just commandline
echo $flounder >&2 | less; and echo $catfish
>_ commandline -p
echo $flounder >&2
>_ commandline -j
echo $flounder >&2 | less
complete - edit command-specific tab-completions
Synopsis
complete ((-c | --command) | (-p | --path)) COMMAND [OPTIONS] [--color WHEN]
complete (-C | --do-complete) [--escape] STRING
Description
complete defines, removes or lists completions for a command.
For an introduction to writing your own completions, see Writing your own
completions in the fish manual.
The following options are available:
-c or --command COMMAND
Specifies that COMMAND is the name of the command. If there is no -c
or -p, one non-option argument will be used as the command.
-p or --path COMMAND
Specifies that COMMAND is the absolute path of the command (option-
ally containing wildcards).
-e or --erase
Deletes the specified completion.
-s or --short-option SHORT_OPTION
Adds a short option to the completions list.
-l or --long-option LONG_OPTION
Adds a GNU-style long option to the completions list.
-o or --old-option OPTION
Adds an old-style short or long option (see below for details).
-a or --arguments ARGUMENTS
Adds the specified option arguments to the completions list.
-k or --keep-order
Keeps the order of ARGUMENTS instead of sorting alphabetically. Mul-
tiple complete calls with -k result in arguments of the later ones
displayed first.
-f or --no-files
This completion may not be followed by a filename.
-F or --force-files
This completion may be followed by a filename, even if another ap-
plicable complete specified --no-files.
-r or --require-parameter
This completion must have an option argument, i.e. may not be fol-
lowed by another option. This means that the next argument is the
argument to the option. If this is not given, the option argument
must be attached like -xFoo or --color=auto.
-x or --exclusive
Short for -r and -f.
-d or --description DESCRIPTION
Add a description for this completion, to be shown in the completion
pager.
-w or --wraps WRAPPED_COMMAND
Causes the specified command to inherit completions from
WRAPPED_COMMAND. This is used for "this command completes like that
other command" kinds of relationships. See below for details.
-n or --condition CONDITION
This completion should only be used if the CONDITION (a shell com-
mand) returns 0. This makes it possible to specify completions that
should only be used in some cases. If multiple conditions are speci-
fied, fish will try them in the order they are specified until one
fails or all succeeded.
-C or --do-complete STRING
Makes complete try to find all possible completions for the speci-
fied string. If there is no STRING, the current commandline is used
instead.
--escape
When used with -C, escape special characters in completions.
--color WHEN
Controls when to use syntax highlighting colors when printing com-
pletions. WHEN can be auto (the default, colorize if the output is
a terminal), always, or never.
-h or --help
Displays help about using this command.
Command-specific tab-completions in fish are based on the notion of options
and arguments. An option is a parameter which begins with a hyphen, such as
-h, -help or --help. Arguments are parameters that do not begin with a hy-
phen. Fish recognizes three styles of options, the same styles as the GNU
getopt library. These styles are:
* Short options, like -a. Short options are a single character long, are
preceded by a single hyphen and can be grouped together (like -la, which
is equivalent to -l -a). Option arguments may be specified by appending
the option with the value (-w32), or, if --require-parameter is given, in
the following parameter (-w 32).
* Old-style options, long like -Wall or -name or even short like -a.
Old-style options can be more than one character long, are preceded by a
single hyphen and may not be grouped together. Option arguments are spec-
ified by default following a space (-foo null) or after = (-foo=null).
* GNU-style long options, like --colors. GNU-style long options can be more
than one character long, are preceded by two hyphens, and can't be
grouped together. Option arguments may be specified after a = (--quot-
ing-style=shell), or, if --require-parameter is given, in the following
parameter (--quoting-style shell).
Multiple commands and paths can be given in one call to define the same
completions for multiple commands.
Multiple command switches and wrapped commands can also be given to define
multiple completions in one call.
Invoking complete multiple times for the same command adds the new defini-
tions on top of any existing completions defined for the command.
When -a or --arguments is specified in conjunction with long, short, or
old-style options, the specified arguments are only completed as arguments
for any of the specified options. If -a or --arguments is specified without
any long, short, or old-style options, the specified arguments are used
when completing non-option arguments to the command (except when completing
an option argument that was specified with -r or --require-parameter).
Command substitutions found in ARGUMENTS should return a newline-separated
list of arguments, and each argument may optionally have a tab character
followed by the argument description. Description given this way override a
description given with -d or --description.
Descriptions given with --description are also used to group options given
with -s, -o or -l. Options with the same (non-empty) description will be
listed as one candidate, and one of them will be picked. If the description
is empty or no description was given this is skipped.
The -w or --wraps options causes the specified command to inherit comple-
tions from another command, "wrapping" the other command. The wrapping com-
mand can also have additional completions. A command can wrap multiple com-
mands, and wrapping is transitive: if A wraps B, and B wraps C, then A au-
tomatically inherits all of C's completions. Wrapping can be removed using
the -e or --erase options. Wrapping only works for completions specified
with -c or --command and are ignored when specifying completions with -p or
--path.
When erasing completions, it is possible to either erase all completions
for a specific command by specifying complete -c COMMAND -e, or by specify-
ing a specific completion option to delete.
When complete is called without anything that would define or erase comple-
tions (options, arguments, wrapping, ...), it shows matching completions
instead. So complete without any arguments shows all loaded completions,
complete -c foo shows all loaded completions for foo. Since completions are
autoloaded, you will have to trigger them first.
Cygwin / MSYS2 / Windows
On Windows, binary executables have a .exe extension, but this extension is
not required when calling an application (and if the name is not ambiguous,
i.e. there isn't also a script called myprog in the same directory as
myprog.exe).
To unify completions between Windows and other OSes, on Cygwin/MSYS2/Win-
dows, COMMAND does not require the .exe extension. Completions for myprog
will also be used for myprog.exe if there are no ambiguities, i.e. if there
are no completions for myprog.exe specifically. However, completions for
myprog.exe will only be used when also using the .exe extension on the com-
mand line.
In other words:
complete -c myprog.exe ... #1
will only work for myprog.exe
complete -c myprog ... #2
can work for both myprog and myprog.exe. But if both completions exist, #2
will only be used for myprog while myprog.exe will use #1.
Examples
The short-style option -o for the gcc command needs a file argument:
complete -c gcc -s o -r
The short-style option -d for the grep command requires one of read, skip
or recurse:
complete -c grep -s d -x -a "read skip recurse"
The su command takes any username as an argument. Usernames are given as
the first colon-separated field in the file /etc/passwd. This can be speci-
fied as:
complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)"
The rpm command has several different modes. If the -e or --erase flag has
been specified, rpm should delete one or more packages, in which case sev-
eral switches related to deleting packages are valid, like the nodeps
switch.
This can be written as:
complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies"
where __fish_contains_opt is a function that checks the command line buffer
for the presence of a specified set of options.
To implement an alias, use the -w or --wraps option:
complete -c hub -w git
Now hub inherits all of the completions from git. Note this can also be
specified in a function declaration (function thing -w otherthing).
complete -c git
Shows all completions for git.
Any command foo that doesn't support grouping multiple short options in one
string (not supporting -xf as short for -x -f) or a short option and its
value in one string (not supporting -d9 instead of -d 9) should be speci-
fied as a single-character old-style option instead of as a short-style op-
tion; for example, complete -c foo -o s; complete -c foo -o v would never
suggest foo -ov but rather foo -o -v.
contains - test if a word is present in a list
Synopsis
contains [OPTIONS] KEY [VALUES ...]
Description
contains tests whether the set VALUES contains the string KEY. If so, con-
tains exits with code 0; if not, it exits with code 1.
The following options are available:
-i or --index
Print the index (number of the element in the set) of the first
matching element.
-h or --help
Displays help about using this command.
Note that contains interprets all arguments starting with a - as an option
to contains, until an -- argument is reached.
See the examples below.
Example
If animals is a list of animals, the following will test if animals con-
tains "cat":
if contains cat $animals
echo Your animal list is evil!
end
This code will add some directories to PATH if they aren't yet included:
for i in ~/bin /usr/local/bin
if not contains $i $PATH
set PATH $PATH $i
end
end
While this will check if function hasargs is being ran with the -q option:
function hasargs
if contains -- -q $argv
echo '$argv contains a -q option'
end
end
The -- here stops contains from treating -q to an option to itself. In-
stead it treats it as a normal string to check.
continue - skip the remainder of the current iteration of the current inner
loop
Synopsis
LOOP_CONSTRUCT; [COMMANDS ...;] continue; [COMMANDS ...;] end
Description
continue skips the remainder of the current iteration of the current inner
loop, such as a for loop or a while loop. It is usually added inside of a
conditional block such as an if statement or a switch statement.
The -h or --help option displays help about using this command.
Example
The following code removes all tmp files that do not contain the word
smurf.
for i in *.tmp
if grep smurf $i
continue
end
# This "rm" is skipped over if "continue" is executed.
rm $i
# As is this "echo"
echo $i
end
See Also
* the break command, to stop the current inner loop
count - count the number of elements of a list
Synopsis
count STRING1 STRING2 ...
COMMAND | count
count [...] < FILE
Description
count prints the number of arguments that were passed to it, plus the num-
ber of newlines passed to it via stdin. This is usually used to find out
how many elements an environment variable list contains, or how many lines
there are in a text file.
count does not accept any options, not even -h or --help.
count exits with a non-zero exit status if no arguments were passed to it,
and with zero if at least one argument was passed.
Note that, like wc -l, reading from stdin counts newlines, so echo -n foo |
count will print 0.
Example
count $PATH
# Returns the number of directories in the users PATH variable.
count *.txt
# Returns the number of files in the current working directory
# ending with the suffix '.txt'.
git ls-files --others --exclude-standard | count
# Returns the number of untracked files in a git repository
printf '%s\n' foo bar | count baz
# Returns 3 (2 lines from stdin plus 1 argument)
count < /etc/hosts
# Counts the number of entries in the hosts file
dirh - print directory history
Synopsis
dirh
Description
dirh prints the current directory history. The current position in the his-
tory is highlighted using the color defined in the fish_color_history_cur-
rent environment variable.
dirh does not accept any parameters.
Note that the cd command limits directory history to the 25 most recently
visited directories. The history is stored in the $dirprev and $dirnext
variables.
See Also
* the cdh command to display a prompt to quickly navigate the history
* the prevd command to move backward
* the nextd command to move forward
dirs - print directory stack
Synopsis
dirs [-c]
Description
dirs prints the current directory stack, as created by pushd and modified
by popd.
The following options are available:
-c: Clear the directory stack instead of printing it.
-h or --help
Displays help about using this command.
dirs does not accept any arguments.
See Also
* the cdh command, which provides a more intuitive way to navigate to re-
cently visited directories.
disown - remove a process from the list of jobs
Synopsis
disown [PID ...]
Description
disown removes the specified job from the list of jobs. The job itself con-
tinues to exist, but fish does not keep track of it any longer. This will
make fish lose all knowledge of the job, so functions defined with
--on-process-exit or --on-job-exit will no longer fire.
Jobs in the list of jobs are sent a hang-up signal when fish terminates,
which usually causes the job to terminate; disown allows these processes to
continue regardless.
If no process is specified, the most recently-used job is removed (like bg
and fg). If one or more PIDs are specified, jobs with the specified
process IDs are removed from the job list. Invalid jobs are ignored and a
warning is printed.
If a job is stopped, it is sent a signal to continue running, and a warning
is printed. It is not possible to use the bg builtin to continue a job once
it has been disowned.
disown returns 0 if all specified jobs were disowned successfully, and 1 if
any problems were encountered.
The --help or -h option displays help about using this command.
Example
firefox &; disown will start the Firefox web browser in the background and
remove it from the job list, meaning it will not be closed when the fish
process is closed.
disown (jobs -p) removes all jobs from the job list without terminating
them.
echo - display a line of text
Synopsis
echo [OPTIONS] [STRING]
Description
NOTE: This page documents the fish builtin echo. To see the documentation
on any non-fish versions, use command man echo.
echo displays STRING of text.
The following options are available:
-n Do not output a newline.
-s Do not separate arguments with spaces.
-E Disable interpretation of backslash escapes (default).
-e Enable interpretation of backslash escapes.
Unlike other shells, this echo accepts -- to signal the end of the options.
Escape Sequences
If -e is used, the following sequences are recognized:
* \ backslash
* \a alert (BEL)
* \b backspace
* \c produce no further output
* \e escape
* \f form feed
* \n new line
* \r carriage return
* \t horizontal tab
* \v vertical tab
* \0NNN byte with octal value NNN (1 to 3 digits)
* \xHH byte with hexadecimal value HH (1 to 2 digits)
Example
> echo 'Hello World'
Hello World
> echo -e 'Top\nBottom'
Top
Bottom
> echo -- -n
-n
See Also
* the printf command, for more control over output formatting
else - execute command if a condition is not met
Synopsis
if CONDITION; COMMANDS_TRUE ...; [else; COMMANDS_FALSE ...;] end
Description
if will execute the command CONDITION*. If the condition's exit status is
0, the commands COMMANDS_TRUE will execute. If it is not 0 and else is
given, COMMANDS_FALSE will be executed.
Example
The following code tests whether a file foo.txt exists as a regular file.
if test -f foo.txt
echo foo.txt exists
else
echo foo.txt does not exist
end
emit - emit a generic event
Synopsis
emit EVENT_NAME [ARGUMENTS ...]
Description
emit emits, or fires, an event. Events are delivered to, or caught by, spe-
cial functions called event handlers. The arguments are passed to the event
handlers as function arguments.
The --help or -h option displays help about using this command.
Example
The following code first defines an event handler for the generic event
named 'test_event', and then emits an event of that type.
function event_test --on-event test_event
echo event test: $argv
end
emit test_event something
Notes
Note that events are only sent to the current fish process as there is no
way to send events from one fish process to another.
end - end a block of commands
Synopsis
begin
[COMMANDS ...]
end
function NAME [OPTIONS]; COMMANDS ...; end
if CONDITION; COMMANDS_TRUE ...; [else; COMMANDS_FALSE ...;] end
switch VALUE; [case [WILDCARD ...]; [COMMANDS ...]; ...] end
while CONDITION; COMMANDS ...; end
for VARNAME in [VALUES ...]; COMMANDS ...; end
Description
The end keyword ends a block of commands started by one of the following
commands:
* begin to start a block of commands
* function to define a function
* if, switch to conditionally execute commands
* while, for to perform commands multiple times
The end keyword does not change the current exit status. Instead, the sta-
tus after it will be the status returned by the most recent command.
eval - evaluate the specified commands
Synopsis
eval [COMMANDS ...]
Description
eval evaluates the specified parameters as a command. If more than one pa-
rameter is specified, all parameters will be joined using a space character
as a separator.
If the command does not need access to stdin, consider using source in-
stead.
If no piping or other compound shell constructs are required, variable-ex-
pansion-as-command, as in set cmd ls -la; $cmd, is also an option.
Example
The following code will call the ls command and truncate each filename to
the first 12 characters.
set cmd ls \| cut -c 1-12
eval $cmd
exec - execute command in current process
Synopsis
exec COMMAND
Description
NOTE: This page documents the fish builtin exec. To see the documentation
on any non-fish versions, use command man exec.
exec replaces the currently running shell with a new command. On successful
completion, exec never returns. exec cannot be used inside a pipeline.
The --help or -h option displays help about using this command.
Example
exec emacs starts up the emacs text editor, and exits fish. When emacs ex-
its, the session will terminate.
exit - exit the shell
Synopsis
exit [CODE]
Description
exit is a special builtin that causes the shell to exit. Either 255 or the
CODE supplied is used, whichever is lesser. Otherwise, the exit status
will be that of the last command executed.
If exit is called while sourcing a file (using the source builtin) the rest
of the file will be skipped, but the shell itself will not exit.
The --help or -h option displays help about using this command.
export - compatibility function for exporting variables
Synopsis
export
export NAME=VALUE
Description
export is a function included for compatibility with POSIX shells. In gen-
eral, the set builtin should be used instead.
When called without arguments, export prints a list of currently-exported
variables, like set -x.
When called with a NAME=VALUE pair, the variable NAME is set to VALUE in
the global scope, and exported as an environment variable to other com-
mands.
There are no options available.
Example
The following commands have an identical effect.
set -gx PAGER bat
export PAGER=bat
Note: If you want to add to e.g. $PATH, you need to be careful to combine
the list. Quote it, like so:
export PATH="$PATH:/opt/bin"
Or just use set, which avoids this:
set -gx PATH $PATH /opt/bin
See more
1. The set command.
false - return an unsuccessful result
Synopsis
false
Description
false sets the exit status to 1.
See Also
* true command
* $status variable
fg - bring job to foreground
Synopsis
fg [PID]
Description
The fg builtin brings the specified job to the foreground, resuming it if
it is stopped. While a foreground job is executed, fish is suspended. If
no job is specified, the last job to be used is put in the foreground. If
PID is specified, the job containing a process with the specified process
ID is put in the foreground.
For compatibility with other shells, job expansion syntax is supported for
fg. A PID of the format %1 will foreground job 1. Job numbers can be seen
in the output of jobs.
The --help or -h option displays help about using this command.
Example
fg will put the last job in the foreground.
fg %3 will put job 3 into the foreground.
fish - the friendly interactive shell
Synopsis
fish [OPTIONS] [FILE [ARG ...]]
fish [OPTIONS] [-c COMMAND [ARG ...]]
Description
fish is a command-line shell written mainly with interactive use in mind.
This page briefly describes the options for invoking fish. The full manual
is available in HTML by using the help command from inside fish, and in the
fish-doc(1) man page. The tutorial is available as HTML via help tutorial
or in man fish-tutorial.
The following options are available:
-c or --command=COMMAND
Evaluate the specified commands instead of reading from the command-
line. Any additional positional arguments are used as $argv.
-C or --init-command=COMMANDS
Evaluate specified commands after reading the configuration but be-
fore executing command specified by -c or reading interactive input.
-d or --debug=DEBUG_CATEGORIES
Enables debug output and specify a pattern for matching debug cate-
gories. See Debugging below for details.
-o or --debug-output=DEBUG_FILE
Specifies a file path to receive the debug output, including cate-
gories and fish_trace. The default is standard error.
-i or --interactive
The shell is interactive.
-l or --login
Act as if invoked as a login shell.
-N or --no-config
Do not read configuration files.
-n or --no-execute
Do not execute any commands, only perform syntax checking.
-p or --profile=PROFILE_FILE
when fish exits, output timing information on all executed commands
to the specified file. This excludes time spent starting up and
reading the configuration.
--profile-startup=PROFILE_FILE
Will write timing for fish startup to specified file.
-P or --private
Enables private mode: fish will not access old or store new history.
--print-rusage-self
When fish exits, output stats from getrusage.
--print-debug-categories
Print all debug categories, and then exit.
-v or --version
Print version and exit.
-f or --features=FEATURES
Enables one or more comma-separated feature flags.
The fish exit status is generally the exit status of the last foreground
command.
Debugging
While fish provides extensive support for debugging fish scripts, it is
also possible to debug and instrument its internals. Debugging can be en-
abled by passing the --debug option. For example, the following command
turns on debugging for background IO thread events, in addition to the de-
fault categories, i.e. debug, error, warning, and warning-path:
> fish --debug=iothread
Available categories are listed by fish --print-debug-categories. The --de-
bug option accepts a comma-separated list of categories, and supports glob
syntax. The following command turns on debugging for complete, history,
history-file, and profile-history, as well as the default categories:
> fish --debug='complete,*history*'
Debug messages output to stderr by default. Note that if fish_trace is set,
execution tracing also outputs to stderr by default. You can output to a
file using the --debug-output option:
> fish --debug='complete,*history*' --debug-output=/tmp/fish.log --init-command='set fish_trace on'
These options can also be changed via the FISH_DEBUG and FISH_DEBUG_OUTPUT
variables. The categories enabled via --debug are added to the ones en-
abled by $FISH_DEBUG, so they can be disabled by prefixing them with -
(reader-*,-ast* enables reader debugging and disables ast debugging).
The file given in --debug-output takes precedence over the file in
FISH_DEBUG_OUTPUT.
Examples
To just start fish:
fish
To run a file with fish:
fish /path/to/script.fish
To run some commands with fish:
fish -c 'echo Hi there!'
You can also pass arguments to those commands:
> fish -c 'printf %s\n $argv' "first line" "second line"
first line
second line
To run a script, except read this other file first:
fish --init-cmd "source otherfile" script.fish
To profile fish's startup and find what takes the most time in your config-
uration:
fish --profile-startup /tmp/start.prof -ic exit
sort -nk2 /tmp/start.prof
fish_add_path - add to the path
Synopsis
fish_add_path path ...
fish_add_path [(-g | --global) | (-U | --universal) | (-P | --path)] [(-m | --move)] [(-a | --append) | (-p | --prepend)] [(-v | --verbose) | (-n | --dry-run)] PATHS ...
Description
fish_add_path is a simple way to add more directories to fish's PATH. It
does this by adding the directories either to fish_user_paths or directly
to PATH (if the --path switch is given).
It is (by default) safe to use fish_add_path in config.fish, or it can be
used once, interactively, and the paths will stay in future because of
universal variables. This is a "do what I mean" style command - it tries to
do the right thing by default, and follow your lead on what you have al-
ready set up (e.g. by using a global fish_user_paths if you have that al-
ready). If you need more control, consider modifying the variable yourself.
Directories are normalized with realpath. Trailing slashes are ignored and
relative paths are made absolute (but symlinks are not resolved). If a di-
rectory is already included, it is not added again and stays in the same
place unless the --move switch is given.
Directories are added in the order they are given, and they are prepended
to the path unless --append is given. If $fish_user_paths is used, that
means they are last in $fish_user_paths, which is itself prepended to PATH,
so they still stay ahead of the system paths. If the --path option is used,
the paths are appended/prepended to PATH directly, so this doesn't happen.
With --path, because PATH must be a global variable instead of a universal
one, the changes won't persist, so those calls need to be stored in
config.fish. This also applies to fish_user_paths if you make it global
(for instance by passing --global).
If no directory is new, the variable (fish_user_paths or PATH) is not set
again or otherwise modified, so variable handlers are not triggered.
If an argument is not an existing directory, fish_add_path ignores it.
Options
-a or --append
Add directories to the end of the variable.
-p or --prepend
Add directories to the front of the variable (this is the default).
-g or --global
Use a global fish_user_paths.
-U or --universal
Use a universal fish_user_paths - this is the default if it doesn't
already exist.
-P or --path
Manipulate PATH directly.
-m or --move
Move already-included directories to the place they would be added -
by default they would be left in place and not added again.
-v or --verbose
Print the set command used, and some more warnings, like when a path
is skipped because it doesn't exist or is not a directory. Verbose
mode is automatically enabled when fish_add_path is used interac-
tively and the output goes to the terminal.
-n or --dry-run
Print the set command that would be used without executing it.
-h or --help
Displays help about using this command.
If --move is used, it may of course lead to the path swapping order, so you
should be careful doing that in config.fish.
Example
# I just installed mycoolthing and need to add it to the path to use it.
# It is at /opt/mycoolthing/bin/mycoolthing,
# so let's add the directory: /opt/mycoolthing/bin.
> fish_add_path /opt/mycoolthing/bin
# I want my ~/.local/bin to be checked first,
# even if it was already added.
> fish_add_path -m ~/.local/bin
# I prefer using a global fish_user_paths
# This isn't saved automatically, I need to add this to config.fish
# if I want it to stay.
> fish_add_path -g ~/.local/bin ~/.otherbin /usr/local/sbin
# I want to append to the entire $PATH because this directory contains fallbacks
# This needs --path/-P because otherwise it appends to $fish_user_paths,
# which is added to the front of $PATH.
> fish_add_path --append --path /opt/fallback/bin
# I want to add the bin/ directory of my current $PWD (say /home/nemo/)
# -v/--verbose shows what fish_add_path did.
> fish_add_path -v bin/
set fish_user_paths /home/nemo/bin /usr/bin /home/nemo/.local/bin
# I have installed ruby via homebrew
> fish_add_path /usr/local/opt/ruby/bin
fish_breakpoint_prompt - define the prompt when stopped at a breakpoint
Synopsis
fish_breakpoint_prompt
function fish_breakpoint_prompt
...
end
Description
fish_breakpoint_prompt is the prompt function when asking for input in re-
sponse to a breakpoint command.
The exit status of commands within fish_breakpoint_prompt will not modify
the value of $status outside of the fish_breakpoint_prompt function.
fish ships with a default version of this function that displays the func-
tion name and line number of the current execution context.
Example
A simple prompt that is a simplified version of the default debugging
prompt:
function fish_breakpoint_prompt -d "Write out the debug prompt"
set -l function (status current-function)
set -l line (status current-line-number)
set -l prompt "$function:$line >"
echo -ns (set_color $fish_color_status) "BP $prompt" (set_color --reset) ' '
end
fish_clipboard_copy - copy text to the system's clipboard
Synopsis
fish_clipboard_copy
foo | fish_clipboard_copy
Description
The fish_clipboard_copy function copies text to the system clipboard.
If stdin is not a terminal (see isatty), it will read all input from there
and copy it. If it is, it will use the current commandline, or the current
selection if there is one.
It is bound to ctrl-x by default.
fish_clipboard_copy works by calling a system-specific backend. If it
doesn't appear to work you may need to install yours.
Currently supported are:
* pbcopy
* wl-copy using wayland
* xsel and xclip for X11
* clip.exe on Windows.
* The OSC 52 clipboard sequence, which your terminal might support
See also
* fish_clipboard_paste - get text from the system's clipboard which does
the inverse.
fish_clipboard_paste - get text from the system's clipboard
Synopsis
fish_clipboard_paste
fish_clipboard_paste | foo
Description
The fish_clipboard_paste function copies text from the system clipboard.
If its stdout is not a terminal (see isatty), it will output everything
there, as-is, without any additional newlines. If it is, it will put the
text in the commandline instead.
If it outputs to the commandline, it will automatically escape the output
if the cursor is currently inside single-quotes so it is suitable for sin-
gle-quotes (meaning it escapes ' and \\).
It is bound to ctrl-v by default.
fish_clipboard_paste works by calling a system-specific backend. If it
doesn't appear to work you may need to install yours.
Currently supported are:
* pbpaste
* wl-paste using wayland
* xsel and xclip for X11
* powershell.exe on Windows (this backend has encoding limitations and uses
windows line endings that fish_clipboard_paste undoes)
See also
* fish_clipboard_copy - copy text to the system's clipboard which does the
inverse.
fish_command_not_found - what to do when a command wasn't found
Synopsis
function fish_command_not_found
...
end
Description
When fish tries to execute a command and can't find it, it invokes this
function.
It can print a message to tell you about it, and it often also checks for a
missing package that would include the command.
Fish ships multiple handlers for various operating systems and chooses from
them when this function is loaded, or you can define your own.
It receives the full commandline as one argument per token, so $argv[1]
contains the missing command.
When you leave fish_command_not_found undefined (e.g. by adding an empty
function file) or explicitly call __fish_default_command_not_found_handler,
fish will just print a simple error.
Example
A simple handler:
function fish_command_not_found
echo Did not find command $argv[1]
end
> flounder
Did not find command flounder
Or the handler for OpenSUSE's command-not-found:
function fish_command_not_found
/usr/bin/command-not-found $argv[1]
end
Or the simple default handler:
function fish_command_not_found
__fish_default_command_not_found_handler $argv
end
Backwards compatibility
This command was introduced in fish 3.2.0. Previous versions of fish used
the "fish_command_not_found" event instead.
To define a handler that works in older versions of fish as well, define it
the old way:
function __fish_command_not_found_handler --on-event fish_command_not_found
echo COMMAND WAS NOT FOUND MY FRIEND $argv[1]
end
in which case fish will define a fish_command_not_found that calls it, or
define a wrapper:
function fish_command_not_found
echo "G'day mate, could not find your command: $argv"
end
function __fish_command_not_found_handler --on-event fish_command_not_found
fish_command_not_found $argv
end
fish_config - start the web-based configuration interface
Synopsis
fish_config [browse]
fish_config prompt (choose | list | save | show)
fish_config theme
fish_config theme choose THEME [ --color-theme=(dark | light) ]
fish_config theme demo
fish_config theme dump
fish_config theme list
fish_config theme show [THEME...]
Description
fish_config is used to configure fish.
Without arguments or with the browse command it starts the web-based con-
figuration interface. The web interface allows you to view your functions,
variables and history, and to make changes to your prompt and color config-
uration. It starts a local web server and opens a browser window. When you
are finished, close the browser window and press the Enter key to terminate
the configuration session.
If the BROWSER environment variable is set, it will be used as the name of
the web browser to open instead of the system default.
With the prompt command fish_config can be used to view and choose a prompt
from fish's sample prompts inside the terminal directly.
Available subcommands for the prompt command:
* choose loads a sample prompt in the current session.
* list lists the names of the available sample prompts.
* save saves the current prompt to a file (via funcsave).
* show shows what the given sample prompts (or all) would look like.
With the theme command fish_config can be used to view and choose a theme
(meaning a color scheme) inside the terminal.
Available subcommands for the theme command:
* choose loads a theme in the current session. If the theme has light and
dark variants (see below), the one matching fish_terminal_color_theme
will be applied (also whenever that variable changes). To override
fish_terminal_color_theme, pass the --color-theme argument.
* demo displays some sample text in the current theme.
* dump prints the current theme in a loadable format.
* list lists the names of the available themes.
* show shows what the given themes (or all) would look like.
* (not recommended) save saves the given theme to universal variables. A
theme set this way will not update as fish_terminal_color_theme changes.
The -h or --help option displays help about using this command.
Theme Files
fish_config theme and the theme selector in the web config tool load their
themes from theme files. These are stored in the fish configuration direc-
tory, typically ~/.config/fish/themes, with a .theme ending.
You can add your own theme by adding a file in that directory.
To get started quickly:
fish_config theme dump > ~/.config/fish/themes/my.theme
which will save your current theme in .theme format.
The format looks like this:
# name: 'My Theme'
[light]
# preferred_background: ffffff
fish_color_normal 000000
fish_color_autosuggestion 7f7f7f
fish_color_command 0000ee
[dark]
# preferred_background: 000000
fish_color_normal ffffff
fish_color_autosuggestion 7f7f7f
fish_color_command 5c5cff
[unknown]
fish_color_normal --reset
fish_color_autosuggestion brblack
fish_color_cancel -r
fish_color_command --reset
The comments provide name and background color to the web config tool.
Themes can have three variants, one for light mode, one for dark mode, and
one for terminals that don't report colors (where fish_terminal_color_theme
is set to unknown).
The other lines are just like set variable value, except that no expansions
are allowed. Quotes are, but aren't necessary.
Other than that, .theme files can contain any variable with a name that
matches the regular expression '^fish_(?:pager_)?color_.*$' - starts with
fish_, an optional pager_, then color_ and then anything.
Example
fish_config or fish_config browse opens a new web browser window and allows
you to configure certain fish settings.
fish_config prompt show demos the available sample prompts.
fish_config prompt choose disco makes the disco prompt the prompt for the
current session. This can also be used in config.fish to set the prompt.
fish_config prompt save saves the current prompt to an autoloaded file.
fish_config prompt save default chooses the default prompt and saves it.
fish_default_key_bindings - set emacs key bindings for fish
Synopsis
fish_default_key_bindings
Description
fish_default_key_bindings sets the emacs key bindings for fish shell.
Some of the Emacs key bindings are defined here.
There are no parameters for fish_default_key_bindings.
Examples
To start using emacs key bindings:
fish_default_key_bindings
fish_delta - compare functions and completions to the default
Synopsis
fish_delta name ...
fish_delta [-f | --no-functions] [-c | --no-completions] [-C | --no-config] [-d | --no-diff] [-n | --new] [-V | --vendor=]
fish_delta [-h | --help]
Description
The fish_delta function tells you, at a glance, which of your functions and
completions differ from the set that fish ships.
It does this by going through the relevant variables (fish_function_path
for functions and fish_complete_path for completions) and comparing the
files against fish's default directories.
If any names are given, it will only compare files by those names (plus a
".fish" extension).
By default, it will also use diff to display the difference between the
files. If diff is unavailable, it will skip it, but in that case it also
cannot figure out if the files really differ.
The exit status is 1 if there was a difference and 2 for other errors, oth-
erwise 0.
Options
The following options are available:
-f or --no-functions
Stops checking functions
-c or --no-completions
Stops checking completions
-C or --no-config
Stops checking configuration files like config.fish or snippets in
the conf.d directories.
-d or --no-diff
Removes the diff display (this happens automatically if diff can't
be found)
-n or --new
Also prints new files (i.e. those that can't be found in fish's de-
fault directories).
-Vvalue or --vendor=value
Determines how the vendor directories are counted. Valid values are:
* "default" - counts vendor files as belonging to the defaults. Any
changes in other directories will be counted as changes over them.
This is the default.
* "user" - counts vendor files as belonging to the user files. Any
changes in them will be counted as new or changed files.
* "ignore" - ignores vendor directories. Files of the same name will
be counted as "new" if no file of the same name in fish's default
directories exists.
-h or --help
Prints fish_delta's help (this).
Example
Running just:
fish_delta
will give you a list of all your changed functions and completions, includ-
ing diffs (if you have the diff command).
It might look like this:
> fish_delta
New: /home/alfa/.config/fish/functions/battery.fish
Changed: /home/alfa/.config/fish/test/completions/cargo.fish
--- /home/alfa/.config/fish/test/completions/cargo.fish 2022-09-02 12:57:55.579229959 +0200
+++ /usr/share/fish/completions/cargo.fish 2022-09-25 17:51:53.000000000 +0200
# the output of `diff` follows
The options are there to select which parts of the output you want. With
--no-completions you can compare just functions, and with --no-diff you can
turn off the diff display.
To only compare your fish_git_prompt, you might use:
fish_delta --no-completions fish_git_prompt
which will only compare files called "fish_git_prompt.fish".
fish_git_prompt - output git information for use in a prompt
Synopsis
fish_git_prompt [FORMAT]
function fish_prompt
printf '%s' $PWD (fish_git_prompt) ' $ '
end
Description
The fish_git_prompt function displays information about the current git
repository, if any.
Git <https://git-scm.com> must be installed.
It is possible to modify the output format by passing an argument. The de-
fault value is " (%s)".
There are numerous customization options, which can be controlled with git
options or fish variables. git options, where available, take precedence
over the fish variable with the same function. git options can be set on a
per-repository or global basis. git options can be set with the git config
command, while fish variables can be set as usual with the set command.
Boolean options (those which enable or disable something) understand "1",
"yes" or "true" to mean true and every other value to mean false.
* $__fish_git_prompt_show_informative_status or the git option bash.showIn-
formativeStatus can be set to 1, true or yes to enable the "informative"
display, which will show a large amount of information - the number of
dirty files, unpushed/unpulled commits, and more. In large repositories,
this can take a lot of time, so you may wish to disable it in these
repositories with git config --local bash.showInformativeStatus false.
It also changes the characters the prompt uses to less plain ones (^a in-
stead of * for the dirty state for example) , and if you are only inter-
ested in that, set $__fish_git_prompt_use_informative_chars instead.
Because counting untracked files requires a lot of time, the number of
untracked files is only shown if enabled via $__fish_git_prompt_showun-
trackedfiles or the git option bash.showUntrackedFiles.
* $__fish_git_prompt_showdirtystate or the git option bash.showDirtyState
can be set to 1, true or yes to show if the repository is "dirty", i.e.
has uncommitted changes.
* $__fish_git_prompt_showuntrackedfiles or the git option bash.showUn-
trackedFiles can be set to 1, true or yes to show if the repository has
untracked files (that aren't ignored).
* $__fish_git_prompt_showupstream can be set to a list of values to deter-
mine how changes between HEAD and upstream are shown:
auto summarize the difference between HEAD and its upstream
verbose
show number of commits ahead/behind (+/-) upstream
name if verbose, then also show the upstream abbrev name
informative
similar to verbose, but shows nothing when equal - this is the
default if informative status is enabled.
git always compare HEAD to @{upstream}
svn always compare HEAD to your SVN upstream
none disables (useful with informative status)
* $__fish_git_prompt_showstashstate can be set to 1, true or yes to display
the state of the stash.
* $__fish_git_prompt_shorten_branch_len can be set to the number of charac-
ters that the branch name will be shortened to.
* $__fish_git_prompt_describe_style can be set to one of the following
styles to describe the current HEAD:
contains
relative to newer annotated tag, such as (v1.6.3.2~35)
branch
relative to newer tag or branch, such as (master~4)
describe
relative to older annotated tag, such as (v1.6.3.1-13-gdd42c2f)
default
an exactly matching tag ((develop))
If none of these apply, the commit SHA shortened to 8 characters is
used.
* $__fish_git_prompt_showcolorhints can be set to 1, true or yes to enable
coloring for the branch name and status symbols.
A number of variables set characters and color used as indicators. Many of
these have a different default if used with informative status enabled, or
$__fish_git_prompt_use_informative_chars set. The usual default is given
first, then the informative default (if it is different). If no default for
the colors is given, they default to $__fish_git_prompt_color.
* $__fish_git_prompt_char_stateseparator (' ', |) - the character to be
used between the state characters
* $__fish_git_prompt_color (no default)
* $__fish_git_prompt_color_prefix - the color of the ( prefix
* $__fish_git_prompt_color_suffix - the color of the ) suffix
* $__fish_git_prompt_color_bare - the color to use for a bare repository -
one without a working tree
* $__fish_git_prompt_color_merging - the color when a merge/rebase/re-
vert/bisect or cherry-pick is in progress
* $__fish_git_prompt_char_cleanstate (a in informative mode) - the charac-
ter to be used when nothing else applies
* $__fish_git_prompt_color_cleanstate (no default)
Variables used with showdirtystate:
* $__fish_git_prompt_char_dirtystate (*, a) - the number of "dirty"
changes, i.e. unstaged files with changes
* $__fish_git_prompt_char_invalidstate (#, a) - the number of "unmerged"
changes, e.g. additional changes to already added files
* $__fish_git_prompt_char_stagedstate (+, a) - the number of staged files
without additional changes
* $__fish_git_prompt_color_dirtystate (red with showcolorhints, same as
color_flags otherwise)
* $__fish_git_prompt_color_invalidstate
* $__fish_git_prompt_color_stagedstate (green with showcolorhints,
color_flags otherwise)
Variables used with showstashstate:
* $__fish_git_prompt_char_stashstate ($, a)
* $__fish_git_prompt_color_stashstate (same as color_flags)
Variables used with showuntrackedfiles:
* $__fish_git_prompt_char_untrackedfiles (%, a|) - the symbol for untracked
files
* $__fish_git_prompt_color_untrackedfiles (same as color_flags)
Variables used with showupstream (also implied by informative status):
* $__fish_git_prompt_char_upstream_ahead (>, a) - the character for the
commits this repository is ahead of upstream
* $__fish_git_prompt_char_upstream_behind (<, a) - the character for the
commits this repository is behind upstream
* $__fish_git_prompt_char_upstream_diverged (<>, aa) - the symbol if this
repository is both ahead and behind upstream
* $__fish_git_prompt_char_upstream_equal (=) - the symbol if this repo is
equal to upstream
* $__fish_git_prompt_char_upstream_prefix ('')
* $__fish_git_prompt_color_upstream
Colors used with showcolorhints:
* $__fish_git_prompt_color_branch (green) - the color of the branch if
nothing else applies
* $__fish_git_prompt_color_branch_detached (red) the color of the branch if
it's detached (e.g. a commit is checked out)
* $__fish_git_prompt_color_branch_dirty (no default) the color of the
branch if it's dirty and not detached
* $__fish_git_prompt_color_branch_staged (no default) the color of the
branch if it just has something staged and is otherwise clean
* $__fish_git_prompt_color_flags (--bold blue) - the default color for
dirty/staged/stashed/untracked state
Note that all colors can also have a corresponding _done color. For exam-
ple, the contents of $__fish_git_prompt_color_upstream_done is printed
right _after_ the upstream.
See also fish_vcs_prompt, which will call all supported version control
prompt functions, including git, Mercurial and Subversion.
Example
A simple prompt that displays git info:
function fish_prompt
# ...
set -g __fish_git_prompt_showupstream auto
printf '%s %s$' $PWD (fish_git_prompt)
end
fish_greeting - display a welcome message in interactive shells
Synopsis
fish_greeting
function fish_greeting
...
end
Description
When an interactive fish starts, it executes fish_greeting and displays its
output.
The default fish_greeting is a function that prints a variable of the same
name ($fish_greeting), so you can also just change that if you just want to
change the text.
If SHELL_WELCOME is set, it is displayed after the greeting. This is a
standard environment variable that may be set by tools like systemd's run0
to display session information.
While you could also just put echo calls into config.fish, fish_greeting
takes care of only being used in interactive shells, so it won't be used
e.g. with scp (which executes a shell), which prevents some errors.
Example
To just empty the text, with the default greeting function:
set -U fish_greeting
or set -g fish_greeting in config.fish.
A simple greeting:
function fish_greeting
echo Hello friend!
echo The time is (set_color yellow)(date +%T)(set_color --reset) and this machine is called $hostname
end
fish_hg_prompt - output Mercurial information for use in a prompt
Synopsis
fish_hg_prompt
function fish_prompt
printf '%s' $PWD (fish_hg_prompt) ' $ '
end
Description
The fish_hg_prompt function displays information about the current Mercur-
ial repository, if any.
Mercurial <https://www.mercurial-scm.org/> (hg) must be installed.
By default, only the current branch is shown because hg status can be slow
on a large repository. You can enable a more informative prompt by setting
the variable $fish_prompt_hg_show_informative_status, for example:
set fish_prompt_hg_show_informative_status
If you enabled the informative status, there are numerous customization op-
tions, which can be controlled with fish variables.
* $fish_color_hg_clean, $fish_color_hg_modified and $fish_color_hg_dirty
are colors used when the repository has the respective status.
Some colors for status symbols:
* $fish_color_hg_added
* $fish_color_hg_renamed
* $fish_color_hg_copied
* $fish_color_hg_deleted
* $fish_color_hg_untracked
* $fish_color_hg_unmerged
The status symbols themselves:
* $fish_prompt_hg_status_added, default 'a'
* $fish_prompt_hg_status_modified, default '*'
* $fish_prompt_hg_status_copied, default 'a'
* $fish_prompt_hg_status_deleted, default 'a'
* $fish_prompt_hg_status_untracked, default '?'
* $fish_prompt_hg_status_unmerged, default '!'
Finally, $fish_prompt_hg_status_order, which can be used to change the or-
der the status symbols appear in. It defaults to added modified copied
deleted untracked unmerged.
See also fish_vcs_prompt, which will call all supported version control
prompt functions, including git, Mercurial and Subversion.
Example
A simple prompt that displays hg info:
function fish_prompt
...
set -g fish_prompt_hg_show_informative_status
printf '%s %s$' $PWD (fish_hg_prompt)
end
fish_indent - indenter and prettifier
Synopsis
fish_indent [OPTIONS] [FILE ...]
Description
fish_indent is used to indent a piece of fish code. fish_indent reads com-
mands from standard input or the given filenames and outputs them to stan-
dard output or a specified file (if -w is given).
The following options are available:
-w or --write
Indents a specified file and immediately writes to that file.
-i or --no-indent
Do not indent commands; only reformat to one job per line.
--only-indent
Do not reformat, only indent each line.
--only-unindent
Do not reformat, only unindent each line.
-c or --check
Do not indent, only return 0 if the code is already indented as
fish_indent would, the number of failed files otherwise. Also print
the failed filenames if not reading from standard input.
-v or --version
Displays the current fish version and then exits.
--ansi
Colorizes the output using ANSI escape sequences using the colors
defined in the environment (such as fish_color_command).
--html
Outputs HTML, which supports syntax highlighting if the appropriate
CSS is defined. The CSS class names are the same as the variable
names, such as fish_color_command.
--dump-parse-tree
Dumps information about the parsed statements to standard error.
This is likely to be of interest only to people working on the fish
source code.
-h or --help
Displays help about using this command.
fish_is_root_user - check if the current user is root
Synopsis
fish_is_root_user
Description
fish_is_root_user will check if the current user is root. It can be useful
for the prompt to display something different if the user is root, for ex-
ample.
Example
A simple example:
function example --description 'Just an example'
if fish_is_root_user
do_something_different
end
end
fish_key_reader - explore what characters keyboard keys send
Synopsis
fish_key_reader [OPTIONS]
Description
fish_key_reader is used to explain how you would bind a certain key se-
quence. By default, it prints the bind command for one key sequence read
interactively over standard input.
The following options are available:
-c or --continuous
Begins a session where multiple key sequences can be inspected. By
default the program exits after capturing a single key sequence.
-h or --help
Displays help about using this command.
-V or --verbose
Explain what sequence was received in addition to the decoded key.
-v or --version
Displays the current fish version and then exits.
Usage Notes
fish_key_reader intentionally disables handling of many signals. To termi-
nate fish_key_reader in --continuous mode do:
* press ctrl-c twice, or
* press ctrl-d twice, or
* type exit, or
* type quit
Example
> fish_key_reader
Press a key:
# press up-arrow
bind up 'do something'
fish_mode_prompt - define the appearance of the mode indicator
Synopsis
fish_mode_prompt
function fish_mode_prompt
echo -n "$fish_bind_mode "
end
Description
The fish_mode_prompt function outputs the mode indicator for use in vi
mode.
The default fish_mode_prompt function will output indicators about the cur-
rent vi editor mode displayed to the left of the regular prompt. Define
your own function to customize the appearance of the mode indicator. The
$fish_bind_mode variable can be used to determine the current mode. It will
be one of default, insert, replace_one, replace, visual, or operator.
You can also define an empty fish_mode_prompt function to remove the vi
mode indicators:
function fish_mode_prompt; end
funcsave fish_mode_prompt
fish_mode_prompt will be executed when the vi mode changes. If it produces
any output, it is displayed and used. If it does not, the other prompt
functions (fish_prompt and fish_right_prompt) will be executed as well in
case they contain a mode display.
If fish_transient_prompt is set to 1, fish_mode_prompt --final-rendering is
run before executing the commandline.
Example
function fish_mode_prompt
switch $fish_bind_mode
case default
set_color --bold red
echo 'N'
case insert
set_color --bold green
echo 'I'
case replace_one
set_color --bold green
echo 'R'
case replace
set_color --bold bryellow
echo 'R'
case visual
set_color --bold brmagenta
echo 'V'
case operator f F t T
set_color --bold cyan
echo 'N'
case '*'
set_color --bold red
echo '?'
end
set_color --reset
end
Outputting multiple lines is not supported in fish_mode_prompt.
fish_opt - create an option specification for the argparse command
Synopsis
fish_opt [-s ALPHANUM] [-l LONG-NAME] [-ormd] [--long-only] [-v COMMAND OPTIONS ... ]
fish_opt --help
Description
This command provides a way to produce option specifications suitable for
use with the argparse command. You can, of course, write the option speci-
fications by hand without using this command. But you might prefer to use
this for the clarity it provides.
The following argparse options are available:
-s or --short ALPHANUM
Takes a single letter or number that is used as the short flag in
the option being defined. Either this option or the --long option
must be provided.
-l or --long LONG-NAME
Takes a string that is used as the long flag in the option being de-
fined. This option is optional and has no default. If no long flag
is defined then only the short flag will be allowed when parsing ar-
guments using the option specification.
--long-only
Deprecated. The option being defined will only allow the long flag
name to be used, even if the short flag is defined (i.e., --short is
specified).
-o or --optional-val
The option being defined can take a value, but it is optional rather
than required. If the option is seen more than once when parsing ar-
guments, only the last value seen is saved. This means the resulting
flag variable created by argparse will zero elements if no value was
given with the option else it will have exactly one element.
-r or --required-val
The option being defined requires a value. If the option is seen
more than once when parsing arguments, only the last value seen is
saved. This means the resulting flag variable created by argparse
will have exactly one element.
-m or --multiple-vals
The value of each instance of the option is accumulated. If --op-
tional-val is provided, the value is optional, and an empty string
is stored if no value is provided. Otherwise, the --requiured-val
option is implied and each instance of the option requires a value.
This means the resulting flag variable created by argparse will have
one element for each instance of this option in the arguments, even
for instances that did not provide a value.
-d or --delete
The option and any values will be deleted from the $argv_opts vari-
ables set by argparse (as with other options, it will also be
deleted from $argv).
-v or --validate COMMAND OPTION...
This option must be the last one, and requires one of -o, -r, or -m.
All the remaining arguments are interpreted a fish script to run to
validate the value of the argument, see argparse documentation for
more details. Note that the interpretation of COMMAND OPTION... is
similar to eval, so you may need to quote or escape special charac-
ters twice if you want them to be interpreted literally when the
validate script is run.
-h or --help
Displays help about using this command.
Examples
Define a single option specification for the boolean help flag:
set -l options (fish_opt -s h -l help)
argparse $options -- $argv
Same as above but with a second flag that requires a value:
set -l options (fish_opt -s h -l help)
set options $options (fish_opt -s m -l max -r)
argparse $options -- $argv
Same as above but the value of the second flag cannot be the empty string:
set -l options (fish_opt -s h -l help)
set options $options (fish_opt -s m -l max -rv test \$_flag_value != "''")
argparse $options -- $argv
Same as above but with a third flag that can be given multiple times saving
the value of each instance seen and only a long flag name (--token) is de-
fined:
set -l options (fish_opt --short=h --long=help)
set options $options (fish_opt --short=m --long=max --required-val --validate test \$_flag_value != "''")
set options $options (fish_opt --long=token --multiple-vals)
argparse $options -- $argv
fish_prompt - define the appearance of the command line prompt
Synopsis
fish_prompt
function fish_prompt
...
end
Description
The fish_prompt function is executed when the prompt is to be shown, and
the output is used as a prompt.
The exit status of commands within fish_prompt will not modify the value of
$status outside of the fish_prompt function.
If fish_transient_prompt is set to 1, fish_prompt --final-rendering is run
before executing the commandline.
If SHELL_PROMPT_PREFIX or SHELL_PROMPT_SUFFIX are set, they are automati-
cally prepended and appended to the left prompt. This applies to all
prompts regardless of whether fish_prompt has been customized.
fish ships with a number of example prompts that can be chosen with the
fish_config command.
Example
A simple prompt:
function fish_prompt -d "Write out the prompt"
# This shows up as USER@HOST /home/user/ >, with the directory colored
# $USER and $hostname are set by fish, so you can just use them
# instead of using `whoami` and `hostname`
printf '%s@%s %s%s%s > ' $USER $hostname \
(set_color $fish_color_cwd) (prompt_pwd) (set_color --reset)
end
fish_right_prompt - define the appearance of the right-side command line
prompt
Synopsis
function fish_right_prompt
...
end
Description
fish_right_prompt is similar to fish_prompt, except that it appears on the
right side of the terminal window.
Multiple lines are not supported in fish_right_prompt.
If fish_transient_prompt is set to 1, fish_right_prompt --final-rendering
is run before executing the commandline.
Example
A simple right prompt:
function fish_right_prompt -d "Write out the right prompt"
date '+%m/%d/%y'
end
fish_should_add_to_history - decide whether a command should be added to the
history
Synopsis
fish_should_add_to_history
function fish_should_add_to_history
...
end
Description
The fish_should_add_to_history function is executed before fish adds a com-
mand to history, and its return status decides whether that is done.
If it returns 0, the command is stored in history, when it returns anything
else, it is not. In the latter case the command can still be recalled for
one command.
The first argument to fish_should_add_to_history is the commandline. His-
tory is added before a command is run, so e.g. status can't be checked.
This is so commands that don't finish like exec - execute command in cur-
rent process and long-running commands are available in new sessions imme-
diately.
If fish_should_add_to_history doesn't exist, fish will save a command to
history unless it starts with a space. If it does exist, this function
takes over all of the duties, so commands starting with space are saved un-
less fish_should_add_to_history says otherwise.
Example
A simple example:
function fish_should_add_to_history
for cmd in vault mysql ls
string match -qr "^$cmd" -- $argv; and return 1
end
return 0
end
This refuses to store any immediate "vault", "mysql" or "ls" calls. Com-
mands starting with space would be stored.
function fish_should_add_to_history
# I don't want `git pull`s in my history when I'm in a specific repository
if string match -qr '^git pull' -- "$argv"
and string match -qr "^/home/me/my-secret-project/" -- (pwd -P)
return 1
end
return 0
end
fish_status_to_signal - convert exit codes to human-friendly signals
Synopsis
fish_status_to_signal NUM
function fish_prompt
echo -n (fish_status_to_signal $pipestatus | string join '|') (prompt_pwd) '$ '
end
Description
fish_status_to_signal converts exit codes to their corresponding hu-
man-friendly signals if one exists. This is likely to be useful for
prompts in conjunction with the $status and $pipestatus variables.
Example
>_ sleep 5
^Ca
>_ fish_status_to_signal $status
SIGINT
fish_svn_prompt - output Subversion information for use in a prompt
Synopsis
fish_svn_prompt
function fish_prompt
printf '%s' $PWD (fish_svn_prompt) ' $ '
end
Description
The fish_svn_prompt function displays information about the current Subver-
sion repository, if any.
Subversion <https://subversion.apache.org/> (svn) must be installed.
There are numerous customization options, which can be controlled with fish
variables.
*
__fish_svn_prompt_color_revision
the colour of the revision number to display in the prompt
*
__fish_svn_prompt_char_separator
the separator between status characters
A number of variables control the symbol ("display") and color ("color")
for the different status indicators:
* __fish_svn_prompt_char_added_display
* __fish_svn_prompt_char_added_color
* __fish_svn_prompt_char_conflicted_display
* __fish_svn_prompt_char_conflicted_color
* __fish_svn_prompt_char_deleted_display
* __fish_svn_prompt_char_deleted_color
* __fish_svn_prompt_char_ignored_display
* __fish_svn_prompt_char_ignored_color
* __fish_svn_prompt_char_modified_display
* __fish_svn_prompt_char_modified_color
* __fish_svn_prompt_char_replaced_display
* __fish_svn_prompt_char_replaced_color
* __fish_svn_prompt_char_unversioned_external_display
* __fish_svn_prompt_char_unversioned_external_color
* __fish_svn_prompt_char_unversioned_display
* __fish_svn_prompt_char_unversioned_color
* __fish_svn_prompt_char_missing_display
* __fish_svn_prompt_char_missing_color
* __fish_svn_prompt_char_versioned_obstructed_display
* __fish_svn_prompt_char_versioned_obstructed_color
* __fish_svn_prompt_char_locked_display
* __fish_svn_prompt_char_locked_color
* __fish_svn_prompt_char_scheduled_display
* __fish_svn_prompt_char_scheduled_color
* __fish_svn_prompt_char_switched_display
* __fish_svn_prompt_char_switched_color
* __fish_svn_prompt_char_token_present_display
* __fish_svn_prompt_char_token_present_color
* __fish_svn_prompt_char_token_other_display
* __fish_svn_prompt_char_token_other_color
* __fish_svn_prompt_char_token_stolen_display
* __fish_svn_prompt_char_token_stolen_color
* __fish_svn_prompt_char_token_broken_display
* __fish_svn_prompt_char_token_broken_color
See also fish_vcs_prompt, which will call all supported version control
prompt functions, including git, Mercurial and Subversion.
Example
A simple prompt that displays svn info:
function fish_prompt
...
printf '%s %s$' $PWD (fish_svn_prompt)
end
fish_tab_title - define the terminal tab's title
Synopsis
fish_title
fish_tab_title
function fish_title
...
end
function fish_tab_title
...
end
Description
The fish_title function is executed before and after a new command is exe-
cuted or put into the foreground and the output is used as a titlebar mes-
sage.
The first argument to fish_title contains the most recently executed fore-
ground command as a string, if any.
This requires that your terminal supports programmable titles and the fea-
ture is turned on.
To disable setting the title, use an empty function (see below).
To set the terminal tab title to something other than the terminal window
title, define the fish_tab_title function, which works like fish_title but
overrides that one.
Example
A simple title:
function fish_title
set -q argv[1]; or set argv fish
# Looks like ~/d/fish: git log
# or /e/apt: fish
echo (fish_prompt_pwd_dir_length=1 prompt_pwd): $argv;
end
Do not change the title:
function fish_title
end
Change the tab title only:
function fish_tab_title
echo fish $fish_pid
end
fish_title - define the terminal's title
Synopsis
fish_title
fish_tab_title
function fish_title
...
end
function fish_tab_title
...
end
Description
The fish_title function is executed before and after a new command is exe-
cuted or put into the foreground and the output is used as a titlebar mes-
sage.
The first argument to fish_title contains the most recently executed fore-
ground command as a string, if any.
This requires that your terminal supports programmable titles and the fea-
ture is turned on.
To disable setting the title, use an empty function (see below).
To set the terminal tab title to something other than the terminal window
title, define the fish_tab_title function, which works like fish_title but
overrides that one.
Example
A simple title:
function fish_title
set -q argv[1]; or set argv fish
# Looks like ~/d/fish: git log
# or /e/apt: fish
echo (fish_prompt_pwd_dir_length=1 prompt_pwd): $argv;
end
Do not change the title:
function fish_title
end
Change the tab title only:
function fish_tab_title
echo fish $fish_pid
end
fish_update_completions - update completions using manual pages
Synopsis
fish_update_completions
Description
fish_update_completions parses manual pages installed on the system, and
attempts to create completion files in the fish configuration directory.
This does not overwrite custom completions.
There are no parameters for fish_update_completions.
fish_vcs_prompt - output version control system information for use in a
prompt
Synopsis
fish_vcs_prompt
function fish_prompt
printf '%s' $PWD (fish_vcs_prompt) ' $ '
end
Description
The fish_vcs_prompt function displays information about the current version
control system (VCS) repository, if any.
It calls out to VCS-specific functions. The currently supported systems
are:
* fish_git_prompt
* fish_hg_prompt
* fish_svn_prompt
If a VCS isn't installed, the respective function does nothing.
The Subversion prompt is disabled by default, because it's slow on large
repositories. To enable it, modify fish_vcs_prompt to uncomment it. See
funced.
For more information, see the documentation for each of the functions
above.
Example
A simple prompt that displays all known VCS info:
function fish_prompt
...
set -g __fish_git_prompt_showupstream auto
printf '%s %s$' $PWD (fish_vcs_prompt)
end
fish_vi_key_bindings - set vi key bindings for fish
Synopsis
fish_vi_key_bindings
fish_vi_key_bindings [--no-erase] [INIT_MODE]
Description
fish_vi_key_bindings sets the vi key bindings for fish shell.
If a valid INIT_MODE is provided (insert, default, visual), then that mode
will become the default . If no INIT_MODE is given, the mode defaults to
insert mode.
The following parameters are available:
--no-erase
Does not clear previous set bindings
Further information on how to use vi mode.
Differences from Vim
Fish's vi mode aims to be familiar to vim users, but there are some differ-
ences:
Word character handling
In vim, underscore (_) is treated as a keyword character by default,
so word motions like w, b, and e treat foo_bar as a single word. In
fish, underscore is treated as punctuation, so word motions stop at
underscores. For example, pressing w on foo_bar in fish stops at the
_, while in vim it would jump past the entire identifier.
The cw command
In vim, cw has special behavior: when the cursor is on a non-space
character, it behaves like ce (change to end of word), but when the
cursor is on a space, it behaves like dwi (delete word then insert).
In fish, cw always behaves like dwi - it deletes to the start of the
next word (including trailing whitespace), then enters insert mode.
To get vim's cw behavior in fish, use ce instead.
Examples
To start using vi key bindings:
fish_vi_key_bindings
or set -g fish_key_bindings fish_vi_key_bindings in config.fish.
for - perform a set of commands multiple times
Synopsis
for VARNAME in [VALUES ...]; COMMANDS ...; end
Description
for is a loop construct. It will perform the commands specified by COMMANDS
multiple times. On each iteration, the local variable specified by VARNAME
is assigned a new value from VALUES. If VALUES is empty, COMMANDS will not
be executed at all. The VARNAME is visible when the loop terminates and
will contain the last value assigned to it. If VARNAME does not already ex-
ist it will be set in the local scope. For our purposes if the for block is
inside a function there must be a local variable with the same name. If the
for block is not nested inside a function then global and universal vari-
ables of the same name will be used if they exist.
Much like set, for does not modify $status, but the evaluation of its sub-
ordinate commands can.
The -h or --help option displays help about using this command.
Example
for i in foo bar baz; echo $i; end
# would output:
foo
bar
baz
Notes
The VARNAME was local to the for block in releases prior to 3.0.0. This
means that if you did something like this:
for var in a b c
if break_from_loop
break
end
end
echo $var
The last value assigned to var when the loop terminated would not be avail-
able outside the loop. What echo $var would write depended on what it was
set to before the loop was run. Likely nothing.
funced - edit a function interactively
Synopsis
funced [OPTIONS] NAME
Description
funced provides an interface to edit the definition of the function NAME.
If the $VISUAL environment variable is set, it will be used as the program
to edit the function. If $VISUAL is unset but $EDITOR is set, that will be
used. Otherwise, a built-in editor will be used. Note that to enter a lit-
eral newline using the built-in editor you should press alt-enter. Pressing
enter signals that you are done editing the function. This does not apply
to an external editor like emacs or vim.
funced will try to edit the original file that a function is defined in,
which might include variable definitions or helper functions as well. If
changes cannot be saved to the original file, a copy will be created in the
user's function directory.
If there is no function called NAME, a new function will be created with
the specified name.
-e command or --editor command
Open the function body inside the text editor given by the command
(for example, -e vi). The special command fish will use the built-in
editor (same as specifying -i).
-i or --interactive
Force opening the function body in the built-in editor even if $VI-
SUAL or $EDITOR is defined.
-s or --save
Automatically save the function after successfully editing it.
-h or --help
Displays help about using this command.
Example
Say you want to modify your prompt.
Run:
>_ funced fish_prompt
This will open up your editor, allowing you to modify the function. When
you're done, save and quit. Fish will reload the function, so you should
see the changes right away.
When you're done, use:
>_ funcsave fish_prompt
For more, see funcsave. To view a function's current definition, use
functions or type.
funcsave - save the definition of a function to the user's autoload directory
Synopsis
funcsave FUNCTION_NAME
funcsave [-q | --quiet] [(-d | --directory) DIR] FUNCTION_NAME
Description
funcsave saves a function to a file in the fish configuration directory.
This function will be automatically loaded by current and future fish ses-
sions. This can be useful to commit functions created interactively for
permanent use.
If you have erased a function using functions's --erase option, funcsave
will remove the saved function definition.
Because fish loads functions on-demand, saved functions cannot serve as
event handlers until they are run or otherwise sourced. To activate an
event handler for every new shell, add the function to the configuration
file instead of using funcsave.
This is often used after funced, which opens the function in $EDITOR or
$VISUAL and loads it into the current session afterwards.
To view a function's current definition, use functions or type.
function - create a function
Synopsis
function NAME [OPTIONS]; BODY; end
Description
function creates a new function NAME with the body BODY.
A function is a list of commands that will be executed when the name of the
function is given as a command.
The following options are available:
-a NAMES or --argument-names NAMES
Assigns the value of successive command-line arguments to the names
given in NAMES (separated by spaces). These are the same arguments
given in argv, and are still available there (unless --inherit-vari-
able argv was used or one of the given NAMES is argv). See also
Argument Handling.
-d DESCRIPTION or --description DESCRIPTION
A description of what the function does, suitable as a completion
description.
-w WRAPPED_COMMAND or --wraps WRAPPED_COMMAND
Inherit completions from the given WRAPPED_COMMAND. This is used to
say that this function completes like that command, for example if
you're creating an alias. See the documentation for complete for
more information. If the wrapped command is the same as the func-
tion name, this will be ignored.
-e EVENT_NAME or --on-event EVENT_NAME
Run this function when the specified named event is emitted. Fish
internally generates named events, for example, when showing the
prompt. Custom events can be emitted using the emit command.
-v VARIABLE_NAME or --on-variable VARIABLE_NAME
Run this function when the variable VARIABLE_NAME changes value.
Note that fish makes no guarantees on any particular timing or even
that the function will be run for every single set. Rather it will
be run when the variable has been set at least once, possibly skip-
ping some values or being run when the variable has been set to the
same value (except for universal variables set in other shells -
only changes in the value will be picked up for those).
-j PID or --on-job-exit PID
Run this function when the job containing a child process with the
given process ID PID exits. Instead of a PID, the string 'caller'
can be specified. This is only allowed when in a command substitu-
tion, and will result in the handler being triggered by the exit of
the job which created this command substitution. This will not
trigger for disowned jobs.
-p PID or --on-process-exit PID
Run this function when the fish child process with process ID PID
exits. Instead of a PID, for backward compatibility, "%self" can be
specified as an alias for $fish_pid, and the function will be run
when the current fish instance exits. This will not trigger for
disowned jobs.
-s SIGSPEC or --on-signal SIGSPEC
Run this function when the signal SIGSPEC is delivered. SIGSPEC can
be a signal number, or the signal name, such as SIGHUP (or just
HUP). Note that the signal must have been delivered to fish; for ex-
ample, ctrl-c sends SIGINT to the foreground process group, which
will not be fish if you are running another command at the time. Ob-
serving a signal will prevent fish from exiting in response to that
signal.
-S or --no-scope-shadowing
Allows the function to access the variables of calling functions.
Normally, any variables inside the function that have the same name
as variables from the calling function are "shadowed", and their
contents are independent of the calling function.
It's important to note that this does not capture referenced vari-
ables or the scope at the time of function declaration! At this
time, fish does not have any concept of closures, and variable life-
times are never extended. In other words, by using --no-scope-shad-
owing the scope of the function each time it is run is shared with
the scope it was called from rather than the scope it was defined
in.
-V or --inherit-variable NAME
Snapshots the value of the variable NAME and defines a local vari-
able with that same name and value when the function is defined.
This is similar to a closure in other languages like Python but a
bit different. Note the word "snapshot" in the first sentence. If
you change the value of the variable after defining the function,
even if you do so in the same scope (typically another function) the
new value will not be used by the function you just created using
this option. See the function notify example below for how this
might be used.
The event handler switches (on-event, on-variable, on-job-exit,
on-process-exit and on-signal) cause a function to run automatically at
specific events. New named events for --on-event can be fired using the
emit builtin. Fish already generates a few events, see Event handlers for
more.
Functions names cannot be reserved words. These are elements of fish syntax
or builtin commands which are essential for the operations of the shell.
Current reserved words are [, _, and, argparse, begin, break, builtin,
case, command, continue, else, end, eval, exec, for, function, if, not, or,
read, return, set, status, string, switch, test, time, and while.
Example
function ll
ls -l $argv
end
will run the ls command, using the -l option, while passing on any addi-
tional files and switches to ls.
function debug -a name val
echo [DEBUG] $name: $val >&2
end
set foo bar
debug foo bar
# prints: [DEBUG] foo: bar
# OR
function debug2 -a var
echo [DEBUG] $var: $$var >&2
end
set foo bar
debug2 foo
# prints: [DEBUG] foo: bar
will create a debug command to print chosen variables to stderr.
function mkdir -d "Create a directory and set CWD"
command mkdir $argv
if test $status = 0
switch $argv[(count $argv)]
case '-*'
case '*'
cd $argv[(count $argv)]
return
end
end
end
This will run the mkdir command, and if it is successful, change the cur-
rent working directory to the one just created.
function notify
set -l job (jobs -l -g)
or begin; echo "There are no jobs" >&2; return 1; end
function _notify_job_$job --on-job-exit $job --inherit-variable job
echo -n \a # beep
functions -e _notify_job_$job
end
end
This will beep when the most recent job completes.
Notes
Events are only received from the current fish process as there is no way
to send events from one fish process to another.
See more
For more explanation of how functions fit into fish, see Functions.
functions - print or erase functions
Synopsis
functions [-a | --all] [-n | --names] [--color WHEN]
functions [-D | --details] [-v] [--color WHEN] FUNCTION
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [-e | -q] FUNCTION ...
Description
functions prints or erases functions.
The following options are available:
-a or --all
Lists all functions, even those whose name starts with an under-
score.
-c or --copy OLDNAME NEWNAME
Creates a new function named NEWNAME, using the definition of the
OLDNAME function.
-d or --description DESCRIPTION
Changes the description of this function.
-e or --erase
Causes the specified functions to be erased. This also means that it
is prevented from autoloading in the current session. Use funcsave
to remove the saved copy.
-D or --details
Reports the path name where the specified function is defined or
could be autoloaded, stdin if the function was defined interactively
or on the command line or by reading standard input, - if the func-
tion was created via source, and n/a if the function isn't avail-
able. (Functions created via alias will return -, because alias uses
source internally. Copied functions will return where the function
was copied.) If the --verbose option is also specified then five
lines are written:
* the path name as already described,
* if the function was copied, the path name to where the function
was originally defined, otherwise autoloaded, not-autoloaded or
n/a,
* the line number within the file or zero if not applicable,
* scope-shadowing if the function shadows the vars in the calling
function (the normal case if it wasn't defined with
--no-scope-shadowing), else no-scope-shadowing, or n/a if the
function isn't defined,
* the function description minimally escaped so it is a single line,
or n/a if the function isn't defined or has no description.
You should not assume that only five lines will be written since we
may add additional information to the output in the future.
--no-details
Turns off function path reporting, so just the definition will be
printed.
-n or --names
Lists the names of all defined functions.
-q or --query
Tests if the specified functions exist.
-v or --verbose
Make some output more verbose.
-H or --handlers
Show all event handlers.
-t or --handlers-type TYPE
Show all event handlers matching the given TYPE.
--color WHEN
Controls when to use syntax highlighting colors when printing func-
tion definitions. WHEN can be auto (the default, colorize if the
output is a terminal), always, or never.
-h or --help
Displays help about using this command.
The default behavior of functions, when called with no arguments, is to
print the names of all defined functions. Unless the -a option is given, no
functions starting with underscores are included in the output.
If any non-option parameters are given, the definition of the specified
functions are printed.
Copying a function using -c copies only the body of the function, and does
not attach any event notifications from the original function.
Only one function's description can be changed in a single invocation of
functions -d.
The exit status of functions is the number of functions specified in the
argument list that do not exist, which can be used in concert with the -q
option.
Examples
functions -n
# Displays a list of currently-defined functions
functions -c foo bar
# Copies the 'foo' function to a new function called 'bar'
functions -e bar
# Erases the function ``bar``
See more
For more explanation of how functions fit into fish, see Functions.
help - display fish documentation
Synopsis
help [SECTION]
Description
help displays the fish help documentation.
If a SECTION is specified, the help for that command is shown.
The -h or --help option displays help about using this command.
If the BROWSER environment variable is set, it will be used to display the
documentation. Otherwise, fish will search for a suitable browser. To use
a different browser than as described above, you can set $fish_help_browser
This variable may be set as a list, where the first element is the browser
command and the rest are browser options.
Example
help fg shows the documentation for the fg builtin.
Notes
Most builtin commands, including this one, display their help in the termi-
nal when given the --help option.
history - show and manipulate command history
Synopsis
history [search] [--show-time] [--case-sensitive]
[--exact | --prefix | --contains] [--max N] [--null] [--reverse]
[SEARCH_STRING ...]
history delete [--case-sensitive]
[--exact | --prefix | --contains] SEARCH_STRING ...
history merge
history save
history clear
history clear-session
history append COMMAND ...
Description
history is used to search, delete, and otherwise manipulate the history of
interactive commands.
The following operations (sub-commands) are available:
search
Returns history items matching the search string. If no search
string is provided it returns all history items. This is the default
operation if no other operation is specified. You only have to ex-
plicitly say history search if you wish to search for one of the
subcommands. The --contains search option will be used if you don't
specify a different search option. Entries are ordered newest to
oldest unless you use the --reverse flag. If stdout is attached to a
tty the output will be piped through your pager by the history func-
tion. The history builtin writes the results to stdout.
delete
Deletes history items. The --contains search option will be used if
you don't specify a different search option. If you don't specify
--exact a prompt will be displayed before any items are deleted ask-
ing you which entries are to be deleted. You can enter the word
"all" to delete all matching entries. You can enter a single ID (the
number in square brackets) to delete just that single entry. You can
enter more than one ID, or an ID range separated by a space to
delete multiple entries. Press [enter] to not delete anything. Note
that the interactive delete behavior is a feature of the history
function. The history builtin only supports --exact --case-sensitive
deletion.
merge Immediately incorporates history changes from other sessions. Ordi-
narily fish ignores history changes from sessions started after the
current one. This command applies those changes immediately.
save Immediately writes all changes to the history file. The shell auto-
matically saves the history file; this option is provided for inter-
nal use and should not normally need to be used by the user.
clear Clears the history file. A prompt is displayed before the history is
erased asking you to confirm you really want to clear all history
unless builtin history is used.
clear-session
Clears the history file from all activity of the current session.
Note: If history merge or builtin history merge is run in a session,
only the history after this will be erased.
append
Appends commands to the history without needing to execute them.
The following options are available:
These flags can appear before or immediately after one of the sub-commands
listed above.
-C or --case-sensitive
Does a case-sensitive search. The default is case-insensitive.
-c or --contains
Searches items in the history that contain the specified text
string. This is the default for the --search flag. This is not cur-
rently supported by the delete subcommand.
-e or --exact
Searches or deletes items in the history that exactly match the
specified text string. This is the default for the delete subcom-
mand. Note that the match is case-insensitive by default. If you re-
ally want an exact match, including letter case, you must use the -C
or --case-sensitive flag.
-p or --prefix
Searches items in the history that begin with the specified text
string. This is not currently supported by the delete subcommand.
-t or --show-time
Prepends each history entry with the date and time the entry was
recorded. By default it uses the strftime format # %c%n. You can
specify another format; e.g., --show-time="%Y-%m-%d %H:%M:%S " or
--show-time="%a%I%p". The short option, -t, doesn't accept a strf-
time format string; it only uses the default format. Any strftime
format is allowed, including %s to get the raw UNIX seconds since
the epoch.
-z or --null
Causes history entries written by the search operations to be termi-
nated by a NUL character rather than a newline. This allows the out-
put to be processed by read -z to correctly handle multiline history
entries.
-*NUMBER* -n NUMBER or --max NUMBER
Limits the matched history items to the first NUMBER matching en-
tries. This is only valid for history search.
-R or --reverse
Causes the history search results to be ordered oldest to newest.
Which is the order used by most shells. The default is newest to
oldest.
--color WHEN
Controls when to use syntax highlighting colors for the history en-
tries. WHEN can be auto (the default, colorize if the output is a
terminal), always, or never.
-h or --help
Displays help for this command.
Example
history clear
# Deletes all history items
history search --contains "foo"
# Outputs a list of all previous commands containing the string "foo".
history delete --prefix "foo"
# Interactively deletes commands which start with "foo" from the history.
# You can select more than one entry by entering their IDs separated by a space.
Customizing the name of the history file
By default interactive commands are logged to $XDG_DATA_HOME/fish/fish_his-
tory (typically ~/.local/share/fish/fish_history).
You can set the fish_history variable to another name for the current shell
session. The default value (when the variable is unset) is fish which cor-
responds to $XDG_DATA_HOME/fish/fish_history. If you set it to e.g. fun,
the history would be written to $XDG_DATA_HOME/fish/fun_history. An empty
string means history will not be stored at all. This is similar to the pri-
vate session features in web browsers.
You can change fish_history at any time (by using set -x fish_history "ses-
sion_name") and it will take effect right away. If you set it to "default",
it will use the default session name (which is "fish").
Other shells such as bash and zsh use a variable named HISTFILE for a simi-
lar purpose. Fish uses a different name to avoid conflicts and signal that
the behavior is different (session name instead of a file path). Also, if
you set the var to anything other than fish or default it will inhibit im-
porting the bash history. That's because the most common use case for this
feature is to avoid leaking private or sensitive history when giving a pre-
sentation.
Notes
If you specify both --prefix and --contains the last flag seen is used.
Note that for backwards compatibility each subcommand can also be specified
as a long option. For example, rather than history search you can type his-
tory --search. Those long options are deprecated and will be removed in a
future release.
if - conditionally execute a command
Synopsis
if CONDITION; COMMANDS_TRUE ...;
[else if CONDITION2; COMMANDS_TRUE2 ...;]
[else; COMMANDS_FALSE ...;]
end
Description
if will execute the command CONDITION. If the condition's exit status is 0,
the commands COMMANDS_TRUE will execute. If the exit status is not 0 and
else is given, COMMANDS_FALSE will be executed.
You can use not, and or or in the condition. See the second example below.
The exit status of the last foreground command to exit can always be ac-
cessed using the $status variable.
The -h or --help option displays help about using this command.
Example
The following code will print foo.txt exists if the file foo.txt exists and
is a regular file, otherwise it will print bar.txt exists if the file
bar.txt exists and is a regular file, otherwise it will print foo.txt and
bar.txt do not exist.
if test -f foo.txt
echo foo.txt exists
else if test -f bar.txt
echo bar.txt exists
else
echo foo.txt and bar.txt do not exist
end
The following code will print "foo.txt exists and is readable" if foo.txt
is a regular file and readable
if test -f foo.txt
and test -r foo.txt
echo "foo.txt exists and is readable"
end
See also
if is only as useful as the command used as the condition.
Fish ships a few:
* test - perform tests on files and text can compare numbers, strings and
check paths
* string - manipulate strings can perform string operations including wild-
card and regular expression matches
* path - manipulate and check paths can check paths for permissions, exis-
tence or type
* contains - test if a word is present in a list can check if an element is
in a list
isatty - test if a file descriptor is a terminal
Synopsis
isatty [FILE_DESCRIPTOR]
Description
isatty tests if a file descriptor is a terminal (as opposed to a file). The
name is derived from the system call of the same name, which for historical
reasons refers to a teletypewriter (TTY).
FILE DESCRIPTOR may be either the number of a file descriptor, or one of
the strings stdin, stdout, or stderr. If not specified, zero is assumed.
If the specified file descriptor is a terminal device, the exit status of
the command is zero. Otherwise, the exit status is non-zero. No messages
are printed to standard error.
The -h or --help option displays help about using this command.
Examples
From an interactive shell, the commands below exit with a return value of
zero:
isatty
isatty stdout
isatty 2
echo | isatty 1
And these will exit non-zero:
echo | isatty
isatty 9
isatty stdout > file
isatty 2 2> file
jobs - print currently running jobs
Synopsis
jobs [OPTIONS] [PID | %JOBID]
Description
NOTE: This page documents the fish builtin jobs. To see the documentation
on any non-fish versions, use command man jobs.
jobs prints a list of the currently running jobs and their status.
jobs accepts the following options:
-c or --command
Prints the command name for each process in jobs.
-g or --group
Only prints the group ID of each job.
-l or --last
Prints only the last job to be started.
-p or --pid
Prints the process ID for each process in all jobs.
-q or --query
Prints no output for evaluation of jobs by exit status only. For
compatibility with old fish versions this is also --quiet (but this
is deprecated).
-h or --help
Displays help about using this command.
On systems that support this feature, jobs will print the CPU usage of each
job since the last command was executed. The CPU usage is expressed as a
percentage of full CPU activity. Note that on multiprocessor systems, the
total activity may be more than 100%.
Arguments of the form PID or %JOBID restrict the output to jobs with the
selected process identifiers or job numbers respectively.
If the output of jobs is redirected or if it is part of a command substitu-
tion, the column header that is usually printed is omitted, making it eas-
ier to parse.
The exit status of jobs is 0 if there are running background jobs and 1
otherwise.
Example
jobs outputs a summary of the current jobs, such as two long-running tasks
in this example:
Job Group State Command
2 26012 running nc -l 55232 < /dev/random &
1 26011 running python tests/test_11.py &
math - perform mathematics calculations
Synopsis
math [(-s | --scale) N] [(-b | --base) BASE] [(-m | --scale-mode) MODE] EXPRESSION ...
Description
math performs mathematical calculations. It supports simple operations
such as addition, subtraction, and so on, as well as functions like abs(),
sqrt() and ln().
By default, the output shows up to 6 decimal places. To change the number
of decimal places, use the --scale option, including --scale=0 for integer
output.
Keep in mind that parameter expansion happens before expressions are evalu-
ated. This can be very useful in order to perform calculations involving
shell variables or the output of command substitutions, but it also means
that parenthesis (()) and the asterisk (*) glob character have to be es-
caped or quoted. x can also be used to denote multiplication, but it needs
to be followed by whitespace to distinguish it from hexadecimal numbers.
Parentheses for functions are optional - math sin pi prints 0. However, a
comma will bind to the inner function, so math pow sin 3, 5 is an error be-
cause it tries to give sin the arguments 3 and 5. When in doubt, use
parentheses.
math ignores whitespace between arguments and takes its input as multiple
arguments (internally joined with a space), so math 2 +2 and math "2 +
2" work the same. math 2 2 is an error.
NOTE:
math is a simple tool for simple uses, provided for convenience. It in-
ternally works with floats for simplicity of implementation and can't do
a number of things real calculators can. If you find yourself limited
by that, use a more full-featured tool.
The following options are available:
-s N or --scale N
Sets the scale of the result. N must be an integer or the word
"max" for the maximum scale. A scale of zero causes results to be
truncated by default. Any non-integer component is thrown away. So
3/2 returns 1 by default, rather than 2 which 1.5 would normally
round to. This is for compatibility with bc which was the basis for
this command prior to fish 3.0.0. Scale values greater than zero
causes the result to be rounded using the usual rules to the speci-
fied number of decimal places.
-b BASE or --base BASE
Sets the numeric base used for output (math always understands hexa-
decimal numbers as input). It currently understands "hex" or "16"
for hexadecimal and "octal" or "8" for octal and implies a scale of
0 (other scales cause an error), so it will truncate the result down
to an integer. This might change in the future. Hex numbers will
be printed with a 0x prefix. Octal numbers will have a prefix of 0
but aren't understood by math as input.
-m MODE or --scale-mode MODE
Sets scale behavior. The MODE can be truncate, round, floor, ceil-
ing. The default value of scale mode is round with non zero scale
and truncate with zero scale.
-h or --help
Displays help about using this command.
Return Values
If the expression is successfully evaluated and doesn't over/underflow or
return NaN the return status is zero (success) else one.
Syntax
math knows some operators, constants, functions and can (obviously) read
numbers.
For numbers, . is always the radix character regardless of locale - 2.5,
not 2,5. Scientific notation (10e5) and hexadecimal (0xFF) are also avail-
able.
math allows you to use underscores as visual separators for digit grouping.
For example, you can write 1_000_000, 0x_89_AB_CD_EF, and 1.234_567_e89.
Operators
math knows the following operators:
+ for addition
- for subtraction
* or x
for multiplication. * is the glob character and needs to be quoted
or escaped, x needs to be followed by whitespace or it looks like 0x
hexadecimal notation.
/ for division
^ for exponentiation
% for modulo
( or )
for grouping. These need to be quoted or escaped because () denotes
a command substitution.
They are all used in an infix manner - 5 + 2, not + 5 2.
Constants
math knows the following constants:
e Euler's number
pi I, you know this one. Half of Tau
tau Equivalent to 2I, or the number of radians in a circle
Use them without a leading $ - pi - 3 should be about 0.
Functions
math supports the following functions:
abs the absolute value, with positive sign
acos arc cosine
asin arc sine
atan arc tangent
atan2 arc tangent of two variables
bitand, bitor and bitxor
perform bitwise operations. These will throw away any non-integer
parts and interpret the rest as an int.
Note: bitnot and bitnand don't exist. This is because numbers in
math don't really have a width in terms of bits, and these opera-
tions necessarily care about leading zeroes.
If you need to negate a specific number you can do it with an xor
with a mask, e.g.:
> math --base=hex bitxor 0x0F, 0xFF
0xF0
> math --base=hex bitxor 0x2, 0x3
# Here we mask with 0x3 == 0b111, so our number is 3 bits wide
# Only the 1 bit isn't set.
0x1
ceil round number up to the nearest integer
cos the cosine
cosh hyperbolic cosine
exp the base-e exponential function
fac factorial - also known as x! (x * (x - 1) * (x - 2) * ... * 1)
floor round number down to the nearest integer
ln the base-e logarithm
log or log10
the base-10 logarithm. To compute the logarithm for an arbitrary
base b, use log(x) / log(b).
log2 the base-2 logarithm
max returns the largest of the given numbers - this takes an arbitrary
number of arguments (but at least one)
min returns the smallest of the given numbers - this takes an arbitrary
number of arguments (but at least one)
ncr "from n choose r" combination function - how many subsets of size r
can be taken from n (order doesn't matter)
npr the number of subsets of size r that can be taken from a set of n
elements (including different order)
pow(x,y)
returns x to the y (and can be written as x ^ y)
round rounds to the nearest integer, away from 0
sin the sine function
sinh the hyperbolic sine
sqrt the square root - (can also be written as x ^ 0.5)
tan the tangent
tanh the hyperbolic tangent
All of the trigonometric functions use radians (the pi-based scale, not
360A<degree>).
Examples
math 1+1 outputs 2.
math $status - 128 outputs the numerical exit status of the last command
minus 128.
math 10 / 6 outputs 1.666667.
math -s0 10.0 / 6.0 outputs 1.
math -s3 10 / 6 outputs 1.667.
math "sin(pi)" outputs 0.
math 5 \* 2 or math "5 * 2" or math 5 "*" 2 all output 10.
math 0xFF outputs 255, math 0 x 3 outputs 0 (because it computes 0 multi-
plied by 3).
math bitand 0xFE, 0x2e outputs 46.
math "bitor(9,2)" outputs 11.
math --base=hex 192 prints 0xc0.
math 'ncr(49,6)' prints 13983816 - that's the number of possible picks in
6-from-49 lotto.
math max 5,2,3,1 prints 5.
Compatibility notes
Fish 1.x and 2.x releases relied on the bc command for handling math ex-
pressions. Starting with fish 3.0.0 fish uses the tinyexpr library and
evaluates the expression without the involvement of any external commands.
You don't need to use -- before the expression, even if it begins with a
minus sign which might otherwise be interpreted as an invalid option. If
you do insert -- before the expression, it will cause option scanning to
stop just like for every other command and it won't be part of the expres-
sion.
nextd - move forward through directory history
Synopsis
nextd [-l | --list] [POS]
Description
nextd moves forwards POS positions in the history of visited directories;
if the end of the history has been hit, a warning is printed.
If the -l or --list option is specified, the current directory history is
also displayed.
The -h or --help option displays help about using this command.
Note that the cd command limits directory history to the 25 most recently
visited directories. The history is stored in the dirprev and dirnext vari-
ables which this command manipulates.
Example
cd /usr/src
# Working directory is now /usr/src
cd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
prevd
# Working directory is now /usr/src
nextd
# Working directory is now /usr/src/fish-shell
See Also
* the cdh command to display a prompt to quickly navigate the history
* the dirh command to print the directory history
* the prevd command to move backward
not - negate the exit status of a job
Synopsis
not COMMAND [OPTIONS ...]
! COMMAND [OPTIONS ...]
Description
not negates the exit status of another command. If the exit status is zero,
not returns 1. Otherwise, not returns 0.
Some other shells only support the ! alias.
The -h or --help option displays help about using this command.
Example
The following code reports an error and exits if no file named spoon can be
found.
if not test -f spoon
echo There is no spoon
exit 1
end
open - open file in its default application
Synopsis
open FILES ...
Description
open opens a file in its default application, using the appropriate tool
for the operating system. On GNU/Linux, this requires the common but op-
tional xdg-open utility, from the xdg-utils package.
Note that this function will not be used if a command by this name exists
(which is the case on macOS or Haiku).
Example
open *.txt opens all the text files in the current directory using your
system's default text editor.
or - conditionally execute a command
Synopsis
COMMAND1; or COMMAND2
Description
or is used to execute a command if the previous command was not successful
(returned a status of something other than 0).
or statements may be used as part of the condition in an if or while block.
or 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, the program is installed. If either step fails, make clean is
run, which removes the files created by the build process.
make; and make install; or make clean
See Also
* and command
path - manipulate and check paths
Synopsis
path basename GENERAL_OPTIONS [(-E | --no-extension)] [PATH ...]
path dirname GENERAL_OPTIONS [PATH ...]
path extension GENERAL_OPTIONS [PATH ...]
path filter GENERAL_OPTIONS [-v | --invert]
[-d] [-f] [-l] [-r] [-w] [-x]
[(-t | --type) TYPE] [(-p | --perm) PERMISSION] [--all] [PATH ...]
path is GENERAL_OPTIONS [(-v | --invert)] [(-t | --type) TYPE]
[-d] [-f] [-l] [-r] [-w] [-x]
[(-p | --perm) PERMISSION] [PATH ...]
path mtime GENERAL_OPTIONS [(-R | --relative)] [PATH ...]
path normalize GENERAL_OPTIONS [PATH ...]
path resolve GENERAL_OPTIONS [PATH ...]
path change-extension GENERAL_OPTIONS EXTENSION [PATH ...]
path sort GENERAL_OPTIONS [-r | --reverse]
[-u | --unique] [--key=(basename | dirname | path)] [PATH ...]
GENERAL_OPTIONS
[-z | --null-in] [-Z | --null-out] [-q | --quiet]
Description
path performs operations on paths.
PATH arguments are taken from the command line unless standard input is
connected to a pipe or a file, in which case they are read from standard
input, one PATH per line. It is an error to supply PATH arguments on both
the command line and on standard input.
Arguments starting with - are normally interpreted as switches; -- causes
the following arguments not to be treated as switches even if they begin
with -. Switches and required arguments are recognized only on the command
line.
When a path starts with -, path filter and path normalize will prepend ./
on output to avoid it being interpreted as an option otherwise, so it's
safe to pass path's output to other commands that can handle relative
paths.
All subcommands accept a -q or --quiet switch, which suppresses the usual
output but exits with the documented status. In this case these commands
will quit early, without reading all of the available input.
All subcommands also accept a -Z or --null-out switch, which makes them
print output separated with NUL instead of newlines. This is for further
processing, e.g. passing to another path, or xargs -0. This is not recom-
mended when the output goes to the terminal or a command substitution.
All subcommands also accept a -z or --null-in switch, which makes them ac-
cept arguments from stdin separated with NULL-bytes. Since Unix paths can't
contain NULL, that makes it possible to handle all possible paths and read
input from e.g. find -print0. If arguments are given on the commandline
this has no effect. This should mostly be unnecessary since path automati-
cally starts splitting on NULL if one appears in the first PATH_MAX bytes,
PATH_MAX being the operating system's maximum length for a path plus a NULL
byte.
Some subcommands operate on the paths as strings and so work on nonexistent
paths, while others need to access the paths themselves and so filter out
nonexistent paths.
The following subcommands are available.
"basename" subcommand
path basename [-E | --no-extension] [-z | --null-in] [-Z | --null-out] [-q | --quiet] [PATH ...]
path basename returns the last path component of the given path, by remov-
ing the directory prefix and removing trailing slashes. In other words, it
is the part that is not the dirname. For files you might call it the "file-
name".
If the -E or ---no-extension option is used and the base name contained a
period, the path is returned with the extension (or the last extension) re-
moved, i.e. the "filename" without an extension (akin to calling path
change-extension "" (path basename $path)).
It returns 0 if there was a basename, i.e. if the path wasn't empty or just
slashes.
Examples
>_ path basename ./foo.mp4
foo.mp4
>_ path basename ../banana
banana
>_ path basename /usr/bin/
bin
>_ path basename /usr/bin/*
# This prints all files in /usr/bin/
# A selection:
cp
fish
grep
rm
"dirname" subcommand
path dirname [-z | --null-in] [-Z | --null-out] [-q | --quiet] [PATH ...]
path dirname returns the dirname for the given path. This is the part be-
fore the last "/", discounting trailing slashes. In other words, it is the
part that is not the basename (discounting superfluous slashes).
It returns 0 if there was a dirname, i.e. if the path wasn't empty or just
slashes.
Examples
>_ path dirname ./foo.mp4
.
>_ path dirname ../banana
..
>_ path dirname /usr/bin/
/usr
"extension" subcommand
path extension [-z | --null-in] [-Z | --null-out] [-q | --quiet] [PATH ...]
path extension returns the extension of the given path. This is the part
after (and including) the last ".", unless that "." followed a "/" or the
basename is "." or "..", in which case there is no extension and an empty
line is printed.
If the filename ends in a ".", only a "." is printed.
It returns 0 if there was an extension.
Examples
>_ path extension ./foo.mp4
.mp4
>_ path extension ../banana
# an empty line, status 1
>_ path extension ~/.config
# an empty line, status 1
>_ path extension ~/.config.d
.d
>_ path extension ~/.config.
.
>_ set -l path (path change-extension '' ./foo.mp4)
>_ set -l extension (path extension ./foo.mp4)
> echo $path$extension
# reconstructs the original path again.
./foo.mp4
"filter" subcommand
path filter [-z | --null-in] [-Z | --null-out] [-q | --quiet] \
[-d] [-f] [-l] [-r] [-w] [-x] \
[-v | --invert] [(-t | --type) TYPE] [(-p | --perm) PERMISSION] [--all] [PATH ...]
path filter returns all of the given paths that match the given checks. In
all cases, the paths need to exist, nonexistent paths are always filtered.
The available filters are:
* -t or --type with the options: "dir", "file", "link", "block", "char",
"fifo" and "socket", in which case the path needs to be a directory,
file, link, block device, character device, named pipe or socket, respec-
tively.
* -d, -f and -l are short for --type=dir, --type=file and --type=link, re-
spectively. There are no shortcuts for the other types.
* -p or --perm with the options: "read", "write", and "exec", as well as
"suid", "sgid", "user" (referring to the path owner) and "group" (refer-
ring to the path's group), in which case the path needs to have all of
the given permissions for the current user.
* -r, -w and -x are short for --perm=read, --perm=write and --perm=exec,
respectively. There are no shortcuts for the other permissions.
Note that the path needs to be any of the given types, but have all of the
given permissions. This is because having a path that is both writable and
executable makes sense, but having a path that is both a directory and a
file doesn't. Links will count as the type of the linked-to file, so links
to files count as files, links to directories count as directories.
The filter options can either be given as multiple options, or comma-sepa-
rated - path filter -t dir,file or path filter --type dir --type file are
equivalent.
With --invert, the meaning of the filtering is inverted - any path that
wouldn't pass (including by not existing) passes, and any path that would
pass fails.
When a path starts with -, path filter will prepend ./ to avoid it being
interpreted as an option otherwise.
It returns 0 if at least one path passed the filter.
With --all, return status 0 (true) if all paths pass the filter, and status
1 (false) if any path fails. This is equivalent to not path filter -v. It
produces no output, only a status.
When --all combined with --invert, it returns status 0 (true) if all paths
fail the filter and status 1 (false) if any path passes.
path is is shorthand for path filter -q, i.e. just checking without produc-
ing output, see The is subcommand.
Examples
>_ path filter /usr/bin /usr/argagagji
# The (hopefully) nonexistent argagagji is filtered implicitly:
/usr/bin
>_ path filter --type file /usr/bin /usr/bin/fish
# Only fish is a file
/usr/bin/fish
>_ path filter --type file,dir --perm exec,write /usr/bin/fish /home/me
# fish is a file, which passes, and executable, which passes,
# but probably not writable, which fails.
#
# $HOME is a directory and both writable and executable, typically.
# So it passes.
/home/me
>_ path filter -fdxw /usr/bin/fish /home/me
# This is the same as above: "-f" is "--type=file", "-d" is "--type=dir",
# "-x" is short for "--perm=exec" and "-w" short for "--perm=write"!
/home/me
>_ path filter -fx $PATH/*
# Prints all possible commands - the first entry of each name is what fish would execute!
>_ path filter --all /usr/bin /usr/argagagji
# This returns 1 (false) because not all paths pass the filter.
"is" subcommand
path is [-z | --null-in] [-Z | --null-out] [-q | --quiet] \
[-d] [-f] [-l] [-r] [-w] [-x] \
[-v | --invert] [(-t | --type) TYPE] [(-p | --perm) PERMISSION] [PATH ...]
path is is short for path filter -q. It returns true if any of the given
files passes the filter, but does not produce any output.
--quiet can still be passed for compatibility but is redundant. The options
are the same as for path filter.
Examples
>_ path is /usr/bin /usr/argagagji
# /usr/bin exists, so this returns a status of 0 (true). It prints nothing.
>_ path is /usr/argagagji
# /usr/argagagji does not, so this returns a status of 1 (false). It also prints nothing.
>_ path is -fx /bin/sh
# /bin/sh is usually an executable file, so this returns true.
"mtime" subcommand
path mtime [-z | --null-in] [-Z | --null-out] [-q | --quiet] [-R | --relative] [PATH ...]
path mtime returns the last modification time ("mtime" in unix jargon) of
the given paths, in seconds since the unix epoch (the beginning of the 1st
of January 1970).
With --relative (or -R), it prints the number of seconds since the modifi-
cation time. It only reads the current time once at start, so in case mul-
tiple paths are given the times are all relative to the start of path mtime
-R running.
If you want to know if a file is newer or older than another file, consider
using test -nt instead. See the test documentation.
It returns 0 if reading mtime for any path succeeded.
Examples
>_ date +%s
# This prints the current time as seconds since the epoch
1657217847
>_ path mtime /etc/
1657213796
>_ path mtime -R /etc/
4078
# So /etc/ on this system was last modified a little over an hour ago
# This is the same as
>_ math (date +%s) - (path mtime /etc/)
"normalize" subcommand
path normalize [-z | --null-in] [-Z | --null-out] [-q | --quiet] [PATH ...]
path normalize returns the normalized versions of all paths. That means it
squashes duplicate "/", collapses "../" with earlier components and removes
"." components.
Unlike realpath or path resolve, it does not make the paths absolute. It
also does not resolve any symlinks. As such it can operate on non-existent
paths.
Because it operates on paths as strings and doesn't resolve symlinks, it
works sort of like pwd -L and cd. E.g. path normalize link/.. will return
., just like cd link; cd .. would return to the current directory. For a
physical view of the filesystem, see path resolve.
Leading "./" components are usually removed. But when a path starts with -,
path normalize will add it instead to avoid confusion with options.
It returns 0 if any normalization was done, i.e. any given path wasn't in
canonical form.
Examples
>_ path normalize /usr/bin//../../etc/fish
# The "//" is squashed and the ".." components neutralize the components before
/etc/fish
>_ path normalize /bin//bash
# The "//" is squashed, but /bin isn't resolved even if your system links it to /usr/bin.
/bin/bash
>_ path normalize ./my/subdirs/../sub2
my/sub2
>_ path normalize -- -/foo
./-/foo
"resolve" subcommand
path resolve [-z | --null-in] [-Z | --null-out] [-q | --quiet] [PATH ...]
path resolve returns the normalized, physical and absolute versions of all
paths. That means it resolves symlinks and does what path normalize does:
it squashes duplicate "/", collapses "../" with earlier components and re-
moves "." components. Then it turns that path into the absolute path start-
ing from the filesystem root "/".
It is similar to realpath, as it creates the "real", canonical version of
the path. However, for paths that can't be resolved, e.g. if they don't ex-
ist or form a symlink loop, it will resolve as far as it can and normalize
the rest.
Because it resolves symlinks, it works sort of like pwd -P. E.g. path re-
solve link/.. will return the parent directory of what the link points to,
just like cd link; cd (pwd -P)/.. would go to it. For a logical view of the
filesystem, see path normalize.
It returns 0 if any normalization or resolution was done, i.e. any given
path wasn't in canonical form.
Examples
>_ path resolve /bin//sh
# The "//" is squashed, and /bin is resolved if your system links it to /usr/bin.
# sh here is bash (this is common on linux systems)
/usr/bin/bash
>_ path resolve /bin/foo///bar/../baz
# Assuming /bin exists and is a symlink to /usr/bin, but /bin/foo doesn't.
# This resolves the /bin/ and normalizes the nonexistent rest:
/usr/bin/foo/baz
"change-extension" subcommand
path change-extension [-z | --null-in] [-Z | --null-out] \
[-q | --quiet] EXTENSION [PATH ...]
path change-extension returns the given paths, with their extension changed
to the given new extension. The extension is the part after (and including)
the last ".", unless that "." followed a "/" or the basename is "." or
"..", in which case there is no previous extension and the new one is
added.
If the extension is empty, any previous extension is stripped, along with
the ".". This is, of course, the inverse of path extension.
One leading dot on the extension is ignored, so ".mp3" and "mp3" are
treated the same.
It returns 0 if it was given any paths.
Examples
>_ path change-extension mp4 ./foo.wmv
./foo.mp4
>_ path change-extension .mp4 ./foo.wmv
./foo.mp4
>_ path change-extension '' ../banana
../banana
>_ path change-extension '' ~/.config
/home/alfa/.config
>_ path change-extension '' ~/.config.d
/home/alfa/.config
>_ path change-extension '' ~/.config.
/home/alfa/.config
"sort" subcommand
path sort [-z | --null-in] [-Z | --null-out] \
[-q | --quiet] [-r | --reverse] \
[--key=basename|dirname|path] [PATH ...]
path sort returns the given paths in sorted order. They are sorted in the
same order as globs - alphabetically, but with runs of numerical digits
compared numerically.
With --reverse or -r the sort is reversed.
With --key= only the given part of the path is compared, e.g. --key=dirname
causes only the dirname to be compared, --key=basename only the basename
and --key=path causes the entire path to be compared (this is the default).
With --unique or -u the sort is deduplicated, meaning only the first of a
run that have the same key is kept. So if you are sorting by basename, then
only the first of each basename is used.
The sort used is stable, so sorting first by basename and then by dirname
works and causes the files to be grouped according to directory.
It currently returns 0 if it was given any paths.
Examples
>_ path sort 10-foo 2-bar
2-bar
10-foo
>_ path sort --reverse 10-foo 2-bar
10-foo
2-bar
>_ path sort --unique --key=basename $fish_function_path/*.fish
# prints a list of all function files fish would use, sorted by name.
Combining path
path is meant to be easy to combine with itself, other tools and fish.
This is why
* path's output is automatically split by fish if it goes into a command
substitution, so just doing (path ...) handles all paths, even those con-
taining newlines, correctly
* path has --null-in to handle null-delimited input (typically automati-
cally detected!), and --null-out to pass on null-delimited output
Some examples of combining path:
# Expand all paths in the current directory, leave only executable files, and print their resolved path
path filter -zZ -xf -- * | path resolve -z
# The same thing, but using find (note -maxdepth needs to come first or find will scream)
# (this also depends on your particular version of find)
# Note the `-z` is unnecessary for any sensible version of find - if `path` sees a NULL,
# it will split on NULL automatically.
find . -maxdepth 1 -type f -executable -print0 | path resolve -z
set -l paths (path filter -p exec $PATH/fish -Z | path resolve)
popd - move through directory stack
Synopsis
popd
Description
popd removes the top directory from the directory stack and changes the
working directory to the new top directory. Use pushd to add directories to
the stack.
The -h or --help option displays help about using this command.
Example
pushd /usr/src
# Working directory is now /usr/src
# Directory stack contains /usr/src
pushd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
# Directory stack contains /usr/src /usr/src/fish-shell
popd
# Working directory is now /usr/src
# Directory stack contains /usr/src
See Also
* the dirs command to print the directory stack
* the cdh command which provides a more intuitive way to navigate to re-
cently visited directories.
prevd - move backward through directory history
Synopsis
prevd [-l | --list] [POS]
Description
prevd moves backwards POS positions in the history of visited directories;
if the beginning of the history has been hit, a warning is printed.
If the -l or --list flag is specified, the current history is also dis-
played.
Note that the cd command limits directory history to the 25 most recently
visited directories. The history is stored in the dirprev and dirnext vari-
ables which this command manipulates.
The -h or --help option displays help about using this command.
Example
cd /usr/src
# Working directory is now /usr/src
cd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
prevd
# Working directory is now /usr/src
nextd
# Working directory is now /usr/src/fish-shell
See Also
* the cdh command to display a prompt to quickly navigate the history
* the dirh command to print the directory history
* the nextd command to move forward
printf - display text according to a format string
Synopsis
printf FORMAT [ARGUMENT ...]
Description
NOTE: This page documents the fish builtin printf. To see the documenta-
tion on any non-fish versions, use command man printf.
printf uses the format string FORMAT to print the ARGUMENT arguments. This
means that it takes format specifiers in the format string and replaces
each with an argument.
The FORMAT argument is re-used as many times as necessary to convert all of
the given arguments. So printf %s\n flounder catfish clownfish shark will
print four lines.
Unlike echo, printf does not append a new line unless it is specified as
part of the string.
It doesn't support any options, so there is no need for a -- separator,
which makes it easier to use for arbitrary input than echo. [1]
Format Specifiers
Valid format specifiers are taken from the C library function printf(3):
* %d or %i: Argument will be used as decimal integer (signed or unsigned)
* %o: An octal unsigned integer
* %u: An unsigned decimal integer - this means negative numbers will wrap
around
* %x or %X: An unsigned hexadecimal integer
* %f, %g or %G: A floating-point number. %f defaults to 6 places after the
decimal point (which is locale-dependent - e.g. in de_DE it will be a ,).
%g and %G will trim trailing zeroes and switch to scientific notation
(like %e) if the numbers get small or large enough.
* %e or %E: A floating-point number in scientific (XXXeYY) notation
* %s: A string
* %b: As a string, interpreting backslash escapes, except that octal es-
capes are of the form 0 or 0ooo.
%% signifies a literal "%".
Conversion can fail, e.g. "102.234" can't losslessly convert to an integer,
causing printf to print an error. If you are okay with losing information,
silence errors with 2>/dev/null.
A number between the % and the format letter specifies the width. The re-
sult will be left-padded with spaces.
Backslash Escapes
printf also knows a number of backslash escapes:
* \" double quote
* \\ backslash
* \a alert (bell)
* \b backspace
* \c produce no further output
* \e escape
* \f form feed
* \n new line
* \r carriage return
* \t horizontal tab
* \v vertical tab
* \ooo octal number (ooo is 1 to 3 digits)
* \xhh hexadecimal number (hhh is 1 to 2 digits)
* \uhhhh 16-bit Unicode character (hhhh is 4 digits)
* \Uhhhhhhhh 32-bit Unicode character (hhhhhhhh is 8 digits)
Errors and Return Status
If the given argument doesn't work for the given format (like when you try
to convert a number like 3.141592 to an integer), printf prints an error,
to stderr. printf will then also return non-zero, but will still try to
print as much as it can.
It will also return non-zero if no argument at all was given, in which case
it will print nothing.
This printf has been imported from the printf in GNU Coreutils version 6.9.
If you would like to use a newer version of printf, for example the one
shipped with your OS, try command printf.
Example
printf '%s\t%s\n' flounder fish
Will print "flounder fish" (separated with a tab character), followed by
a newline character. This is useful for writing completions, as fish ex-
pects completion scripts to output the option followed by the description,
separated with a tab character.
printf '%s: %d' "Number of bananas in my pocket" 42
Will print "Number of bananas in my pocket: 42", without a newline.
See Also
* the echo command, for simpler output
Footnotes
[1] In fact, while fish's echo supports --, POSIX forbids it, so other im-
plementations can't be used if the input contains anything starting
with -.
prompt_hostname - print the hostname, shortened for use in the prompt
Synopsis
prompt_hostname
Description
prompt_hostname prints a shortened version the current hostname for use in
the prompt. It will print just the first component of the hostname, every-
thing up to the first dot.
Examples
function fish_prompt
echo -n (whoami)@(prompt_hostname) (prompt_pwd) '$ '
end
# The machine's full hostname is foo.bar.com
>_ prompt_hostname
foo
prompt_login - describe the login suitable for prompt
Synopsis
prompt_login
Description
prompt_login is a function to describe the current login. It will show the
user, the host and also whether the shell is running in a chroot (currently
Debian's debian_chroot file is supported).
Examples
function fish_prompt
echo -n (prompt_login) (prompt_pwd) '$ '
end
>_ prompt_login
root@bananablaster
prompt_pwd - print pwd suitable for prompt
Synopsis
prompt_pwd
Description
prompt_pwd is a function to print the current working directory in a way
suitable for prompts. It will replace the home directory with "~" and
shorten every path component but the last to a default of one character.
To change the number of characters per path component, pass --dir-length=
or set fish_prompt_pwd_dir_length to the number of characters. Setting it
to 0 or an invalid value will disable shortening entirely. This defaults to
1.
To keep some components unshortened, pass --full-length-dirs= or set
fish_prompt_pwd_full_dirs to the number of components. This defaults to 1,
keeping the last component.
If any positional arguments are given, prompt_pwd shortens them instead of
PWD.
Options
-d or --dir-length MAX
Causes the components to be shortened to MAX characters each. This
overrides fish_prompt_pwd_dir_length.
-D or --full-length-dirs NUM
Keeps NUM components (counted from the right) as full length without
shortening. This overrides fish_prompt_pwd_full_dirs.
-h or --help
Displays help about using this command.
Examples
>_ cd ~/
>_ echo $PWD
/home/alfa
>_ prompt_pwd
~
>_ cd /tmp/banana/sausage/with/mustard
>_ prompt_pwd
/t/b/s/w/mustard
>_ set -g fish_prompt_pwd_dir_length 3
>_ prompt_pwd
/tmp/ban/sau/wit/mustard
>_ prompt_pwd --full-length-dirs=2 --dir-length=1
/t/b/s/with/mustard
>_ echo (prompt_pwd | string split /)[-1]
mustard
>_ echo (string join / (prompt_pwd | string split /)[-3..-1])
s/with/mustard
psub - perform process substitution
Synopsis
COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [(-s | --suffix) SUFFIX] )
Description
Some shells (e.g., ksh, bash) feature a syntax that is a mix between com-
mand substitution and piping, called process substitution. It is used to
send the output of a command into the calling command, much like command
substitution, but with the difference that the output is not sent through
commandline arguments but through a named pipe, with the filename of the
named pipe sent as an argument to the calling program. psub combined with a
regular command substitution provides the same functionality.
The following options are available:
-f or --file
Use a regular file instead of a named pipe to communicate with the
calling process. This will cause psub to be significantly slower
when large amounts of data are involved, but has the advantage that
the reading process can seek in the stream. This is the default.
-F or --fifo
Use a named pipe rather than a file. You should only use this if the
command produces no more than 8 KiB of output. The limit on the
amount of data a FIFO can buffer varies with the OS but is typically
8 KiB, 16 KiB or 64 KiB. If you use this option and the command on
the left of the psub pipeline produces more output a deadlock is
likely to occur.
-s or --suffix SUFFIX
Append SUFFIX to the filename.
-h or --help
Displays help about using this command.
Example
diff (sort a.txt | psub) (sort b.txt | psub)
# shows the difference between the sorted versions of files ``a.txt`` and ``b.txt``.
source-highlight -f esc (cpp main.c | psub -f -s .c)
# highlights ``main.c`` after preprocessing as a C source.
pushd - push directory to directory stack
Synopsis
pushd DIRECTORY
Description
The pushd function adds DIRECTORY to the top of the directory stack and
makes it the current working directory. popd will pop it off and return to
the original directory.
Without arguments, it exchanges the top two directories in the stack.
pushd +NUMBER rotates the stack counter-clockwise i.e. from bottom to top
pushd -NUMBER rotates clockwise i.e. top to bottom.
The -h or --help option displays help about using this command.
Example
cd ~/dir1
pushd ~/dir2
pushd ~/dir3
# Working directory is now ~/dir3
# Directory stack contains ~/dir2 ~/dir1
pushd /tmp
# Working directory is now /tmp
# Directory stack contains ~/dir3 ~/dir2 ~/dir1
pushd +1
# Working directory is now ~/dir3
# Directory stack contains ~/dir2 ~/dir1 /tmp
popd
# Working directory is now ~/dir2
# Directory stack contains ~/dir1 /tmp
See Also
* the dirs command to print the directory stack
* the cdh command which provides a more intuitive way to navigate to re-
cently visited directories.
pwd - output the current working directory
Synopsis
pwd [-P | --physical]
pwd [-L | --logical]
Description
NOTE: This page documents the fish builtin pwd. To see the documentation
on any non-fish versions, use command man pwd.
pwd outputs (prints) the current working directory.
The following options are available:
-L or --logical
Output the logical working directory, without resolving symlinks
(default behavior).
-P or --physical
Output the physical working directory, with symlinks resolved.
-h or --help
Displays help about using this command.
See Also
Navigate directories using the directory history or the directory stack
random - generate random number
Synopsis
random
random SEED
random START END
random START STEP END
random choice [ITEMS ...]
Description
random generates a pseudo-random integer from a uniform distribution. The
range (inclusive) depends on the arguments.
No arguments indicate a range of 0 to 32767 (inclusive).
If one argument is specified, the internal engine will be seeded with the
argument for future invocations of random and no output will be produced.
Two arguments indicate a range from START to END (both START and END in-
cluded).
Three arguments indicate a range from START to END with a spacing of STEP
between possible outputs.
random choice will select one random item from the succeeding arguments.
The -h or --help option displays help about using this command.
Note that seeding the engine will NOT give the same result across different
systems.
You should not consider random cryptographically secure, or even statisti-
cally accurate.
Example
The following code will count down from a random even number between 10 and
20 to 1:
for i in (seq (random 10 2 20) -1 1)
echo $i
end
And this will open a random picture from any of the subdirectories:
open (random choice **.jpg)
Or, to only get even numbers from 2 to 20:
random 2 2 20
Or odd numbers from 1 to 3:
random 1 2 3 # or 1 2 4
read - read line of input into variables
Synopsis
read [OPTIONS] [VARIABLE ...]
Description
NOTE: This page documents the fish builtin read. To see the documentation
on any non-fish versions, use command man read.
read reads from standard input and stores the result in shell variables. In
an alternative mode, it can also print to its own standard output, for ex-
ample for use in command substitutions.
By default, read reads a single line and splits it into variables on spaces
or tabs. Alternatively, a null character or a maximum number of characters
can be used to terminate the input, and other delimiters can be given.
Unlike other shells, there is no default variable (such as REPLY) for stor-
ing the result - instead, it is printed on standard output.
When read reaches the end-of-file (EOF) instead of the terminator, the exit
status is set to 1. Otherwise, it is set to 0.
If read sets a variable and you don't specify a scope, it will use the same
rules that set - display and change shell variables does - if the variable
exists, it will use it (in the lowest scope). If it doesn't, it will use an
unexported function-scoped variable.
The following options, like the corresponding ones in set - display and
change shell variables, control variable scope or attributes:
-U or --universal
Sets a universal variable. The variable will be immediately avail-
able to all the user's fish instances on the machine, and will be
persisted across restarts of the shell.
-f or --function
Sets a variable scoped to the executing function. It is erased when
the function ends.
-l or --local
Sets a locally-scoped variable in this block. It is erased when the
block ends. Outside of a block, this is the same as --function.
-g or --global
Sets a globally-scoped variable. Global variables are available to
all functions running in the same shell. They can be modified or
erased.
-u or --unexport
Prevents the variables from being exported to child processes (de-
fault behaviour).
-x or --export
Exports the variables to child processes.
The following options control the interactive mode:
-c CMD or --command CMD
Sets the initial string in the interactive mode command buffer to
CMD.
-s or --silent
Masks characters written to the terminal, replacing them with aster-
isks. This is useful for reading things like passwords or other sen-
sitive information.
-p or --prompt PROMPT_CMD
Uses the output of the shell command PROMPT_CMD as the prompt for
the interactive mode. The default prompt command is set_color green;
echo -n read; set_color --reset; echo -n "> "
-P or --prompt-str PROMPT_STR
Uses the literal PROMPT_STR as the prompt for the interactive mode.
-R or --right-prompt RIGHT_PROMPT_CMD
Uses the output of the shell command RIGHT_PROMPT_CMD as the right
prompt for the interactive mode. There is no default right prompt
command.
-S or --shell
Enables syntax highlighting, tab completions and command termination
suitable for entering shellscript code in the interactive mode.
NOTE: Prior to fish 3.0, the short opt for --shell was -s, but it
has been changed for compatibility with bash's -s short opt for
--silent.
The following options control how much is read and how it is stored:
-d or --delimiter DELIMITER
Splits on DELIMITER. DELIMITER will be used as an entire string to
split on, not a set of characters.
-n or --nchars NCHARS
Makes read return after reading NCHARS characters or the end of the
line, whichever comes first.
-t, --tokenize or --tokenize-raw
Causes read to split the input into variables by the shell's tok-
enization rules. This means it will honor quotes and escaping.
This option is of course incompatible with other options to control
splitting like --delimiter and does not honor IFS (like fish's tok-
enizer). The -t -or --tokenize variants perform quote removal, so
e.g. a\ b is stored as a b. However variables and command substitu-
tions are not expanded.
-a or --list
Stores the result as a list in a single variable. This option is
also available as --array for backwards compatibility.
-z or --null
Marks the end of the line with the NUL character, instead of new-
line. This also disables interactive mode.
-L or --line
Reads each line into successive variables, and stops after each
variable has been filled. This cannot be combined with the --delim-
iter option.
Without the --line option, read reads a single line of input from standard
input, breaks it into tokens, and then assigns one token to each variable
specified in VARIABLES. If there are more tokens than variables, the com-
plete remainder is assigned to the last variable.
If no option to determine how to split like --delimiter, --line or --tok-
enize is given, the variable IFS is used as a list of characters to split
on. Relying on the use of IFS is deprecated and this behaviour will be re-
moved in future versions. The default value of IFS contains space, tab and
newline characters. As a special case, if IFS is set to the empty string,
each character of the input is considered a separate token.
With the --line option, read reads a line of input from standard input into
each provided variable, stopping when each variable has been filled. The
line is not tokenized.
If no variable names are provided, read enters a special case that provides
redirection from standard input to standard output, useful for command sub-
stitution. For instance, the fish shell command below can be used to read a
password from the console instead of hardcoding it in the command itself,
which prevents it from showing up in fish's history:
mysql -uuser -p(read)
When running in this mode, read does not split the input in any way and
text is redirected to standard output without any further processing or ma-
nipulation.
If -l or --list is provided, only one variable name is allowed and the to-
kens are stored as a list in this variable.
In order to protect the shell from consuming too many system resources,
read will only consume a maximum of 100 MiB (104857600 bytes); if the ter-
minator is not reached before this limit then VARIABLE is set to empty and
the exit status is set to 122. This limit can be altered with the
fish_read_limit variable. If set to 0 (zero), the limit is removed.
Example
read has a few separate uses.
The following code stores the value 'hello' in the shell variable foo.
echo hello | read foo
The while command is a neat way to handle command output line-by-line:
printf '%s\n' line1 line2 line3 line4 | while read -l foo
echo "This is another line: $foo"
end
Delimiters given via "-d" are taken as one string:
echo a==b==c | read -d == -l a b c
echo $a # a
echo $b # b
echo $c # c
--tokenize honors quotes and escaping like the shell's argument passing:
echo 'a\ b' | read -t first second
echo $first # outputs "a b", $second is empty
echo 'a"foo bar"b (command echo wurst)*" "{a,b}' | read -lt -l a b c
echo $a # outputs 'afoo barb' (without the quotes)
echo $b # outputs '(command echo wurst)* {a,b}' (without the quotes)
echo $c # nothing
For an example on interactive use, see Querying for user input.
realpath - convert a path to an absolute path without symlinks
Synopsis
realpath [OPTIONS] PATH
Description
NOTE: This page documents the fish builtin realpath. To see the documenta-
tion on any non-fish versions, use command man realpath.
realpath follows all symbolic links encountered for the provided PATH,
printing the absolute path resolved. fish provides a realpath-alike builtin
intended to enrich systems where no such command is installed by default.
If a realpath command exists, that will be preferred. builtin realpath
will explicitly use the fish implementation of realpath.
The following options are available:
-s or --no-symlinks
Don't resolve symlinks, only make paths absolute, squash multiple
slashes and remove trailing slashes.
-h or --help
Displays help about using this command.
return - stop the current inner function
Synopsis
return [N]
Description
return halts a currently running function. The exit status is set to N if
it is given. If return is invoked outside of a function or dot script it
is equivalent to exit.
It is often added inside of a conditional block such as an if statement or
a switch statement to conditionally stop the executing function and return
to the caller; it can also be used to specify the exit status of a func-
tion.
If at the top level of a script, it exits with the given status, like exit.
If at the top level in an interactive session, it will set status, but not
exit the shell.
The -h or --help option displays help about using this command.
Example
An implementation of the false command as a fish function:
function false
return 1
end
set - display and change shell variables
Synopsis
set
set (-f | --function) (-l | --local) (-g | --global) (-U | --universal) [--no-event]
set [-Uflg] NAME [VALUE ...]
set [-Uflg] NAME[[INDEX ...]] [VALUE ...]
set (-x | --export) (-u | --unexport) [-Uflg] NAME [VALUE ...]
set (-a | --append) (-p | --prepend) [-Uflg] NAME VALUE ...
set (-e | --erase) [-Uflg] [-xu] [NAME][[INDEX]] ...]
set (-q | --query) [-Uflg] [-xu] [NAME][[INDEX]] ...]
set (-S | --show) (-L | --long) [NAME ...]
Description
set manipulates shell variables.
If both NAME and VALUE are provided, set assigns any values to variable
NAME. Variables in fish are lists, multiple values are allowed. One or
more variable INDEX can be specified including ranges (not for all op-
tions.)
If no VALUE is given, the variable will be set to the empty list.
If set is ran without arguments, it prints the names and values of all
shell variables in sorted order. Passing scope or export flags allows fil-
tering this to only matching variables, so set --local would only show lo-
cal variables.
With --erase and optionally a scope flag set will erase the matching vari-
able (or the variable of that name in the smallest possible scope).
With --show, set will describe the given variable names, explaining how
they have been defined - in which scope with which values and options.
The following options control variable scope:
-U or --universal
Sets a universal variable. The variable will be immediately avail-
able to all the user's fish instances on the machine, and will be
persisted across restarts of the shell.
-f or --function
Sets a variable scoped to the executing function. It is erased when
the function ends.
-l or --local
Sets a locally-scoped variable in this block. It is erased when the
block ends. Outside of a block, this is the same as --function.
-g or --global
Sets a globally-scoped variable. Global variables are available to
all functions running in the same shell. They can be modified or
erased.
These options modify how variables operate:
--export or -x
Causes the specified shell variable to be exported to child
processes (making it an "environment variable").
--unexport or -u
Causes the specified shell variable to NOT be exported to child
processes.
--path
Treat specified variable as a path variable; variable will be split
on colons (:) and will be displayed joined by colons when quoted
(echo "$PATH") or exported.
--unpath
Causes variable to no longer be treated as a path variable. Note:
variables ending in "PATH" are automatically path variables.
Further options:
-a or --append NAME VALUE ...
Appends VALUES to the current set of values for variable NAME. Can
be used with --prepend to both append and prepend at the same time.
This cannot be used when assigning to a variable slice.
-p or --prepend NAME VALUE ...
Prepends VALUES to the current set of values for variable NAME.
This can be used with --append to both append and prepend at the
same time. This cannot be used when assigning to a variable slice.
-e or --erase NAME[INDEX]
Causes the specified shell variables to be erased. Supports erasing
from multiple scopes at once. Individual items in a variable at IN-
DEX in brackets can be specified.
-q or --query NAME[INDEX]
Test if the specified variable names are defined. If an INDEX is
provided, check for items at that slot. With a given scope (like
--global) or attribute (like --export or --path) check only vari-
ables that match. Does not output anything, but the shell status is
set to the number of variables specified that were not defined, up
to a maximum of 255. If no variable was given, it also returns 255.
-n or --names
List only the names of all defined variables, not their value. The
names are guaranteed to be sorted.
-S or --show
Shows information about the given variables. If no variable names
are given then all variables are shown in sorted order. It shows
the scopes the given variables are set in, along with the values in
each and whether or not it is exported. No other flags can be used
with this option.
--no-event
Don't generate a variable change event when setting or erasing a
variable. We recommend using this carefully because the event han-
dlers are usually set up for a reason. Possible uses include modi-
fying the variable inside a variable handler.
-L or --long
Do not abbreviate long values when printing set variables.
-h or --help
Displays help about using this command.
If a variable is set to more than one value, the variable will be a list
with the specified elements. If a variable is set to zero elements, it
will become a list with zero elements.
If the variable name is one or more list elements, such as PATH[1 3 7],
only those list elements specified will be changed. If you specify a nega-
tive index when expanding or assigning to a list variable, the index will
be calculated from the end of the list. For example, the index -1 means
the last index of a list.
The scoping rules when creating or updating a variable are:
* Variables may be explicitly set as universal, global, function, or local.
Variables with the same name but in a different scope will not be
changed.
* If the scope of a variable is not explicitly set but a variable by that
name has been previously defined, the scope of the existing variable is
used. If the variable is already defined in multiple scopes, the vari-
able with the narrowest scope will be updated.
* If a variable's scope is not explicitly set and there is no existing
variable by that name, the variable will be local to the currently exe-
cuting function. Note that this is different from using the -l or --lo-
cal flag, in which case the variable will be local to the most-inner cur-
rently executing block, while without them the variable will be local to
the function as a whole. If no function is executing, the variable will
be set in the global scope.
The exporting rules when creating or updating a variable are identical to
the scoping rules for variables:
* Variables may be explicitly set to either exported or not exported. When
an exported variable goes out of scope, it is unexported.
* If a variable is not explicitly set to be exported or not exported, but
has been previously defined, the previous exporting rule for the variable
is kept.
* If a variable is not explicitly set to be either exported or unexported
and has never before been defined, the variable will not be exported.
In query mode, the scope to be examined can be specified. Whether the
variable has to be a path variable or exported can also be specified.
In erase mode, if variable indices are specified, only the specified slices
of the list variable will be erased.
set requires all options to come before any other arguments. For example,
set flags -l will have the effect of setting the value of the variable
flags to '-l', not making the variable local.
Exit status
In assignment mode, set does not modify the exit status, but passes along
whatever status was set, including by command substitutions. This allows
capturing the output and exit status of a subcommand, like in if set output
(command).
In query mode, the exit status is the number of variables that were not
found.
In erase mode, set exits with a zero exit status in case of success, with a
non-zero exit status if the commandline was invalid, if any of the vari-
ables did not exist or was a special read-only variable.
Examples
Print all global, exported variables:
> set -gx
Set the value of the variable _$foo_ to be 'hi'.:
> set foo hi
Append the value "there" to the variable $foo:
> set -a foo there
Remove _$smurf_ from the scope:
> set -e smurf
Remove _$smurf_ from the global and universal scopes:
> set -e -Ug smurf
Change the fourth element of the $PATH list to ~/bin:
> set PATH[4] ~/bin
Outputs the path to Python if type -p returns true:
if set python_path (type -p python)
echo "Python is at $python_path"
end
Setting a variable doesn't modify $status; a command substitution still
will, though:
> echo $status
0
> false
> set foo bar
> echo $status
1
> true
> set foo banana (false)
> echo $status
1
VAR=VALUE command sets a variable for just one command, like other shells.
This runs fish with a temporary home directory:
> HOME=(mktemp -d) fish
(which is essentially the same as):
> begin; set -lx HOME (mktemp -d); fish; end
Notes
* Fish versions prior to 3.0 supported the syntax set PATH[1] PATH[4] /bin
/sbin, which worked like set PATH[1 4] /bin /sbin.
set_color - set the terminal color
Synopsis
set_color [OPTIONS] [VALUE]
Description
set_color is used to control the color and styling of text in the terminal.
VALUE describes that styling. VALUE can be a reserved color name like red
or an RGB color value given as 3 or 6 hexadecimal digits ("F27" or
"FF2277"). A special keyword normal resets text formatting to terminal de-
faults, however it is not recommended and the --reset option is preferred
as it is less confusing and more future-proof.
Valid colors include:
* black, red, green, yellow, blue, magenta, cyan, white
* brblack, brred, brgreen, bryellow, brblue, brmagenta, brcyan, brwhite
The br- (as in 'bright') forms are full-brightness variants of the 8 stan-
dard-brightness colors on many terminals. brblack has higher brightness
than black - towards gray.
An RGB value with three or six hex digits, such as A0FF33 or f2f can be
used. A three digit value is equivalent to specifying each digit twice;
e.g., set_color 2BC is the same as set_color 22BBCC. Hexadecimal RGB val-
ues can be in lower or uppercase.
If fish_term24bit is set to 0, fish will translate RGB values to the near-
est color on the 256-color palette. If fish_term256 is also set to 0, fish
will translate them to the 16-color palette instead. Fish launched as fish
-d term_support will include diagnostic messages that indicate the color
support mode in use.
If multiple colors are specified, fish prefers the first RGB one. However
if fish_term256 is set to 0, fish prefers the first named color specified.
The following options are available:
-f or --foreground COLOR
Sets the foreground color. This is equivalent to calling set_color
COLOR with the exception that the keyword normal will only reset the
foreground color to its default, instead of all colors and modes.
It cannot be used with VALUE or --print-colors.
-b or --background COLOR
Sets the background color.
--underline-color COLOR
Set the underline color.
-c or --print-colors
Prints the given colors or a colored list of the 16 named colors.
It cannot be used with --foreground.
-o or --bold
Sets bold mode.
-d or --dim
Sets dim mode.
-i or --italics, or -iSTATE or --italics=STATE
Sets italics mode. The state can be on (default), or off.
-r or --reverse, or -iSTATE or --reverse=STATE
Sets reverse mode. The state can be on (default), or off.
-s or --strikethrough, or -sSTATE or --strikethrough=STATE
Sets strikethrough mode. The state can be on (default), or off.
-u or --underline, or -uSTYLE or --underline=STYLE
Set the underline mode; supported styles are single (default), dou-
ble, curly, dotted, dashed and off.
--reset
Reset the text formatting to the terminal defaults before applying
the new colors and modes. This is equivalent to calling set_color
normal except that it is possible to set the foreground color in the
same call (e.g. set_color --reset green)
--theme=THEME
Ignored. Color variables that contain only this option are treated
like missing / empty color variables, i.e. fish will use the fall-
back color instead. fish_config theme choose erases all color vari-
able whose value includes this option, and adds this option to all
color variables it sets. This allows identifying variables set by a
theme, and it allows fish to update color variables whenever
fish_terminal_color_theme changes.
-h or --help
Displays help about using this command.
Notes
1. Using set_color normal will reset all colors and modes to the terminal's
default.
2. In contrast, set_color --foreground normal will only reset the fore-
ground color and leave all the other colors and modes unchanged.
3. Because of the risk of confusion, set_color --reset is recommended over
set_color normal.
4. Setting the background color only affects subsequently written charac-
ters. Fish provides no way to set the background color for the entire
terminal window. Configuring the window background color (and other at-
tributes such as its opacity) has to be done using whatever mechanisms
the terminal provides. Look for a config option.
5. Some terminals use the --bold escape sequence to switch to a brighter
color set rather than increasing the weight of text.
6. set_color works by printing sequences of characters to standard output.
If used in command substitution or a pipe, these characters will also be
captured. This may or may not be desirable. Checking the exit status of
isatty stdout before using set_color can be useful to decide not to col-
orize output in a script.
Examples
set_color red; echo "Roses are red"
set_color blue; echo "Violets are blue"
set_color 62A; echo "Eggplants are dark purple"
set_color normal; echo "Normal is nice" # Resets the background too
source - evaluate contents of file
Synopsis
source FILE [ARGUMENTS ...]
SOMECOMMAND | source
. FILE [ARGUMENTS ...]
Description
source evaluates the commands of the specified FILE in the current shell as
a new block of code. This is different from starting a new process to per-
form the commands (i.e. fish < FILE) since the commands will be evaluated
by the current shell, which means that changes in shell variables will af-
fect the current shell. If additional arguments are specified after the
file name, they will be inserted into the argv variable. The argv variable
will not include the name of the sourced file.
fish will search the working directory to resolve relative paths but will
not search PATH .
If no file is specified and a file or pipeline is connected to standard in-
put, or if the file name - is used, source will read from standard input.
If no file is specified and there is no redirected file or pipeline on
standard input, an error will be printed.
The exit status of source is the exit status of the last job to execute. If
something goes wrong while opening or reading the file, source exits with a
non-zero status.
Some other shells only support the . alias (a single period). The use of .
is deprecated in favour of source, and . will be removed in a future ver-
sion of fish.
source creates a new local scope; set --local within a sourced block will
not affect variables in the enclosing scope.
The -h or --help option displays help about using this command.
Example
source ~/.config/fish/config.fish
# Causes fish to re-read its initialization file.
status - query fish runtime information
Synopsis
status
status is-login
status is-interactive
status is-interactive-read
status is-block
status is-breakpoint
status is-command-substitution
status is-no-job-control
status is-full-job-control
status is-interactive-job-control
status current-command
status current-commandline
status filename
status basename
status dirname
status fish-path
status function
status line-number
status stack-trace
status job-control CONTROL_TYPE
status features
status test-feature FEATURE
status build-info
status get-file FILE
status list-files [PATH ...]
status terminal
status test-terminal-feature FEATURE
status language [list-available|set [LANGUAGE ...]|unset]
Description
With no arguments, status displays a summary of the current login and job
control status of the shell.
The following operations (subcommands) are available:
is-command-substitution, -c or --is-command-substitution
Returns 0 if fish is currently executing a command substitution.
is-block, -b or --is-block
Returns 0 if fish is currently executing a block of code.
is-breakpoint
Returns 0 if fish is currently showing a prompt in the context of a
breakpoint command. See also the fish_breakpoint_prompt function.
is-interactive, -i or --is-interactive
Returns 0 if fish is interactive - that is, connected to a keyboard.
is-interactive-read or --is-interactive-read
Returns 0 if fish is running an interactive read builtin which is
connected to a keyboard.
is-login, -l or --is-login
Returns 0 if fish is a login shell - that is, if fish should perform
login tasks such as setting up PATH.
is-full-job-control or --is-full-job-control
Returns 0 if full job control is enabled.
is-interactive-job-control or --is-interactive-job-control
Returns 0 if interactive job control is enabled.
is-no-job-control or --is-no-job-control
Returns 0 if no job control is enabled.
current-command
Prints the name of the currently-running function or command, like
the deprecated _ variable.
current-commandline
Prints the entirety of the currently-running commandline, inclusive
of all jobs and operators.
filename, current-filename, -f or --current-filename
Prints the filename of the currently-running script. If the current
script was called via a symlink, this will return the symlink. If
the current script was received by piping into source, then this
will return -.
basename
Prints just the filename of the running script, without any path
components before.
dirname
Prints just the path to the running script, without the actual file-
name itself. This can be relative to PWD (including just "."), de-
pending on how the script was called. This is the same as passing
the filename to dirname(3). It's useful if you want to use other
files in the current script's directory or similar.
fish-path
Prints the absolute path to the currently executing instance of
fish. This is a best-effort attempt and the exact output is down to
what the platform gives fish. In some cases you might only get
"fish".
function or current-function
Prints the name of the currently called function if able, when miss-
ing displays "Not a function" (or equivalent translated string).
line-number, current-line-number, -n or --current-line-number
Prints the line number of the currently running script.
stack-trace, print-stack-trace, -t or --print-stack-trace
Prints a stack trace of all function calls on the call stack.
job-control, -j or --job-control CONTROL_TYPE
Sets the job control type to CONTROL_TYPE, which can be none, full,
or interactive.
features
Lists all available feature flags.
test-feature FEATURE
Returns 0 when FEATURE is enabled, 1 if it is disabled, and 2 if it
is not recognized.
build-info
This prints information on how fish was build - which architecture,
which build system or profile was used, etc. This is mainly useful
for debugging.
get-file FILE
NOTE: this subcommand is mainly intended for fish's internal use;
let us know if you want to use it elsewhere.
This prints a file embedded in the fish binary at compile time. This
includes the default set of functions and completions, as well as
the man pages and themes. Which files are included depends on build
settings. Returns 0 if the file was included, 1 otherwise.
list-files FILE...
NOTE: this subcommand is mainly intended for fish's internal use;
let us know if you want to use it elsewhere.
This lists the files embedded in the fish binary at compile time.
Only files where the path starts with the optional FILE argument are
shown. Returns 0 if something was printed, 1 otherwise.
terminal
Prints the name and version of the terminal fish is running inside
(for example as reported via XTVERSION). This is not available dur-
ing early startup but only starting from when the first interactive
prompt is shown, possibly via builtin read, so before the first
fish_prompt or fish_read event.
terminal-os
Prints the name of the operating system (OS) the terminal is running
on, as reported via XTGETTCAP query-os-name. Like status terminal,
this only works once the first interactive prompt is shown. Returns
1 if the OS name is not available.
test-terminal-feature FEATURE
Returns 0 when the terminal was detected to support the given fea-
ture. Like status terminal, this only works once the first interac-
tive prompt is shown.
Currently the only available FEATURE is scroll-content-up. An error
will be printed when passed an unrecognized feature.
language
Show or modify message localization settings. When invoked without
arguments, the current language settings are shown.
Available subcommands:
list-available prints the language names for which fish has transla-
tions. These names can be used with the set subcommand.
set sets the language precedence for fish's messages. Overrides
language settings configured via environment variables, but only ap-
plies to fish itself, not to any child processes. Takes a list of
language names from the set shown by the list-available subcommand.
For some languages, fish's translation catalogs are incomplete,
meaning not all messages can be shown in these languages. There-
fore, we allow specifying a list here, with translations taken from
the first specified language which has a translation available for a
message. For example, after running status language set pt_BR fr,
all messages which have a translation into Brazilian Portuguese will
be shown in that language. The remaining messages will be shown in
French, if a French translation is available. If none of the speci-
fied languages have a translation available for a message, the mes-
sage will be shown in English.
unset undoes the effects of the set subcommand. Language settings
will be taken from environment variables again.
Notes
For backwards compatibility most subcommands can also be specified as a
long or short option. For example, rather than status is-login you can type
status --is-login. The flag forms are deprecated and may be removed in a
future release.
You can only specify one subcommand per invocation even if you use the flag
form of the subcommand.
string - manipulate strings
Synopsis
string collect [-a | --allow-empty] [-N | --no-trim-newlines] [STRING ...]
string escape [-n | --no-quoted] [--style=] [STRING ...]
string join [-q | --quiet] [-n | --no-empty] SEP [STRING ...]
string join0 [-q | --quiet] [-n | --no-empty] [STRING ...]
string length [-q | --quiet] [STRING ...]
string lower [-q | --quiet] [STRING ...]
string match [-a | --all] [-e | --entire] [-i | --ignore-case]
[-g | --groups-only] [-r | --regex] [-n | --index]
[-q | --quiet] [-v | --invert]
PATTERN [STRING ...]
string pad [-r | --right] [-C | --center] [(-c | --char) CHAR] [(-w | --width) INTEGER]
[STRING ...]
string repeat [(-n | --count) COUNT] [(-m | --max) MAX] [-N | --no-newline]
[-q | --quiet] [STRING ...]
string repeat [-N | --no-newline] [-q | --quiet] COUNT [STRING ...]
string replace [-a | --all] [-f | --filter] [-i | --ignore-case]
[-r | --regex] [-q | --quiet] PATTERN REPLACE [STRING ...]
string shorten [(-c | --char) CHARS] [(-m | --max) INTEGER]
[-N | --no-newline] [-l | --left] [-q | --quiet] [STRING ...]
string split [(-f | --fields) FIELDS] [(-m | --max) MAX] [-n | --no-empty]
[-q | --quiet] [-r | --right] SEP [STRING ...]
string split0 [(-f | --fields) FIELDS] [(-m | --max) MAX] [-n | --no-empty]
[-q | --quiet] [-r | --right] [STRING ...]
string sub [(-s | --start) START] [(-e | --end) END] [(-l | --length) LENGTH]
[-q | --quiet] [STRING ...]
string trim [-l | --left] [-r | --right] [(-c | --chars) CHARS]
[-q | --quiet] [STRING ...]
string unescape [--style=] [STRING ...]
string upper [-q | --quiet] [STRING ...]
Description
string performs operations on strings.
STRING arguments are taken from the command line unless standard input is
connected to a pipe or a file, in which case they are read from standard
input, one STRING per line. It is an error to supply STRING arguments on
the command line and on standard input.
Arguments beginning with - are normally interpreted as switches; -- causes
the following arguments not to be treated as switches even if they begin
with -. Switches and required arguments are recognized only on the command
line.
Most subcommands accept a -q or --quiet switch, which suppresses the usual
output but exits with the documented status. In this case these commands
will quit early, without reading all of the available input.
The following subcommands are available.
"collect" subcommand
string collect [-a | --allow-empty] [-N | --no-trim-newlines] [STRING ...]
string collect collects its input into a single output argument, without
splitting the output when used in a command substitution. This is useful
when trying to collect multiline output from another command into a vari-
able. Exit status: 0 if any output argument is non-empty, or 1 otherwise.
A command like echo (cmd | string collect) is mostly equivalent to a quoted
command substitution (echo "$(cmd)"). The main difference is that the for-
mer evaluates to zero or one elements whereas the quoted command substitu-
tion always evaluates to one element due to string interpolation.
If invoked with multiple arguments instead of input, string collect pre-
serves each argument separately, where the number of output arguments is
equal to the number of arguments given to string collect.
Any trailing newlines on the input are trimmed, just as with "$(cmd)" sub-
stitution. Use --no-trim-newlines to disable this behavior, which may be
useful when running a command such as set contents (cat filename | string
collect -N).
With --allow-empty, string collect always prints one (empty) argument. This
can be used to prevent an argument from disappearing.
Examples
>_ echo "zero $(echo one\ntwo\nthree) four"
zero one
two
three four
>_ echo \"(echo one\ntwo\nthree | string collect)\"
"one
two
three"
>_ echo \"(echo one\ntwo\nthree | string collect -N)\"
"one
two
three
"
>_ echo foo(true | string collect --allow-empty)bar
foobar
"escape" and "unescape" subcommands
string escape [-n | --no-quoted] [--style=] [STRING ...]
string unescape [--style=] [STRING ...]
string escape escapes each STRING in one of several ways.
--style=script (default) alters the string such that it can be passed back
to eval to produce the original argument again. By default, all special
characters are escaped, and quotes are used to simplify the output when
possible. If -n or --no-quoted is given, the simplifying quoted format is
not used. Exit status: 0 if at least one string was escaped, or 1 other-
wise.
--style=var ensures the string can be used as a variable name by hex encod-
ing any non-alphanumeric characters. The string is first converted to UTF-8
before being encoded.
--style=url ensures the string can be used as a URL by hex encoding any
character which is not legal in a URL. The string is first converted to
UTF-8 before being encoded.
--style=regex escapes an input string for literal matching within a regex
expression. The string is first converted to UTF-8 before being encoded.
string unescape performs the inverse of the string escape command. If the
string to be unescaped is not properly formatted it is ignored. For exam-
ple, doing string unescape --style=var (string escape --style=var $str)
will return the original string. There is no support for unescaping
--style=regex.
Examples
>_ echo \x07 | string escape
\cg
>_ string escape --style=var 'a1 b2'\u6161
a1_20_b2_E6_85_A1_
"join" and "join0" subcommands
string join [-q | --quiet] [-n | --no-empty] [--] SEP [STRING ...]
string join0 [-q | --quiet] [-n | --no-empty] [--] [STRING ...]
Joins its STRING arguments into a single string separated by SEP (for
string join) or by the zero byte (NUL) (for string join0). Exit status: 0
if at least one join was performed, or 1 otherwise.
-n, --no-empty
Exclude empty strings from consideration (e.g. string join -n + a b
"" c would expand to a+b+c not a+b++c).
-q, --quiet
Do not print the strings, only set the exit status as described
above.
WARNING: Insert a -- before positional arguments to prevent them from be-
ing interpreted as flags. Otherwise, any strings starting with - will be
treated as flag arguments, meaning they will most likely result in the com-
mand failing. This is also true if you specify a variable which expands to
such a string instead of a literal string. If you don't need to append
flag arguments at the end of the command, just always use -- to avoid un-
welcome surprises.
string join0 adds a trailing NUL. This is most useful in conjunction with
tools that accept NUL-delimited input, such as sort -z.
Because Unix uses NUL as the string terminator, passing the output of
string join0 as an argument to a command (via a command substitution) won't
actually work. Fish will pass the correct bytes along, but the command
won't be able to tell where the argument ends. This is a limitation of
Unix' argument passing.
Examples
>_ seq 3 | string join ...
1...2...3
# Give a list of NUL-separated filenames to du (this is a GNU extension)
>_ string join0 file1 file2 file\nwith\nmultiple\nlines | du --files0-from=-
# Just put the strings together without a separator
>_ string join '' a b c
abc
>_ set -l markdown_list '- first' '- second' '- third'
# Strings with leading hyphens (also in variable expansions) are interpreted as flag arguments by default.
>_ string join \n $markdown_list
string join: - first: unknown option
# Use '--' to prevent this.
>_ string join -- \n $markdown_list
- first
- second
- third
"length" subcommand
string length [-q | --quiet] [-V | --visible] [STRING ...]
string length reports the length of each string argument in characters.
Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise.
With -V or --visible, it uses the visible width of the arguments. That
means it will discount escape sequences fish knows about, account for
$fish_emoji_width and $fish_ambiguous_width. It will also count each line
(separated by \n) on its own, and with a carriage return (\r) count only
the widest stretch on a line. The intent is to measure the number of
columns the STRING would occupy in the current terminal.
Examples
>_ string length 'hello, world'
12
>_ set str foo
>_ string length -q $str; echo $status
0
# Equivalent to test -n "$str"
>_ string length --visible (set_color red)foobar
# the set_color is discounted, so this is the width of "foobar"
6
>_ string length --visible dhdhdhdh
# depending on $fish_emoji_width, this is either 4 or 8
# in new terminals it should be
8
>_ string length --visible abcdef\r123
# this displays as "123def", so the width is 6
6
>_ string length --visible a\nbc
# counts "a" and "bc" as separate lines, so it prints width for each
1
2
"lower" subcommand
string lower [-q | --quiet] [STRING ...]
string lower converts each string argument to lowercase. Exit status: 0 if
at least one string was converted to lowercase, else 1. This means that in
conjunction with the -q flag you can readily test whether a string is al-
ready lowercase.
"match" subcommand
string match [-a | --all] [-e | --entire] [-i | --ignore-case]
[-g | --groups-only] [-r | --regex] [-n | --index]
[-q | --quiet] [-v | --invert] [(-m | --max-matches) MAX]
PATTERN [STRING ...]
string match tests each STRING against PATTERN and prints matching sub-
strings. Only the first match for each STRING is reported unless -a or
--all is given, in which case all matches are reported.
If you specify the -e or --entire then each matching string is printed in-
cluding any prefix or suffix not matched by the pattern (equivalent to grep
without the -o flag). You can, obviously, achieve the same result by
prepending and appending * or .* depending on whether or not you have spec-
ified the --regex flag. The --entire flag is a way to avoid having to com-
plicate the pattern in that fashion and make the intent of the string match
clearer. Without --entire and --regex, a PATTERN will need to match the en-
tire STRING before it will be reported.
Matching can be made case-insensitive with --ignore-case or -i.
If --groups-only or -g is given, only the capturing groups will be reported
- meaning the full match will be skipped. This is incompatible with --en-
tire and --invert, and requires --regex. It is useful as a simple cutting
tool instead of string replace, so you can choose "this part" of a string.
If --index or -n is given, each match is reported as a 1-based start posi-
tion and a length. By default, PATTERN is interpreted as a glob pattern
matched against each entire STRING argument. A glob pattern is only consid-
ered a valid match if it matches the entire STRING.
If --regex or -r is given, PATTERN is interpreted as a Perl-compatible reg-
ular expression, which does not have to match the entire STRING. For a reg-
ular expression containing capturing groups, multiple items will be re-
ported for each match, one for the entire match and one for each capturing
group. With this, only the matching part of the STRING will be reported,
unless --entire is given.
When matching via regular expressions, string match automatically sets
variables for all named capturing groups ((?<name>expression)). It will
create a variable with the name of the group, in the default scope, for
each named capturing group, and set it to the value of the capturing group
in the first matched argument. If a named capture group matched an empty
string, the variable will be set to the empty string (like set var ""). If
it did not match, the variable will be set to nothing (like set var). When
--regex is used with --all, this behavior changes. Each named variable will
contain a list of matches, with the first match contained in the first ele-
ment, the second match in the second, and so on. If the group was empty or
did not match, the corresponding element will be an empty string.
If --invert or -v is used the selected lines will be only those which do
not match the given glob pattern or regular expression.
If --max-matches MAX or -m MAX is used, string will stop checking for
matches after MAX lines of input have matched. This can be used as an
"early exit" optimization when processing long inputs but expecting a lim-
ited and fixed number of outputs that might be found considerably before
the input stream has been exhausted. If combined with --invert or -v, con-
siders only inverted matches.
Exit status: 0 if at least one match was found, or 1 otherwise.
Match Glob Examples
>_ string match 'a' a
a
>_ string match 'a*b' axxb
axxb
>_ string match -i 'a*B' Axxb
Axxb
>_ string match -- '-*' -h foo --version bar
# To match things that look like options, we need a `--`
# to tell string its options end there.
-h
--version
>_ echo 'ok?' | string match '*?'
ok?
# Note that only the second STRING will match here.
>_ string match 'foo' 'foo1' 'foo' 'foo2'
foo
>_ string match -e 'foo' 'foo1' 'foo' 'foo2'
foo1
foo
foo2
>_ string match 'foo*' 'foo1' 'foo' 'foo2'
foo1
foo2
Match Regex Examples
>_ string match -r 'cat|dog|fish' 'nice dog'
dog
>_ string match -r -v "c.*[12]" {cat,dog}(seq 1 4)
dog1
dog2
cat3
dog3
cat4
dog4
>_ string match -r -- '-.*' -h foo --version bar
# To match things that look like options, we need a `--`
# to tell string its options end there.
-h
--version
>_ string match -r '(\d\d?):(\d\d):(\d\d)' 2:34:56
2:34:56
2
34
56
>_ string match -r '^(\w{2,4})\1$' papa mud murmur
papa
pa
murmur
mur
>_ string match -r -a -n at ratatat
2 2
4 2
6 2
>_ string match -r -i '0x[0-9a-f]{1,8}' 'int magic = 0xBadC0de;'
0xBadC0de
>_ echo $version
3.1.2-1575-ga2ff32d90
>_ string match -rq '(?<major>\d+).(?<minor>\d+).(?<revision>\d+)' -- $version
>_ echo "You are using fish $major!"
You are using fish 3!
>_ string match -raq ' *(?<sentence>[^.!?]+)(?<punctuation>[.!?])?' "hello, friend. goodbye"
>_ printf "%s\n" -- $sentence
hello, friend
goodbye
>_ printf "%s\n" -- $punctuation
.
>_ string match -rq '(?<word>hello)' 'hi'
>_ count $word
0
"pad" subcommand
string pad [-r | --right] [-C | --center] [(-c | --char) CHAR] [(-w | --width) INTEGER]
[STRING ...]
string pad extends each STRING to the given visible width by adding CHAR to
the left. That means the width of all visible characters added together,
excluding escape sequences and accounting for fish_emoji_width and
fish_ambiguous_width. It is the amount of columns in a terminal the STRING
occupies.
The escape sequences reflect what fish knows about, and how it computes its
output. Your terminal might support more escapes, or not support escape se-
quences that fish knows about.
If -C or --center is given, add the padding to before and after the string.
If it is impossible to perfectly center the result (because the required
amount of padding is an odd number), extra padding will be added to the
left, unless --right is also given.
If -r or --right is given, add the padding after a string.
If -c or --char is given, pad with CHAR instead of whitespace.
The output is padded to the maximum width of all input strings. If -w or
--width is given, use at least that.
Examples
>_ string pad -w 10 abc abcdef
abc
abcdef
>_ string pad --right --char=dh "fish are pretty" "rich. "
fish are pretty
rich. dhdhdhdh
>_ string pad -w$COLUMNS (date)
# Prints the current time on the right edge of the screen.
See also
* The printf command can do simple padding, for example printf %10s\n works
like string pad -w10.
* string length with the --visible option can be used to show what fish
thinks the width is.
"shorten" subcommand
string shorten [(-c | --char) CHARS] [(-m | --max) INTEGER]
[-N | --no-newline] [-l | --left] [-q | --quiet] [STRING ...]
string shorten truncates each STRING to the given visible width and adds an
ellipsis to indicate it. "Visible width" means the width of all visible
characters added together, excluding escape sequences and accounting for
fish_emoji_width and fish_ambiguous_width. It is the amount of columns in a
terminal the STRING occupies.
The escape sequences reflect what fish knows about, and how it computes its
output. Your terminal might support more escapes, or not support escape se-
quences that fish knows about.
If -m or --max is given, truncate at the given width. Otherwise, the lowest
non-zero width of all input strings is used. A max of 0 means no shortening
takes place, all STRINGs are printed as-is.
If -N or --no-newline is given, only the first line (or last line with
--left) of each STRING is used, and an ellipsis is added if it was multi-
line. This only works for STRINGs being given as arguments, multiple lines
given on stdin will be interpreted as separate STRINGs instead.
If -c or --char is given, add CHAR instead of an ellipsis. This can also be
empty or more than one character.
If -l or --left is given, remove text from the left on instead, so this
prints the longest suffix of the string that fits. With --no-newline, this
will take from the last line instead of the first.
If -q or --quiet is given, string shorten only runs for the return value -
if anything would be shortened, it returns 0, else 1.
The default ellipsis is ^a|. If fish thinks your system is incapable because
of your locale, it will use ... instead.
The return value is 0 if any shortening occurred, 1 otherwise.
Examples
>_ string shorten foo foobar
# No width was given, we infer, and "foo" is the shortest.
foo
foa|
>_ string shorten --char="..." foo foobar
# The target width is 3 because of "foo",
# and our ellipsis is 3 too, so we can't really show anything.
# This is the default ellipsis if your locale doesn't allow "a|".
foo
...
>_ string shorten --char="" --max 4 abcdef 123456
# Leaving the char empty makes us not add an ellipsis
# So this truncates at 4 columns:
abcd
1234
>_ touch "a multiline"\n"file"
>_ for file in *; string shorten -N -- $file; end
# Shorten the multiline file so we only show one line per file:
a multilinea|
>_ ss -p | string shorten -m$COLUMNS -c ""
# `ss` from Linux' iproute2 shows socket information, but prints extremely long lines.
# This shortens input so it fits on the screen without overflowing lines.
>_ git branch | string match -rg '^\* (.*)' | string shorten -m20
# Take the current git branch and shorten it at 20 columns.
# Here the branch is "builtin-path-with-expand"
builtin-path-with-ea|
>_ git branch | string match -rg '^\* (.*)' | string shorten -m20 --left
# Taking 20 columns from the right instead:
a|in-path-with-expand
See also
* string pad does the inverse of this command, adding padding to a specific
width instead.
* The printf command can do simple padding, for example printf %10s\n works
like string pad -w10.
* string length with the --visible option can be used to show what fish
thinks the width is.
"repeat" subcommand
string repeat [(-n | --count) COUNT] [(-m | --max) MAX] [-N | --no-newline]
[-q | --quiet] [STRING ...]
string repeat [-N | --no-newline] [-q | --quiet] COUNT [STRING ...]
string repeat repeats the STRING -n or --count times. The -m or --max op-
tion will limit the number of outputted characters (excluding the newline).
This option can be used by itself or in conjunction with --count. If both
--count and --max are present, max char will be outputted unless the final
repeated string size is less than max, in that case, the string will repeat
until count has been reached. Both --count and --max will accept a number
greater than or equal to zero, in the case of zero, nothing will be out-
putted. The first argument is interpreted as COUNT if --count or --max are
not explicitly specified. If -N or --no-newline is given, the output won't
contain a newline character at the end. Exit status: 0 if yielded string is
not empty, 1 otherwise.
Examples
Repeat Examples
>_ string repeat -n 2 'foo '
foo foo
>_ echo foo | string repeat -n 2
foofoo
>_ string repeat -n 2 -m 5 'foo'
foofo
>_ string repeat -m 5 'foo'
foofo
>_ string repeat 2 'foo'
foofoo
>_ string repeat 2 -n 3
222
"replace" subcommand
string replace [-a | --all] [-f | --filter] [-i | --ignore-case]
[-r | --regex] [(-m | --max-matches) MAX] [-q | --quiet]
PATTERN REPLACEMENT [STRING ...]
string replace is similar to string match but replaces non-overlapping
matching substrings with a replacement string and prints the result. By de-
fault, PATTERN is treated as a literal substring to be matched.
If -r or --regex is given, PATTERN is interpreted as a Perl-compatible reg-
ular expression, and REPLACEMENT can contain C-style escape sequences like
t as well as references to capturing groups by number or name as $n or
${n}.
If you specify the -f or --filter flag then each input string is printed
only if a replacement was done. This is useful where you would otherwise
use this idiom: a_cmd | string match pattern | string replace pattern
new_pattern. You can instead just write a_cmd | string replace --filter
pattern new_pattern.
If --max-matches MAX or -m MAX is used, string replace will stop all pro-
cessing after MAX lines of input have matched the specified pattern. In the
event of --filter or -f, this means the output will be MAX lines in length.
This can be used as an "early exit" optimization when processing long in-
puts but expecting a limited and fixed number of outputs that might be
found considerably before the input stream has been exhausted.
Exit status: 0 if at least one replacement was performed, or 1 otherwise.
Replace Literal Examples
>_ string replace is was 'blue is my favorite'
blue was my favorite
>_ string replace 3rd last 1st 2nd 3rd
1st
2nd
last
>_ string replace -a ' ' _ 'spaces to underscores'
spaces_to_underscores
Replace Regex Examples
>_ string replace -r -a '[^\d.]+' ' ' '0 one two 3.14 four 5x'
0 3.14 5
>_ string replace -r '(\w+)\s+(\w+)' '$2 $1 $$' 'left right'
right left $
>_ string replace -r '\s*newline\s*' '\n' 'put a newline here'
put a
here
"split" and "split0" subcommands
string split [(-f | --fields) FIELDS [-a | --allow-empty]] [(-m | --max) MAX] [-n | --no-empty]
[-q | --quiet] [-r | --right] SEP [STRING ...]
string split0 [(-f | --fields) FIELDS [-a | --allow-empty]] [(-m | --max) MAX] [-n | --no-empty]
[-q | --quiet] [-r | --right] [STRING ...]
string split splits each STRING on the separator SEP, which can be an empty
string. If -m or --max is specified, at most MAX splits are done on each
STRING. If -r or --right is given, splitting is performed right-to-left.
This is only useful in combination with -m or --max. With -n or --no-empty,
empty results are excluded from consideration (e.g. hello\n\nworld would
expand to two strings and not three). Exit status: 0 if at least one split
was performed, or 1 otherwise.
Use -f or --fields to print out specific fields. FIELDS is a comma-sepa-
rated string of field numbers and/or spans. Each field is one-indexed, and
will be printed on separate lines. If a given field does not exist, then
the command exits with status 1 and does not print anything, unless --al-
low-empty is used.
See also the --delimiter option of the read command.
string split0 splits each STRING on the zero byte (NUL). Options are the
same as string split except that no separator is given.
split0 has the important property that its output is not further split when
used in a command substitution, allowing for the command substitution to
produce elements containing newlines. This is most useful when used with
Unix tools that produce zero bytes, such as find -print0 or sort -z. See
split0 examples below.
Be aware that commandline arguments cannot include NULs, so you likely want
to pass to string split0 via a pipe, not a command substitution.
Examples
>_ string split . example.com
example
com
>_ string split -r -m1 / /usr/local/bin/fish
/usr/local/bin
fish
>_ string split '' abc
a
b
c
>_ string split --allow-empty -f1,3-4,5 '' abcd
a
c
d
NUL Delimited Examples
>_ # Count files in a directory, without being confused by newlines.
>_ # Note: Don't use `string split0 (find . -print0)`, because arguments cannot include NUL.
>_ count (find . -print0 | string split0)
42
>_ # Sort a list of elements which may contain newlines
>_ set foo beta alpha\ngamma
>_ set foo (string join0 $foo | sort -z | string split0)
>_ string escape $foo[1]
alpha\ngamma
"sub" subcommand
string sub [(-s | --start) START] [(-e | --end) END] [(-l | --length) LENGTH]
[-q | --quiet] [STRING ...]
string sub prints a substring of each string argument. The start/end of the
substring can be specified with -s/-e or --start/--end followed by a
1-based index value. Positive index values are relative to the start of the
string and negative index values are relative to the end of the string. The
default start value is 1. The length of the substring can be specified with
-l or --length. If the length or end is not specified, the substring con-
tinues to the end of each STRING. Exit status: 0 if at least one substring
operation was performed, 1 otherwise. --length is mutually exclusive with
--end.
Examples
>_ string sub --length 2 abcde
ab
>_ string sub -s 2 -l 2 abcde
bc
>_ string sub --start=-2 abcde
de
>_ string sub --end=3 abcde
abc
>_ string sub -e -1 abcde
abcd
>_ string sub -s 2 -e -1 abcde
bcd
>_ string sub -s -3 -e -2 abcde
c
"trim" subcommand
string trim [-l | --left] [-r | --right] [(-c | --chars) CHARS]
[-q | --quiet] [STRING ...]
string trim removes leading and trailing whitespace from each STRING. If -l
or --left is given, only leading whitespace is removed. If -r or --right is
given, only trailing whitespace is trimmed.
The -c or --chars switch causes the set of characters in CHARS to be re-
moved instead of whitespace. This is a set of characters, not a string - if
you pass -c foo, it will remove any "f" or "o", not just "foo" as a whole.
Exit status: 0 if at least one character was trimmed, or 1 otherwise.
Examples
>_ string trim ' abc '
abc
>_ string trim --right --chars=yz xyzzy zany
x
zan
"upper" subcommand
string upper [-q | --quiet] [STRING ...]
string upper converts each string argument to uppercase. Exit status: 0 if
at least one string was converted to uppercase, else 1. This means that in
conjunction with the -q flag you can readily test whether a string is al-
ready uppercase.
Regular Expressions
Both the match and replace subcommand support regular expressions when used
with the -r or --regex option. The dialect is that of PCRE2.
In general, special characters are special by default, so a+ matches one or
more "a"s, while a\+ matches an "a" and then a "+". (a+) matches one or
more "a"s in a capturing group ((?:XXXX) denotes a non-capturing group).
For the replacement parameter of replace, $n refers to the n-th group of
the match. In the match parameter, \n (e.g. \1) refers back to groups.
Some features include repetitions:
* * refers to 0 or more repetitions of the previous expression
* + 1 or more
* ? 0 or 1.
* {n} to exactly n (where n is a number)
* {n,m} at least n, no more than m.
* {n,} n or more
Character classes, some of the more important:
* . any character except newline
* \d a decimal digit and \D, not a decimal digit
* \s whitespace and \S, not whitespace
* \w a "word" character and \W, a "non-word" character
* [...] (where "..." is some characters) is a character set
* [^...] is the inverse of the given character set
* [x-y] is the range of characters from x-y
* [[:xxx:]] is a named character set
* [[:^xxx:]] is the inverse of a named character set
* [[:alnum:]] : "alphanumeric"
* [[:alpha:]] : "alphabetic"
* [[:ascii:]] : "0-127"
* [[:blank:]] : "space or tab"
* [[:cntrl:]] : "control character"
* [[:digit:]] : "decimal digit"
* [[:graph:]] : "printing, excluding space"
* [[:lower:]] : "lower case letter"
* [[:print:]] : "printing, including space"
* [[:punct:]] : "printing, excluding alphanumeric"
* [[:space:]] : "white space"
* [[:upper:]] : "upper case letter"
* [[:word:]] : "same as w"
* [[:xdigit:]] : "hexadecimal digit"
Groups:
* (...) is a capturing group
* (?:...) is a non-capturing group
* \n is a backreference (where n is the number of the group, starting with
1)
* $n is a reference from the replacement expression to a group in the match
expression.
And some other things:
* \b denotes a word boundary, \B is not a word boundary.
* ^ is the start of the string or line, $ the end.
* | is "alternation", i.e. the "or".
Comparison to other tools
Most operations string supports can also be done by external tools. Some of
these include grep, sed and cut.
If you are familiar with these, it is useful to know how string differs
from them.
In contrast to these classics, string reads input either from stdin or as
arguments. string also does not deal with files, so it requires redirec-
tions to be used with them.
In contrast to grep, string's match defaults to glob-mode, while replace
defaults to literal matching. If set to regex-mode, they use PCRE regular
expressions, which is comparable to grep's -P option. match defaults to
printing just the match, which is like grep with -o (use --entire to enable
grep-like behavior).
Like sed's s/old/new/ command, string replace still prints strings that
don't match. sed's -n in combination with a /p modifier or command is like
string replace -f.
string split somedelimiter is a replacement for tr somedelimiter \n.
string-collect - join strings into one
Synopsis
string collect [-a | --allow-empty] [-N | --no-trim-newlines] [STRING ...]
Description
string collect collects its input into a single output argument, without
splitting the output when used in a command substitution. This is useful
when trying to collect multiline output from another command into a vari-
able. Exit status: 0 if any output argument is non-empty, or 1 otherwise.
A command like echo (cmd | string collect) is mostly equivalent to a quoted
command substitution (echo "$(cmd)"). The main difference is that the for-
mer evaluates to zero or one elements whereas the quoted command substitu-
tion always evaluates to one element due to string interpolation.
If invoked with multiple arguments instead of input, string collect pre-
serves each argument separately, where the number of output arguments is
equal to the number of arguments given to string collect.
Any trailing newlines on the input are trimmed, just as with "$(cmd)" sub-
stitution. Use --no-trim-newlines to disable this behavior, which may be
useful when running a command such as set contents (cat filename | string
collect -N).
With --allow-empty, string collect always prints one (empty) argument. This
can be used to prevent an argument from disappearing.
Examples
>_ echo "zero $(echo one\ntwo\nthree) four"
zero one
two
three four
>_ echo \"(echo one\ntwo\nthree | string collect)\"
"one
two
three"
>_ echo \"(echo one\ntwo\nthree | string collect -N)\"
"one
two
three
"
>_ echo foo(true | string collect --allow-empty)bar
foobar
string-escape - escape special characters
Synopsis
string escape [-n | --no-quoted] [--style=] [STRING ...]
string unescape [--style=] [STRING ...]
Description
string escape escapes each STRING in one of several ways.
--style=script (default) alters the string such that it can be passed back
to eval to produce the original argument again. By default, all special
characters are escaped, and quotes are used to simplify the output when
possible. If -n or --no-quoted is given, the simplifying quoted format is
not used. Exit status: 0 if at least one string was escaped, or 1 other-
wise.
--style=var ensures the string can be used as a variable name by hex encod-
ing any non-alphanumeric characters. The string is first converted to UTF-8
before being encoded.
--style=url ensures the string can be used as a URL by hex encoding any
character which is not legal in a URL. The string is first converted to
UTF-8 before being encoded.
--style=regex escapes an input string for literal matching within a regex
expression. The string is first converted to UTF-8 before being encoded.
string unescape performs the inverse of the string escape command. If the
string to be unescaped is not properly formatted it is ignored. For exam-
ple, doing string unescape --style=var (string escape --style=var $str)
will return the original string. There is no support for unescaping
--style=regex.
Examples
>_ echo \x07 | string escape
\cg
>_ string escape --style=var 'a1 b2'\u6161
a1_20_b2_E6_85_A1_
string-join - join strings with delimiter
Synopsis
string join [-q | --quiet] [-n | --no-empty] [--] SEP [STRING ...]
string join0 [-q | --quiet] [-n | --no-empty] [--] [STRING ...]
Description
Joins its STRING arguments into a single string separated by SEP (for
string join) or by the zero byte (NUL) (for string join0). Exit status: 0
if at least one join was performed, or 1 otherwise.
-n, --no-empty
Exclude empty strings from consideration (e.g. string join -n + a b
"" c would expand to a+b+c not a+b++c).
-q, --quiet
Do not print the strings, only set the exit status as described
above.
WARNING: Insert a -- before positional arguments to prevent them from be-
ing interpreted as flags. Otherwise, any strings starting with - will be
treated as flag arguments, meaning they will most likely result in the com-
mand failing. This is also true if you specify a variable which expands to
such a string instead of a literal string. If you don't need to append
flag arguments at the end of the command, just always use -- to avoid un-
welcome surprises.
string join0 adds a trailing NUL. This is most useful in conjunction with
tools that accept NUL-delimited input, such as sort -z.
Because Unix uses NUL as the string terminator, passing the output of
string join0 as an argument to a command (via a command substitution) won't
actually work. Fish will pass the correct bytes along, but the command
won't be able to tell where the argument ends. This is a limitation of
Unix' argument passing.
Examples
>_ seq 3 | string join ...
1...2...3
# Give a list of NUL-separated filenames to du (this is a GNU extension)
>_ string join0 file1 file2 file\nwith\nmultiple\nlines | du --files0-from=-
# Just put the strings together without a separator
>_ string join '' a b c
abc
>_ set -l markdown_list '- first' '- second' '- third'
# Strings with leading hyphens (also in variable expansions) are interpreted as flag arguments by default.
>_ string join \n $markdown_list
string join: - first: unknown option
# Use '--' to prevent this.
>_ string join -- \n $markdown_list
- first
- second
- third
string-join0 - join strings with zero bytes
Synopsis
string join [-q | --quiet] [-n | --no-empty] [--] SEP [STRING ...]
string join0 [-q | --quiet] [-n | --no-empty] [--] [STRING ...]
Description
Joins its STRING arguments into a single string separated by SEP (for
string join) or by the zero byte (NUL) (for string join0). Exit status: 0
if at least one join was performed, or 1 otherwise.
-n, --no-empty
Exclude empty strings from consideration (e.g. string join -n + a b
"" c would expand to a+b+c not a+b++c).
-q, --quiet
Do not print the strings, only set the exit status as described
above.
WARNING: Insert a -- before positional arguments to prevent them from be-
ing interpreted as flags. Otherwise, any strings starting with - will be
treated as flag arguments, meaning they will most likely result in the com-
mand failing. This is also true if you specify a variable which expands to
such a string instead of a literal string. If you don't need to append
flag arguments at the end of the command, just always use -- to avoid un-
welcome surprises.
string join0 adds a trailing NUL. This is most useful in conjunction with
tools that accept NUL-delimited input, such as sort -z.
Because Unix uses NUL as the string terminator, passing the output of
string join0 as an argument to a command (via a command substitution) won't
actually work. Fish will pass the correct bytes along, but the command
won't be able to tell where the argument ends. This is a limitation of
Unix' argument passing.
Examples
>_ seq 3 | string join ...
1...2...3
# Give a list of NUL-separated filenames to du (this is a GNU extension)
>_ string join0 file1 file2 file\nwith\nmultiple\nlines | du --files0-from=-
# Just put the strings together without a separator
>_ string join '' a b c
abc
>_ set -l markdown_list '- first' '- second' '- third'
# Strings with leading hyphens (also in variable expansions) are interpreted as flag arguments by default.
>_ string join \n $markdown_list
string join: - first: unknown option
# Use '--' to prevent this.
>_ string join -- \n $markdown_list
- first
- second
- third
string-length - print string lengths
Synopsis
string length [-q | --quiet] [-V | --visible] [STRING ...]
Description
string length reports the length of each string argument in characters.
Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise.
With -V or --visible, it uses the visible width of the arguments. That
means it will discount escape sequences fish knows about, account for
$fish_emoji_width and $fish_ambiguous_width. It will also count each line
(separated by \n) on its own, and with a carriage return (\r) count only
the widest stretch on a line. The intent is to measure the number of
columns the STRING would occupy in the current terminal.
Examples
>_ string length 'hello, world'
12
>_ set str foo
>_ string length -q $str; echo $status
0
# Equivalent to test -n "$str"
>_ string length --visible (set_color red)foobar
# the set_color is discounted, so this is the width of "foobar"
6
>_ string length --visible dhdhdhdh
# depending on $fish_emoji_width, this is either 4 or 8
# in new terminals it should be
8
>_ string length --visible abcdef\r123
# this displays as "123def", so the width is 6
6
>_ string length --visible a\nbc
# counts "a" and "bc" as separate lines, so it prints width for each
1
2
string-lower - convert strings to lowercase
Synopsis
string lower [-q | --quiet] [STRING ...]
Description
string lower converts each string argument to lowercase. Exit status: 0 if
at least one string was converted to lowercase, else 1. This means that in
conjunction with the -q flag you can readily test whether a string is al-
ready lowercase.
string-match - match substrings
Synopsis
string match [-a | --all] [-e | --entire] [-i | --ignore-case]
[-g | --groups-only] [-r | --regex] [-n | --index]
[-q | --quiet] [-v | --invert] [(-m | --max-matches) MAX]
PATTERN [STRING ...]
Description
string match tests each STRING against PATTERN and prints matching sub-
strings. Only the first match for each STRING is reported unless -a or
--all is given, in which case all matches are reported.
If you specify the -e or --entire then each matching string is printed in-
cluding any prefix or suffix not matched by the pattern (equivalent to grep
without the -o flag). You can, obviously, achieve the same result by
prepending and appending * or .* depending on whether or not you have spec-
ified the --regex flag. The --entire flag is a way to avoid having to com-
plicate the pattern in that fashion and make the intent of the string match
clearer. Without --entire and --regex, a PATTERN will need to match the en-
tire STRING before it will be reported.
Matching can be made case-insensitive with --ignore-case or -i.
If --groups-only or -g is given, only the capturing groups will be reported
- meaning the full match will be skipped. This is incompatible with --en-
tire and --invert, and requires --regex. It is useful as a simple cutting
tool instead of string replace, so you can choose "this part" of a string.
If --index or -n is given, each match is reported as a 1-based start posi-
tion and a length. By default, PATTERN is interpreted as a glob pattern
matched against each entire STRING argument. A glob pattern is only consid-
ered a valid match if it matches the entire STRING.
If --regex or -r is given, PATTERN is interpreted as a Perl-compatible reg-
ular expression, which does not have to match the entire STRING. For a reg-
ular expression containing capturing groups, multiple items will be re-
ported for each match, one for the entire match and one for each capturing
group. With this, only the matching part of the STRING will be reported,
unless --entire is given.
When matching via regular expressions, string match automatically sets
variables for all named capturing groups ((?<name>expression)). It will
create a variable with the name of the group, in the default scope, for
each named capturing group, and set it to the value of the capturing group
in the first matched argument. If a named capture group matched an empty
string, the variable will be set to the empty string (like set var ""). If
it did not match, the variable will be set to nothing (like set var). When
--regex is used with --all, this behavior changes. Each named variable will
contain a list of matches, with the first match contained in the first ele-
ment, the second match in the second, and so on. If the group was empty or
did not match, the corresponding element will be an empty string.
If --invert or -v is used the selected lines will be only those which do
not match the given glob pattern or regular expression.
If --max-matches MAX or -m MAX is used, string will stop checking for
matches after MAX lines of input have matched. This can be used as an
"early exit" optimization when processing long inputs but expecting a lim-
ited and fixed number of outputs that might be found considerably before
the input stream has been exhausted. If combined with --invert or -v, con-
siders only inverted matches.
Exit status: 0 if at least one match was found, or 1 otherwise.
Examples
Match Glob Examples
>_ string match 'a' a
a
>_ string match 'a*b' axxb
axxb
>_ string match -i 'a*B' Axxb
Axxb
>_ string match -- '-*' -h foo --version bar
# To match things that look like options, we need a `--`
# to tell string its options end there.
-h
--version
>_ echo 'ok?' | string match '*?'
ok?
# Note that only the second STRING will match here.
>_ string match 'foo' 'foo1' 'foo' 'foo2'
foo
>_ string match -e 'foo' 'foo1' 'foo' 'foo2'
foo1
foo
foo2
>_ string match 'foo*' 'foo1' 'foo' 'foo2'
foo1
foo2
Match Regex Examples
>_ string match -r 'cat|dog|fish' 'nice dog'
dog
>_ string match -r -v "c.*[12]" {cat,dog}(seq 1 4)
dog1
dog2
cat3
dog3
cat4
dog4
>_ string match -r -- '-.*' -h foo --version bar
# To match things that look like options, we need a `--`
# to tell string its options end there.
-h
--version
>_ string match -r '(\d\d?):(\d\d):(\d\d)' 2:34:56
2:34:56
2
34
56
>_ string match -r '^(\w{2,4})\1$' papa mud murmur
papa
pa
murmur
mur
>_ string match -r -a -n at ratatat
2 2
4 2
6 2
>_ string match -r -i '0x[0-9a-f]{1,8}' 'int magic = 0xBadC0de;'
0xBadC0de
>_ echo $version
3.1.2-1575-ga2ff32d90
>_ string match -rq '(?<major>\d+).(?<minor>\d+).(?<revision>\d+)' -- $version
>_ echo "You are using fish $major!"
You are using fish 3!
>_ string match -raq ' *(?<sentence>[^.!?]+)(?<punctuation>[.!?])?' "hello, friend. goodbye"
>_ printf "%s\n" -- $sentence
hello, friend
goodbye
>_ printf "%s\n" -- $punctuation
.
>_ string match -rq '(?<word>hello)' 'hi'
>_ count $word
0
string-pad - pad strings to a fixed width
Synopsis
string pad [-r | --right] [-C | --center] [(-c | --char) CHAR] [(-w | --width) INTEGER]
[STRING ...]
Description
string pad extends each STRING to the given visible width by adding CHAR to
the left. That means the width of all visible characters added together,
excluding escape sequences and accounting for fish_emoji_width and
fish_ambiguous_width. It is the amount of columns in a terminal the STRING
occupies.
The escape sequences reflect what fish knows about, and how it computes its
output. Your terminal might support more escapes, or not support escape se-
quences that fish knows about.
If -C or --center is given, add the padding to before and after the string.
If it is impossible to perfectly center the result (because the required
amount of padding is an odd number), extra padding will be added to the
left, unless --right is also given.
If -r or --right is given, add the padding after a string.
If -c or --char is given, pad with CHAR instead of whitespace.
The output is padded to the maximum width of all input strings. If -w or
--width is given, use at least that.
Examples
>_ string pad -w 10 abc abcdef
abc
abcdef
>_ string pad --right --char=dh "fish are pretty" "rich. "
fish are pretty
rich. dhdhdhdh
>_ string pad -w$COLUMNS (date)
# Prints the current time on the right edge of the screen.
See Also
* The printf command can do simple padding, for example printf %10s\n works
like string pad -w10.
* string length with the --visible option can be used to show what fish
thinks the width is.
string-repeat - multiply a string
Synopsis
string repeat [(-n | --count) COUNT] [(-m | --max) MAX] [-N | --no-newline]
[-q | --quiet] [STRING ...]
string repeat [-N | --no-newline] [-q | --quiet] COUNT [STRING ...]
Description
string repeat repeats the STRING -n or --count times. The -m or --max op-
tion will limit the number of outputted characters (excluding the newline).
This option can be used by itself or in conjunction with --count. If both
--count and --max are present, max char will be outputted unless the final
repeated string size is less than max, in that case, the string will repeat
until count has been reached. Both --count and --max will accept a number
greater than or equal to zero, in the case of zero, nothing will be out-
putted. The first argument is interpreted as COUNT if --count or --max are
not explicitly specified. If -N or --no-newline is given, the output won't
contain a newline character at the end. Exit status: 0 if yielded string is
not empty, 1 otherwise.
Examples
Repeat Examples
>_ string repeat -n 2 'foo '
foo foo
>_ echo foo | string repeat -n 2
foofoo
>_ string repeat -n 2 -m 5 'foo'
foofo
>_ string repeat -m 5 'foo'
foofo
>_ string repeat 2 'foo'
foofoo
>_ string repeat 2 -n 3
222
string-replace - replace substrings
Synopsis
string replace [-a | --all] [-f | --filter] [-i | --ignore-case]
[-r | --regex] [(-m | --max-matches) MAX] [-q | --quiet]
PATTERN REPLACEMENT [STRING ...]
Description
string replace is similar to string match but replaces non-overlapping
matching substrings with a replacement string and prints the result. By de-
fault, PATTERN is treated as a literal substring to be matched.
If -r or --regex is given, PATTERN is interpreted as a Perl-compatible reg-
ular expression, and REPLACEMENT can contain C-style escape sequences like
t as well as references to capturing groups by number or name as $n or
${n}.
If you specify the -f or --filter flag then each input string is printed
only if a replacement was done. This is useful where you would otherwise
use this idiom: a_cmd | string match pattern | string replace pattern
new_pattern. You can instead just write a_cmd | string replace --filter
pattern new_pattern.
If --max-matches MAX or -m MAX is used, string replace will stop all pro-
cessing after MAX lines of input have matched the specified pattern. In the
event of --filter or -f, this means the output will be MAX lines in length.
This can be used as an "early exit" optimization when processing long in-
puts but expecting a limited and fixed number of outputs that might be
found considerably before the input stream has been exhausted.
Exit status: 0 if at least one replacement was performed, or 1 otherwise.
Examples
Replace Literal Examples
>_ string replace is was 'blue is my favorite'
blue was my favorite
>_ string replace 3rd last 1st 2nd 3rd
1st
2nd
last
>_ string replace -a ' ' _ 'spaces to underscores'
spaces_to_underscores
Replace Regex Examples
>_ string replace -r -a '[^\d.]+' ' ' '0 one two 3.14 four 5x'
0 3.14 5
>_ string replace -r '(\w+)\s+(\w+)' '$2 $1 $$' 'left right'
right left $
>_ string replace -r '\s*newline\s*' '\n' 'put a newline here'
put a
here
string-shorten - shorten strings to a width, with an ellipsis
Synopsis
string shorten [(-c | --char) CHARS] [(-m | --max) INTEGER]
[-N | --no-newline] [-l | --left] [-q | --quiet] [STRING ...]
Description
string shorten truncates each STRING to the given visible width and adds an
ellipsis to indicate it. "Visible width" means the width of all visible
characters added together, excluding escape sequences and accounting for
fish_emoji_width and fish_ambiguous_width. It is the amount of columns in a
terminal the STRING occupies.
The escape sequences reflect what fish knows about, and how it computes its
output. Your terminal might support more escapes, or not support escape se-
quences that fish knows about.
If -m or --max is given, truncate at the given width. Otherwise, the lowest
non-zero width of all input strings is used. A max of 0 means no shortening
takes place, all STRINGs are printed as-is.
If -N or --no-newline is given, only the first line (or last line with
--left) of each STRING is used, and an ellipsis is added if it was multi-
line. This only works for STRINGs being given as arguments, multiple lines
given on stdin will be interpreted as separate STRINGs instead.
If -c or --char is given, add CHAR instead of an ellipsis. This can also be
empty or more than one character.
If -l or --left is given, remove text from the left on instead, so this
prints the longest suffix of the string that fits. With --no-newline, this
will take from the last line instead of the first.
If -q or --quiet is given, string shorten only runs for the return value -
if anything would be shortened, it returns 0, else 1.
The default ellipsis is ^a|. If fish thinks your system is incapable because
of your locale, it will use ... instead.
The return value is 0 if any shortening occurred, 1 otherwise.
Examples
>_ string shorten foo foobar
# No width was given, we infer, and "foo" is the shortest.
foo
foa|
>_ string shorten --char="..." foo foobar
# The target width is 3 because of "foo",
# and our ellipsis is 3 too, so we can't really show anything.
# This is the default ellipsis if your locale doesn't allow "a|".
foo
...
>_ string shorten --char="" --max 4 abcdef 123456
# Leaving the char empty makes us not add an ellipsis
# So this truncates at 4 columns:
abcd
1234
>_ touch "a multiline"\n"file"
>_ for file in *; string shorten -N -- $file; end
# Shorten the multiline file so we only show one line per file:
a multilinea|
>_ ss -p | string shorten -m$COLUMNS -c ""
# `ss` from Linux' iproute2 shows socket information, but prints extremely long lines.
# This shortens input so it fits on the screen without overflowing lines.
>_ git branch | string match -rg '^\* (.*)' | string shorten -m20
# Take the current git branch and shorten it at 20 columns.
# Here the branch is "builtin-path-with-expand"
builtin-path-with-ea|
>_ git branch | string match -rg '^\* (.*)' | string shorten -m20 --left
# Taking 20 columns from the right instead:
a|in-path-with-expand
See Also
* string pad does the inverse of this command, adding padding to a specific
width instead.
* The printf command can do simple padding, for example printf %10s\n works
like string pad -w10.
* string length with the --visible option can be used to show what fish
thinks the width is.
string-split - split strings by delimiter
Synopsis
string split [(-f | --fields) FIELDS [-a | --allow-empty]] [(-m | --max) MAX] [-n | --no-empty]
[-q | --quiet] [-r | --right] SEP [STRING ...]
string split0 [(-f | --fields) FIELDS [-a | --allow-empty]] [(-m | --max) MAX] [-n | --no-empty]
[-q | --quiet] [-r | --right] [STRING ...]
Description
string split splits each STRING on the separator SEP, which can be an empty
string. If -m or --max is specified, at most MAX splits are done on each
STRING. If -r or --right is given, splitting is performed right-to-left.
This is only useful in combination with -m or --max. With -n or --no-empty,
empty results are excluded from consideration (e.g. hello\n\nworld would
expand to two strings and not three). Exit status: 0 if at least one split
was performed, or 1 otherwise.
Use -f or --fields to print out specific fields. FIELDS is a comma-sepa-
rated string of field numbers and/or spans. Each field is one-indexed, and
will be printed on separate lines. If a given field does not exist, then
the command exits with status 1 and does not print anything, unless --al-
low-empty is used.
See also the --delimiter option of the read command.
string split0 splits each STRING on the zero byte (NUL). Options are the
same as string split except that no separator is given.
split0 has the important property that its output is not further split when
used in a command substitution, allowing for the command substitution to
produce elements containing newlines. This is most useful when used with
Unix tools that produce zero bytes, such as find -print0 or sort -z. See
split0 examples below.
Be aware that commandline arguments cannot include NULs, so you likely want
to pass to string split0 via a pipe, not a command substitution.
Examples
>_ string split . example.com
example
com
>_ string split -r -m1 / /usr/local/bin/fish
/usr/local/bin
fish
>_ string split '' abc
a
b
c
>_ string split --allow-empty -f1,3-4,5 '' abcd
a
c
d
NUL Delimited Examples
>_ # Count files in a directory, without being confused by newlines.
>_ # Note: Don't use `string split0 (find . -print0)`, because arguments cannot include NUL.
>_ count (find . -print0 | string split0)
42
>_ # Sort a list of elements which may contain newlines
>_ set foo beta alpha\ngamma
>_ set foo (string join0 $foo | sort -z | string split0)
>_ string escape $foo[1]
alpha\ngamma
string-split0 - split on zero bytes
Synopsis
string split [(-f | --fields) FIELDS [-a | --allow-empty]] [(-m | --max) MAX] [-n | --no-empty]
[-q | --quiet] [-r | --right] SEP [STRING ...]
string split0 [(-f | --fields) FIELDS [-a | --allow-empty]] [(-m | --max) MAX] [-n | --no-empty]
[-q | --quiet] [-r | --right] [STRING ...]
Description
string split splits each STRING on the separator SEP, which can be an empty
string. If -m or --max is specified, at most MAX splits are done on each
STRING. If -r or --right is given, splitting is performed right-to-left.
This is only useful in combination with -m or --max. With -n or --no-empty,
empty results are excluded from consideration (e.g. hello\n\nworld would
expand to two strings and not three). Exit status: 0 if at least one split
was performed, or 1 otherwise.
Use -f or --fields to print out specific fields. FIELDS is a comma-sepa-
rated string of field numbers and/or spans. Each field is one-indexed, and
will be printed on separate lines. If a given field does not exist, then
the command exits with status 1 and does not print anything, unless --al-
low-empty is used.
See also the --delimiter option of the read command.
string split0 splits each STRING on the zero byte (NUL). Options are the
same as string split except that no separator is given.
split0 has the important property that its output is not further split when
used in a command substitution, allowing for the command substitution to
produce elements containing newlines. This is most useful when used with
Unix tools that produce zero bytes, such as find -print0 or sort -z. See
split0 examples below.
Be aware that commandline arguments cannot include NULs, so you likely want
to pass to string split0 via a pipe, not a command substitution.
Examples
>_ string split . example.com
example
com
>_ string split -r -m1 / /usr/local/bin/fish
/usr/local/bin
fish
>_ string split '' abc
a
b
c
>_ string split --allow-empty -f1,3-4,5 '' abcd
a
c
d
NUL Delimited Examples
>_ # Count files in a directory, without being confused by newlines.
>_ # Note: Don't use `string split0 (find . -print0)`, because arguments cannot include NUL.
>_ count (find . -print0 | string split0)
42
>_ # Sort a list of elements which may contain newlines
>_ set foo beta alpha\ngamma
>_ set foo (string join0 $foo | sort -z | string split0)
>_ string escape $foo[1]
alpha\ngamma
string-sub - extract substrings
Synopsis
string sub [(-s | --start) START] [(-e | --end) END] [(-l | --length) LENGTH]
[-q | --quiet] [STRING ...]
Description
string sub prints a substring of each string argument. The start/end of the
substring can be specified with -s/-e or --start/--end followed by a
1-based index value. Positive index values are relative to the start of the
string and negative index values are relative to the end of the string. The
default start value is 1. The length of the substring can be specified with
-l or --length. If the length or end is not specified, the substring con-
tinues to the end of each STRING. Exit status: 0 if at least one substring
operation was performed, 1 otherwise. --length is mutually exclusive with
--end.
Examples
>_ string sub --length 2 abcde
ab
>_ string sub -s 2 -l 2 abcde
bc
>_ string sub --start=-2 abcde
de
>_ string sub --end=3 abcde
abc
>_ string sub -e -1 abcde
abcd
>_ string sub -s 2 -e -1 abcde
bcd
>_ string sub -s -3 -e -2 abcde
c
string-trim - remove trailing whitespace
Synopsis
string trim [-l | --left] [-r | --right] [(-c | --chars) CHARS]
[-q | --quiet] [STRING ...]
Description
string trim removes leading and trailing whitespace from each STRING. If -l
or --left is given, only leading whitespace is removed. If -r or --right is
given, only trailing whitespace is trimmed.
The -c or --chars switch causes the set of characters in CHARS to be re-
moved instead of whitespace. This is a set of characters, not a string - if
you pass -c foo, it will remove any "f" or "o", not just "foo" as a whole.
Exit status: 0 if at least one character was trimmed, or 1 otherwise.
Examples
>_ string trim ' abc '
abc
>_ string trim --right --chars=yz xyzzy zany
x
zan
string-unescape - expand escape sequences
Synopsis
string escape [-n | --no-quoted] [--style=] [STRING ...]
string unescape [--style=] [STRING ...]
Description
string escape escapes each STRING in one of several ways.
--style=script (default) alters the string such that it can be passed back
to eval to produce the original argument again. By default, all special
characters are escaped, and quotes are used to simplify the output when
possible. If -n or --no-quoted is given, the simplifying quoted format is
not used. Exit status: 0 if at least one string was escaped, or 1 other-
wise.
--style=var ensures the string can be used as a variable name by hex encod-
ing any non-alphanumeric characters. The string is first converted to UTF-8
before being encoded.
--style=url ensures the string can be used as a URL by hex encoding any
character which is not legal in a URL. The string is first converted to
UTF-8 before being encoded.
--style=regex escapes an input string for literal matching within a regex
expression. The string is first converted to UTF-8 before being encoded.
string unescape performs the inverse of the string escape command. If the
string to be unescaped is not properly formatted it is ignored. For exam-
ple, doing string unescape --style=var (string escape --style=var $str)
will return the original string. There is no support for unescaping
--style=regex.
Examples
>_ echo \x07 | string escape
\cg
>_ string escape --style=var 'a1 b2'\u6161
a1_20_b2_E6_85_A1_
string-upper - convert strings to uppercase
Synopsis
string upper [-q | --quiet] [STRING ...]
Description
string upper converts each string argument to uppercase. Exit status: 0 if
at least one string was converted to uppercase, else 1. This means that in
conjunction with the -q flag you can readily test whether a string is al-
ready uppercase.
suspend - suspend the current shell
Synopsis
suspend [--force]
Description
suspend suspends execution of the current shell by sending it a SIGTSTP
signal, returning to the controlling process. It can be resumed later by
sending it a SIGCONT. In order to prevent suspending a shell that doesn't
have a controlling process, it will not suspend the shell if it is a login
shell. This requirement is bypassed if the --force option is given or the
shell is not interactive.
switch - conditionally execute a block of commands
Synopsis
switch VALUE; [case [GLOB ...]; [COMMANDS ...]; ...] end
Description
switch performs one of several blocks of commands, depending on whether a
specified value equals one of several globbed values. case is used together
with the switch statement in order to determine which block should be exe-
cuted.
Each case command is given one or more parameters. The first case command
with a parameter that matches the string specified in the switch command
will be evaluated. case parameters may contain globs. These need to be es-
caped or quoted in order to avoid regular glob expansion using filenames.
Note that fish does not fall through on case statements. Only the first
matching case is executed.
Note that break cannot be used to exit a case/switch block early like in
other languages. It can only be used in loops.
Note that command substitutions in a case statement will be evaluated even
if its body is not taken. All substitutions, including command substitu-
tions, must be performed before the value can be compared against the para-
meter.
Example
If the variable $animal contains the name of an animal, the following code
would attempt to classify it:
switch $animal
case cat
echo evil
case wolf dog human moose dolphin whale
echo mammal
case duck goose albatross
echo bird
case shark trout stingray
echo fish
case '*'
echo I have no idea what a $animal is
end
If the above code was run with $animal set to whale, the output would be
mammal.
test - perform tests on files and text
Synopsis
test [EXPRESSION]
[ [EXPRESSION] ]
Description
NOTE: This page documents the fish builtin test. To see the documentation
on any non-fish versions, use command man test.
test checks the given conditions and sets the exit status to 0 if they are
true, 1 if they are false.
The first form (test) is preferred. For compatibility with other shells,
the second form is available: a matching pair of square brackets ([ [EX-
PRESSION] ]).
When using a variable or command substitution as an argument with test you
should almost always enclose it in double-quotes, as variables expanding to
zero or more than one argument will most likely interact badly with test.
WARNING:
For historical reasons, test supports the one-argument form (test foo),
and this will also be triggered by e.g. test -n $foo if $foo is unset.
We recommend you don't use the one-argument form and quote all variables
or command substitutions used with test.
This confusing misfeature will be removed in future. test -n without any
additional argument will be false, test -z will be true and any other
invocation with exactly one or zero arguments, including test -d and
test "foo" will be an error.
The same goes for [, e.g. [ "foo" ] and [ -d ] will be errors.
This can be turned on already via the test-require-arg feature flag, and
will eventually become the default and then only option.
Operators for files and directories
-b FILE
Returns true if FILE is a block device.
-c FILE
Returns true if FILE is a character device.
-d FILE
Returns true if FILE is a directory.
-e FILE
Returns true if FILE exists.
-f FILE
Returns true if FILE is a regular file.
-g FILE
Returns true if FILE has the set-group-ID bit set.
-G FILE
Returns true if FILE exists and has the same group ID as the current
user.
-k FILE
Returns true if FILE has the sticky bit set. If the OS does not sup-
port the concept it returns false. See -
https://en.wikipedia.org/wiki/Sticky_bit.
-L FILE
Returns true if FILE is a symbolic link.
-O FILE
Returns true if FILE exists and is owned by the current user.
-p FILE
Returns true if FILE is a named pipe.
-r FILE
Returns true if FILE is marked as readable.
-s FILE
Returns true if the size of FILE is greater than zero.
-S FILE
Returns true if FILE is a socket.
-t FD Returns true if the file descriptor FD is a terminal (TTY).
-u FILE
Returns true if FILE has the set-user-ID bit set.
-w FILE
Returns true if FILE is marked as writable; note that this does not
check if the filesystem is read-only.
-x FILE
Returns true if FILE is marked as executable.
Operators to compare files and directories
FILE1 -nt FILE2
Returns true if FILE1 is newer than FILE2, or FILE1 exists and FILE2
does not.
FILE1 -ot FILE2
Returns true if FILE1 is older than FILE2, or FILE2 exists and FILE1
does not.
FILE1 -ef FILE1
Returns true if FILE1 and FILE2 refer to the same file.
Operators for text strings
STRING1 = STRING2
Returns true if the strings STRING1 and STRING2 are identical.
STRING1 != STRING2
Returns true if the strings STRING1 and STRING2 are not identical.
-n STRING
Returns true if the length of STRING is non-zero.
-z STRING
Returns true if the length of STRING is zero.
Operators to compare and examine numbers
NUM1 -eq NUM2
Returns true if NUM1 and NUM2 are numerically equal.
NUM1 -ne NUM2
Returns true if NUM1 and NUM2 are not numerically equal.
NUM1 -gt NUM2
Returns true if NUM1 is greater than NUM2.
NUM1 -ge NUM2
Returns true if NUM1 is greater than or equal to NUM2.
NUM1 -lt NUM2
Returns true if NUM1 is less than NUM2.
NUM1 -le NUM2
Returns true if NUM1 is less than or equal to NUM2.
Both integers and floating point numbers are supported.
Operators to combine expressions
COND1 -a COND2
Returns true if both COND1 and COND2 are true.
COND1 -o COND2
Returns true if either COND1 or COND2 are true.
Expressions can be inverted using the ! operator:
! EXPRESSION
Returns true if EXPRESSION is false, and false if EXPRESSION is
true.
Expressions can be grouped using parentheses.
( EXPRESSION )
Returns the value of EXPRESSION.
Note that parentheses will usually require escaping with \ (so they appear
as \( and \)) to avoid being interpreted as a command substitution.
Examples
If the /tmp directory exists, copy the /etc/motd file to it:
if test -d /tmp
cp /etc/motd /tmp/motd
end
If the variable MANPATH is defined and not empty, print the contents. (If
MANPATH is not defined, then it will expand to zero arguments, unless
quoted.)
if test -n "$MANPATH"
echo $MANPATH
end
Be careful with unquoted variables:
if test -n $MANPATH
# This will also be reached if $MANPATH is unset,
# because in that case we have `test -n`, so it checks if "-n" is non-empty, and it is.
echo $MANPATH
end
This will change in a future release of fish, or already with the test-re-
quire-arg feature flag - if $MANPATH is unset, if test -n $MANPATH will be
false.
Parentheses and the -o and -a operators can be combined to produce more
complicated expressions. In this example, success is printed if there is a
/foo or /bar file as well as a /baz or /bat file.
if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \)
echo Success.
end
Numerical comparisons will fail if one of the operands is not a number:
if test 42 -eq "The answer to life, the universe and everything"
echo So long and thanks for all the fish # will not be executed
end
A common comparison is with status:
if test $status -eq 0
echo "Previous command succeeded"
end
The previous test can likewise be inverted:
if test ! $status -eq 0
echo "Previous command failed"
end
which is logically equivalent to the following:
if test $status -ne 0
echo "Previous command failed"
end
Standards
Unlike many things in fish, test implements a subset of the IEEE Std
1003.1-2008 (POSIX.1) standard <https://pubs.opengroup.org/on-
linepubs/9699919799/utilities/test.html>. The following exceptions apply:
* The < and > operators for comparing strings are not implemented.
* With test-require-arg, the zero- and one-argument modes will behave dif-
ferently.
In cases such as this, one can use command test to explicitly use the
system's standalone test rather than this builtin test.
See also
Other commands that may be useful as a condition, and are often easier to
use:
* string - manipulate strings, which can do string operations including
wildcard and regular expression matching
* path - manipulate and check paths, which can do file checks and opera-
tions, including filters on multiple paths at once
time - measure how long a command or block takes
Synopsis
time COMMAND
Description
NOTE: This page documents the fish keyword time. To see the documentation
on any non-fish versions, use command man time.
time causes fish to measure how long a command takes and print the results
afterwards. The command can be a simple fish command or a block. The re-
sults can not currently be redirected.
For checking timing after a command has completed, check $CMD_DURATION.
Your system most likely also has a time command. To use that use something
like command time, as in command time sleep 10. Because it's not inside
fish, it won't have access to fish functions and won't be able to time
blocks and such.
How to interpret the output
Time outputs a few different values. Let's look at an example:
> time string repeat -n 10000000 y\n | command grep y >/dev/null
________________________________________________________
Executed in 805.98 millis fish external
usr time 798.88 millis 763.88 millis 34.99 millis
sys time 141.22 millis 40.20 millis 101.02 millis
The time after "Executed in" is what is known as the "wall-clock time". It
is simply a measure of how long it took from the start of the command until
it finished. Typically it is reasonably close to CMD_DURATION, except for a
slight skew because the two are taken at slightly different times.
The other times are all measures of CPU time. That means they measure how
long the CPU was used in this part, and they count multiple cores sepa-
rately. So a program with four threads using all CPU for a second will have
a time of 4 seconds.
The "usr" time is how much CPU time was spent inside the program itself,
the "sys" time is how long was spent in the kernel on behalf of that pro-
gram.
The "fish" time is how much CPU was spent in fish, the "external" time how
much was spent in external commands.
So in this example, since string is a builtin, everything that string re-
peat did is accounted to fish. Any time it spends doing syscalls like
write() is accounted for in the fish/sys time.
And grep here is explicitly invoked as an external command, so its times
will be counted in the "external" column.
Note that, as in this example, the CPU times can add up to more than the
execution time. This is because things can be done in parallel - grep can
match while string repeat writes.
Example
(for obvious reasons exact results will vary on your system)
>_ time sleep 1s
________________________________________________________
Executed in 1,01 secs fish external
usr time 2,32 millis 0,00 micros 2,32 millis
sys time 0,88 millis 877,00 micros 0,00 millis
>_ time for i in 1 2 3; sleep 1s; end
________________________________________________________
Executed in 3,01 secs fish external
usr time 9,16 millis 2,94 millis 6,23 millis
sys time 0,23 millis 0,00 millis 0,23 millis
Inline variable assignments need to follow the time keyword:
>_ time a_moment=1.5m sleep $a_moment
________________________________________________________
Executed in 90.00 secs fish external
usr time 4.62 millis 4.62 millis 0.00 millis
sys time 2.35 millis 0.41 millis 1.95 millis
trap - perform an action when the shell receives a signal
Synopsis
trap [OPTIONS] [[ARG] REASON ... ]
Description
NOTE: This page documents the fish builtin trap. To see the documentation
on any non-fish versions, use command man trap.
trap is a wrapper around the fish event delivery framework. It exists for
backwards compatibility with POSIX shells. For other uses, it is recom-
mended to define an event handler.
The following parameters are available:
ARG Command to be executed on signal delivery.
REASON
Name of the event to trap. For example, a signal like INT or SIGINT,
or the special symbol EXIT.
-l or --list-signals
Prints a list of signal names.
-p or --print
Prints all defined signal handlers.
-h or --help
Displays help about using this command.
If ARG and REASON are both specified, ARG is the command to be executed
when the event specified by REASON occurs (e.g., the signal is delivered).
If ARG is absent (and there is a single REASON) or -, each specified signal
is reset to its original disposition (the value it had upon entrance to the
shell). If ARG is the null string the signal specified by each REASON is
ignored by the shell and by the commands it invokes.
If ARG is not present and -p has been supplied, then the trap commands as-
sociated with each REASON are displayed. If no arguments are supplied or if
only -p is given, trap prints the list of commands associated with each
signal.
Signal names are case insensitive and the SIG prefix is optional. Trapping
a signal will prevent fish from exiting in response to that signal.
The exit status is 1 if any REASON is invalid; otherwise trap returns 0.
Example
trap "status --print-stack-trace" SIGUSR1
# Prints a stack trace each time the SIGUSR1 signal is sent to the shell.
true - return a successful result
Synopsis
true
Description
true sets the exit status to 0.
: (a single colon) is an alias for the true command.
See Also
* false command
* $status variable
type - locate a command and describe its type
Synopsis
type [OPTIONS] NAME [...]
Description
NOTE: This page documents the fish builtin type. To see the documentation
on any non-fish versions, use command man type.
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
Don't print function definitions when used with no options or with
-a/--all.
-f or --no-functions
Suppresses function 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 func-
tion NAME if NAME resolves to a function loaded from a file on disk
(i.e. not interactively defined at the prompt), or nothing other-
wise.
-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 status.
For compatibility with old fish versions this is also --quiet.
--color WHEN
Controls when to use syntax highlighting colors when printing func-
tion definitions. WHEN can be auto (the default, colorize if the
output is a terminal), always, or never.
-h or --help
Displays help about using this command.
The -q, -p, -t and -P flags (and their long flag aliases) are mutually ex-
clusive. Only one can be specified at a time.
type returns 0 if at least one entry was found, 1 otherwise, and 2 for in-
valid 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 subtracted
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; con-
sult the documentation for setrlimit in your operating system.
The value of limit can be a number in the unit specified for the resource
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 op-
tion 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 sta-
tus is 0 unless an invalid option or argument is supplied, or an error oc-
curs 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 increased;
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 as-
signing 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 imple-
mentation 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 empirically
guesses this number by writing to a pipe and waiting for SIGPIPE. Fish
does not do this because this method of determining pipe size is unreli-
able. Depending on bash version, there may also be further 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
NOTE: This page documents the fish builtin umask. To see the documentation
on any non-fish versions, use command man umask.
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 represents
the only rights that will be granted by default.
Access rights are explained in the manual page for the chmod(1) program.
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 variable.
Array variables as a whole can not be edited using vared, but individual
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
NOTE: This page documents the fish builtin wait. To see the documentation
on any non-fish versions, use command man wait.
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 com-
plete.
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 fin-
ish.
for i in (seq 1 5); sleep 10 &; end
hoge &
wait sleep
spawns five sleep jobs and hoge in the background, and then waits until all
sleeps finish, and doesn't wait for hoge.
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 exe-
cutes COMMANDS.
The exit status of the while loop is the exit status of the last iteration
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 dif-
ferences.
Command substitutions
Fish spells command substitutions as $(command) or (command), but not `com-
mand`.
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 col-
lect. If those are used as the last command in a command substitution 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 variety 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 vari-
able expands to all its elements, with each element as its own argument
(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 er-
ror.
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 envi-
ronment 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.
The ** glob will match in subdirectories as well. In other shells this of-
ten needs to be turned on with an option, like setopt globstar in bash.
Unlike bash, fish will also follow symlinks, and will sort the results in a
natural sort, with included numbers compared as numbers. That means it will
sort e.g. music tracks correctly even if they have numbers like 1 instead
of 01.
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 transformed
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 equivalent 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)
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
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 minor syntactical sugar that introduces a lot of
special rules, which is why fish doesn't have them. Pipes are a core con-
cept, 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 termina-
tor 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 num-
ber of elements (set -q foo[2]).
Arithmetic Expansion
Fish does not have $((i+1)) arithmetic expansion, computation is handled 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. Because
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. The output of the fish_right_prompt function is used
for the right-sided 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 --reset)
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 a function. To achieve the effect of \h, fish provides 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
Fish does not currently have subshells. You will have to find a different
solution. The isolation can usually be achieved by scoping variables (with
set -l), but if you really do need to run your code in a new shell environ-
ment you can use fish -c 'your code here' to do so explicitly.
() subshells are often confused with {} grouping, which does not use a sub-
shell. 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 be run in the same process, so while read loops can set vari-
ables 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 $(command) or
(command). Bash also uses subshells to implement them.
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 interac-
tive 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 exe-
cuted. 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 high-
lighting, 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 op-
tions, 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. You can customize it, see how to
change your prompt.
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.
This only works for fish's own documentation for itself and its built-in
commands (the "builtins"). For any other commands on your system, they
should provide their own documentation, often in the man system. For exam-
ple man ls should tell you about your computer'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.
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 typ-
ing a few letters:
> rsync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo
To accept the autosuggestion, hit right (^a) or ctrl-f. To accept a single
word of the autosuggestion, alt-right (^a). 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 parentheses
there (that "command" and "directory") is the completion description. 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 replaced
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 sepa-
rate arguments, and $name would have been made into a list of two ele-
ments.)
Unlike other shells, variables are not further split after substitution:
> mkdir $name
> ls
Mister Noodle
In bash, this would have created two directories "Mister" and "Noodle". In
fish, it created only one: the variable had the value "Mister Noodle", so
that is the argument that was passed to mkdir, spaces and all.
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, of-
ten 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 ALL-
CAPS, 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 something
else, it inherits that parents exported variables. So if your terminal emu-
lator starts fish, and it exports $LANG set to en_US.UTF-8, fish will re-
ceive that setting. And whatever started your terminal emulator also gave
it some variables that it will then pass on unless it specifically decides
not to. This is how fish usually receives the values for things like $LANG,
$PATH and $TERM, without you having to specify 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 ar-
gument. 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 con-
tain 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 vari-
able 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 subcommands.
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
One particular bit is that you can use lists like Brace expansion. If you
attach another string to a list, it'll combine every element of the list
with the string:
> set mydirs /usr/bin /bin
> echo $mydirs/fish # this is just like {/usr/bin,/bin}/fish
/usr/bin/fish /bin/fish
This also means that, if the list is empty, there will be no argument:
> set empty # no argument
> echo $empty/this_is_gone # prints an empty line
If you quote the list, it will be used as one string and so you'll get one
argument even if it is empty.
For more, see Lists. For more on combining lists with strings (or even
other lists), see cartesian products and Variable expansion.
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 ctrl-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.
Command Substitutions
Command substitutions use the output of one command as an argument to an-
other. Unlike other shells, fish does not use backticks `` for command sub-
stitutions. Instead, it uses parentheses with or without a dollar:
> 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 mul-
tiple 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 integer
(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 usu-
ally returns 0, set --query arglbargl boogagoogoo usually 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 "statA<<s" 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 succeed.
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 ex-
ists 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 arguments
or (quoted) wildcards.
For more, see Conditions.
Functions
A fish function is a list of commands, which may optionally take arguments.
Unlike other shells, arguments are not passed in "numbered variables" like
$1, but instead in a single list $argv. To create a function, 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 syntax.
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 functions:
> 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 command.
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 funcsave
fish_prompt. This saves the prompt in ~/.config/fish/func-
tions/fish_prompt.fish. (Or, if you want, you can create that file manually
from the start.)
Multiple lines are OK. Colors can be set via set_color by passing it named
ANSI colors, or hex RGB values:
function fish_prompt
set_color purple
date "+%m/%d/%y"
set_color FF0000
echo (pwd) '>' (set_color --reset)
end
This prompt would look like:
02/06/13
/home/tutorial > _
See also Writing your own prompt.
You can choose among sample prompts by running fish_config for a web UI or
fish_config prompt for a simpler version inside your terminal.
$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 inher-
ited 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 direc-
tories to the path if they aren't already included. It does this by modify-
ing the $fish_user_paths universal variable, which is automatically
prepended to $PATH. For example, to permanently add /usr/local/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 config.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 de-
tails.
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 ~/.con-
fig/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 a even after a reboot. You can make
a variable universal with set -U:
> set -U EDITOR vim
Now in another shell:
> echo $EDITOR
vim
You only need to set universal variables once interactively. There is no
need to add them to your config files. For more details, see Universal
Variables.
Ready for more?
If you want to learn more about fish, there is lots of detailed documenta-
tion, the official gitter channel <https://gitter.im/fish-shell/fish-
shell>, an official mailing list <https://lists.source-
forge.net/lists/listinfo/fish-users>, and the github page
<https://github.com/fish-shell/fish-shell/>.
Writing your own completions
To specify a completion, use the complete command. complete takes as a pa-
rameter the name of the command to specify a completion for. For example,
to add a completion for the program myprog (or myprog.exe on Cygwin/MSYS2),
start the completion command with complete -c myprog ...
For a complete description of the various switches accepted by the complete
command, see the documentation for the complete builtin, or write complete
--help inside the fish shell.
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 com-
plete -c myprog -a 'start stop'. The argument to the -a switch is always a
single string. At completion time, it will be tokenized on spaces and tabs,
and variable expansion, command substitution and other forms of parameter
expansion will take place:
# If myprog can list the valid outputs with the list-outputs subcommand:
complete -c myprog -l output -a '(myprog list-outputs)'
fish has a special syntax to support specifying switches accepted by a com-
mand. 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 (with one -, like -shuffle), respectively. If the
command 'myprog' has an option that can be written as -o or --output, that
is:
complete -c myprog -s o -l output
If this option takes an optional argument, you would also add --argument or
-a, and give that the possible arguments:
complete -c myprog -s o -l output -a "yes no"
This offers the arguments "yes" and "no" for:
> myprog -o<TAB>
> myprog --output=<TAB>
By default, option arguments are optional, so the candidates are only of-
fered 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-parameter
/ -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>
Fish will also offer files by default, in addition to the arguments you
specified. 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 specific
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 comple-
tions 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_subcommand_from` helper function.
# It 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 com-
pletions 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 in-
terface may change in future fish versions. A few of these functions are
described here.
Functions beginning with the string __fish_print_ print a newline separated
list of strings. For example, __fish_print_filesystems prints a list of all
known file systems. Functions beginning with __fish_complete_ print out a
newline separated list of completions with descriptions. The description is
separated from the completion by a tab character.
* __fish_complete_directories STRING DESCRIPTION performs path completion
on STRING, allowing only directories, and giving them the description DE-
SCRIPTION.
* __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 command
name as description.
* __fish_complete_suffix SUFFIX performs file completion but sorts files
ending in SUFFIX first. This is useful in conjunction with complete
--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. Cur-
rently, this is a static list, and not dependent on what file systems the
host operating system actually understands.
* __fish_print_hostnames prints a list of all known hostnames. This func-
tion 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 interfaces.
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_complete_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 ~/.con-
fig/fish/completions (controlled by the XDG_CONFIG_HOME environment vari-
able);
* 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, usually
~/.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 comple-
tions for their software, usually /usr/share/fish/vendor_completions.d;
* The completions shipped with fish, usually installed in
/usr/share/fish/completions; and
* Completions automatically generated from the operating system's manual,
usually stored in ~/.cache/fish/generated_completions (controlled by
XDG_CACHE_HOME environment variable).
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 con-
sider 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 completions
with your program, install them to the "vendor" completions directory. 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 comple-
tionsdir 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 com-
mand, 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).
If the SHELL_PROMPT_PREFIX or SHELL_PROMPT_SUFFIX environment variables are
set, they are automatically prepended and appended to the left prompt.
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 signify a
redirection.
Because we've used echo, it adds spaces between the two so it ends up look-
ing 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 color
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 for-
matting 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 --reset) '>'
end
"--reset" tells the terminal to go back to its default formatting options.
set_color works by producing an escape sequence, which is a special piece
of text that terminals interpret as instructions - for example, to change
color. So set_color red produces the same effect as:
echo \e\[31m
Although you can write your own escape sequences by hand, it's much easier
to use set_color.
Shortening the working directory
This is fine, but our PWD can be a bit long, and we are typically only in-
terested 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 --reset) '>'
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 --reset) '>'
end
With a current directory of "/home/tutorial/Music/Lena Raine/Oneknowing",
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 is 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 --reset)
end
And to print it, we add it to our string join:
string join '' -- (set_color green) (prompt_pwd) (set_color --reset) $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 --reset)
end
string join '' -- (set_color green) (prompt_pwd) (set_color --reset) $stat '>'
end
And it looks like:
~/M/L/Oneknowing>false
~/M/L/Oneknowing[1]>_
after we run false (which returns 1).
Transient prompt
To enable transient prompt functionality, set the fish_transient_prompt
variable to 1:
set -g fish_transient_prompt 1
With this set, fish re-runs prompt functions with a --final-rendering argu-
ment before running a commandline. So you can use it to declutter your old
prompts. For example if you want to see only the current directory name
when you scroll up:
function fish_prompt
set -l last_status $status
set -l stat
set -l pwd
# Check if it's a transient or final prompt
if contains -- --final-rendering $argv
set pwd (path basename $PWD)
else
set pwd (prompt_pwd)
# Prompt status only if it's not 0
if test $last_status -ne 0
set stat (set_color red)"[$last_status]"(set_color --reset)
end
end
string join '' -- (set_color green) $pwd (set_color --reset) $stat '>'
end
Now running two commands in the same directory could result in this screen:
Oneknowing>false
~/M/L/Oneknowing[1]>_
Save the prompt
Once you are happy with your prompt, you can save it with funcsave
fish_prompt (see funcsave - save the definition of a function to the user's
autoload directory) or write it to ~/.config/fish/func-
tions/fish_prompt.fish yourself.
If you want to edit it again, open that file or use funced fish_prompt (see
funced - edit a function interactively).
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 de-
sign fish. The fish design has three high level goals. These are:
1. Everything that can be done in other shell languages should be possible
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 expressiveness.
Most tradeoffs between power and ease of use can be avoided with careful
design.
3. Whenever possible without breaking the above goals, fish should follow
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 sit-
uation 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 re-
lated. 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 draw-
backs 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 ac-
ceptable 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 in-
credibly 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 combi-
nations quickly becomes an issue. Configuration options often imply assump-
tions about the code which change when reimplementing the code, causing is-
sues with backwards compatibility. But mostly, configuration 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 de-
fault, 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, different
language substyles or any number of other common shell configuration op-
tions.
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 default.
Both zsh and bash support command-specific completions, but no such comple-
tions are shipped with bash by default, and they are turned off by default
in zsh. Other features that zsh supports that are disabled by default in-
clude tab-completion of strings containing wildcards, 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 intu-
itive 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 fea-
tures 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 commands.
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 functions
should have exactly the same types of argument expansion as other com-
mands, 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 program
is discoverability. In a graphical program, one can discover all the common
features by simply looking at the user interface and guessing what the dif-
ferent buttons, menus and other widgets do. The traditional way to discover
features in command-line programs is through manual pages. This requires
both that the user starts to use a different program, and then they remem-
ber 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 er-
ror message describing what went wrong and a relevant help page. Whenever
possible, errors should be flagged red by the syntax highlighter.
* 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 4.6.0 (released March 28, 2026)
Notable improvements and fixes
* New Spanish translations (#12489 <https://github.com/fish-shell/fish-
shell/issues/12489>).
* New Japanese translations (#12499 <https://github.com/fish-shell/fish-
shell/issues/12499>).
Deprecations and removed features
* The default width for emoji is switched from 1 to 2, improving the expe-
rience for users connecting to old systems from modern desktops. Users of
old desktops who notice that lines containing emoji are misaligned can
set $fish_emoji_width back to 1 (#12562 <https://github.com/fish-
shell/fish-shell/issues/12562>).
Interactive improvements
* The tab completion pager now left-justifies the description of each col-
umn (#12546 <https://github.com/fish-shell/fish-shell/issues/12546>).
* fish now supports the SHELL_PROMPT_PREFIX, SHELL_PROMPT_SUFFIX, and
SHELL_WELCOME environment variables. The prefix and suffix are automati-
cally prepended and appended to the left prompt, and the welcome message
is displayed on startup after the greeting. These variables are set by
systemd's run0 for example (#10924 <https://github.com/fish-shell/fish-
shell/issues/10924>).
Improved terminal support
* set_color is able to turn off italics, reverse mode, strikethrough and
underline individually (e.g. --italics=off).
* set_color learned the foreground (--foreground or -f) and reset (--reset)
options.
* An error caused by slow terminal responses at macOS startup has been ad-
dressed (#12571 <https://github.com/fish-shell/fish-shell/issues/12571>).
Other improvements
* Signals like SIGWINCH (as sent on terminal resize) no longer interrupt
builtin output (#12496 <https://github.com/fish-shell/fish-shell/is-
sues/12496>).
* For compatibility with Bash, fish now accepts |& as alternate spelling of
&|, for piping both standard output and standard error (#11516
<https://github.com/fish-shell/fish-shell/issues/11516>).
* fish_indent now preserves comments and newlines immediately preceding a
brace block ({ }) (#12505 <https://github.com/fish-shell/fish-shell/is-
sues/12505>).
* A crash when suspending certain pipelines with ctrl-z has been fixed (-
#12301 <https://github.com/fish-shell/fish-shell/issues/12301>).
For distributors and developers
* cargo xtask subcommands no longer panic on test failures.
Regression fixes:
* (from 4.5.0) Intermediate ^a artifact when redrawing prompt (#12476
<https://github.com/fish-shell/fish-shell/issues/12476>).
* (from 4.4.0) history honors explicitly specified --color= again (#12512
<https://github.com/fish-shell/fish-shell/issues/12512>).
* (from 4.4.0) Vi mode dl and dh (#12461 <https://github.com/fish-
shell/fish-shell/issues/12461>).
* (from 4.3.0) Error completing of commands starting with - (#12522
<https://github.com/fish-shell/fish-shell/issues/12522>).
fish 4.5.0 (released February 17, 2026)
This is mostly a patch release for Vi mode regressions in 4.4.0 but other
minor behavior changes are included as well.
Interactive improvements
* ctrl-l no longer cancels history search (#12436 <https://github.com/fish-
shell/fish-shell/issues/12436>).
* History search cursor positioning now works correctly with characters of
arbitrary width.
Deprecations and removed features
* fish no longer reads the terminfo database to alter behaviour based on
the TERM environment variable, and does not depend on ncurses or ter-
minfo. The ignore-terminfo feature flag, introduced and enabled by de-
fault in fish 4.1, is now permanently enabled. fish may no longer work
correctly on Data General Dasher D220 and Wyse WY-350 terminals, but
should continue to work on all known terminal emulators released in the
21st century.
Regression fixes:
* (from 4.4.0) Vi mode d,f key binding did not work (#12417
<https://github.com/fish-shell/fish-shell/issues/12417>).
* (from 4.4.0) Vi mode c,w key binding wrongly deleted trailing spaces (-
#12443 <https://github.com/fish-shell/fish-shell/issues/12443>).
* (from 4.4.0) Vi mode crash on c,i,w after accepting autosuggestion (-
#12430 <https://github.com/fish-shell/fish-shell/issues/12430>).
* (from 4.4.0) fish_vi_key_bindings called with a mode argument produced an
error (#12413 <https://github.com/fish-shell/fish-shell/issues/12413>).
* (from 4.0.0) Build on Illumos (#12410 <https://github.com/fish-
shell/fish-shell/issues/12410>).
fish 4.4.0 (released February 03, 2026)
Deprecations and removed features
* The default fossil prompt has been disabled (#12342
<https://github.com/fish-shell/fish-shell/issues/12342>).
Interactive improvements
* The bind builtin lists mappings from all modes if --mode is not provided
(#12214 <https://github.com/fish-shell/fish-shell/issues/12214>).
* Line-wise autosuggestions that don't start a command are no longer shown
(739b82c34db, 58e7a50de8a).
* Builtin history now assumes that PAGER supports ANSI color sequences.
* fish now clears the terminal's FLUSHO flag when acquiring control of the
terminal, to fix an issue caused by pressing ctrl-o on macOS (#12304
<https://github.com/fish-shell/fish-shell/issues/12304>).
New or improved bindings
* Vi mode word movements (w, W, e, and E) are now largely in line with Vim.
The only exception is that underscores are treated as word separators (-
#12269 <https://github.com/fish-shell/fish-shell/issues/12269>).
* New special input functions to support these movements: forward-word-vi,
kill-word-vi, forward-bigword-vi, kill-bigword-vi, forward-word-end,
backward-word-end, forward-bigword-end, backward-bigword-end,
kill-a-word, kill-inner-word, kill-a-bigword, and kill-inner-bigword.
* Vi mode key bindings now support counts for movement and deletion com-
mands (e.g. d3w or 3l), via a new operator mode (#2192
<https://github.com/fish-shell/fish-shell/issues/2192>).
* New catppuccin-* color themes.
Improved terminal support
* set_color learned the strikethrough (--strikethrough or -s) modifier.
For distributors and developers
* The CMake option WITH_GETTEXT has been renamed to WITH_MESSAGE_LOCALIZA-
TION, to reflect that it toggles localization independently of the back-
end used in the implementation.
* New cargo xtask commands can replace some CMake workflows.
Regression fixes:
* (from 4.1.0) Crash when autosuggesting Unicode characters with nontrivial
lowercase mapping (#12326 <https://github.com/fish-shell/fish-shell/is-
sues/12326>, 78f4541116e).
* (from 4.3.0) Glitch on read --prompt-str "" (#12296
<https://github.com/fish-shell/fish-shell/issues/12296>).
fish 4.3.3 (released January 07, 2026)
This release fixes the following problems identified in fish 4.3.0:
* Selecting a completion could insert only part of the token (#12249
<https://github.com/fish-shell/fish-shell/issues/12249>).
* Glitch with soft-wrapped autosuggestions and fish_right_prompt (#12255
<https://github.com/fish-shell/fish-shell/issues/12255>).
* Spurious echo in tmux when typing a command really fast (#12261
<https://github.com/fish-shell/fish-shell/issues/12261>).
* tomorrow theme always using the light variant (#12266
<https://github.com/fish-shell/fish-shell/issues/12266>).
* fish_config theme choose sometimes not shadowing themes set by e.g. web-
config (#12278 <https://github.com/fish-shell/fish-shell/issues/12278>).
* The sample prompts and themes are correctly installed (#12241
<https://github.com/fish-shell/fish-shell/issues/12241>).
* Last line of command output could be hidden when missing newline (#12246
<https://github.com/fish-shell/fish-shell/issues/12246>).
Other improvements include:
* The abbr, bind, complete, functions, history and type commands now sup-
port a --color option to control syntax highlighting in their output.
Valid values are auto (default), always, or never.
* Existing file paths in redirection targets such as > file.txt are now
highlighted using fish_color_valid_path, indicating that file.txt will be
clobbered (#12260 <https://github.com/fish-shell/fish-shell/is-
sues/12260>).
fish 4.3.2 (released December 30, 2025)
This release fixes the following problems identified in 4.3.0:
* Pre-built macOS packages failed to start due to a Malformed Mach-O file
error (#12224 <https://github.com/fish-shell/fish-shell/issues/12224>).
* extra_functionsdir (usually vendor_functions.d) and friends were not used
(#12226 <https://github.com/fish-shell/fish-shell/issues/12226>).
* Sample config file ~/.config/fish/config.fish/ and config directories
~/.config/fish/conf.d/, ~/.config/fish/completions/ and ~/.con-
fig/fish/functions/ were recreated on every startup instead of only the
first time fish runs on a system (#12230 <https://github.com/fish-
shell/fish-shell/issues/12230>).
* Spurious echo of ^[[I in some scenarios (#12232 <https://github.com/fish-
shell/fish-shell/issues/12232>).
* Infinite prompt redraw loop on some prompts (#12233
<https://github.com/fish-shell/fish-shell/issues/12233>).
* The removal of pre-built HTML docs from tarballs revealed that cross com-
pilation is broken because we use ${CMAKE_BINARY_DIR}/fish_indent for
building HTML docs. As a workaround, the new CMake build option FISH_IN-
DENT_FOR_BUILDING_DOCS can be set to the path of a runnable fish_indent
binary.
fish 4.3.1 (released December 28, 2025)
This release fixes the following problem identified in 4.3.0:
* Possible crash after expanding an abbreviation (#12223
<https://github.com/fish-shell/fish-shell/issues/12223>).
fish 4.3.0 (released December 28, 2025)
Deprecations and removed features
* fish no longer sets user-facing universal variables by default, making
the configuration easier to understand. Specifically, the fish_color_*,
fish_pager_color_* and fish_key_bindings variables are now set in the
global scope by default. After upgrading to 4.3.0, fish will (once and
never again) migrate these universals to globals set at startup in the
~/.config/fish/conf.d/fish_frozen_theme.fish and ~/.con-
fig/fish/conf.d/fish_frozen_key_bindings.fish files. We suggest that you
delete those files and set your theme in ~/.config/fish/config.fish.
* You can still configure fish to propagate theme changes instantly; see
here for an example.
* You can still opt into storing color variables in the universal scope
via fish_config theme save though unlike fish_config theme choose, it
does not support dynamic theme switching based on the terminal's color
theme (see below).
* In addition to setting the variables which are explicitly defined in the
given theme, fish_config theme choose now clears only color variables
that were set by earlier invocations of a fish_config theme choose com-
mand (which is how fish's default theme is set).
Scripting improvements
* New status language command allows showing and modifying language set-
tings for fish messages without having to modify environment variables.
* When using a noninteractive fish instance to compute completions, comman-
dline --cursor works as expected instead of throwing an error (#11993
<https://github.com/fish-shell/fish-shell/issues/11993>).
* fish_trace can now be set to all to also trace execution of key bindings,
event handlers as well as prompt and title functions.
Interactive improvements
* When typing immediately after starting fish, the first prompt is now ren-
dered correctly.
* Completion accuracy was improved for file paths containing = or : (#5363
<https://github.com/fish-shell/fish-shell/issues/5363>).
* Prefix-matching completions are now shown even if they don't match the
case typed by the user (#7944 <https://github.com/fish-shell/fish-
shell/issues/7944>).
* On Cygwin/MSYS, command name completion will favor the non-exe name (foo)
unless the user started typing the extension.
* When using the exe name (foo.exe), fish will use the description and com-
pletions for foo if there are none for foo.exe.
* Autosuggestions now also show soft-wrapped portions (#12045
<https://github.com/fish-shell/fish-shell/issues/12045>).
New or improved bindings
* ctrl-w (backward-kill-path-component) also deletes escaped spaces (#2016
<https://github.com/fish-shell/fish-shell/issues/2016>).
* New special input functions backward-path-component, forward-path-compo-
nent and kill-path-component (#12127 <https://github.com/fish-shell/fish-
shell/issues/12127>).
Improved terminal support
* Themes can now be made color-theme-aware by including both [light] and
[dark] sections in the theme file. Some default themes have been made
color-theme-aware, meaning they dynamically adjust as your terminal's
background color switches between light and dark colors (#11580
<https://github.com/fish-shell/fish-shell/issues/11580>).
* The working directory is now reported on every fresh prompt (via OSC 7),
fixing scenarios where a child process (like ssh) left behind a stale
working directory (#12191 <https://github.com/fish-shell/fish-shell/is-
sues/12191>).
* OSC 133 prompt markers now also mark the prompt end, which improves shell
integration with terminals like iTerm2 (#11837 <https://github.com/fish-
shell/fish-shell/issues/11837>).
* Operating-system-specific key bindings are now decided based on the
terminal's host OS.
* New feature flag omit-term-workarounds can be turned on to prevent fish
from trying to work around some incompatible terminals.
For distributors and developers
* Tarballs no longer contain prebuilt documentation, so building and in-
stalling documentation requires Sphinx. To avoid users accidentally los-
ing docs, the BUILD_DOCS and INSTALL_DOCS configuration options have been
replaced with a new WITH_DOCS option.
* fish_key_reader and fish_indent are now installed as hardlinks to fish,
to save some space.
Regression fixes:
* (from 4.1.0) Crash on incorrectly-set color variables (#12078
<https://github.com/fish-shell/fish-shell/issues/12078>).
* (from 4.1.0) Crash when autosuggesting Unicode characters with nontrivial
lowercase mapping.
* (from 4.2.0) Incorrect emoji width computation on macOS.
* (from 4.2.0) Mouse clicks and ctrl-l edge cases in multiline command
lines (#12121 <https://github.com/fish-shell/fish-shell/issues/12121>).
* (from 4.2.0) Completions for Git remote names on some non-glibc systems.
* (from 4.2.0) Expansion of ~$USER.
fish 4.2.1 (released November 13, 2025)
This release fixes the following problems identified in 4.2.0:
* When building from a tarball without Sphinx (that is, with
-DBUILD_DOCS=OFF or when sphinx-build is not found), builtin man pages
and help files were missing, which has been fixed (#12052
<https://github.com/fish-shell/fish-shell/issues/12052>).
* fish_config's theme selector (the "colors" tab) was broken, which has
been fixed (#12053 <https://github.com/fish-shell/fish-shell/is-
sues/12053>).
fish 4.2.0 (released November 10, 2025)
Notable improvements and fixes
* History-based autosuggestions now include multi-line commands.
* A transient prompt containing more lines than the final prompt will now
be cleared properly (#11875 <https://github.com/fish-shell/fish-shell/is-
sues/11875>).
* Taiwanese Chinese translations have been added.
* French translations have been supplemented (#11842
<https://github.com/fish-shell/fish-shell/issues/11842>).
Deprecations and removed features
* fish now assumes UTF-8 for character encoding even if the system does not
have a UTF-8 locale. Input bytes which are not valid UTF-8 are still
round-tripped correctly. For example, file paths using legacy encodings
can still be used, but may be rendered differently on the command line.
* On systems where no multi-byte locale is available, fish will no longer
fall back to using ASCII replacements for Unicode characters such as
"a|".
Interactive improvements
* The title of the terminal tab can now be set separately from the window
title by defining the fish_tab_title function (#2692
<https://github.com/fish-shell/fish-shell/issues/2692>).
* fish now hides the portion of a multiline prompt that is scrolled out of
view due to a huge command line. This prevents duplicate lines after re-
painting with partially visible prompt (#11911 <https://github.com/fish-
shell/fish-shell/issues/11911>).
* fish_config prompt's choose and save subcommands have been taught to re-
set fish_mode_prompt in addition to the other prompt functions (#11937
<https://github.com/fish-shell/fish-shell/issues/11937>).
* fish no longer force-disables mouse capture (DECSET/DECRST 1000), so you
can use those commands to let mouse clicks move the cursor or select com-
pletions items (#4918 <https://github.com/fish-shell/fish-shell/is-
sues/4918>).
* The alt-p binding no longer adds a redundant space to the command line.
* When run as a login shell on macOS, fish now sets MANPATH correctly when
that variable was already present in the environment (#10684
<https://github.com/fish-shell/fish-shell/issues/10684>).
* A Windows-specific case of the web-based config failing to launch has
been fixed (#11805 <https://github.com/fish-shell/fish-shell/is-
sues/11805>).
* A MSYS2-specific workaround for Konsole and WezTerm has been added, to
prevent them from using the wrong working directory when opening new tabs
(#11981 <https://github.com/fish-shell/fish-shell/issues/11981>).
For distributors and developers
* Release tags and source code tarballs are GPG-signed again (#11996
<https://github.com/fish-shell/fish-shell/issues/11996>).
* Documentation in release tarballs is now built with the latest version of
Sphinx, which means that pre-built man pages include OSC 8 hyperlinks.
* The Sphinx dependency is now specified in pyproject.toml, which allows
you to use uv <https://github.com/astral-sh/uv> to provide Sphinx for
building documentation (e.g. uv run cargo install --path .).
* The minimum supported Rust version (MSRV) has been updated to 1.85.
* The standalone build mode has been made the default. This means that the
files in $CMAKE_INSTALL_PREFIX/share/fish will not be used anymore, ex-
cept for HTML docs. As a result, future upgrades will no longer break
running shells if one of fish's internal helper functions has been
changed in the updated version. For now, the data files are still in-
stalled redundantly, to prevent upgrades from breaking already-running
shells (#11921 <https://github.com/fish-shell/fish-shell/issues/11921>).
To reverse this change (which should not be necessary), patch out the em-
bed-data feature from cmake/Rust.cmake. This option will be removed in
future.
* OpenBSD 7.8 revealed an issue with fish's approach for displaying builtin
man pages, which has been fixed.
Regression fixes:
* (from 4.1.0) Fix the web-based config for Python 3.9 and older (#12039
<https://github.com/fish-shell/fish-shell/issues/12039>).
* (from 4.1.0) Correct wrong terminal modes set by fish -c 'read; cat (-
#12024 <https://github.com/fish-shell/fish-shell/issues/12024>).
* (from 4.1.0) On VTE-based terminals, stop redrawing the prompt on resize
again, to avoid glitches.
* (from 4.1.0) On MSYS2, fix saving/loading of universal variables (#11948
<https://github.com/fish-shell/fish-shell/issues/11948>).
* (from 4.1.0) Fix error using man for the commands ! . : [ { (#11955
<https://github.com/fish-shell/fish-shell/issues/11955>).
* (from 4.1.0) Fix build issues on illumos systems (#11982
<https://github.com/fish-shell/fish-shell/issues/11982>).
* (from 4.1.0) Fix crash on invalid function command (#11912
<https://github.com/fish-shell/fish-shell/issues/11912>).
* (from 4.0.0) Fix build on SPARC and MIPS Linux by disabling SIGSTKFLT.
* (from 4.0.0) Fix crash when passing negative PIDs to builtin wait (#11929
<https://github.com/fish-shell/fish-shell/issues/11929>).
* (from 4.0.0) On Linux, fix status fish-path output when fish has been re-
installed since it was started.
fish 4.1.2 (released October 7, 2025)
This release fixes the following regressions identified in 4.1.0:
* Fixed spurious error output when completing remote file paths for scp (-
#11860 <https://github.com/fish-shell/fish-shell/issues/11860>).
* Fixed the alt-l binding not formatting ls output correctly (one entry per
line, no colors) (#11888 <https://github.com/fish-shell/fish-shell/is-
sues/11888>).
* Fixed an issue where focus events (currently only enabled in tmux) would
cause multiline prompts to be redrawn in the wrong line (#11870
<https://github.com/fish-shell/fish-shell/issues/11870>).
* Stopped printing output that would cause a glitch on old versions of Mid-
night Commander (#11869 <https://github.com/fish-shell/fish-shell/is-
sues/11869>).
* Added a fix for some configurations of Zellij where escape key processing
was delayed (#11868 <https://github.com/fish-shell/fish-shell/is-
sues/11868>).
* Fixed a case where the web-based configuration tool would generate in-
valid configuration (#11861 <https://github.com/fish-shell/fish-shell/is-
sues/11861>).
* Fixed a case where pasting into fish -c read would fail with a noisy er-
ror (#11836 <https://github.com/fish-shell/fish-shell/issues/11836>).
* Fixed a case where upgrading fish would break old versions of fish that
were still running.
In general, fish still needs to be restarted after it is upgraded, except
for standalone builds <https://github.com/fish-shell/fish-
shell/?tab=readme-ov-file#building-fish-with-embedded-data-experimental>.
fish 4.1.1 (released September 30, 2025)
This release fixes the following regressions identified in 4.1.0:
* Many of our new Chinese translations were more confusing than helpful;
they have been fixed or removed (#11833 <https://github.com/fish-
shell/fish-shell/issues/11833>).
Note that you can work around this type of issue by configuring fish's
message localization: if your environment contains something like
LANG=zh_CN.UTF-8, you can use set -g LC_MESSAGES en to use English mes-
sages inside fish. This will not affect fish's child processes unless
LC_MESSAGES was already exported.
* Some fish_config subcommands for showing prompts and themes had been bro-
ken in standalone Linux builds (those using the embed-data cargo fea-
ture), which has been fixed (#11832 <https://github.com/fish-shell/fish-
shell/issues/11832>).
* On Windows Terminal, we observed an issue where fish would fail to read
the terminal's response to our new startup queries, causing noticeable
lags and a misleading error message. A workaround has been added (#11841
<https://github.com/fish-shell/fish-shell/issues/11841>).
* A WezTerm issue breaking shifted key input
<https://github.com/wezterm/wezterm/issues/6087> has resurfaced on some
versions of WezTerm; our workaround has been extended to cover all ver-
sions for now (#11204 <https://github.com/fish-shell/fish-shell/is-
sues/11204>).
* Fixed a crash in the web-based configuration tool when using the new un-
derline styles (#11840 <https://github.com/fish-shell/fish-shell/is-
sues/11840>).
fish 4.1.0 (released September 27, 2025)
Notable improvements and fixes
* Compound commands (begin; echo 1; echo 2; end) can now be written using
braces ({ echo1; echo 2 }), like in other shells.
* fish now supports transient prompts: if fish_transient_prompt is set to
1, fish will reexecute prompt functions with the --final-rendering argu-
ment before running a commandline (#11153 <https://github.com/fish-
shell/fish-shell/issues/11153>).
* Tab completion results are truncated up to the common directory path, in-
stead of somewhere inside that path. E.g. if you complete "share/func-
tions", and it includes the files "foo.fish" and "bar.fish", the comple-
tion pager will now show "a|/foo.fish" and "a|/bar.fish" (#11250
<https://github.com/fish-shell/fish-shell/issues/11250>).
* Self-installing builds as created by e.g. cargo install no longer install
other files, see below.
* Our gettext-based message-localization has been reworked, adding transla-
tions to self-installing builds; see below.
Deprecations and removed features
* set_color --background=COLOR no longer implicitly activates bold mode.
If your theme is stored in universal variables (the historical default),
some bold formatting might be lost. To fix this, we suggest updating to
the latest version of our theme, to explicitly activate bold mode, for
example use fish_config theme save "fish default".
* {echo,echo} or { echo, echo } are no longer interpreted as brace expan-
sion tokens but as compound commands.
* Terminfo-style key names (bind -k nul) are no longer supported. They had
been superseded by fish's own key names since 4.0 (#11342
<https://github.com/fish-shell/fish-shell/issues/11342>).
* fish no longer reads the terminfo database, so its behavior is generally
no longer affected by the TERM environment variable (#11344
<https://github.com/fish-shell/fish-shell/issues/11344>). For the time
being, this change can be reversed via the ignore-terminfo feature flag.
To do so, run the following once and restart fish:
set -Ua fish_features no-ignore-terminfo
* The --install option when fish is built as self-installing is removed,
see below.
* set_color ff0000 now outputs 24-bit RGB true-color even if COLORTERM is
unset. One can override this by setting fish_term24bit to 0 (#11372
<https://github.com/fish-shell/fish-shell/issues/11372>).
* fish now requires the terminal to respond to queries for the Primary De-
vice Attribute. For now, this can be reversed via a feature flag, by
running (once) set -Ua fish_features no-query-term and restarting fish.
* Users of GNU screen may experience minor glitches when starting fish.
Scripting improvements
* The argparse builtin has seen many improvements, see below.
* The string pad command now has a -C/--center option.
* The psub command now allows combining --suffix with --fifo (#11729
<https://github.com/fish-shell/fish-shell/issues/11729>).
* The read builtin has learned the --tokenize-raw option to tokenize with-
out quote removal (#11084 <https://github.com/fish-shell/fish-shell/is-
sues/11084>).
Interactive improvements
* Autosuggestions are now also provided in multi-line command lines. Like
ctrl-r, these operate only on the current line.
* Autosuggestions used to not suggest multi-line command-lines from his-
tory; now autosuggestions include individual lines from multi-line com-
mand-lines.
* The history pager search now preserves ordering between ctrl-s forward
and ctrl-r backward searches.
* Instead of highlighting events by flashing all text to the left of the
cursor, failing history token search (alt-.) flashes the associated to-
ken, failing tab-completion flashes the to-be-completed token (#11050
<https://github.com/fish-shell/fish-shell/issues/11050>), deleting an au-
tosuggestion (shift-delete) flashes the suggestion, and all other scenar-
ios flash the full command line.
* Pasted commands are now stripped of any $ command prefixes, to help
pasting code snippets.
* Builtin help options (e.g. abbr --help) now use man directly, meaning
that variables like MANWIDTH are respected (#11786
<https://github.com/fish-shell/fish-shell/issues/11786>).
* funced will now edit copied functions directly, instead of the file where
function --copy was invoked. (#11614 <https://github.com/fish-shell/fish-
shell/issues/11614>)
* Added a simple fish_jj_prompt which reduces visual noise in the prompt
inside Jujutsu <https://jj-vcs.github.io/jj/latest/> repositories that
are colocated with Git.
New or improved bindings
* On non-macOS systems, alt-left, alt-right, alt-backspace and alt-delete
no longer operate on punctuation-delimited words but on whole arguments,
possibly including special characters like / and quoted spaces. On ma-
cOS, the corresponding ctrl- prefixed keys operate on whole arguments.
Word operations are still available via the other respective modifier,
just like in most web browsers.
* ctrl-z (undo) after executing a command will restore the previous cursor
position instead of placing the cursor at the end of the command line.
* The alt-s binding will now also use run0 if available.
* Some mouse support has been added: the OSC 133 prompt marking feature has
learned about kitty's click_events=1 flag, which allows moving fish's
cursor by clicking in the command line, and selecting pager items (#10932
<https://github.com/fish-shell/fish-shell/issues/10932>).
* Before clearing the screen and redrawing, ctrl-l now pushes all text lo-
cated above the prompt to the terminal's scrollback, via a new special
input function scrollback-push. For compatibility with terminals that do
not implement ECMA-48's SCROLL UP command, this function is only used if
the terminal advertises support for that via XTGETTCAP.
* Vi mode has learned ctrl-a (increment) and ctrl-x (decrement) (#11570
<https://github.com/fish-shell/fish-shell/issues/11570>).
Completions
* git completions now show the remote URL as description when completing
remotes.
* systemctl completions no longer print escape codes if SYSTEMD_COLORS hap-
pens to be set (#11465 <https://github.com/fish-shell/fish-shell/is-
sues/11465>).
* Added and improved many completion scripts, notably tmux.
Improved terminal support
* Support for double, curly, dotted and dashed underlines, for use in
fish_color_* variables and the set_color builtin (#10957
<https://github.com/fish-shell/fish-shell/issues/10957>).
* Underlines can now be colored independent of text (#7619
<https://github.com/fish-shell/fish-shell/issues/7619>).
* New documentation page Terminal Compatibility (also accessible via man
fish-terminal-compatibility) lists the terminal control sequences used by
fish.
Other improvements
* Updated Chinese and German translations.
* fish_indent --dump-parse-tree now emits simple metrics about the tree in-
cluding its memory consumption.
* We added some tools to improve development workflows, for example
build_tools/{check,update_translations,release}.sh and tests/test_dri-
ver.py. In conjunction with cargo, these enable almost all day-to-day
development tasks without using CMake.
For distributors
* Builtin commands that support the --help option now require the man pro-
gram. The direct dependency on mandoc and nroff has been removed.
* fish no longer uses gettext MO files, see below. If you have use cases
which are incompatible with our new approach, please let us know.
* The fish_indent and fish_key_reader programs are now also available as
builtins. If fish is invoked via e.g. a symlink with one of these names,
it will act like the given tool (i.e. it's a multi-call binary). This
allows truly distributing fish as a single file (#10876
<https://github.com/fish-shell/fish-shell/issues/10876>).
* The CMake build configuration has been simplified and no longer sec-
ond-guesses rustup. It will run rustc and cargo via PATH or in
~/.cargo/bin/. If that doesn't match your setup, set the Rust_COMPILER
and Rust_CARGO CMake variables (#11328 <https://github.com/fish-
shell/fish-shell/issues/11328>).
* Cygwin support has been reintroduced, since Rust gained a Cygwin target
<https://github.com/rust-lang/rust/pull/134999> (#11238
<https://github.com/fish-shell/fish-shell/issues/11238>).
* CMake 3.15 is now required.
Changes to self-installing builds
The self-installing build type introduced in fish 4.0 has been changed (-
#11143 <https://github.com/fish-shell/fish-shell/issues/11143>). Now fish
built with embedded data will just read the data straight from its own bi-
nary or write it out to temporary files when necessary, instead of requir-
ing an installation step on start. That means it is now possible to build
fish as a single file and copy it to any system with a compatible CPU ar-
chitecture, including as a different user, without extracting any files.
As before, this is the default when building via cargo, and disabled when
building via CMake. For packagers we continue to recommend CMake.
Note: When fish is built like this, the __fish_data_dir variable will be
empty because that directory no longer has meaning. You should generally
not need these files. For example, if you want to make sure that comple-
tions for "foo" are loaded, use complete -C"foo " >/dev/null instead).
The raw files are still exposed via status subcommands, mainly for fish's
internal use, but you can also use them as a last resort.
Remaining benefits of a full installation (as currently done by CMake) are:
* man pages like fish(1) in standard locations, easily accessible from out-
side fish.
* a local copy of the HTML documentation, typically accessed via the help
function. In builds with embedded data, help will redirect to e.g. -
https://fishshell.com/docs/current/
* fish_indent and fish_key_reader as separate files, making them easily ac-
cessible outside fish
* an (empty) /etc/fish/config.fish as well as empty directories
/etc/fish/{functions,completions,conf.d}
* $PREFIX/share/pkgconfig/fish.pc, which defines directories for configura-
tion-snippets, like vendor_completions.d
Changes to gettext localization
We replaced several parts of the gettext functionality with custom imple-
mentations (#11726 <https://github.com/fish-shell/fish-shell/is-
sues/11726>). Most notably, message extraction, which should now work re-
liably, and the runtime implementation, where we no longer dynamically link
to gettext, but instead use our own implementation, whose behavior is simi-
lar to GNU gettext, with some minor deviations. Our implementation now
fully respects fish variables, so locale variables do not have to be ex-
ported for fish localizations to work. They still have to be exported to
inform other programs about language preferences. The LANGUAGE environment
variable is now treated as a path variable, meaning it is an implicitly
colon-separated list. While we no longer have any runtime dependency on
gettext, we still need gettext tools for building, most notably msgfmt.
When building without msgfmt available, localization will not work with the
resulting executable. Localization data is no longer sourced at runtime
from MO files on the file system, but instead built into the executable.
This is always done, independently of the other data embedding, so all fish
executables will have access to all message catalogs, regardless of the
state of the file system. Disabling our new localize-messages cargo fea-
ture will cause fish to be built without localization support. CMake
builds can continue to use the WITH_GETTEXT option, with the same semantics
as the localize-messages feature. The current implementation does not pro-
vide any configuration options for controlling which language catalogs are
built into the executable (other than disabling them all). As a
workaround, you can delete files in the po directory before building to ex-
clude unwanted languages.
Changes to the argparse builtin
* argparse now saves recognised options, including option-arguments in
argv_opts, allowing them to be forwarded to other commands (#6466
<https://github.com/fish-shell/fish-shell/issues/6466>).
* argparse options can now be marked to be deleted from argv_opts (by
adding a & at the end of the option spec, before a ! if present). There
is now also a corresponding -d / --delete option to fish_opt.
* argparse --ignore-unknown now removes preceding known short options from
groups containing unknown options (e.g. when parsing -abc, if a is known
but b is not, then argv will contain -bc).
* argparse now has an -u / --move-unknown option that works like --ig-
nore-unknown but preserves unknown options in argv.
* argparse now has an -S / --strict-longopts option that forbids abbreviat-
ing long options or passing them with a single dash (e.g. if there is a
long option called foo, --fo and --foo won't match it).
* argparse now has a -U / --unknown-arguments option to specify how to
parse unknown option's arguments.
* argparse now allows specifying options that take multiple optional values
by using =* in the option spec (#8432 <https://github.com/fish-
shell/fish-shell/issues/8432>). In addition, fish_opt has been modified
to support such options by using the --multiple-vals together with -o /
--optional-val; -m is also now acceptable as an abbreviation for --multi-
ple-vals.
* fish_opt no longer requires you give a short flag name when defining op-
tions, provided you give it a long flag name with more than one charac-
ter.
* argparse option specifiers for long-only options can now start with /,
allowing the definition of long options with a single letter. Due to this
change, the --long-only option to fish_opt is now no longer necessary and
is deprecated.
* fish_opt now has a -v / --validate option you can use to give a fish
script to validate values of the option.
----
fish 4.0.9 (released September 27, 2025)
This release fixes:
* a regression in 4.0.6 causing shifted keys to not be inserted on some
terminals (#11813 <https://github.com/fish-shell/fish-shell/is-
sues/11813>).
* a regression in 4.0.6 causing the build to fail on systems where char is
unsigned (#11804 <https://github.com/fish-shell/fish-shell/is-
sues/11804>).
* a regression in 4.0.0 causing a crash on an invalid bg invocation.
----
fish 4.0.8 (released September 18, 2025)
This release fixes a regression in 4.0.6 that caused user bindings to be
shadowed by either fish's or a plugin's bindings (#11803
<https://github.com/fish-shell/fish-shell/issues/11803>).
----
fish 4.0.6 (released September 12, 2025)
This release of fish fixes a number of issues identified in fish 4.0.2:
* fish now properly inherits $PATH under Windows WSL2 (#11354
<https://github.com/fish-shell/fish-shell/issues/11354>).
* Remote filesystems are detected properly again on non-Linux systems.
* the printf builtin no longer miscalculates width of multi-byte characters
(#11412 <https://github.com/fish-shell/fish-shell/issues/11412>).
* For many years, fish has been "relocatable" -- it was possible to move
the entire CMAKE_INSTALL_PREFIX and fish would use paths relative to its
binary. Only gettext locale paths were still determined purely at com-
pile time, which has been fixed.
* the commandline builtin failed to print the commandline set by a command-
line -C invocation, which broke some completion scripts. This has been
corrected (#11423 <https://github.com/fish-shell/fish-shell/is-
sues/11423>).
* To work around terminals that fail to parse Operating System Command
(OSC) sequences, a temporary feature flag has been added. It allows you
to disable prompt marking (OSC 133) by running (once) set -Ua fish_fea-
tures no-mark-prompt and restarting fish (#11749
<https://github.com/fish-shell/fish-shell/issues/11749>).
* The routines to save history and universal variables have seen some ro-
bustness improvements.
* builtin status current-command no longer prints a trailing blank line.
* A crash displaying multi-line quoted command substitutions has been fixed
(#11444 <https://github.com/fish-shell/fish-shell/issues/11444>).
* Commands like set fish_complete_path ... accidentally disabled completion
autoloading, which has been corrected.
* nmcli completions have been fixed to query network information dynami-
cally instead of only when completing the first time.
* Git completions no longer print an error when no git-foo executable is in
PATH.
* Custom completions like complete foo -l long -xa ... that use the output
of commandline -t. on a command-line like foo --long= have been invali-
dated by a change in 4.0; the completion scripts have been adjusted ac-
cordingly (#11508 <https://github.com/fish-shell/fish-shell/is-
sues/11508>).
* Some completions were misinterpreted, which caused garbage to be dis-
played in the completion list. This has been fixed.
* fish no longer interprets invalid control sequences from the terminal as
if they were alt-[ or alt-o key strokes.
* bind has been taught about the printscreen and menu keys.
* alt-delete now deletes the word right of the cursor.
* ctrl-alt-h erases the last word again (#11548 <https://github.com/fish-
shell/fish-shell/issues/11548>).
* alt-left alt-right were misinterpreted because they send unexpected se-
quences on some terminals; a workaround has been added. (#11479
<https://github.com/fish-shell/fish-shell/issues/11479>).
* Key bindings like bind shift-A are no longer accepted; use bind shift-a
or bind A.
* Key bindings like bind shift-a take precedence over bind A when the key
event included the shift modifier.
* Bindings using shift with non-ASCII letters (such as ctrl-shift-~Aox) are
now supported.
* Bindings with modifiers such as bind ctrl-w work again on non-Latin key-
board layouts such as a Russian one. This is implemented by allowing key
events such as ctrl-~N to match bindings of the corresponding Latin key,
using the kitty keyboard protocol's base layout key (#11520
<https://github.com/fish-shell/fish-shell/issues/11520>).
* Vi mode: The cursor position after pasting via p has been corrected.
* Vi mode: Trying to replace the last character via r no longer replaces
the last-but-one character (#11484 <https://github.com/fish-shell/fish-
shell/issues/11484>).
----
fish 4.0.2 (released April 20, 2025)
This release of fish fixes a number of issues identified in fish 4.0.1:
* Completions are quoted, rather than backslash-escaped, only if the com-
pletion is unambiguous. Continuing to edit the token is therefore easier
(#11271 <https://github.com/fish-shell/fish-shell/issues/11271>). This
changes the behavior introduced in 4.0.0 where all completions were
quoted.
* The warning when the terminfo database can't be found has been downgraded
to a log message. fish will act as if the terminal behaves like
xterm-256color, which is correct for the vast majority of cases (#11277
<https://github.com/fish-shell/fish-shell/issues/11277>, #11290
<https://github.com/fish-shell/fish-shell/issues/11290>).
* Key combinations using the super (Windows/command) key can now (actually)
be bound using the super- prefix (#11217 <https://github.com/fish-
shell/fish-shell/issues/11217>). This was listed in the release notes for
4.0.1 but did not work correctly.
* function is stricter about argument parsing, rather than allowing addi-
tional parameters to be silently ignored (#11295
<https://github.com/fish-shell/fish-shell/issues/11295>).
* Using parentheses in the test builtin works correctly, following a re-
gression in 4.0.0 where they were not recognized (#11387
<https://github.com/fish-shell/fish-shell/issues/11387>).
* delete in Vi mode when Num Lock is active will work correctly (#11303
<https://github.com/fish-shell/fish-shell/issues/11303>).
* Abbreviations cannot alter the command-line contents, preventing a crash
(#11324 <https://github.com/fish-shell/fish-shell/issues/11324>).
* Improvements to various completions, including new completions for
wl-randr (#11301 <https://github.com/fish-shell/fish-shell/is-
sues/11301>), performance improvements for cargo completions by avoiding
network requests (#11347 <https://github.com/fish-shell/fish-shell/is-
sues/11347>), and other improvements for btrfs (#11320
<https://github.com/fish-shell/fish-shell/issues/11320>), cryptsetup (-
#11315 <https://github.com/fish-shell/fish-shell/issues/11315>), git (-
#11319 <https://github.com/fish-shell/fish-shell/issues/11319>, #11322
<https://github.com/fish-shell/fish-shell/issues/11322>, #11323
<https://github.com/fish-shell/fish-shell/issues/11323>), jj (#11046
<https://github.com/fish-shell/fish-shell/issues/11046>), and systemd-an-
alyze (#11314 <https://github.com/fish-shell/fish-shell/issues/11314>).
* The Mercurial (hg) prompt can handle working directories that contain an
embedded newline, rather than producing errors (#11348
<https://github.com/fish-shell/fish-shell/issues/11348>).
* A number of crashes have been fixed. Triggers include prompts containing
backspace characters (#11280 <https://github.com/fish-shell/fish-
shell/issues/11280>), history pager search (#11355
<https://github.com/fish-shell/fish-shell/issues/11355>), invalid UTF-8
in read (#11383 <https://github.com/fish-shell/fish-shell/issues/11383>),
and the kill-selection binding (#11367 <https://github.com/fish-
shell/fish-shell/issues/11367>).
* A race condition in the test suite has been fixed (#11254
<https://github.com/fish-shell/fish-shell/issues/11254>), and a test for
fish versioning relaxed to support downstream distributors' modifications
(#11173 <https://github.com/fish-shell/fish-shell/issues/11173>).
* Small improvements to the documentation (#11264 <https://github.com/fish-
shell/fish-shell/issues/11264>, #11329 <https://github.com/fish-
shell/fish-shell/issues/11329>, #11361 <https://github.com/fish-
shell/fish-shell/issues/11361>).
----
fish 4.0.1 (released March 12, 2025)
This release of fish includes the following improvements compared to fish
4.0.0:
* Key combinations using the super (Windows/command) key can be bound using
the super- prefix (#11217 <https://github.com/fish-shell/fish-shell/is-
sues/11217>).
* Konsole's menu shows the "Open folder with" option again (#11198
<https://github.com/fish-shell/fish-shell/issues/11198>).
*
$fish_color_search_match will now only be applied to the foreground color
if it has an explicit foreground. For example, this allows setting::
set -g fish_color_search_match --reverse
* Cursor shape commands (\e[2 q) are no longer sent in non-interactive
shells or in redirections (#11255 <https://github.com/fish-shell/fish-
shell/issues/11255>).
* status gained a is-interactive-read subcommand, to check whether the
script is being called from an interactive read invocation.
* fish's background tasks are now started in a way that avoids an error on
macOS Terminal.app (#11181 <https://github.com/fish-shell/fish-shell/is-
sues/11181>).
* Using key combinations within qemu should work correctly.
* Prompts containing control characters no longer cause incorrect display
of command lines (#11252 <https://github.com/fish-shell/fish-shell/is-
sues/11252>).
* Cancelling the command-line in Vi mode displays correctly again (#11261
<https://github.com/fish-shell/fish-shell/issues/11261>).
* The acidhub prompt properly displays the git branch again (#11179
<https://github.com/fish-shell/fish-shell/issues/11179>).
* Completions for wine correctly include files again (#11202
<https://github.com/fish-shell/fish-shell/issues/11202>).
* On macOS, paths from /etc/paths and /etc/manpaths containing colons are
handled correctly (#10684 <https://github.com/fish-shell/fish-shell/is-
sues/10684>). This functionality was included in the 4.0.0 release notes
but was missing from the source code.
* The XTerm modifyOtherKeys keyboard encoding is no longer used under
WezTerm, as it does not work correctly in all layouts (#11204
<https://github.com/fish-shell/fish-shell/issues/11204>).
* option-left and other similar keys should now work in iTerm versions be-
fore 3.5.12; the kitty keyboard protocol is now disabled on these ver-
sions (#11192 <https://github.com/fish-shell/fish-shell/issues/11192>).
* The kitty keyboard protocol is no longer used under Midnight Commander,
as it does not work correctly (#10640 <https://github.com/fish-
shell/fish-shell/issues/10640>).
* fish now sends the commandline along with the OSC 133 semantic prompt
command start sequence. This fixes a test in the kitty terminal (#11203
<https://github.com/fish-shell/fish-shell/issues/11203>).
* Git completions for third-party commands like "git-absorb" are completed
correctly again (#11205 <https://github.com/fish-shell/fish-shell/is-
sues/11205>).
* Completions for diskutil no longer produce an error (#11201
<https://github.com/fish-shell/fish-shell/issues/11201>).
* The output of certain error messages no longer prints newlines to stan-
dard output (#11248 <https://github.com/fish-shell/fish-shell/is-
sues/11248>).
* A number of crashes have been fixed, including file names longer than 255
bytes (#11221 <https://github.com/fish-shell/fish-shell/issues/11221>),
using fish on a btrfs filesystem (#11219 <https://github.com/fish-
shell/fish-shell/issues/11219>), history files that do not have the ex-
pected format (#11236 <https://github.com/fish-shell/fish-shell/is-
sues/11236>), and pasting into an empty command line (#11256
<https://github.com/fish-shell/fish-shell/issues/11256>).
----
fish 4.0.0 (released February 27, 2025)
fish's core code has been ported from C++ to Rust (#9512
<https://github.com/fish-shell/fish-shell/issues/9512>). This means a large
change in dependencies and how to build fish. However, there should be no
direct impact on users. Packagers should see the For Distributors section
at the end.
Notable backwards-incompatible changes
* As part of a larger binding rework, bind gained a new key notation. In
most cases the old notation should keep working, but in rare cases you
may have to change a bind invocation to use the new notation. See below
for details.
* ctrl-c now calls a new bind function called clear-commandline. The old
behavior, which leaves a "^C" marker, is available as cancel-commandline
(#10935 <https://github.com/fish-shell/fish-shell/issues/10935>)
* random will produce different values from previous versions of fish when
used with the same seed, and will work more sensibly with small seed num-
bers. The seed was never guaranteed to give the same result across sys-
tems, so we do not expect this to have a large impact (#9593
<https://github.com/fish-shell/fish-shell/issues/9593>).
* Variables in command position that expand to a subcommand keyword are now
forbidden to fix a likely user error. For example, set editor command
emacs; $editor is no longer allowed (#10249 <https://github.com/fish-
shell/fish-shell/issues/10249>).
* functions --handlers will now list handlers in a different order. Now it
is definition order, first to last, where before it was last to first.
This was never specifically defined, and we recommend not relying on a
specific order (#9944 <https://github.com/fish-shell/fish-shell/is-
sues/9944>).
* The qmark-noglob feature, introduced in fish 3.0, is enabled by default.
That means ? will no longer act as a single-character glob. You can, for
the time being, turn it back on by adding no-qmark-noglob to fish_fea-
tures and restarting fish:
set -Ua fish_features no-qmark-noglob
The flag will eventually be made read-only, making it impossible to turn
off.
* Terminals that fail to ignore unrecognized OSC or CSI sequences may dis-
play garbage. We know cool-retro-term and emacs' ansi-term are affected,
but most mainstream terminals are not.
* fish no longer searches directories from the Windows system/user $PATH
environment variable for Linux executables. To execute Linux binaries by
name (i.e. not with a relative or absolute path) from a Windows folder,
make sure the /mnt/c/... path is explicitly added to $fish_user_paths and
not just automatically appended to $PATH by wsl.exe (#10506
<https://github.com/fish-shell/fish-shell/issues/10506>).
* Under Microsoft Windows Subsystem for Linux 1 (not WSL 2), backgrounded
jobs that have not been disowned and do not terminate on their own after
a SIGHUP + SIGCONT sequence will be explicitly killed by fish on exit
(after the usual prompt to close or disown them) to work around a WSL 1
deficiency that sees backgrounded processes that run into SIGTTOU remain
in a suspended state indefinitely (#5263 <https://github.com/fish-
shell/fish-shell/issues/5263>). The workaround is to explicitly disown
processes you wish to outlive the shell session.
Notable improvements and fixes
* fish now requests XTerm's modifyOtherKeys keyboard encoding and kitty
keyboard protocol's <https://sw.kovidgoyal.net/kitty/keyboard-protocol/>
progressive enhancements (#10359 <https://github.com/fish-shell/fish-
shell/issues/10359>). Depending on terminal support, this allows to
binding more key combinations, including arbitrary combinations of modi-
fiers ctrl, alt and shift, and distinguishing (for example) ctrl-i from
tab.
Additionally, bind now supports a human-readable syntax in addition to
byte sequences. This includes modifier names, and names for keys like
enter and backspace. For example
* bind up 'do something' binds the up-arrow key instead of a two-key se-
quence ("u" and then "p")
* bind ctrl-x,alt-c 'do something' binds a sequence of two keys.
Any key argument that starts with an ASCII control character (like \e or
\cX) or is up to 3 characters long, not a named key, and does not contain
, or - will be interpreted in the old syntax to keep compatibility for
the majority of bindings.
Keyboard protocols can be turned off by disabling the "keyboard-proto-
cols" feature flag:
set -Ua fish_features no-keyboard-protocols
This is a temporary measure to work around buggy terminals (#11056
<https://github.com/fish-shell/fish-shell/issues/11056>), which appear to
be relatively rare. Use this if something like "=0" or "=5u" appears in
your commandline mysteriously.
* fish can now be built as a self-installing binary (#10367
<https://github.com/fish-shell/fish-shell/issues/10367>). That means it
can be easily built on one system and copied to another, where it can ex-
tract supporting files. To do this, run:
cargo install --path . # in a clone of the fish repository
# or `cargo build --release` and copy target/release/fish{,_indent,_key_reader} wherever you want
The first time it runs interactively, it will extract all the data files
to ~/.local/share/fish/install/. A specific path can be used for the
data files with fish --install=PATH To uninstall, remove the fish bina-
ries and that directory.
This build system is experimental; the main build system, using cmake,
remains the recommended approach for packaging and installation to a pre-
fix.
* A new function fish_should_add_to_history can be overridden to decide
whether a command should be added to the history (#10302
<https://github.com/fish-shell/fish-shell/issues/10302>).
* Bindings can now mix special input functions and shell commands, so bind
ctrl-g expand-abbr "commandline -i \n" works as expected (#8186
<https://github.com/fish-shell/fish-shell/issues/8186>).
* Special input functions run from bindings via commandline -f are now ap-
plied immediately, instead of after the currently executing binding (-
#3031 <https://github.com/fish-shell/fish-shell/issues/3031>, #10126
<https://github.com/fish-shell/fish-shell/issues/10126>). For example,
commandline -i foo; commandline | grep foo succeeds now.
* Undo history is no longer truncated after every command, but kept for the
lifetime of the shell process.
* The ctrl-r history search now uses glob syntax (#10131
<https://github.com/fish-shell/fish-shell/issues/10131>).
* The ctrl-r history search now operates only on the line or command sub-
stitution at cursor, making it easier to combine commands from history (-
#9751 <https://github.com/fish-shell/fish-shell/issues/9751>).
* Abbreviations can now be restricted to specific commands. For instance:
abbr --add --command git back 'reset --hard HEAD^'
will expand "back" to reset --hard HEAD^, but only when the command is
git (#9411 <https://github.com/fish-shell/fish-shell/issues/9411>).
Deprecations and removed features
* commandline --tokenize (short option -o) has been deprecated in favor of
commandline --tokens-expanded (short option -x) which expands variables
and other shell syntax, removing the need to use eval in completion
scripts (#10212 <https://github.com/fish-shell/fish-shell/issues/10212>).
* Two new feature flags:
* remove-percent-self (see status features) disables PID expansion of
%self, which has been supplanted by $fish_pid (#10262
<https://github.com/fish-shell/fish-shell/issues/10262>).
* test-require-arg disables test's one-argument mode. That means test -n
without an additional argument will return false, test -z will keep re-
turning true. Any other option without an argument, anything that is
not an option and no argument will be an error. This also goes for [,
test's alternate name. This is a frequent source of confusion and so
we are breaking with POSIX explicitly in this regard. In addition to
the feature flag, there is a debug category "deprecated-test". Running
fish with fish -d deprecated-test will show warnings whenever a test
invocation that would change is used. (#10365 <https://github.com/fish-
shell/fish-shell/issues/10365>).
These can be enabled with:
set -Ua fish_features remove-percent-self test-require-arg
We intend to enable them by default in future, and after that eventually
make them read-only.
* Specifying key names as terminfo names (using the bind -k syntax) is dep-
recated and may be removed in a future version.
* When a terminal pastes text into fish using bracketed paste, fish used to
switch to a special paste bind mode. This bind mode has been removed.
The behavior on paste is no longer configurable.
* When an interactive fish is stopped or terminated by a signal that cannot
be caught (SIGSTOP or SIGKILL), it may leave the terminal in a state
where keypresses with modifiers are sent as CSI u sequences, instead of
traditional control characters or escape sequences that are recognized by
Readline and compatible programs, such as bash and python. If this hap-
pens, you can use the reset command from ncurses to restore the terminal
state.
* fish_key_reader --verbose no longer shows timing information.
* Terminal information is no longer read from hashed terminfo databases, or
termcap databases (#10269 <https://github.com/fish-shell/fish-shell/is-
sues/10269>). The vast majority of systems use a non-hashed terminfo
database, which is still supported.
* source returns an error if used without a filename or pipe/redirection (-
#10774 <https://github.com/fish-shell/fish-shell/issues/10774>).
Scripting improvements
* for loops will no longer remember local variables from the previous iter-
ation (#10525 <https://github.com/fish-shell/fish-shell/issues/10525>).
* A new history append subcommand appends a command to the history, without
executing it (#4506 <https://github.com/fish-shell/fish-shell/is-
sues/4506>).
* A new redirection: <? /path/to/file will try opening the file as input,
and if it doesn't succeed silently uses /dev/null instead. This can help
with checks like test -f /path/to/file; and string replace foo bar <
/path/to/file. (#10387 <https://github.com/fish-shell/fish-shell/is-
sues/10387>)
* A new option commandline --tokens-raw prints a list of tokens without any
unescaping (#10212 <https://github.com/fish-shell/fish-shell/is-
sues/10212>).
* A new option commandline --showing-suggestion tests whether an autosug-
gestion is currently displayed (#10586 <https://github.com/fish-
shell/fish-shell/issues/10586>).
* functions and type now show that a function was copied and its source,
rather than solely Defined interactively (#6575 <https://github.com/fish-
shell/fish-shell/issues/6575>).
* Stack trace now shows line numbers for copied functions (#6575
<https://github.com/fish-shell/fish-shell/issues/6575>).
* foo & && bar is now a syntax error, like in other shells (#9911
<https://github.com/fish-shell/fish-shell/issues/9911>).
* if -e foo; end now prints a more accurate error (#10000
<https://github.com/fish-shell/fish-shell/issues/10000>).
* cd into a directory that is not readable but accessible (permissions --x)
is now possible (#10432 <https://github.com/fish-shell/fish-shell/is-
sues/10432>).
* An integer overflow in string repeat leading to a near-infinite loop has
been fixed (#9899 <https://github.com/fish-shell/fish-shell/is-
sues/9899>).
* string shorten behaves better in the presence of non-printable charac-
ters, including fixing an integer overflow that shortened strings more
than intended (#9854 <https://github.com/fish-shell/fish-shell/is-
sues/9854>).
* string pad no longer allows non-printable characters as padding (#9854
<https://github.com/fish-shell/fish-shell/issues/9854>).
* string repeat now allows omission of -n when the first argument is an in-
teger (#10282 <https://github.com/fish-shell/fish-shell/issues/10282>).
* string match and replace have a new --max-matches option to return as
soon as the specified number of matches have been identified, which can
improve performance in scripts (#10587 <https://github.com/fish-
shell/fish-shell/issues/10587>).
* functions --handlers-type caller-exit once again lists functions defined
as function --on-job-exit caller, rather than them being listed by func-
tions --handlers-type process-exit.
* A new set --no-event option sets or erases variables without triggering a
variable event. This can be useful to change a variable in an event han-
dler (#10480 <https://github.com/fish-shell/fish-shell/issues/10480>).
* Commas in command substitution output are no longer used as separators in
brace expansion, preventing a surprising expansion in some cases (#5048
<https://github.com/fish-shell/fish-shell/issues/5048>).
* Universal variables can now store strings containing invalid UTF-8 (-
#10313 <https://github.com/fish-shell/fish-shell/issues/10313>).
* A new path basename -E option that causes it to return the basename
("filename" with the directory prefix removed) with the final extension
(if any) also removed. This is a shorter version of path change-extension
"" (path basename $foo) (#10521 <https://github.com/fish-shell/fish-
shell/issues/10521>).
* A new math --scale-mode option to select truncate, round, floor, ceiling
as you wish; the default value is truncate. (#9117
<https://github.com/fish-shell/fish-shell/issues/9117>).
* random is now less strict about its arguments, allowing a start larger or
equal to the end. (#10879 <https://github.com/fish-shell/fish-shell/is-
sues/10879>)
* function --argument-names now produces an error if a read-only variable
name is used, rather than simply ignoring it (#10842
<https://github.com/fish-shell/fish-shell/issues/10842>).
* Tilde expansion in braces (that is, {~,}) works correctly (#10610
<https://github.com/fish-shell/fish-shell/issues/10610>).
Interactive improvements
* Autosuggestions were sometimes not shown after recalling a line from his-
tory, which has been fixed (#10287 <https://github.com/fish-shell/fish-
shell/issues/10287>).
* Up-arrow search matches -- which are highlighted in reverse colors -- are
no longer syntax-highlighted, to fix bad contrast with the search match
highlighting.
* Command abbreviations (those with --position command or without a --posi-
tion) now also expand after decorators like command (#10396
<https://github.com/fish-shell/fish-shell/issues/10396>).
* Abbreviations now expand after process separators like ; and |. This
fixes a regression in version 3.6 (#9730 <https://github.com/fish-
shell/fish-shell/issues/9730>).
* When exporting interactively defined functions (using type, functions or
funcsave) the function body is now indented, to match the interactive
command line editor (#8603 <https://github.com/fish-shell/fish-shell/is-
sues/8603>).
* ctrl-x (fish_clipboard_copy) on multiline commands now includes indenta-
tion (#10437 <https://github.com/fish-shell/fish-shell/issues/10437>).
* ctrl-v (fish_clipboard_paste) now strips ASCII control characters from
the pasted text. This is consistent with normal keyboard input (#5274
<https://github.com/fish-shell/fish-shell/issues/5274>).
* When a command like fg %2 fails to find the given job, it no longer be-
haves as if no job spec was given (#9835 <https://github.com/fish-
shell/fish-shell/issues/9835>).
* Redirection in command position like >echo is now highlighted as error (-
#8877 <https://github.com/fish-shell/fish-shell/issues/8877>).
* fish_vi_cursor now works properly inside the prompt created by builtin
read (#10088 <https://github.com/fish-shell/fish-shell/issues/10088>).
* fish no longer fails to open a FIFO if interrupted by a terminal resize
signal (#10250 <https://github.com/fish-shell/fish-shell/issues/10250>).
* read --help and friends no longer ignore redirections. This fixes a re-
gression in version 3.1 (#10274 <https://github.com/fish-shell/fish-
shell/issues/10274>).
* Measuring a command with time now considers the time taken for command
substitution (#9100 <https://github.com/fish-shell/fish-shell/is-
sues/9100>).
* fish_add_path now automatically enables verbose mode when used interac-
tively (in the command line), in an effort to be clearer about what it
does (#10532 <https://github.com/fish-shell/fish-shell/issues/10532>).
* fish no longer adopts TTY modes of failed commands (#10603
<https://github.com/fish-shell/fish-shell/issues/10603>).
* complete -e cmd now prevents autoloading completions for cmd (#6716
<https://github.com/fish-shell/fish-shell/issues/6716>).
* fish's default color scheme no longer uses the color "blue", as it has
bad contrast against the background in a few terminal's default palettes
(#10758 <https://github.com/fish-shell/fish-shell/issues/10758>, #10786
<https://github.com/fish-shell/fish-shell/issues/10786>) The color scheme
will not be upgraded for existing installs. If you want, you should se-
lect it again via fish_config.
* Command lines which are larger than the terminal are now displayed cor-
rectly, instead of multiple blank lines being displayed (#7296
<https://github.com/fish-shell/fish-shell/issues/7296>).
* Prompts that use external commands will no longer produce an infinite
loop if the command crashes (#9796 <https://github.com/fish-shell/fish-
shell/issues/9796>).
* The output of jobs shows "-" for jobs that have the same process group ID
as the fish process, rather than "-2" (#10833 <https://github.com/fish-
shell/fish-shell/issues/10833>).
* Job expansion (%1 syntax) works properly for jobs that are a mixture of
external commands and functions (#10832 <https://github.com/fish-
shell/fish-shell/issues/10832>).
* Command lines which have more lines than the terminal can be displayed
and edited correctly (#10827 <https://github.com/fish-shell/fish-
shell/issues/10827>).
* Functions that have been erased are no longer highlighted as valid com-
mands (#10866 <https://github.com/fish-shell/fish-shell/issues/10866>).
* not, time, and variable assignments (that is not time a=b env) is cor-
rectly recognized as valid syntax (#10890 <https://github.com/fish-
shell/fish-shell/issues/10890>).
* The Web-based configuration removes old right-hand-side prompts again,
fixing a regression in fish 3.4.0 (#10675 <https://github.com/fish-
shell/fish-shell/issues/10675>).
* Further protection against programs which crash and leave the terminal in
an inconsistent state (#10834 <https://github.com/fish-shell/fish-
shell/issues/10834>, #11038 <https://github.com/fish-shell/fish-shell/is-
sues/11038>).
* A workaround for git being very slow on macOS has been applied, improving
performance after a fresh boot (#10535 <https://github.com/fish-
shell/fish-shell/issues/10535>).
New or improved bindings
* When the cursor is on a command that resolves to an executable script,
alt-o will now open that script in your editor (#10266
<https://github.com/fish-shell/fish-shell/issues/10266>).
* During up-arrow history search, shift-delete will delete the current
search item and move to the next older item. Previously this was only
supported in the history pager.
* shift-delete will also remove the currently-displayed autosuggestion from
history, and remove it as a suggestion.
* ctrl-Z (also known as ctrl-shift-z) is now bound to redo.
* Some improvements to the alt-e binding which edits the command line in an
external editor:
* The editor's cursor position is copied back to fish. This is currently
supported for Vim and Kakoune.
* Cursor position synchronization is only supported for a set of known
editors, which are now also detected in aliases which use complete
--wraps. For example, use complete --wraps my-vim vim to synchronize
cursors when EDITOR=my-vim.
* Multiline commands are indented before being sent to the editor, which
matches how they are displayed in fish.
* The ...-path-component bindings, like backward-kill-path-component, now
treat # as part of a path component (#10271 <https://github.com/fish-
shell/fish-shell/issues/10271>).
* Bindings like alt-l that print output in between prompts now work cor-
rectly with multiline commandlines.
* alt-d on an empty command line lists the directory history again. This
restores the behavior of version 2.1.
* history-prefix-search-backward and -forward now maintain the cursor posi-
tion, instead of moving the cursor to the end of the command line (#10430
<https://github.com/fish-shell/fish-shell/issues/10430>).
* The following keys have refined behavior if the terminal supports the new
keyboard encodings:
* shift-enter now inserts a newline instead of executing the command
line.
* ctrl-backspace now deletes the last word instead of only one character
(#10741 <https://github.com/fish-shell/fish-shell/issues/10741>).
* ctrl-delete deletes the next word (same as alt-d).
* New special input functions:
* forward-char-passive and backward-char-passive are like their non-pas-
sive variants but do not accept autosuggestions or move focus in the
completion pager (#10398 <https://github.com/fish-shell/fish-shell/is-
sues/10398>).
* forward-token, backward-token, kill-token, and backward-kill-token are
similar to the *-bigword variants but for the whole argument token
(which includes escaped spaces) (#2014 <https://github.com/fish-
shell/fish-shell/issues/2014>).
* clear-commandline, which merely clears the command line, as an alterna-
tive to cancel-commandline which prints ^C and a new prompt (#10213
<https://github.com/fish-shell/fish-shell/issues/10213>).
* The accept-autosuggestion special input function now returns false when
there was nothing to accept (#10608 <https://github.com/fish-shell/fish-
shell/issues/10608>).
* Vi mode has seen some improvements but continues to suffer from the lack
of people working on it.
* New default cursor shapes for insert and replace mode.
* ctrl-n in insert mode accepts autosuggestions (#10339
<https://github.com/fish-shell/fish-shell/issues/10339>).
* Outside insert mode, the cursor will no longer be placed beyond the
last character on the commandline.
* When the cursor is at the end of the commandline, a single l will ac-
cept an autosuggestion (#10286 <https://github.com/fish-shell/fish-
shell/issues/10286>).
* The cursor position after pasting (p) has been corrected.
* Added an additional binding, _, for moving to the beginning of the line
(#10720 <https://github.com/fish-shell/fish-shell/issues/10720>).
* When the cursor is at the start of a line, escaping from insert mode no
longer moves the cursor to the previous line.
* Added bindings for clipboard interaction, like ",+,p and ",+,y,y.
* Deleting in visual mode now moves the cursor back, matching vi (#10394
<https://github.com/fish-shell/fish-shell/issues/10394>).
* The ;, ,, v, V, I, and gU bindings work in visual mode (#10601
<https://github.com/fish-shell/fish-shell/issues/10601>, #10648
<https://github.com/fish-shell/fish-shell/issues/10648>).
* Support % motion (#10593 <https://github.com/fish-shell/fish-shell/is-
sues/10593>).
* ctrl-k to remove the contents of the line beyond the cursor in all
modes (#10648 <https://github.com/fish-shell/fish-shell/issues/10648>).
* Support ab and ib vi text objects. New input functions are introduced
jump-{to,till}-matching-bracket (#1842 <https://github.com/fish-
shell/fish-shell/issues/1842>).
* The E binding now correctly handles the last character of the word, by
jumping to the next word (#9700 <https://github.com/fish-shell/fish-
shell/issues/9700>).
Completions
* Command-specific tab completions may now offer results whose first char-
acter is a period. For example, it is now possible to tab-complete git
add for files with leading periods. The default file completions hide
these files, unless the token itself has a leading period (#3707
<https://github.com/fish-shell/fish-shell/issues/3707>).
* Option completion now uses fuzzy subsequence filtering, just like non-op-
tion completion (#830 <https://github.com/fish-shell/fish-shell/is-
sues/830>). This means that --fb may be completed to --foobar if there
is no better match.
* Completions that insert an entire token now use quotes instead of back-
slashes to escape special characters (#5433 <https://github.com/fish-
shell/fish-shell/issues/5433>).
* Normally, file name completions start after the last : or = in a token.
This helps commands like rsync --files-from=. This special meaning can
now disabled by escaping these separators as \: and \=. This matches
Bash's behavior. Note that this escaping is usually not necessary since
the completion engine already tries to guess whether the separator is ac-
tually part of a file name.
* Various new completion scripts and numerous updates to existing ones.
* Completions could hang if the PAGER environment variable was sent to cer-
tain editors on macOS, FreeBSD and some other platforms. This has been
fixed (#10820 <https://github.com/fish-shell/fish-shell/issues/10820>).
* Generated completions are now stored in $XDG_CACHE_HOME/fish or
~/.cache/fish by default (#10369 <https://github.com/fish-shell/fish-
shell/issues/10369>)
* A regression in fish 3.1, where completing a command line could change it
completely, has been fixed (#10904 <https://github.com/fish-shell/fish-
shell/issues/10904>).
Improved terminal support
* fish now marks the prompt and command-output regions (via OSC 133) to en-
able terminal shell integration (#10352 <https://github.com/fish-
shell/fish-shell/issues/10352>). Shell integration shortcuts can scroll
to the next/previous prompt or show the last command output in a pager.
* fish now reports the working directory (via OSC 7) unconditionally in-
stead of only for some terminals (#9955 <https://github.com/fish-
shell/fish-shell/issues/9955>).
* fish now sets the terminal window title (via OSC 0) unconditionally in-
stead of only for some terminals (#10037 <https://github.com/fish-
shell/fish-shell/issues/10037>).
* Focus reporting in tmux is no longer disabled on the first prompt.
* Focus reporting is now disabled during commands run inside key bindings
(#6942 <https://github.com/fish-shell/fish-shell/issues/6942>).
* Cursor changes are applied to all terminals that support them, and the
list of specifically-supported terminals has been removed (#10693
<https://github.com/fish-shell/fish-shell/issues/10693>).
* If it cannot find the terminfo entry given by TERM environment variable,
fish will now use an included xterm-256color definition to match the vast
majority of current terminal emulators (#10905 <https://github.com/fish-
shell/fish-shell/issues/10905>). If you need to have a specific terminfo
profile for your terminal's TERM variable, install it into the terminfo
database.
* Further improvements to the correct display of prompts which fill the
width of the terminal (#8164 <https://github.com/fish-shell/fish-
shell/issues/8164>).
Other improvements
* status gained a build-info subcommand, to print information on how fish
was built, to help with debugging (#10896 <https://github.com/fish-
shell/fish-shell/issues/10896>).
* fish_indent will now collapse multiple empty lines into one (#10325
<https://github.com/fish-shell/fish-shell/issues/10325>).
* fish_indent now preserves the modification time of files if there were no
changes (#10624 <https://github.com/fish-shell/fish-shell/issues/10624>).
* Performance in launching external processes has been improved for many
cases (#10869 <https://github.com/fish-shell/fish-shell/issues/10869>).
* Performance and interactivity under Windows Subsystem for Linux has been
improved, with a workaround for Windows-specific locations being appended
to $PATH by default (#10506 <https://github.com/fish-shell/fish-shell/is-
sues/10506>).
* On macOS, paths from /etc/paths and /etc/manpaths containing colons are
handled correctly (#10684 <https://github.com/fish-shell/fish-shell/is-
sues/10684>).
* Additional filesystems such as AFS are properly detected as remote, which
avoids certain hangs due to expensive filesystem locks (#10818
<https://github.com/fish-shell/fish-shell/issues/10818>).
* A spurious error when launching multiple instances of fish for the first
time has been removed (#10813 <https://github.com/fish-shell/fish-
shell/issues/10813>).
For distributors
fish has been ported to Rust. This means a significant change in dependen-
cies, which are listed in the README. In short, Rust 1.70 or greater is re-
quired, and a C++ compiler is no longer needed (although a C compiler is
still required, for some C glue code and the tests).
CMake remains the recommended build system, because of cargo's limited sup-
port for installing support files. Version 3.5 remains the minimum sup-
ported version. The Xcode generator for CMake is not supported any longer
(#9924 <https://github.com/fish-shell/fish-shell/issues/9924>). CMake
builds default to optimized release builds (#10799
<https://github.com/fish-shell/fish-shell/issues/10799>).
fish no longer depends on the ncurses library, but still uses a terminfo
database. When packaging fish, please add a dependency on the package con-
taining your terminfo database instead of curses.
The test target was removed as it can no longer be defined in new CMake
versions. Use make fish_run_tests. Any existing test target will not print
output if it fails (#11116 <https://github.com/fish-shell/fish-shell/is-
sues/11116>).
The Web-based configuration has been rewritten to use Alpine.js (#9554
<https://github.com/fish-shell/fish-shell/issues/9554>).
----
fish 4.0b1 (released December 17, 2024)
A number of improvements were included in fish 4.0.0 following the beta re-
lease of 4.0b1. These include fixes for regressions, improvements to com-
pletions and documentation, and the removal of a small number of problem-
atic changes.
The full list of fixed issues can be found on the GitHub milestone page for
4.0-final <https://github.com/fish-shell/fish-shell/milestone/43>.
----
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
<https://github.com/fish-shell/fish-shell/issues/10190>).
* Wildcards (*) will no longer sometimes generate paths that did not exist
(#10205 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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 other-
wise modified (#10318 <https://github.com/fish-shell/fish-shell/is-
sues/10318>).
* The warning for when a builtin returns a negative exit code was improved,
now mentioning the original status (#10187 <https://github.com/fish-
shell/fish-shell/issues/10187>).
* Added completions for
* cobra-cli (#10293 <https://github.com/fish-shell/fish-shell/is-
sues/10293>)
* dmidecode (#10368 <https://github.com/fish-shell/fish-shell/is-
sues/10368>)
* mycli (#10309 <https://github.com/fish-shell/fish-shell/issues/10309>)
* ollama (#10327 <https://github.com/fish-shell/fish-shell/issues/10327>)
* pstree (#10317 <https://github.com/fish-shell/fish-shell/issues/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, de-
tailed below. Although work continues on the porting of fish internals 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 remain C++ programs.
Notable improvements and fixes
* Improvements to the history pager, including:
* The history pager will now also attempt subsequence matches (#9476
<https://github.com/fish-shell/fish-shell/issues/9476>), so you can
find a command line like git log 3.6.1..Integration_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 <https://github.com/fish-
shell/fish-shell/issues/10005>). This makes it nicer to search some-
thing with up 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 editing the
command you tried to find right away (#9934 <https://github.com/fish-
shell/fish-shell/issues/9934>).
* Performance improvements for command completions and globbing, where sup-
ported by the operating system, especially on slow filesystems such as
NFS (#9891 <https://github.com/fish-shell/fish-shell/issues/9891>, #9931
<https://github.com/fish-shell/fish-shell/issues/9931>, #10032
<https://github.com/fish-shell/fish-shell/issues/10032>, #10052
<https://github.com/fish-shell/fish-shell/issues/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 possible.
The timeout can be set via the new fish_sequence_key_delay_ms variable (-
#7401 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/10080>). Users that set
.dircolors should manually import it using other means. Typically this
would be set -gx LS_COLORS (dircolors -c .dircolors | string split '
')[3]
Scripting improvements
* Running exit with a negative number no longer crashes fish (#9659
<https://github.com/fish-shell/fish-shell/issues/9659>).
* fish --command will now return a non-zero status if parsing failed (#9888
<https://github.com/fish-shell/fish-shell/issues/9888>).
* The jobs builtin will now escape the commands it prints (#9808
<https://github.com/fish-shell/fish-shell/issues/9808>).
* string repeat no longer overflows if the count is a multiple of the chunk
size (#9900 <https://github.com/fish-shell/fish-shell/issues/9900>).
* The builtin builtin will now properly error out with invalid arguments
instead of doing nothing and returning true (#9942
<https://github.com/fish-shell/fish-shell/issues/9942>).
* command time in a pipeline is allowed again, as is command and and com-
mand or (#9985 <https://github.com/fish-shell/fish-shell/issues/9985>).
* exec will now also apply variable overrides, so FOO=bar exec will now set
$FOO correctly (#9995 <https://github.com/fish-shell/fish-shell/is-
sues/9995>).
* umask will now handle empty symbolic modes correctly, like umask
u=,g=rwx,o= (#10177 <https://github.com/fish-shell/fish-shell/is-
sues/10177>).
* Improved error messages for errors occurring in command substitutions (-
#10054 <https://github.com/fish-shell/fish-shell/issues/10054>).
Interactive improvements
* read no longer enables bracketed paste so it doesn't stay enabled in com-
bined commandlines like mysql -p(read --silent) (#8285
<https://github.com/fish-shell/fish-shell/issues/8285>).
* Vi mode now uses fish_cursor_external to set the cursor shape for exter-
nal commands (#4656 <https://github.com/fish-shell/fish-shell/is-
sues/4656>).
* Opening the history search in vi mode switches to insert mode correctly
(#10141 <https://github.com/fish-shell/fish-shell/issues/10141>).
* Vi mode cursor shaping is now enabled in iTerm2 (#9698
<https://github.com/fish-shell/fish-shell/issues/9698>).
* Completing commands as root includes commands not owned by root, fixing a
regression introduced in fish 3.2.0 (#9699 <https://github.com/fish-
shell/fish-shell/issues/9699>).
* Selection uses fish_color_selection for the foreground and background
colors, as intended, rather than just the background (#9717
<https://github.com/fish-shell/fish-shell/issues/9717>).
* The completion pager will no longer sometimes skip the last entry when
moving through a long list (#9833 <https://github.com/fish-shell/fish-
shell/issues/9833>).
* The interactive history delete interface now allows specifying index
ranges like "1..5" (#9736 <https://github.com/fish-shell/fish-shell/is-
sues/9736>), and history delete --exact now properly saves the history (-
#10066 <https://github.com/fish-shell/fish-shell/issues/10066>).
* Command completion will now call the stock manpath on macOS, instead of a
potential Homebrew version. This prevents awkward error messages (#9817
<https://github.com/fish-shell/fish-shell/issues/9817>).
* the redo special input function restores the pre-undo cursor position.
* A new bind function history-pager-delete, bound to shift-delete by de-
fault, will delete the currently-selected history pager item from history
(#9454 <https://github.com/fish-shell/fish-shell/issues/9454>).
* fish_key_reader will now use printable characters as-is, so pressing
"A<paragraph>" no longer leads to it telling you to bind \u00F6 (#9986
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/10045>).
* The repaint-mode binding will now only move the cursor if there is re-
painting to be done. This fixes alt combination bindings in vi mode (-
#7910 <https://github.com/fish-shell/fish-shell/issues/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 elimi-
nates visible flicker unless the terminal is very slow (#10044
<https://github.com/fish-shell/fish-shell/issues/10044>).
* The alias convenience function has better support for commands with un-
usual characters, like + (#8720 <https://github.com/fish-shell/fish-
shell/issues/8720>).
* A longstanding issue where items in the pager would sometimes display
without proper formatting has been fixed (#9617 <https://github.com/fish-
shell/fish-shell/issues/9617>).
* The alt-l binding, which lists the directory of the token under the cur-
sor, correctly expands tilde (~) to the home directory (#9954
<https://github.com/fish-shell/fish-shell/issues/9954>).
* Various fish utilities that use an external pager will now try a selec-
tion 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 avail-
able (#10074 <https://github.com/fish-shell/fish-shell/issues/10074>).
* Command-specific tab completions may now offer results whose first char-
acter is a period. For example, it is now possible to tab-complete git
add for files with leading periods. The default file completions hide
these files, unless the token itself has a leading period (#3707
<https://github.com/fish-shell/fish-shell/issues/3707>).
Improved prompts
* The default theme now only uses named colors, so it will track the termi-
nal's palette (#9913 <https://github.com/fish-shell/fish-shell/is-
sues/9913>).
* The Dracula theme has now been synced with upstream (#9807
<https://github.com/fish-shell/fish-shell/issues/9807>); use fish_config
to re-apply it to pick up the changes.
* fish_vcs_prompt now also supports fossil (#9497 <https://github.com/fish-
shell/fish-shell/issues/9497>).
* Prompts which display the working directory using the prompt_pwd function
correctly display directories beginning with dashes (#10169
<https://github.com/fish-shell/fish-shell/issues/10169>).
Completions
* Added completions for:
* age and age-keygen (#9813 <https://github.com/fish-shell/fish-shell/is-
sues/9813>)
* airmon-ng (#10116 <https://github.com/fish-shell/fish-shell/is-
sues/10116>)
* ar (#9720 <https://github.com/fish-shell/fish-shell/issues/9720>)
* blender (#9905 <https://github.com/fish-shell/fish-shell/issues/9905>)
* bws (#10165 <https://github.com/fish-shell/fish-shell/issues/10165>)
* calendar (#10138 <https://github.com/fish-shell/fish-shell/is-
sues/10138>)
* checkinstall (#10106 <https://github.com/fish-shell/fish-shell/is-
sues/10106>)
* crc (#10034 <https://github.com/fish-shell/fish-shell/issues/10034>)
* doctl
* gimp (#9904 <https://github.com/fish-shell/fish-shell/issues/9904>)
* gojq (#9740 <https://github.com/fish-shell/fish-shell/issues/9740>)
* horcrux (#9922 <https://github.com/fish-shell/fish-shell/issues/9922>)
* ibmcloud (#10004 <https://github.com/fish-shell/fish-shell/is-
sues/10004>)
* iwctl (#6884 <https://github.com/fish-shell/fish-shell/issues/6884>)
* java_home (#9998 <https://github.com/fish-shell/fish-shell/is-
sues/9998>)
* krita (#9903 <https://github.com/fish-shell/fish-shell/issues/9903>)
* oc (#10034 <https://github.com/fish-shell/fish-shell/issues/10034>)
* qjs (#9723 <https://github.com/fish-shell/fish-shell/issues/9723>)
* qjsc (#9731 <https://github.com/fish-shell/fish-shell/issues/9731>)
* rename (#10136 <https://github.com/fish-shell/fish-shell/issues/10136>)
* rpm-ostool (#9669 <https://github.com/fish-shell/fish-shell/is-
sues/9669>)
* smerge (#10135 <https://github.com/fish-shell/fish-shell/issues/10135>)
* userdel (#10056 <https://github.com/fish-shell/fish-shell/is-
sues/10056>)
* watchexec (#10027 <https://github.com/fish-shell/fish-shell/is-
sues/10027>)
* wpctl (#10043 <https://github.com/fish-shell/fish-shell/issues/10043>)
* xxd (#10137 <https://github.com/fish-shell/fish-shell/issues/10137>)
* zabbix (#9647 <https://github.com/fish-shell/fish-shell/issues/9647>)
* The zfs completions no longer print errors about setting a read-only
variable (#9705 <https://github.com/fish-shell/fish-shell/issues/9705>).
* The kitty completions have been removed in favor of keeping them upstream
(#9750 <https://github.com/fish-shell/fish-shell/issues/9750>).
* git completions now support aliases that reference other aliases (#9992
<https://github.com/fish-shell/fish-shell/issues/9992>).
* The gw and gradlew completions are loaded properly (#10127
<https://github.com/fish-shell/fish-shell/issues/10127>).
* Improvements to many other completions.
* Improvements to the manual page completion generator (#9787
<https://github.com/fish-shell/fish-shell/issues/9787>, #9814
<https://github.com/fish-shell/fish-shell/issues/9814>, #9961
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-
shell/fish-shell/issues/9828>).
* Updates to the German translations (#9824 <https://github.com/fish-
shell/fish-shell/issues/9824>).
* The colors of the Nord theme better match their official style (#10168
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/10162>).
* The CMake configure step will now also look for libterminfo as an alter-
native name for libtinfo, as used in NetBSD curses (#9794
<https://github.com/fish-shell/fish-shell/issues/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 minor
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 wildcards
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 external pro-
gram 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
<https://github.com/fish-shell/fish-shell/issues/9468>).
* abbr --add --universal now warns about --universal being non-functional,
to make it easier to detect old-style abbr calls (#9475
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/9460>).
Scripting improvements
* abbr --list no longer escapes the abbr name, which is necessary to be
able to pass it to abbr --erase (#9470 <https://github.com/fish-
shell/fish-shell/issues/9470>).
* read will now print an error if told to set a read-only variable, instead
of silently doing nothing (#9346 <https://github.com/fish-shell/fish-
shell/issues/9346>).
* set_color -v no longer crashes fish (#9640 <https://github.com/fish-
shell/fish-shell/issues/9640>).
Interactive improvements
* Using fish_vi_key_bindings in combination with fish's --no-config mode
works without locking up the shell (#9443 <https://github.com/fish-
shell/fish-shell/issues/9443>).
* The history pager now uses more screen space, usually half the screen (-
#9458 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/2613>, #9473
<https://github.com/fish-shell/fish-shell/issues/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 prefer-
ence to $PAGER (#9488 <https://github.com/fish-shell/fish-shell/is-
sues/9488>).
* ctrl-g closes the history pager, like other shells (#9484
<https://github.com/fish-shell/fish-shell/issues/9484>).
* The documentation for the :, [ and . builtin commands can now be looked
up with man (#9552 <https://github.com/fish-shell/fish-shell/is-
sues/9552>).
* fish no longer crashes when searching history for non-ASCII codepoints
case-insensitively (#9628 <https://github.com/fish-shell/fish-shell/is-
sues/9628>).
* The alt-s binding will now also use please if available (#9635
<https://github.com/fish-shell/fish-shell/issues/9635>).
* Themes that don't specify every color option can be installed correctly
in the Web-based configuration (#9590 <https://github.com/fish-
shell/fish-shell/issues/9590>).
* Compatibility with Midnight Commander's prompt integration has been im-
proved (#9540 <https://github.com/fish-shell/fish-shell/issues/9540>).
* A spurious error, noted when using fish in Google Drive directories under
WSL 2, has been silenced (#9550 <https://github.com/fish-shell/fish-
shell/issues/9550>).
* Using read in fish_greeting or similar functions will not trigger an in-
finite loop (#9564 <https://github.com/fish-shell/fish-shell/is-
sues/9564>).
* Compatibility when upgrading from old versions of fish (before 3.4.0) has
been improved (#9569 <https://github.com/fish-shell/fish-shell/is-
sues/9569>).
Improved prompts
* The git prompt will compute the stash count to be used independently of
the informative status (#9572 <https://github.com/fish-shell/fish-
shell/issues/9572>).
Completions
* Added completions for:
* apkanalyzer (#9558 <https://github.com/fish-shell/fish-shell/is-
sues/9558>)
* neovim (#9543 <https://github.com/fish-shell/fish-shell/issues/9543>)
* otool
* pre-commit (#9521 <https://github.com/fish-shell/fish-shell/is-
sues/9521>)
* proxychains (#9486 <https://github.com/fish-shell/fish-shell/is-
sues/9486>)
* scrypt (#9583 <https://github.com/fish-shell/fish-shell/issues/9583>)
* stow (#9571 <https://github.com/fish-shell/fish-shell/issues/9571>)
* trash and helper utilities trash-empty, trash-list, trash-put,
trash-restore (#9560 <https://github.com/fish-shell/fish-shell/is-
sues/9560>)
* ssh-copy-id (#9675 <https://github.com/fish-shell/fish-shell/is-
sues/9675>)
* Improvements to many completions, including the speed of completing di-
rectories in WSL 2 (#9574 <https://github.com/fish-shell/fish-shell/is-
sues/9574>).
* Completions using __fish_complete_suffix are now offered in the correct
order, fixing a regression in 3.6.0 (#8924 <https://github.com/fish-
shell/fish-shell/issues/8924>).
* git completions for git-foo-style commands was restored, fixing a regres-
sion in 3.6.0 (#9457 <https://github.com/fish-shell/fish-shell/is-
sues/9457>).
* File completion now offers ../ and ./ again, fixing a regression in 3.6.0
(#9477 <https://github.com/fish-shell/fish-shell/issues/9477>).
* The behaviour of completions using __fish_complete_path matches standard
path completions (#9285 <https://github.com/fish-shell/fish-shell/is-
sues/9285>).
Other improvements
* Improvements and corrections to the documentation.
For distributors
* fish 3.6.1 builds correctly on Cygwin (#9502 <https://github.com/fish-
shell/fish-shell/issues/9502>).
----
fish 3.6.0 (released January 7, 2023)
Notable improvements and fixes
* By default, ctrl-r now opens the command history in the pager (#602
<https://github.com/fish-shell/fish-shell/issues/602>). This is fully
searchable and syntax-highlighted, as an alternative to the incremental
search seen in other shells. The new special input function history-pager
has been added for custom bindings.
* Abbreviations are more flexible (#9313 <https://github.com/fish-
shell/fish-shell/issues/9313>, #5003 <https://github.com/fish-shell/fish-
shell/issues/5003>, #2287 <https://github.com/fish-shell/fish-shell/is-
sues/2287>):
* They may optionally replace tokens anywhere on the command line, in-
stead 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
<https://github.com/fish-shell/fish-shell/issues/9057>):
> touch foo
> sleep 10
> path mtime --relative foo
10
* string gained a new shorten subcommand to shorten strings to a given vis-
ible width (#9156 <https://github.com/fish-shell/fish-shell/is-
sues/9156>):
> string shorten --max 10 "Hello this is a long string"
Hello thia|
* 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 <https://github.com/fish-shell/fish-shell/is-
sues/3589>).
* fish will now mark the extent of many errors with a squiggly line, in-
stead of just a caret (^) at the beginning (#9130
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-
shell/fish-shell/issues/9255>).
* set --erase can now be used with multiple scopes at once, like set -efglU
foo (#7711 <https://github.com/fish-shell/fish-shell/issues/7711>, #9280
<https://github.com/fish-shell/fish-shell/issues/9280>).
* status gained a new subcommand, current-commandline, which retrieves the
entirety of the currently-executing command line when called from a func-
tion during execution. This allows easier job introspection (#8905
<https://github.com/fish-shell/fish-shell/issues/8905>, #9296
<https://github.com/fish-shell/fish-shell/issues/9296>).
Deprecations and removed features
* The \x and \X escape syntax is now equivalent. \xAB previously behaved
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
<https://github.com/fish-shell/fish-shell/issues/9247>, #9245
<https://github.com/fish-shell/fish-shell/issues/9245>, #1352
<https://github.com/fish-shell/fish-shell/issues/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") instead
of just checking if it is defined. This allows specifically turning fea-
tures off without having to erase variables, such as via universal vari-
ables. If you have defined a variable to a different value and expect it
to count as true, you need to change it (#9274 <https://github.com/fish-
shell/fish-shell/issues/9274>). For example, set -g
__fish_git_prompt_show_informative_status 0 previously 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 uni-
versal 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 using
--min-args, --max-args or for commands that take no options (but might in
future) (#9006 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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 un-
set (#9129 <https://github.com/fish-shell/fish-shell/issues/9129>).
* math produces an error for division-by-zero, as well as augmenting some
errors with their extent (#9190 <https://github.com/fish-shell/fish-
shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/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 noticeable
on NetBSD (#9085 <https://github.com/fish-shell/fish-shell/issues/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 en-
try), this should often result in a fully or almost fully usable terminal
(#9026 <https://github.com/fish-shell/fish-shell/issues/9026>).
* A new variable, fish_cursor_selection_mode, can be used to configure
whether the command line selection includes the character under the cur-
sor (inclusive) or not (exclusive). The new default is exclusive; use set
fish_cursor_selection_mode inclusive to get the previous behavior back (-
#7762 <https://github.com/fish-shell/fish-shell/issues/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 ter-
minal (#9105 <https://github.com/fish-shell/fish-shell/issues/9105>, -
#2698 <https://github.com/fish-shell/fish-shell/issues/2698>).
* The complete-and-search binding, used with shift-tab by default, selects
the first item in the results immediately (#9080
<https://github.com/fish-shell/fish-shell/issues/9080>).
* bind output is now syntax-highlighted when used interactively.
* alt-h (the default __fish_man_page binding) does a better job of showing
the manual page of the command under cursor (#9020
<https://github.com/fish-shell/fish-shell/issues/9020>).
* If fish_color_valid_path contains an actual color instead of just modi-
fiers, those will be used for valid paths even if the underlying color
isn't "normal" (#9159 <https://github.com/fish-shell/fish-shell/is-
sues/9159>).
* The key combination for the QUIT terminal sequence, often ctrl-\ (\x1c),
can now be used as a binding (#9234 <https://github.com/fish-shell/fish-
shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/3741>, #9172 <https://github.com/fish-shell/fish-shell/issues/9172>)
* When running fish on a remote system (such as inside SSH or a container),
ctrl-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
<https://github.com/fish-shell/fish-shell/issues/9197>, #9215
<https://github.com/fish-shell/fish-shell/issues/9215>).
* fish's builtins now handle keyboard interrupts (ctrl-c) correctly (#9266
<https://github.com/fish-shell/fish-shell/issues/9266>).
Completions
* Added completions for:
* ark
* asciinema (#9257 <https://github.com/fish-shell/fish-shell/is-
sues/9257>)
* clojure (#9272 <https://github.com/fish-shell/fish-shell/issues/9272>)
* csh
* direnv (#9268 <https://github.com/fish-shell/fish-shell/issues/9268>)
* dive (#9082 <https://github.com/fish-shell/fish-shell/issues/9082>)
* dolphin
* dua (#9277 <https://github.com/fish-shell/fish-shell/issues/9277>)
* efivar (#9318 <https://github.com/fish-shell/fish-shell/issues/9318>)
* eg
* es (#9388 <https://github.com/fish-shell/fish-shell/issues/9388>)
* firefox-developer-edition and firefox (#9090 <https://github.com/fish-
shell/fish-shell/issues/9090>)
* fortune (#9177 <https://github.com/fish-shell/fish-shell/issues/9177>)
* kb
* kind (#9110 <https://github.com/fish-shell/fish-shell/issues/9110>)
* konsole
* ksh
* loadkeys (#9312 <https://github.com/fish-shell/fish-shell/issues/9312>)
* okular
* op (#9300 <https://github.com/fish-shell/fish-shell/issues/9300>)
* ouch (#9405 <https://github.com/fish-shell/fish-shell/issues/9405>)
* pix
* readelf (#8746 <https://github.com/fish-shell/fish-shell/issues/8746>,
#9386 <https://github.com/fish-shell/fish-shell/issues/9386>)
* qshell
* rc
* sad (#9145 <https://github.com/fish-shell/fish-shell/issues/9145>)
* tcsh
* toot
* tox (#9078 <https://github.com/fish-shell/fish-shell/issues/9078>)
* wish
* xed
* xonsh (#9389 <https://github.com/fish-shell/fish-shell/issues/9389>)
* xplayer
* xreader
* xviewer
* yash (#9391 <https://github.com/fish-shell/fish-shell/issues/9391>)
* zig (#9083 <https://github.com/fish-shell/fish-shell/issues/9083>)
* Improvements to many completions, including making cd completion much
faster (#9220 <https://github.com/fish-shell/fish-shell/issues/9220>).
* Completion of tilde (~) works properly even when the file name contains
an escaped character (#9073 <https://github.com/fish-shell/fish-shell/is-
sues/9073>).
* fish no longer loads completions if the command is used via a relative
path and is not in PATH (#9133 <https://github.com/fish-shell/fish-
shell/issues/9133>).
* fish no longer completes inside of comments (#9320
<https://github.com/fish-shell/fish-shell/issues/9320>).
Improved terminal support
* Opening help on WSL now uses PowerShell to open the browser if available,
removing some awkward UNC path errors (#9119 <https://github.com/fish-
shell/fish-shell/issues/9119>).
Other improvements
* The Web-based configuration tool now works on systems with IPv6 disabled
(#3857 <https://github.com/fish-shell/fish-shell/issues/3857>).
* Aliases can ignore arguments by ending them with # (#9199
<https://github.com/fish-shell/fish-shell/issues/9199>).
* string is now faster when reading large strings from stdin (#9139
<https://github.com/fish-shell/fish-shell/issues/9139>).
* string repeat uses less memory and is faster. (#9124
<https://github.com/fish-shell/fish-shell/issues/9124>)
* Builtins are much faster when writing to a pipe or file. (#9229
<https://github.com/fish-shell/fish-shell/issues/9229>).
* Performance improvements to highlighting (#9180 <https://github.com/fish-
shell/fish-shell/issues/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 correctly
if the line contains multiple instances of that text (#9066
<https://github.com/fish-shell/fish-shell/issues/9066>).
* process-exit and job-exit events are now generated for all background
jobs, including those launched from event handlers (#9096
<https://github.com/fish-shell/fish-shell/issues/9096>).
* A crash when completing a token that contained both a potential glob and
a quoted variable expansion was fixed (#9137 <https://github.com/fish-
shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/9181>).
* The "Disco" sample prompt no longer prints an error in some working di-
rectories (#9164 <https://github.com/fish-shell/fish-shell/issues/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 al-
ways 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 <https://github.com/fish-shell/fish-shell/issues/9143>).
* printf no longer tries to interpret the first argument as an option (-
#9132 <https://github.com/fish-shell/fish-shell/issues/9132>).
* Interactive read in scripts will now have the correct keybindings again
(#9227 <https://github.com/fish-shell/fish-shell/issues/9227>).
* A possible stack overflow when recursively evaluating substitutions has
been fixed (#9302 <https://github.com/fish-shell/fish-shell/is-
sues/9302>).
* A crash with relative $CDPATH has been fixed (#9407
<https://github.com/fish-shell/fish-shell/issues/9407>).
* printf now properly fills extra %d specifiers with 0 even on macOS and
BSD (#9321 <https://github.com/fish-shell/fish-shell/issues/9321>).
* fish_key_reader now correctly exits when receiving a SIGHUP (like after
closing the terminal) (#9309 <https://github.com/fish-shell/fish-
shell/issues/9309>).
* fish_config theme save now works as documented instead of erroring out (-
#9088 <https://github.com/fish-shell/fish-shell/issues/9088>, #9273
<https://github.com/fish-shell/fish-shell/issues/9273>).
* fish no longer triggers prompts to install command line tools when first
run on macOS (#9343 <https://github.com/fish-shell/fish-shell/is-
sues/9343>).
* fish_git_prompt now quietly fails on macOS if the xcrun cache is not yet
populated (#6625 <https://github.com/fish-shell/fish-shell/issues/6625>),
working around a potential hang.
For distributors
* The vendored PCRE2 sources have been removed. It is recommended to de-
clare PCRE2 as a dependency when packaging fish. If the CMake variable
FISH_USE_SYSTEM_PCRE2 is false, fish will now download and build PCRE2
from the official repo (#8355 <https://github.com/fish-shell/fish-
shell/issues/8355>, #8363 <https://github.com/fish-shell/fish-shell/is-
sues/8363>). Note this variable defaults to true if PCRE2 is found in-
stalled 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 <https://github.com/fish-
shell/fish-shell/issues/8981>).
* printf returns a better error when used with arguments interpreted as oc-
tal numbers (#9035 <https://github.com/fish-shell/fish-shell/is-
sues/9035>).
* history merge when in private mode is now an error, rather than wiping
out other sessions' history (#9050 <https://github.com/fish-shell/fish-
shell/issues/9050>).
* The error message when launching a command that is built for the wrong
architecture on macOS is more helpful (#9052 <https://github.com/fish-
shell/fish-shell/issues/9052>).
* Added completions for:
* choose (#9065 <https://github.com/fish-shell/fish-shell/issues/9065>)
* expect (#9060 <https://github.com/fish-shell/fish-shell/issues/9060>)
* navi (#9064 <https://github.com/fish-shell/fish-shell/issues/9064>)
* qdbus (#9031 <https://github.com/fish-shell/fish-shell/issues/9031>)
* reflector (#9027 <https://github.com/fish-shell/fish-shell/is-
sues/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
<https://github.com/fish-shell/fish-shell/issues/9053>).
* On terminals that emit a CSI u sequence for shift-space, fish inserts a
space instead of printing an error. (#9054 <https://github.com/fish-
shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/9019>).
* Cancelling an initial command (from fish's --init-command option) with
ctrl-c no longer prevents configuration scripts from running (#9024
<https://github.com/fish-shell/fish-shell/issues/9024>).
* The job summary contained extra blank lines if the prompt used multiple
lines, which is now fixed (#9044 <https://github.com/fish-shell/fish-
shell/issues/9044>).
* Using special input functions in bindings, in combination with and/or
conditionals, no longer crashes (#9051 <https://github.com/fish-
shell/fish-shell/issues/9051>).
----
fish 3.5.0 (released June 16, 2022)
Notable improvements and fixes
* A new path builtin command to filter and transform paths (#7659
<https://github.com/fish-shell/fish-shell/issues/7659>, #8958
<https://github.com/fish-shell/fish-shell/issues/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 in-
voking completions, if there is a wildcard in the path component under
the cursor (#954 <https://github.com/fish-shell/fish-shell/issues/954>, -
#8593 <https://github.com/fish-shell/fish-shell/issues/8593>).
* Scripts can now catch and handle the SIGINT and SIGTERM signals, either
via function --on-signal or with trap (#6649 <https://github.com/fish-
shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/8857>, -
#8865 <https://github.com/fish-shell/fish-shell/issues/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 expression
(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 back-
ground and then starting bar as a second job.
Reformatting with fish_indent would already introduce spaces, turning
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-ampersand-nobg-in-to-
ken 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 <https://github.com/fish-shell/fish-
shell/issues/8473>, #3847 <https://github.com/fish-shell/fish-shell/is-
sues/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 un-
known escape sequences. We don't expect anyone to have ever used fish
with such a terminal (#8769 <https://github.com/fish-shell/fish-shell/is-
sues/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
<https://github.com/fish-shell/fish-shell/issues/8781>)
* The meaning of an empty color variable has changed (#8793
<https://github.com/fish-shell/fish-shell/issues/8793>). Previously, 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 vari-
ables - 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 termi-
nal). 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 ac-
cidentally use color that was set before. fish_config has been adjusted
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 pre-
vious fish versions won't be loaded.
* The git prompt in informative mode now defaults to skipping counting un-
tracked 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 indi-
vidual 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
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/9011>, #7918
<https://github.com/fish-shell/fish-shell/issues/7918>, #8979
<https://github.com/fish-shell/fish-shell/issues/8979>).
Scripting improvements
* Quoted command substitution that directly follow a variable expansion
(like echo "$var$(echo x)") no longer affect the variable expansion (-
#8849 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/8611>, #8496
<https://github.com/fish-shell/fish-shell/issues/8496>):
math 5 + 2_123_252
* math's min and max functions now take a variable number of arguments in-
stead of always requiring 2 (#8644 <https://github.com/fish-shell/fish-
shell/issues/8644>, #8646 <https://github.com/fish-shell/fish-shell/is-
sues/8646>):
> math min 8,2,4
2
* read is now faster as the last process in a pipeline (#8552
<https://github.com/fish-shell/fish-shell/issues/8552>).
* string join gained a new --no-empty flag to skip empty arguments (#8774
<https://github.com/fish-shell/fish-shell/issues/8774>, #8351
<https://github.com/fish-shell/fish-shell/issues/8351>).
* read now only triggers the fish_read event, not the fish_prompt event (-
#8797 <https://github.com/fish-shell/fish-shell/issues/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 commands. (#8705
<https://github.com/fish-shell/fish-shell/issues/8705>).
* Some functions shipped with fish printed error messages to standard out-
put, but they now they rightly go to standard error (#8855
<https://github.com/fish-shell/fish-shell/issues/8855>).
* jobs now correctly reports CPU usage as a percentage, instead of as a
number of clock ticks (#8919 <https://github.com/fish-shell/fish-
shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-
shell/fish-shell/issues/8804>).
* less and other interactive commands would occasionally be stopped when
run in a pipeline with fish functions; this has been fixed (#8699
<https://github.com/fish-shell/fish-shell/issues/8699>).
* Case-changing autosuggestions generated mid-token now correctly append
only the suffix, instead of duplicating the token (#8820
<https://github.com/fish-shell/fish-shell/issues/8820>).
* ulimit learned a number of new options for the resource limits available
on Linux, FreeBSD ande NetBSD, and returns a specific warning if the
limit specified is not available on the active operating system (#8823
<https://github.com/fish-shell/fish-shell/issues/8823>, #8786
<https://github.com/fish-shell/fish-shell/issues/8786>).
* The vared command can now successfully edit variables named "tmp" or
"prompt" (#8836 <https://github.com/fish-shell/fish-shell/issues/8836>, -
#8837 <https://github.com/fish-shell/fish-shell/issues/8837>).
* time now emits an error if used after the first command in a pipeline (-
#8841 <https://github.com/fish-shell/fish-shell/issues/8841>).
* fish_add_path now prints a message for skipped non-existent paths when
using the -v flag (#8884 <https://github.com/fish-shell/fish-shell/is-
sues/8884>).
* Since fish 3.2.0, pressing ctrl-d while a command is running would end up
inserting a space into the next commandline, which has been fixed (#8871
<https://github.com/fish-shell/fish-shell/issues/8871>).
* A bug that caused multi-line prompts to be moved down a line when pasting
or switching modes has been fixed (#3481 <https://github.com/fish-
shell/fish-shell/issues/3481>).
* The Web-based configuration system no longer strips too many quotes in
the abbreviation display (#8917 <https://github.com/fish-shell/fish-
shell/issues/8917>, #8918 <https://github.com/fish-shell/fish-shell/is-
sues/8918>).
* Fish started with --no-config will now use the default keybindings (#8493
<https://github.com/fish-shell/fish-shell/issues/8493>)
* When fish inherits a USER environment variable value that doesn't corre-
spond to the current effective user ID, it will now correct it in all
cases (#8879 <https://github.com/fish-shell/fish-shell/issues/8879>, -
#8583 <https://github.com/fish-shell/fish-shell/issues/8583>).
* Fish sets a new EUID variable containing the current effective user id (-
#8866 <https://github.com/fish-shell/fish-shell/issues/8866>).
* history search no longer interprets the search term as an option (#8853
<https://github.com/fish-shell/fish-shell/issues/8853>)
* The status message when a job terminates should no longer be erased by a
multiline prompt (#8817 <https://github.com/fish-shell/fish-shell/is-
sues/8817>)
New or improved bindings
* The alt-s binding will now insert doas instead of sudo if necessary (-
#8942 <https://github.com/fish-shell/fish-shell/issues/8942>).
* The kill-whole-line special input function now kills the newline preced-
ing 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 preserving new-
lines (#8983 <https://github.com/fish-shell/fish-shell/issues/8983>).
* On terminals that emit special sequences for these combinations,
shift-space is bound like space, and ctrl-enter is bound like return (-
#8874 <https://github.com/fish-shell/fish-shell/issues/8874>).
Improved prompts
* A new Astronaut prompt (#8775 <https://github.com/fish-shell/fish-
shell/issues/8775>), a multi-line prompt using plain text reminiscent of
the Starship.rs prompt.
Completions
* Added completions for:
* archlinux-java (#8911 <https://github.com/fish-shell/fish-shell/is-
sues/8911>)
* apk (#8951 <https://github.com/fish-shell/fish-shell/issues/8951>)
* brightnessctl (#8758 <https://github.com/fish-shell/fish-shell/is-
sues/8758>)
* efibootmgr (#9010 <https://github.com/fish-shell/fish-shell/is-
sues/9010>)
* fastboot (#8904 <https://github.com/fish-shell/fish-shell/issues/8904>)
* optimus-manager (#8913 <https://github.com/fish-shell/fish-shell/is-
sues/8913>)
* rclone (#8819 <https://github.com/fish-shell/fish-shell/issues/8819>)
* sops (#8821 <https://github.com/fish-shell/fish-shell/issues/8821>)
* tuned-adm (#8760 <https://github.com/fish-shell/fish-shell/is-
sues/8760>)
* wg-quick (#8687 <https://github.com/fish-shell/fish-shell/issues/8687>)
* complete can now be given multiple --condition options. They will be at-
tempted 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 re-
duce the number of conditions that need to be evaluated (#8536
<https://github.com/fish-shell/fish-shell/issues/8536>, #8967
<https://github.com/fish-shell/fish-shell/issues/8967>).
Improved terminal support
* Working directory reporting is enabled for kitty (#8806
<https://github.com/fish-shell/fish-shell/issues/8806>).
* Changing the cursor shape is now enabled by default in iTerm2 (#3696
<https://github.com/fish-shell/fish-shell/issues/3696>).
For distributors
* libatomic is now correctly detected as necessary when building on RISC-V
(#8850 <https://github.com/fish-shell/fish-shell/issues/8850>, #8851
<https://github.com/fish-shell/fish-shell/issues/8851>).
* In some cases, the build process found the wrong libintl on macOS. This
has been corrected (#5244 <https://github.com/fish-shell/fish-shell/is-
sues/5244>).
* The paths for completions, functions, and configuration snippets now in-
clude subdirectories fish/vendor_completions.d, fish/vendor_functions.d,
and fish/vendor_conf.d (respectively) within XDG_DATA_HOME (or ~/.lo-
cal/share if not defined) (#8887 <https://github.com/fish-shell/fish-
shell/issues/8887>, #7816 <https://github.com/fish-shell/fish-shell/is-
sues/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
<https://github.com/fish-shell/fish-shell/issues/8778>)
* fish builds correctly on NetBSD (#8788 <https://github.com/fish-
shell/fish-shell/issues/8788>) and OpenIndiana (#8780
<https://github.com/fish-shell/fish-shell/issues/8780>).
* nextd-or-forward-word, bound to alt-right by default, was inadvertently
changed to move like forward-bigword. This has been corrected (#8790
<https://github.com/fish-shell/fish-shell/issues/8790>).
* funcsave -q and funcsave --quiet now work correctly (#8830
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-
shell/issues/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 <https://github.com/fish-shell/fish-
shell/issues/8132>). The current theme can be saved with fish_config
theme dump, and custom themes can be added by saving them in ~/.con-
fig/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 scoping vari-
ables and avoids issues with --local, which is actually block-scoped (-
#565 <https://github.com/fish-shell/fish-shell/issues/565>, #8145
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/8182>, #7784
<https://github.com/fish-shell/fish-shell/issues/7784>, #4012
<https://github.com/fish-shell/fish-shell/issues/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_autosuggestion_en-
abled 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
<https://github.com/fish-shell/fish-shell/issues/8376>)
* The fish_git_prompt function, which is included in the default prompts,
now overrides git to avoid running commands set by per-repository con-
figuration. This avoids a potential security issue in some circumstances,
and has been assigned CVE-2022-20001 (#8589 <https://github.com/fish-
shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/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 --features
ampersand-nobg-in-token,qmark-noglob or with a universal variable called
fish_features:
> set -Ua fish_features ampersand-nobg-in-token
* $status is now forbidden as a command, to prevent a surprisingly common
error among new users: Running if $status (#8171
<https://github.com/fish-shell/fish-shell/issues/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 desirable (#8214
<https://github.com/fish-shell/fish-shell/issues/8214>).
* _ is now a reserved keyword (#8342 <https://github.com/fish-shell/fish-
shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/8054>). This allows com-
mands 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 output
capturing groups, excluding the full match. This allows string match to
do simple transformations (#6056 <https://github.com/fish-shell/fish-
shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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 exiting (#8148
<https://github.com/fish-shell/fish-shell/issues/8148>).
* An oversight prevented all syntax checks from running on commands given
to fish -c (#8171 <https://github.com/fish-shell/fish-shell/is-
sues/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 fol-
lowed by a newline (#8197 <https://github.com/fish-shell/fish-shell/is-
sues/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 <https://github.com/fish-shell/fish-shell/is-
sues/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
<https://github.com/fish-shell/fish-shell/issues/8485>).
* List expansion correctly reports an error when used with all zero indexes
(#8213 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/8258>)
* Some error messages occurring after fork, like "text file busy" have been
replaced by bespoke error messages for fish (like "File is currently open
for writing"). This also restores error messages with current glibc ver-
sions that removed sys_errlist (#8234 <https://github.com/fish-
shell/fish-shell/issues/8234>, #4183 <https://github.com/fish-shell/fish-
shell/issues/4183>).
* The realpath builtin now also squashes leading slashes with the --no-sym-
links option (#8281 <https://github.com/fish-shell/fish-shell/is-
sues/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
<https://github.com/fish-shell/fish-shell/issues/8264>).
* On MacOS terminals that are not granted permissions to access a folder,
cd would print a spurious "rotten symlink" error, which has been cor-
rected to "permission denied" (#8264 <https://github.com/fish-shell/fish-
shell/issues/8264>).
* Since fish 3.0, for loops would trigger a variable handler function be-
fore the loop was entered. As the variable had not actually changed or
been set, this was a spurious event and has been removed (#8384
<https://github.com/fish-shell/fish-shell/issues/8384>).
* math now correctly prints negative values and values larger than 2**31
when in hex or octal bases (#8417 <https://github.com/fish-shell/fish-
shell/issues/8417>).
* dirs always produces an exit status of 0, instead of sometimes returning
1 (#8211 <https://github.com/fish-shell/fish-shell/issues/8211>).
* cd "" no longer crashes fish (#8147 <https://github.com/fish-shell/fish-
shell/issues/8147>).
* set --query can now query whether a variable is a path variable via
--path or --unpath (#8494 <https://github.com/fish-shell/fish-shell/is-
sues/8494>).
* Tilde characters (~) produced by custom completions are no longer escaped
when applied to the command line, making it easier to use the output of a
recursive complete -C in completion scripts (#4570
<https://github.com/fish-shell/fish-shell/issues/4570>).
* set --show reports when a variable is read-only (#8179
<https://github.com/fish-shell/fish-shell/issues/8179>).
* Erasing $fish_emoji_width will reset fish to the default guessed emoji
width (#8274 <https://github.com/fish-shell/fish-shell/issues/8274>).
* The la function no longer lists entries for "." and "..", matching other
systems defaults (#8519 <https://github.com/fish-shell/fish-shell/is-
sues/8519>).
* abbr -q returns the correct exit status when given multiple abbreviation
names as arguments (#8431 <https://github.com/fish-shell/fish-shell/is-
sues/8431>).
* command -v returns an exit status of 127 instead of 1 if no command was
found (#8547 <https://github.com/fish-shell/fish-shell/issues/8547>).
* argparse with --ignore-unknown no longer breaks with multiple unknown op-
tions in a short option group (#8637 <https://github.com/fish-shell/fish-
shell/issues/8637>).
* Comments inside command substitutions or brackets now correctly ignore
parentheses, quotes, and brackets (#7866 <https://github.com/fish-
shell/fish-shell/issues/7866>, #8022 <https://github.com/fish-shell/fish-
shell/issues/8022>, #8695 <https://github.com/fish-shell/fish-shell/is-
sues/8695>).
* complete -C supports a new --escape option, which turns on escaping in
returned completion strings (#3469 <https://github.com/fish-shell/fish-
shell/issues/3469>).
* Invalid byte or unicode escapes like \Utest or \xNotHex are now a tok-
enizer error instead of causing the token to be truncated (#8545
<https://github.com/fish-shell/fish-shell/issues/8545>).
Interactive improvements
* Vi mode cursors are now set properly after ctrl-c (#8125
<https://github.com/fish-shell/fish-shell/issues/8125>).
* funced will try to edit the whole file containing a function definition,
if there is one (#391 <https://github.com/fish-shell/fish-shell/is-
sues/391>).
* Running a command line consisting of just spaces now deletes an ephemeral
(starting with space) history item again (#8232 <https://github.com/fish-
shell/fish-shell/issues/8232>).
* Command substitutions no longer respect job control, instead running in-
side fish's own process group (#8172 <https://github.com/fish-shell/fish-
shell/issues/8172>). This more closely matches other shells, and improves
ctrl-c reliability inside a command substitution.
* history and __fish_print_help now properly support less before version
530, including the version that ships with macOS. (#8157
<https://github.com/fish-shell/fish-shell/issues/8157>).
* help now knows which section is in which document again (#8245
<https://github.com/fish-shell/fish-shell/issues/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 existing setups
(#8292 <https://github.com/fish-shell/fish-shell/issues/8292>).
* When executing a command, abbreviations are no longer expanded when the
cursor is separated from the command by spaces, making it easier to sup-
press abbreviation expansion of commands without arguments. (#8423
<https://github.com/fish-shell/fish-shell/issues/8423>).
* fish_key_reader's output was simplified. By default, it now only prints a
bind statement. The previous per-character timing information can be seen
with a new --verbose switch (#8467 <https://github.com/fish-shell/fish-
shell/issues/8467>).
* Custom completions are now also loaded for commands that contain tildes
or variables like ~/bin/fish or $PWD/fish (#8442
<https://github.com/fish-shell/fish-shell/issues/8442>).
* Command lines spanning multiple lines will not be overwritten by the com-
pletion pager when it fills the entire terminal (#8509
<https://github.com/fish-shell/fish-shell/issues/8509>, #8405
<https://github.com/fish-shell/fish-shell/issues/8405>).
* When redrawing a multiline prompt, the old prompt is now properly cleared
(#8163 <https://github.com/fish-shell/fish-shell/issues/8163>).
* Interactive completion would occasionally ignore the last word on the
command line due to a race condition. This has been fixed (#8175
<https://github.com/fish-shell/fish-shell/issues/8175>).
* Propagation of universal variables from a fish process that is closing is
faster (#8209 <https://github.com/fish-shell/fish-shell/issues/8209>).
* The command line is drawn in the correct place if the prompt ends with a
newline (#8298 <https://github.com/fish-shell/fish-shell/issues/8298>).
* history learned a new subcommand clear-session to erase all history from
the current session (#5791 <https://github.com/fish-shell/fish-shell/is-
sues/5791>).
* Pressing ctrl-c in fish_key_reader will no longer print the incorrect
"Press [ctrl-C] again to exit" message (#8510 <https://github.com/fish-
shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-
shell/issues/8579>).
* When looking for locale information, the Debian configuration is now used
when available (#8557 <https://github.com/fish-shell/fish-shell/is-
sues/8557>).
* Pasting text containing quotes from the clipboard trims spaces more ap-
propriately (#8550 <https://github.com/fish-shell/fish-shell/is-
sues/8550>).
* The clipboard bindings ignore X-based clipboard programs if the DISPLAY
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, includ-
ing the ability to set pager colors.
* The default fish_title prints a shorter title with shortened $PWD and no
more redundant "fish" (#8641 <https://github.com/fish-shell/fish-
shell/issues/8641>).
* Holding down an arrow key won't freeze the terminal with long periods of
flashing (#8610 <https://github.com/fish-shell/fish-shell/issues/8610>).
* Multi-char bindings are no longer interrupted if a signal handler en-
queues an event. (#8628 <https://github.com/fish-shell/fish-shell/is-
sues/8628>).
New or improved bindings
* escape can now bound without breaking arrow key bindings (#8428
<https://github.com/fish-shell/fish-shell/issues/8428>).
* The alt-h binding (to open a commandas manual page) now also ignores com-
mand (#8447 <https://github.com/fish-shell/fish-shell/issues/8447>).
Improved prompts
* The fish_status_to_signal helper function returns the correct signal
names for the current platform, rather than Linux (#8530
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-
shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/8434>)
* asd (#8759 <https://github.com/fish-shell/fish-shell/issues/8759>)
* az (#8141 <https://github.com/fish-shell/fish-shell/issues/8141>)
* black (#8123 <https://github.com/fish-shell/fish-shell/issues/8123>)
* clasp (#8373 <https://github.com/fish-shell/fish-shell/issues/8373>)
* cpupower (#8302 <https://github.com/fish-shell/fish-shell/issues/8302>)
* dart (#8315 <https://github.com/fish-shell/fish-shell/issues/8315>)
* dscacheutil
* elvish (#8416 <https://github.com/fish-shell/fish-shell/issues/8416>)
* ethtool (#8283 <https://github.com/fish-shell/fish-shell/issues/8283>)
* exif (#8246 <https://github.com/fish-shell/fish-shell/issues/8246>)
* findstr (#8481 <https://github.com/fish-shell/fish-shell/issues/8481>)
* git-sizer (#8156 <https://github.com/fish-shell/fish-shell/is-
sues/8156>)
* gnome-extensions (#8732 <https://github.com/fish-shell/fish-shell/is-
sues/8732>)
* gping (#8181 <https://github.com/fish-shell/fish-shell/issues/8181>)
* isatty (#8609 <https://github.com/fish-shell/fish-shell/issues/8609>)
* istioctl (#8343 <https://github.com/fish-shell/fish-shell/issues/8343>)
* kmutil
* kubectl (#8734 <https://github.com/fish-shell/fish-shell/issues/8734>)
* matlab (#8505 <https://github.com/fish-shell/fish-shell/issues/8505>)
* mono (#8415 <https://github.com/fish-shell/fish-shell/issues/8415>) and
related tools csharp, gacutil, gendarme, ikdasm, ilasm, mkbundle,
monodis, monop, sqlsharp and xsp (#8452 <https://github.com/fish-
shell/fish-shell/issues/8452>)
* Angular's ng (#8111 <https://github.com/fish-shell/fish-shell/is-
sues/8111>)
* nodeenv (#8533 <https://github.com/fish-shell/fish-shell/issues/8533>)
* octave (#8505 <https://github.com/fish-shell/fish-shell/issues/8505>)
* pabcnet_clear (#8421 <https://github.com/fish-shell/fish-shell/is-
sues/8421>)
* qmk (#8180 <https://github.com/fish-shell/fish-shell/issues/8180>)
* rakudo (#8113 <https://github.com/fish-shell/fish-shell/issues/8113>)
* rc-status (#8757 <https://github.com/fish-shell/fish-shell/is-
sues/8757>)
* roswell (#8330 <https://github.com/fish-shell/fish-shell/issues/8330>)
* sbcl (#8330 <https://github.com/fish-shell/fish-shell/issues/8330>)
* starship (#8520 <https://github.com/fish-shell/fish-shell/issues/8520>)
* topgrade (#8651 <https://github.com/fish-shell/fish-shell/issues/8651>)
* wine, wineboot and winemaker (#8411 <https://github.com/fish-
shell/fish-shell/issues/8411>)
* Windows Subsystem for Linux (WSL)'s wslpath (#8364
<https://github.com/fish-shell/fish-shell/issues/8364>)
* Windows' color (#8483 <https://github.com/fish-shell/fish-shell/is-
sues/8483>), attrib, attributes, choice, clean, cleanmgr, cmd, cmdkey,
comp, forfiles, powershell, reg, schtasks, setx (#8486
<https://github.com/fish-shell/fish-shell/issues/8486>)
* zef (#8114 <https://github.com/fish-shell/fish-shell/issues/8114>)
* Improvements to many completions, especially for git aliases (#8129
<https://github.com/fish-shell/fish-shell/issues/8129>), subcommands (-
#8134 <https://github.com/fish-shell/fish-shell/issues/8134>) and submod-
ules (#8716 <https://github.com/fish-shell/fish-shell/issues/8716>).
* Many adjustments to complete correct options for system utilities on BSD
and macOS.
* When evaluating custom completions, the command line state no longer in-
cludes variable overrides (var=val). This unbreaks completions that read
commandline -op.
Improved terminal support
* Dynamic terminal titles are enabled on WezTerm (#8121
<https://github.com/fish-shell/fish-shell/issues/8121>).
* Directory history navigation works out of the box with Apple Terminal's
default key settings (#2330 <https://github.com/fish-shell/fish-shell/is-
sues/2330>).
* fish now assumes Unicode 9+ widths for emoji under iTerm 2 (#8200
<https://github.com/fish-shell/fish-shell/issues/8200>).
* Skin-tone emoji modifiers (U+1F3FB through U+1F3FF) are now measured as
width 0 (#8275 <https://github.com/fish-shell/fish-shell/issues/8275>).
* fish's escape sequence removal now also knows Tmux's wrapped escapes.
* Vi mode cursors are enabled in Apple Terminal.app (#8167
<https://github.com/fish-shell/fish-shell/issues/8167>).
* Vi cursor shaping and $PWD reporting is now also enabled on foot (#8422
<https://github.com/fish-shell/fish-shell/issues/8422>).
* ls will use colors also on newer versions of Apple Terminal.app (#8309
<https://github.com/fish-shell/fish-shell/issues/8309>).
* The delete and shift-tab keys work more reliably under st (#8352
<https://github.com/fish-shell/fish-shell/issues/8352>, #8354
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/7851>)
* The HTML version of the documentation now includes copy buttons for code
examples (#8218 <https://github.com/fish-shell/fish-shell/issues/8218>).
* The HTML version of the documentation and the web-based configuration
tool now pick more modern system fonts instead of falling back to Arial
and something like Courier New most of the time (#8632
<https://github.com/fish-shell/fish-shell/issues/8632>).
* The Debian & Ubuntu package linked from fishshell.com is now a single
package, rather than split into fish and fish-common (#7845
<https://github.com/fish-shell/fish-shell/issues/7845>).
* The macOS installer does not assert that Rosetta is required to install
fish on machines with Apple Silicon (#8566 <https://github.com/fish-
shell/fish-shell/issues/8566>).
* The macOS installer now cleans up previous .pkg installations when up-
grading. (#2963 <https://github.com/fish-shell/fish-shell/issues/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_INSTALL_DATADIR
(#8150 <https://github.com/fish-shell/fish-shell/issues/8150>).
* Building using NetBSD curses works on any platform (#8087
<https://github.com/fish-shell/fish-shell/issues/8087>).
* The build system now uses the default linker instead of forcing use of
the gold or lld linker (#8152 <https://github.com/fish-shell/fish-
shell/issues/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 univer-
sal variable changes (#8088 <https://github.com/fish-shell/fish-shell/is-
sues/8088>).
* A superfluous error that was produced when setting the PATH or CDPATH en-
vironment variables to include colon-delimited components that do not ex-
ist was removed (#8095 <https://github.com/fish-shell/fish-shell/is-
sues/8095>).
* The Vi mode indicator in the prompt is repainted correctly after ctrl-c
cancels the current command (#8103 <https://github.com/fish-shell/fish-
shell/issues/8103>).
* fish builds correctly on platforms that do not have a spawn.h header,
such as old versions of OS X (#8097 <https://github.com/fish-shell/fish-
shell/issues/8097>).
A number of improvements to the documentation, and fixes for completions,
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 sample
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 <https://github.com/fish-shell/fish-shell/is-
sues/7958>).
* The documentation has been reorganized to be easier to understand (#7773
<https://github.com/fish-shell/fish-shell/issues/7773>).
Deprecations and removed features
* The $fish_history value "default" is no longer special. It used to be
treated the same as "fish" (#7650 <https://github.com/fish-shell/fish-
shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/7958>).
Scripting improvements
* math gained new functions log2 (like the documentation claimed), max and
min (#7856 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/7877>).
* Shebang (#!) lines are no longer required within shell scripts, improving
support for scripts with concatenated binary contents. If a file fails to
execute and passes a (rudimentary) binary safety check, fish will re-in-
voke it using /bin/sh (#7802 <https://github.com/fish-shell/fish-
shell/issues/7802>).
* Exit codes are better aligned with bash. A failed execution now reports
$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 perfor-
mance and allowing use with Linux's special API files (/proc, /sys and
such) (#7836 <https://github.com/fish-shell/fish-shell/issues/7836>).
* fish should now better handle cd on filesystems with broken stat(3) re-
sponses (#7577 <https://github.com/fish-shell/fish-shell/issues/7577>).
* Builtins now properly report a $status of 1 upon unsuccessful writes (-
#7857 <https://github.com/fish-shell/fish-shell/issues/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 arguments are pro-
vided, matching the documentation. (#7938 <https://github.com/fish-
shell/fish-shell/issues/7938>).
* fish produces more specific errors when a command in a command substitu-
tion wasn't found or is not allowed. This now prints something like "Un-
known command" instead of "Unknown error while evaluating command substi-
tution".
* fish_indent allows inline variable assignments (FOO=BAR command) to use
line continuation, instead of joining them into one line (#7955
<https://github.com/fish-shell/fish-shell/issues/7955>).
* fish gained a --no-config option to disable configuration files. This ap-
plies 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 directories (#7921
<https://github.com/fish-shell/fish-shell/issues/7921>, #1256
<https://github.com/fish-shell/fish-shell/issues/1256>).
* When universal variables are unavailable for some reason, setting a uni-
versal variable now sets a global variable instead (#7921
<https://github.com/fish-shell/fish-shell/issues/7921>).
* $last_pid now contains the process ID of the last process in the
pipeline, allowing it to be used in scripts (#5036
<https://github.com/fish-shell/fish-shell/issues/5036>, #5832
<https://github.com/fish-shell/fish-shell/issues/5832>, #7721
<https://github.com/fish-shell/fish-shell/issues/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 argu-
ment, 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 correctly (-
#8082 <https://github.com/fish-shell/fish-shell/issues/8082>).
Interactive improvements
* Commands entered before the previous command finishes will now be prop-
erly syntax highlighted.
* fish now automatically creates config.fish and the configuration directo-
ries in $XDG_CONFIG_HOME/fish (by default ~/.config/fish) if they do not
already exist (#7402 <https://github.com/fish-shell/fish-shell/is-
sues/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 hap-
pens to run some scripts in $SHELL in its startup path (#7864
<https://github.com/fish-shell/fish-shell/issues/7864>).
* fish no longer rings the bell when flashing the command line. The flash-
ing should already be enough notification and the bell can be annoying (-
#7875 <https://github.com/fish-shell/fish-shell/issues/7875>).
* fish --help is more helpful if the documentation isn't installed (#7824
<https://github.com/fish-shell/fish-shell/issues/7824>).
* funced won't include an entry on where a function is defined, thanks to
the new functions --no-details option (#7879 <https://github.com/fish-
shell/fish-shell/issues/7879>).
* A new variable, fish_killring, containing entries from the killring, is
now available (#7445 <https://github.com/fish-shell/fish-shell/is-
sues/7445>).
* fish --private prints a note on private mode on startup even if
$fish_greeting is an empty list (#7974 <https://github.com/fish-
shell/fish-shell/issues/7974>).
* fish no longer attempts to lock history or universal variable files on
remote filesystems, including NFS and Samba mounts. In rare cases, up-
dates to these files may be dropped if separate fish instances modify
them simultaneously. (#7968 <https://github.com/fish-shell/fish-shell/is-
sues/7968>).
* wait and on-process-exit work correctly with jobs that have already ex-
ited (#7210 <https://github.com/fish-shell/fish-shell/issues/7210>).
* __fish_print_help (used for --help output for fish's builtins) now re-
spects the LESS environment variable, and if not set, uses better default
pager settings (#7997 <https://github.com/fish-shell/fish-shell/is-
sues/7997>).
* Errors from alias are now printed to standard error, matching other
builtins and functions (#7925 <https://github.com/fish-shell/fish-
shell/issues/7925>).
* ls output is colorized on OpenBSD if colorls utility is installed (#8035
<https://github.com/fish-shell/fish-shell/issues/8035>)
* The default pager color looks better in terminals with light backgrounds
(#3412 <https://github.com/fish-shell/fish-shell/issues/3412>).
* Further robustness improvements to the bash history import (#7874
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/8031>). To allow a C lo-
cale, 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 <https://github.com/fish-shell/fish-
shell/issues/8043>).
* Color variables can now also be given like --background red and -b red,
not just --background=red (#8053 <https://github.com/fish-shell/fish-
shell/issues/8053>).
* exit run within fish_prompt now exits properly (#8033
<https://github.com/fish-shell/fish-shell/issues/8033>).
* When attempting to execute the unsupported POSIX-style brace command
group ({ ... }) fish will suggest its equivalent begin; ...; end commands
(#6415 <https://github.com/fish-shell/fish-shell/issues/6415>).
New or improved bindings
* Pasting in Vi mode puts text in the right place in normal mode (#7847
<https://github.com/fish-shell/fish-shell/issues/7847>).
* Vi mode's u is bound to undo instead of history-search-backward, follow-
ing GNU readline's behavior. Similarly, ctrl-r is bound to redo instead
of history-search-backward, following Vim (#7908
<https://github.com/fish-shell/fish-shell/issues/7908>).
* s in Vi visual mode now does the same thing as c (#8039
<https://github.com/fish-shell/fish-shell/issues/8039>).
* The binding for ",*,y now uses fish_clipboard_copy, allowing it to sup-
port more than just xsel.
* The ctrl-space binding can be correctly customised (#7922
<https://github.com/fish-shell/fish-shell/issues/7922>).
* exit works correctly in bindings (#7967 <https://github.com/fish-
shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/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_append
allow toggling the presence of a prefix/suffix on the current command-
line. (#7905 <https://github.com/fish-shell/fish-shell/issues/7905>).
* backward-kill-path-component ctrl-w) no longer erases parts of two tokens
when the cursor is positioned immediately after /. (#6258
<https://github.com/fish-shell/fish-shell/issues/6258>).
Improved prompts
* The default Vi mode prompt now uses foreground instead of background col-
ors, making it less obtrusive (#7880 <https://github.com/fish-shell/fish-
shell/issues/7880>).
* Performance of the "informative" git prompt is improved somewhat (#7871
<https://github.com/fish-shell/fish-shell/issues/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 vari-
ous 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
<https://github.com/fish-shell/fish-shell/issues/7884>, #7897
<https://github.com/fish-shell/fish-shell/issues/7897>, #7930
<https://github.com/fish-shell/fish-shell/issues/7930>). The new prompts
will only take effect when selected and existing 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 terlar prompts (-
#7932 <https://github.com/fish-shell/fish-shell/issues/7932>).
* The Web-based configuration's prompt picker now shows and installs right
prompts (#7930 <https://github.com/fish-shell/fish-shell/issues/7930>).
* The git prompt now has the same symbol order in normal and "informative"
mode, and it's customizable via $__fish_git_prompt_status_order (#7926
<https://github.com/fish-shell/fish-shell/issues/7926>).
Completions
* Added completions for:
* firewall-cmd (#7900 <https://github.com/fish-shell/fish-shell/is-
sues/7900>)
* sv (#8069 <https://github.com/fish-shell/fish-shell/issues/8069>)
* Improvements to plenty of completions!
* Commands that wrap cd (using complete --wraps cd) get the same comple-
tions as cd (#4693 <https://github.com/fish-shell/fish-shell/is-
sues/4693>).
* The --force-files option to complete works for bare arguments, not just
options (#7920 <https://github.com/fish-shell/fish-shell/issues/7920>).
* Completion descriptions for functions don't include the function defini-
tion, making them more concise (#7911 <https://github.com/fish-
shell/fish-shell/issues/7911>).
* The kill completions no longer error on MSYS2 (#8046
<https://github.com/fish-shell/fish-shell/issues/8046>).
* Completion scripts are now loaded when calling a command via a relative
path (like ./git) (#6001 <https://github.com/fish-shell/fish-shell/is-
sues/6001>, #7992 <https://github.com/fish-shell/fish-shell/is-
sues/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 pre-
fixes with matching case (#7744 <https://github.com/fish-shell/fish-
shell/issues/7744>).
Improved terminal support
* fish no longer tries to detect a missing new line during startup, pre-
venting an erroneous ^a from appearing if the terminal is resized at the
wrong time, which can happen in tiling window managers (#7893
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/8011>).
* If the prompt takes up the entire line, the last character should no
longer be chopped off in certain terminals (#8002
<https://github.com/fish-shell/fish-shell/issues/8002>).
* fish's reflow handling has been disabled by default for kitty (#7961
<https://github.com/fish-shell/fish-shell/issues/7961>).
* The default prompt no longer produces errors when used with a dumb termi-
nal (#7904 <https://github.com/fish-shell/fish-shell/issues/7904>).
* Terminal size variables are updated for window size change signal han-
dlers (SIGWINCH).
* Pasting within a multi-line command using a terminal that supports brack-
eted paste works correctly, instead of producing an error (#7782
<https://github.com/fish-shell/fish-shell/issues/7782>).
* set_color produces an error when used with invalid arguments, rather than
empty output which interacts badly with Cartesian product expansion.
For distributors
* fish runs correctly on platforms without the O_CLOEXEC flag for open(2)
(#8023 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/7841>).
* fish will no longer hang on exit if another process is in the foreground
on macOS (#7901 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/7853>).
* Arguments longer than 1024 characters no longer trigger excessive CPU us-
age on macOS (#7837 <https://github.com/fish-shell/fish-shell/is-
sues/7837>).
* fish builds correctly on macOS when using new versions of Xcode (#7838
<https://github.com/fish-shell/fish-shell/issues/7838>).
* Completions for aura (#7865 <https://github.com/fish-shell/fish-shell/is-
sues/7865>) and tshark (#7858 <https://github.com/fish-shell/fish-
shell/issues/7858>) should no longer produce errors.
* Background jobs no longer interfere with syntax highlighting (a regres-
sion introduced in fish 3.2.1, #7842 <https://github.com/fish-shell/fish-
shell/issues/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, in-
stead of the terminal modes typically used for commands. This fixes a bug
introduced in 3.2.0, where text would unexpectedly appear on the termi-
nal, especially when pasting (#7770 <https://github.com/fish-shell/fish-
shell/issues/7770>).
* Prompts which use the internal __fish_print_pipestatus function will dis-
play correctly rather than carrying certain modifiers (such as bold) fur-
ther than intended (#7771 <https://github.com/fish-shell/fish-shell/is-
sues/7771>).
* Redirections to internal file descriptors is allowed again, reversing the
changes in 3.2.0. This fixes a problem with Midnight Commander (#7769
<https://github.com/fish-shell/fish-shell/issues/7769>).
* Universal variables should be fully reliable regardless of operating sys-
tem again (#7774 <https://github.com/fish-shell/fish-shell/issues/7774>).
* fish_git_prompt no longer causes screen flickering in certain terminals
(#7775 <https://github.com/fish-shell/fish-shell/issues/7775>).
* fish_add_path manipulates the fish_user_paths variable correctly when
moving multiple paths (#7776 <https://github.com/fish-shell/fish-
shell/issues/7776>).
* Pasting with a multi-line command no longer causes a __fish_tok-
enizer_state error (#7782 <https://github.com/fish-shell/fish-shell/is-
sues/7782>).
* psub inside event handlers cleans up temporary files properly (#7792
<https://github.com/fish-shell/fish-shell/issues/7792>).
* Event handlers declared with --on-job-exit $fish_pid no longer run con-
stantly (#7721 <https://github.com/fish-shell/fish-shell/issues/7721>),
although these functions should use --on-event fish_exit instead.
* Changing terminal modes inside config.fish works (#7783
<https://github.com/fish-shell/fish-shell/issues/7783>).
* set_color --print-colors no longer prints all colors in bold (#7805
<https://github.com/fish-shell/fish-shell/issues/7805>)
* Completing commands starting with a - no longer prints an error (#7809
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/7777>).
* The new type builtin now has the (deprecated) --quiet long form of -q (-
#7766 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/7789>).
* The history file can be made a symbolic link without it being overwritten
(#7754 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/7785>).
* Improvements to the rsync completions (#7763 <https://github.com/fish-
shell/fish-shell/issues/7763>), some completion descriptions (#7788
<https://github.com/fish-shell/fish-shell/issues/7788>), and completions
that use IP address (#7787 <https://github.com/fish-shell/fish-shell/is-
sues/7787>).
* Improvements to the appearance of fish_config (#7811
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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 re-
place no longer has to read all of stdin before it can begin to output.
This makes it usable also for pipes where the previous command 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 <https://github.com/fish-shell/fish-
shell/issues/904>). For example:
~/dev/build/fish-shell-git/src/fish-shell/build (makepkg)>
will turn into:
a|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
<https://github.com/fish-shell/fish-shell/issues/6924>).
* fish is less aggressive about resetting terminal modes, such as flow con-
trol, after every command. Although flow control remains off by default,
enterprising users can now enable it with stty (#2315
<https://github.com/fish-shell/fish-shell/issues/2315>, #7704
<https://github.com/fish-shell/fish-shell/issues/7704>).
* A new "fish_add_path" helper function to add paths to $PATH without pro-
ducing duplicates, to be used interactively or in config.fish (#6960
<https://github.com/fish-shell/fish-shell/issues/6960>, #7028
<https://github.com/fish-shell/fish-shell/issues/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 config.fish or in-
teractively, and the path will just be there, once.
* Better errors with "test" (#6030 <https://github.com/fish-shell/fish-
shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/6500>, #7371
<https://github.com/fish-shell/fish-shell/issues/7371>, #7523
<https://github.com/fish-shell/fish-shell/issues/7523>), matching the de-
sign on fishshell.com.
* fish --no-execute will no longer complain about unknown commands or
non-matching wildcards, as these could be defined differently at runtime
(especially for functions). This makes it usable as a static syntax
checker (#977 <https://github.com/fish-shell/fish-shell/issues/977>).
* string match --regex now integrates named PCRE2 capture groups as fish
variables, allowing variables to be set directly from string match (#7459
<https://github.com/fish-shell/fish-shell/issues/7459>). To support this
functionality, string is now a reserved word and can no longer be wrapped
in a function.
* Globs and other expansions are limited to 512,288 results (#7226
<https://github.com/fish-shell/fish-shell/issues/7226>). Because operat-
ing 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
<https://github.com/fish-shell/fish-shell/issues/2382>), and the comple-
tion tutorial has also been moved out into its own document (#6709
<https://github.com/fish-shell/fish-shell/issues/6709>).
Syntax changes and new commands
* Range limits in index range expansions like $x[$start..$end] may be omit-
ted: $start and $end default to 1 and -1 (the last item) respectively (-
#6574 <https://github.com/fish-shell/fish-shell/issues/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 directo-
ries. For example **/foo may match foo in the current directory (#7222
<https://github.com/fish-shell/fish-shell/issues/7222>).
Scripting improvements
* The type, _ (gettext), . (source) and : (no-op) functions are now imple-
mented builtins for performance purposes (#7342 <https://github.com/fish-
shell/fish-shell/issues/7342>, #7036 <https://github.com/fish-shell/fish-
shell/issues/7036>, #6854 <https://github.com/fish-shell/fish-shell/is-
sues/6854>).
* set and backgrounded jobs no longer overwrite $pipestatus (#6820
<https://github.com/fish-shell/fish-shell/issues/6820>), improving its
use in command substitutions (#6998 <https://github.com/fish-shell/fish-
shell/issues/6998>).
* Computed ("electric") variables such as status are now only global in
scope, so set -Uq status returns false (#7032 <https://github.com/fish-
shell/fish-shell/issues/7032>).
* The output for set --show has been shortened, only mentioning the scopes
in which a variable exists (#6944 <https://github.com/fish-shell/fish-
shell/issues/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 terminated
the last foreground job, or 0 if the job exited normally (#6824
<https://github.com/fish-shell/fish-shell/issues/6824>, #6822
<https://github.com/fish-shell/fish-shell/issues/6822>).
* A new subcommand, string pad, allows extending strings to a given width
(#7340 <https://github.com/fish-shell/fish-shell/issues/7340>, #7102
<https://github.com/fish-shell/fish-shell/issues/7102>).
* string sub has a new --end option to specify the end index of a substring
(#6765 <https://github.com/fish-shell/fish-shell/issues/6765>, #5974
<https://github.com/fish-shell/fish-shell/issues/5974>).
* string split has a new --fields option to specify fields to output, simi-
lar to cut -f (#6770 <https://github.com/fish-shell/fish-shell/is-
sues/6770>).
* string trim now also trims vertical tabs by default (#6795
<https://github.com/fish-shell/fish-shell/issues/6795>).
* string replace no longer prints an error if a capturing group wasn't
matched, instead treating it as empty (#7343 <https://github.com/fish-
shell/fish-shell/issues/7343>).
* string subcommands now quit early when used with --quiet (#7495
<https://github.com/fish-shell/fish-shell/issues/7495>).
* string repeat now handles multiple arguments, repeating each one (#5988
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/7030>).
* fish_indent now removes unnecessary quotes in simple cases (#6722
<https://github.com/fish-shell/fish-shell/issues/6722>) and gained a
--check option to just check if a file is indented correctly (#7251
<https://github.com/fish-shell/fish-shell/issues/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 successful
(#6947 <https://github.com/fish-shell/fish-shell/issues/6947>).
* A new fish_job_summary function is called whenever a background job stops
or ends, or any job terminates from a signal (#6959
<https://github.com/fish-shell/fish-shell/issues/6959>, #2727
<https://github.com/fish-shell/fish-shell/issues/2727>, #4319
<https://github.com/fish-shell/fish-shell/issues/4319>). The default be-
haviour 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 simplify
common tasks such as running (dirname (status filename)) (#7076
<https://github.com/fish-shell/fish-shell/issues/7076>, #1818
<https://github.com/fish-shell/fish-shell/issues/1818>).
* Broken pipelines are now handled more smoothly; in particular, bad redi-
rection mid-pipeline results in the job continuing to run but with the
broken file descriptor replaced with a closed file descriptor. This al-
lows better error recovery and is more in line with other shells' behav-
iour (#7038 <https://github.com/fish-shell/fish-shell/issues/7038>).
* jobs --quiet PID no longer prints "no suitable job" if the job for PID
does not exist (eg because it has finished) (#6809
<https://github.com/fish-shell/fish-shell/issues/6809>, #6812
<https://github.com/fish-shell/fish-shell/issues/6812>).
* jobs now shows continued child processes correctly (#6818
<https://github.com/fish-shell/fish-shell/issues/6818>)
* disown should no longer create zombie processes when job control is off,
such as in config.fish (#7183 <https://github.com/fish-shell/fish-
shell/issues/7183>).
* command, jobs and type builtins support --query as the long form of -q,
matching other builtins. The long form --quiet is deprecated (#7276
<https://github.com/fish-shell/fish-shell/issues/7276>).
* argparse no longer requires a short flag letter for long-only options (-
#7585 <https://github.com/fish-shell/fish-shell/issues/7585>) and only
prints a backtrace with invalid options to argparse itself (#6703
<https://github.com/fish-shell/fish-shell/issues/6703>).
* argparse now passes the validation variables (e.g. $_flag_value) as lo-
cal-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 complete
--command git, and it can show the loaded completions for specific com-
mands with complete COMMANDNAME (#7321 <https://github.com/fish-
shell/fish-shell/issues/7321>).
* set_color -b (without an argument) no longer prints an error message,
matching other invalid invocations of this command (#7154
<https://github.com/fish-shell/fish-shell/issues/7154>).
* exec no longer produces a syntax error when the command cannot be found
(#6098 <https://github.com/fish-shell/fish-shell/issues/6098>).
* set --erase and abbr --erase can now erase multiple things in one go,
matching functions --erase (#7377 <https://github.com/fish-shell/fish-
shell/issues/7377>).
* abbr --erase no longer prints errors when used with no arguments or on an
unset abbreviation (#7376 <https://github.com/fish-shell/fish-shell/is-
sues/7376>, #7732 <https://github.com/fish-shell/fish-shell/is-
sues/7732>).
* test -t, for testing whether file descriptors are connected to a termi-
nal, works for file descriptors 0, 1, and 2 (#4766
<https://github.com/fish-shell/fish-shell/issues/4766>). It can still
return incorrect results in other cases (#1228 <https://github.com/fish-
shell/fish-shell/issues/1228>).
* Trying to execute scripts with Windows line endings (CRLF) produces a
sensible error (#2783 <https://github.com/fish-shell/fish-shell/is-
sues/2783>).
* Trying to execute commands with arguments that exceed the operating sys-
tem limit now produces a specific error (#6800 <https://github.com/fish-
shell/fish-shell/issues/6800>).
* An alias that delegates to a command with the same name no longer trig-
gers an error about recursive completion (#7389 <https://github.com/fish-
shell/fish-shell/issues/7389>).
* math now has a --base option to output the result in hexadecimal or octal
(#7496 <https://github.com/fish-shell/fish-shell/issues/7496>) and pro-
duces more specific error messages (#7508 <https://github.com/fish-
shell/fish-shell/issues/7508>).
* math learned bitwise functions bitand, bitor and bitxor, used like math
"bitand(0xFE, 5)" (#7281 <https://github.com/fish-shell/fish-shell/is-
sues/7281>).
* math learned tau for those who don't like typing "2 * pi".
* Failed redirections will now set $status (#7540 <https://github.com/fish-
shell/fish-shell/issues/7540>).
* fish sets exit status in a more consistent manner after errors, including
invalid expansions like $foo[.
* Using read --silent while fish is in private mode was adding these poten-
tially-sensitive entries to the history; this has been fixed (#7230
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/7358>).
* A new fish_status_to_signal function for transforming exit statuses to
signal names has been added (#7597 <https://github.com/fish-shell/fish-
shell/issues/7597>, #7595 <https://github.com/fish-shell/fish-shell/is-
sues/7595>).
* The fallback realpath builtin supports the -s/--no-symlinks option, like
GNU realpath (#7574 <https://github.com/fish-shell/fish-shell/is-
sues/7574>).
* functions and type now explain when a function was defined via source in-
stead of just saying Defined in -.
* Significant performance improvements when globbing, appending to vari-
ables or in math.
* echo no longer interprets options at the beginning of an argument (eg
echo "-n foo") (#7614 <https://github.com/fish-shell/fish-shell/is-
sues/7614>).
* fish now finds user configuration even if the HOME environment variable
is not set (#7620 <https://github.com/fish-shell/fish-shell/is-
sues/7620>).
* fish no longer crashes when started from a Windows-style working direc-
tory (eg F:\path) (#7636 <https://github.com/fish-shell/fish-shell/is-
sues/7636>).
* fish -c now reads the remaining arguments into $argv (#2314
<https://github.com/fish-shell/fish-shell/issues/2314>).
* The pwd command supports the long options --logical and --physical,
matching other implementations (#6787 <https://github.com/fish-
shell/fish-shell/issues/6787>).
* fish --profile now only starts profiling after fish is ready to execute
commands (all configuration is completed). There is a new --pro-
file-startup option that only profiles the startup and configuration
process (#7648 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/7698>, #7702 <https://github.com/fish-shell/fish-shell/is-
sues/7702>).
* It is no longer an error to run builtin with closed stdin. For example
count <&- now prints 0, instead of failing.
* Blocks, functions, and builtins no longer permit redirecting to file de-
scriptors other than 0 (standard input), 1 (standard output) and 2 (stan-
dard error). For example, echo hello >&5 is now an error. This prevents
corruption of internal state (#3303 <https://github.com/fish-shell/fish-
shell/issues/3303>).
Interactive improvements
* fish will now always attempt to become process group leader in interac-
tive mode (#7060 <https://github.com/fish-shell/fish-shell/issues/7060>).
This helps avoid hangs in certain circumstances, and allows tmux's cur-
rent directory introspection to work (#5699 <https://github.com/fish-
shell/fish-shell/issues/5699>).
* The interactive reader now allows ending a line in a logical operators
(&& and ||) instead of complaining about a missing command. (This was al-
ready syntactically valid, but interactive sessions didn't know about it
yet).
* The prompt is reprinted after a background job exits (#1018
<https://github.com/fish-shell/fish-shell/issues/1018>).
* fish no longer inserts a space after a completion ending in ., , or - is
accepted, improving completions for tools that provide dynamic comple-
tions (#6928 <https://github.com/fish-shell/fish-shell/issues/6928>).
* If a filename is invalid when first pressing tab, but becomes valid, it
will be completed properly on the next attempt (#6863
<https://github.com/fish-shell/fish-shell/issues/6863>).
* help string match/replace/<subcommand> will show the help for string sub-
commands (#6786 <https://github.com/fish-shell/fish-shell/issues/6786>).
* fish_key_reader sets the exit status to 0 when used with --help or --ver-
sion (#6964 <https://github.com/fish-shell/fish-shell/issues/6964>).
* fish_key_reader and fish_indent send output from --version to standard
output, matching other fish binaries (#6964 <https://github.com/fish-
shell/fish-shell/issues/6964>).
* A new variable $status_generation is incremented only when the previous
command produces an exit status (#6815 <https://github.com/fish-
shell/fish-shell/issues/6815>). This can be used, for example, to check
whether a failure status is a holdover due to a background job, or actu-
ally 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 config.fish (#7265
<https://github.com/fish-shell/fish-shell/issues/7265>).
* Events are properly emitted after a job is cancelled (#2356
<https://github.com/fish-shell/fish-shell/issues/2356>).
* fish_preexec and fish_postexec events are no longer triggered for empty
commands (#4829 <https://github.com/fish-shell/fish-shell/issues/4829>, -
#7085 <https://github.com/fish-shell/fish-shell/issues/7085>).
* Functions triggered by the fish_exit event are correctly run when the
terminal is closed or the shell receives SIGHUP (#7014
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-
shell/issues/7039>).
* A new fish_posterror event is emitted when attempting to execute a com-
mand with syntax errors (#6880 <https://github.com/fish-shell/fish-
shell/issues/6880>, #6816 <https://github.com/fish-shell/fish-shell/is-
sues/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 de-
bugging categories have been added, including config, path, reader and
screen (#6511 <https://github.com/fish-shell/fish-shell/issues/6511>).
See the output of fish --print-debug-categories for the full list.
* The warning about read-only filesystems has been moved to a new "warn-
ing-path" debug category and can be disabled by setting a debug category
of -warning-path (#6630 <https://github.com/fish-shell/fish-shell/is-
sues/6630>):
fish --debug=-warning-path
* The enabled debug categories are now printed on shell startup (#7007
<https://github.com/fish-shell/fish-shell/issues/7007>).
* The -o short option to fish, for --debug-output, works correctly instead
of producing an invalid option error (#7254 <https://github.com/fish-
shell/fish-shell/issues/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 com-
mandline options can be passed, like when fish is called in a shebang (-
#7359 <https://github.com/fish-shell/fish-shell/issues/7359>).
* Abbreviations are now expanded after all command terminators (eg ; or |),
not just space, as in fish 2.7.1 and before (#6970
<https://github.com/fish-shell/fish-shell/issues/6970>), and after clos-
ing a command substitution (#6658 <https://github.com/fish-shell/fish-
shell/issues/6658>).
* The history file is now created with user-private permissions, matching
other shells (#6926 <https://github.com/fish-shell/fish-shell/is-
sues/6926>). The directory containing the history file was already pri-
vate, so there should not have been any private data revealed.
* The output of time is now properly aligned in all cases (#6726
<https://github.com/fish-shell/fish-shell/issues/6726>, #6714
<https://github.com/fish-shell/fish-shell/issues/6714>) and no longer de-
pends on locale (#6757 <https://github.com/fish-shell/fish-shell/is-
sues/6757>).
* The command-not-found handling has been simplified. When it can't find a
command, fish now just executes a function called fish_command_not_found
instead of firing an event, making it easier to replace and reason about.
Previously-defined __fish_command_not_found_handler functions with an ap-
propriate event listener will still work (#7293 <https://github.com/fish-
shell/fish-shell/issues/7293>).
* ctrl-c handling has been reimplemented in C++ and is therefore quicker (-
#5259 <https://github.com/fish-shell/fish-shell/issues/5259>), no longer
occasionally prints an "unknown command" error (#7145
<https://github.com/fish-shell/fish-shell/issues/7145>) or overwrites
multiline prompts (#3537 <https://github.com/fish-shell/fish-shell/is-
sues/3537>).
* ctrl-c no longer kills background jobs for which job control is disabled,
matching POSIX semantics (#6828 <https://github.com/fish-shell/fish-
shell/issues/6828>, #6861 <https://github.com/fish-shell/fish-shell/is-
sues/6861>).
* Autosuggestions work properly after ctrl-c cancels the current command
line (#6937 <https://github.com/fish-shell/fish-shell/issues/6937>).
* History search is now case-insensitive unless the search string contains
an uppercase character (#7273 <https://github.com/fish-shell/fish-
shell/issues/7273>).
* fish_update_completions gained a new --keep option, which improves speed
by skipping completions that already exist (#6775
<https://github.com/fish-shell/fish-shell/issues/6775>, #6796
<https://github.com/fish-shell/fish-shell/issues/6796>).
* Aliases containing an embedded backslash appear properly in the output of
alias (#6910 <https://github.com/fish-shell/fish-shell/issues/6910>).
* open no longer hangs indefinitely on certain systems, as a bug in
xdg-open has been worked around (#7215 <https://github.com/fish-
shell/fish-shell/issues/7215>).
* Long command lines no longer add a blank line after execution (#6826
<https://github.com/fish-shell/fish-shell/issues/6826>) and behave better
with backspace (#6951 <https://github.com/fish-shell/fish-shell/is-
sues/6951>).
* functions -t works like the long option --handlers-type, as documented,
instead of producing an error (#6985 <https://github.com/fish-shell/fish-
shell/issues/6985>).
* History search now flashes when it found no more results (#7362
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/7335>).
* set_color --print-colors now also respects the bold, dim, underline, re-
verse, italic and background modifiers, to better show their effect (-
#7314 <https://github.com/fish-shell/fish-shell/issues/7314>).
* The fish Web configuration tool (fish_config) shows prompts correctly on
Termux for Android (#7298 <https://github.com/fish-shell/fish-shell/is-
sues/7298>) and detects Windows Services for Linux 2 properly (#7027
<https://github.com/fish-shell/fish-shell/issues/7027>). It no longer
shows the history variable as it may be too large (one can use the His-
tory tab instead). It also starts the browser in another thread, avoiding
hangs in some circumstances, especially with Firefox's Developer Edition
(#7158 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-
shell/fish-shell/issues/7714>).
* funcsave gained a new --directory option to specify the location of the
saved function (#7041 <https://github.com/fish-shell/fish-shell/is-
sues/7041>).
* help works properly on MSYS2 (#7113 <https://github.com/fish-shell/fish-
shell/issues/7113>) and only uses cmd.exe if running on WSL (#6797
<https://github.com/fish-shell/fish-shell/issues/6797>).
* Resuming a piped job by its number, like fg %1, works correctly (#7406
<https://github.com/fish-shell/fish-shell/issues/7406>). Resumed jobs
show the correct title in the terminal emulator (#7444
<https://github.com/fish-shell/fish-shell/issues/7444>).
* Commands run from key bindings now use the same TTY modes as normal com-
mands (#7483 <https://github.com/fish-shell/fish-shell/issues/7483>).
* Autosuggestions from history are now case-sensitive (#3978
<https://github.com/fish-shell/fish-shell/issues/3978>).
* $status from completion scripts is no longer passed outside the comple-
tion, which keeps the status display in the prompt as the last command's
status (#7555 <https://github.com/fish-shell/fish-shell/issues/7555>).
* Updated localisations for pt_BR (#7480 <https://github.com/fish-
shell/fish-shell/issues/7480>).
* fish_trace output now starts with -> (like fish --profile), making the
depth more visible (#7538 <https://github.com/fish-shell/fish-shell/is-
sues/7538>).
* Resizing the terminal window no longer produces a corrupted prompt (#6532
<https://github.com/fish-shell/fish-shell/issues/6532>, #7404
<https://github.com/fish-shell/fish-shell/issues/7404>).
* functions produces an error rather than crashing on certain invalid argu-
ments (#7515 <https://github.com/fish-shell/fish-shell/issues/7515>).
* A crash in completions with inline variable assignment (eg A= b) has been
fixed (#7344 <https://github.com/fish-shell/fish-shell/issues/7344>).
* fish_private_mode may now be changed dynamically using set (#7589
<https://github.com/fish-shell/fish-shell/issues/7589>), and history is
kept in memory in private mode (but not stored permanently) (#7590
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/1383>).
* Importing bash history or reporting errors with recursive globs (**) no
longer hangs (#7407 <https://github.com/fish-shell/fish-shell/is-
sues/7407>, #7497 <https://github.com/fish-shell/fish-shell/is-
sues/7497>).
* bind now shows \x7f for the del key instead of a literal DEL character (-
#7631 <https://github.com/fish-shell/fish-shell/issues/7631>)
* Paths containing variables or tilde expansion are only suggested when
they are still valid (#7582 <https://github.com/fish-shell/fish-shell/is-
sues/7582>).
* Syntax highlighting can now color a command as invalid even if executed
quickly (#5912 <https://github.com/fish-shell/fish-shell/issues/5912>).
* Redirection targets are no longer highlighted as error if they contain
variables which will likely be defined by the current commandline (#6654
<https://github.com/fish-shell/fish-shell/issues/6654>).
* fish is now more resilient against broken terminal modes (#7133
<https://github.com/fish-shell/fish-shell/issues/7133>, #4873
<https://github.com/fish-shell/fish-shell/issues/4873>).
* fish handles being in control of the TTY without owning its own process
group better, avoiding some hangs in special configurations (#7388
<https://github.com/fish-shell/fish-shell/issues/7388>).
* Keywords can now be colored differently by setting the fish_color_keyword
variable (fish_color_command is used as a fallback) (#7678
<https://github.com/fish-shell/fish-shell/issues/7678>).
* Just like fish_indent, the interactive reader will indent continuation
lines that follow a line ending in a backslash, |, && or || (#7694
<https://github.com/fish-shell/fish-shell/issues/7694>).
* Commands with a trailing escaped space are saved in history correctly (-
#7661 <https://github.com/fish-shell/fish-shell/issues/7661>).
* fish_prompt no longer mangles Unicode characters in the private-use range
U+F600-U+F700. (#7723 <https://github.com/fish-shell/fish-shell/is-
sues/7723>).
* The universal variable file, fish_variables, can be made a symbolic link
without it being overwritten (#7466 <https://github.com/fish-shell/fish-
shell/issues/7466>).
* fish is now more resilient against mktemp failing (#7482
<https://github.com/fish-shell/fish-shell/issues/7482>).
New or improved bindings
* As mentioned above, new special input functions undo (ctrl-_ or ctrl-z)
and redo (alt-/) can be used to revert changes to the command line or the
pager search field (#6570 <https://github.com/fish-shell/fish-shell/is-
sues/6570>).
* ctrl-z is now available for binding (#7152 <https://github.com/fish-
shell/fish-shell/issues/7152>).
* Additionally, using the cancel special input function (bound to escape by
default) right after fish picked an unambiguous completion will undo that
(#7433 <https://github.com/fish-shell/fish-shell/issues/7433>).
* fish_clipboard_paste (ctrl-v) trims indentation from multiline commands,
because fish already indents (#7662 <https://github.com/fish-shell/fish-
shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/6648>, -
#6755 <https://github.com/fish-shell/fish-shell/issues/6755>, #6769
<https://github.com/fish-shell/fish-shell/issues/6769>, #7442
<https://github.com/fish-shell/fish-shell/issues/7442>, #7516
<https://github.com/fish-shell/fish-shell/issues/7516>).
* Vi mode bindings support ~ (tilde) to toggle the case of the selected
character (#6908 <https://github.com/fish-shell/fish-shell/issues/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 situations.
* 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 (pageup) now moves to the
oldest search instead of the youngest - that's end-of-history (pagedown).
* A new special input function forward-single-char moves one character to
the right, and if an autosuggestion is available, only take a single
character from it (#7217 <https://github.com/fish-shell/fish-shell/is-
sues/7217>, #4984 <https://github.com/fish-shell/fish-shell/is-
sues/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
<https://github.com/fish-shell/fish-shell/issues/7217>). This includes
suppress-autosuggestion to reflect whether an autosuggestion was sup-
pressed (#1419 <https://github.com/fish-shell/fish-shell/issues/1419>)
* A new function __fish_preview_current_file, bound to alt-o, opens the
current file at the cursor in a pager (#6838 <https://github.com/fish-
shell/fish-shell/issues/6838>, #6855 <https://github.com/fish-shell/fish-
shell/issues/6855>).
* edit_command_buffer (alt-e and alt-v) passes the cursor position to the
external editor if the editor is recognized (#6138
<https://github.com/fish-shell/fish-shell/issues/6138>, #6954
<https://github.com/fish-shell/fish-shell/issues/6954>).
* __fish_prepend_sudo (alt-s) now toggles a sudo prefix (#7012
<https://github.com/fish-shell/fish-shell/issues/7012>) and avoids shift-
ing the cursor (#6542 <https://github.com/fish-shell/fish-shell/is-
sues/6542>).
* __fish_prepend_sudo (alt-s) now uses the previous commandline if the cur-
rent one is empty, to simplify rerunning the previous command with sudo
(#7079 <https://github.com/fish-shell/fish-shell/issues/7079>).
* __fish_toggle_comment_commandline (alt-#) now uncomments and presents the
last comment from history if the commandline is empty (#7137
<https://github.com/fish-shell/fish-shell/issues/7137>).
* __fish_whatis_current_token (alt-w) prints descriptions for functions and
builtins (#7191 <https://github.com/fish-shell/fish-shell/issues/7191>, -
#2083 <https://github.com/fish-shell/fish-shell/issues/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 charac-
ters (#7353 <https://github.com/fish-shell/fish-shell/issues/7353>, #7354
<https://github.com/fish-shell/fish-shell/issues/7354>, #4025
<https://github.com/fish-shell/fish-shell/issues/4025>, #7328
<https://github.com/fish-shell/fish-shell/issues/7328>, #7325
<https://github.com/fish-shell/fish-shell/issues/7325>)
* fish's clipboard bindings now also support Windows Subsystem for Linux
via PowerShell and clip.exe (#7455 <https://github.com/fish-shell/fish-
shell/issues/7455>, #7458 <https://github.com/fish-shell/fish-shell/is-
sues/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 <https://github.com/fish-shell/fish-shell/issues/7398>).
Improved prompts
* The default and example prompts print the correct exit status for com-
mands prefixed with not (#6566 <https://github.com/fish-shell/fish-
shell/issues/6566>).
* git prompts include all untracked files in the repository, not just those
in the current directory (#6086 <https://github.com/fish-shell/fish-
shell/issues/6086>).
* The git prompts correctly show stash states (#6876
<https://github.com/fish-shell/fish-shell/issues/6876>, #7136
<https://github.com/fish-shell/fish-shell/issues/7136>) and clean states
(#7471 <https://github.com/fish-shell/fish-shell/issues/7471>).
* The Mercurial prompt correctly shows untracked status (#6906
<https://github.com/fish-shell/fish-shell/issues/6906>), and by default
only shows the branch for performance reasons. A new variable
$fish_prompt_hg_show_informative_status can be set to enable more infor-
mation.
* The fish_vcs_prompt passes its arguments to the various VCS prompts that
it calls (#7033 <https://github.com/fish-shell/fish-shell/issues/7033>).
* The Subversion prompt was broken in a number of ways in 3.1.0 and has
been restored (#6715 <https://github.com/fish-shell/fish-shell/is-
sues/6715>, #7278 <https://github.com/fish-shell/fish-shell/is-
sues/7278>).
* A new helper function fish_is_root_user simplifies checking for superuser
privilege (#7031 <https://github.com/fish-shell/fish-shell/issues/7031>,
#7123 <https://github.com/fish-shell/fish-shell/issues/7123>).
* New colorschemes - ayu Light, ayu Dark and ayu Mirage (#7596
<https://github.com/fish-shell/fish-shell/issues/7596>).
* Bugs related to multiline prompts, including repainting (#5860
<https://github.com/fish-shell/fish-shell/issues/5860>) or navigating di-
rectory history (#3550 <https://github.com/fish-shell/fish-shell/is-
sues/3550>) leading to graphical glitches have been fixed.
* The nim prompt now handles vi mode better (#6802
<https://github.com/fish-shell/fish-shell/issues/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, regardless of terminal
(#6968 <https://github.com/fish-shell/fish-shell/issues/6968>). The
fish_vi_cursor option --force-iterm has been deprecated.
* diff will now colourize output, if supported (#7308
<https://github.com/fish-shell/fish-shell/issues/7308>).
* Autosuggestions appear when the cursor passes the right prompt (#6948
<https://github.com/fish-shell/fish-shell/issues/6948>) or wraps to the
next line (#7213 <https://github.com/fish-shell/fish-shell/issues/7213>).
* The cursor shape in Vi mode changes properly in Windows Terminal (#6999
<https://github.com/fish-shell/fish-shell/issues/6999>, #6478
<https://github.com/fish-shell/fish-shell/issues/6478>).
* The spurious warning about terminal size in small terminals has been re-
moved (#6980 <https://github.com/fish-shell/fish-shell/issues/6980>).
* Dynamic titles are now enabled in Alacritty (#7073
<https://github.com/fish-shell/fish-shell/issues/7073>) and emacs' vterm
(#7122 <https://github.com/fish-shell/fish-shell/issues/7122>).
* Current working directory updates are enabled in foot (#7099
<https://github.com/fish-shell/fish-shell/issues/7099>) and WezTerm (-
#7649 <https://github.com/fish-shell/fish-shell/issues/7649>).
* The width computation for certain emoji agrees better with terminals (es-
pecially flags). (#7237 <https://github.com/fish-shell/fish-shell/is-
sues/7237>).
* Long command lines are wrapped in all cases, instead of sometimes being
put on a new line (#5118 <https://github.com/fish-shell/fish-shell/is-
sues/5118>).
* The pager is properly rendered with long command lines selected (#2557
<https://github.com/fish-shell/fish-shell/issues/2557>).
* Sessions with right prompts can be resized correctly in terminals that
handle reflow, like GNOME Terminal (and other VTE-based terminals), up-
coming Konsole releases and Alacritty. This detection can be overridden
with the new fish_handle_reflow variable (#7491 <https://github.com/fish-
shell/fish-shell/issues/7491>).
* fish now sets terminal modes sooner, which stops output from appearing
before the greeting and prompt are ready (#7489 <https://github.com/fish-
shell/fish-shell/issues/7489>).
* Better detection of new Konsole versions for true color support and cur-
sor shape changing.
* fish no longer attempts to modify the terminal size via TIOCSWINSZ, im-
proving compatibility with Kitty (#6994 <https://github.com/fish-
shell/fish-shell/issues/6994>).
Completions
* Added completions for
* 7z, 7za and 7zr (#7220 <https://github.com/fish-shell/fish-shell/is-
sues/7220>)
* alias (#7035 <https://github.com/fish-shell/fish-shell/issues/7035>)
* alternatives (#7616 <https://github.com/fish-shell/fish-shell/is-
sues/7616>)
* apk (#7108 <https://github.com/fish-shell/fish-shell/issues/7108>)
* asciidoctor (#7000 <https://github.com/fish-shell/fish-shell/is-
sues/7000>)
* avifdec and avifenc (#7674 <https://github.com/fish-shell/fish-
shell/issues/7674>)
* bluetoothctl (#7438 <https://github.com/fish-shell/fish-shell/is-
sues/7438>)
* cjxl and djxl (#7673 <https://github.com/fish-shell/fish-shell/is-
sues/7673>)
* cmark (#7000 <https://github.com/fish-shell/fish-shell/issues/7000>)
* create_ap (#7096 <https://github.com/fish-shell/fish-shell/is-
sues/7096>)
* deno (#7138 <https://github.com/fish-shell/fish-shell/issues/7138>)
* dhclient (#6684 <https://github.com/fish-shell/fish-shell/issues/6684>)
* Postgres-related commands dropdb, createdb, pg_restore, pg_dump and
pg_dumpall (#6620 <https://github.com/fish-shell/fish-shell/is-
sues/6620>)
* dotnet (#7558 <https://github.com/fish-shell/fish-shell/issues/7558>)
* downgrade (#6751 <https://github.com/fish-shell/fish-shell/is-
sues/6751>)
* gapplication, gdbus, gio and gresource (#7300 <https://github.com/fish-
shell/fish-shell/issues/7300>)
* gh (#7112 <https://github.com/fish-shell/fish-shell/issues/7112>)
* gitk
* groups (#6889 <https://github.com/fish-shell/fish-shell/issues/6889>)
* hashcat (#7746 <https://github.com/fish-shell/fish-shell/issues/7746>)
* hikari (#7083 <https://github.com/fish-shell/fish-shell/issues/7083>)
* icdiff (#7503 <https://github.com/fish-shell/fish-shell/issues/7503>)
* imv (#6675 <https://github.com/fish-shell/fish-shell/issues/6675>)
* john (#7746 <https://github.com/fish-shell/fish-shell/issues/7746>)
* julia (#7468 <https://github.com/fish-shell/fish-shell/issues/7468>)
* k3d (#7202 <https://github.com/fish-shell/fish-shell/issues/7202>)
* ldapsearch (#7578 <https://github.com/fish-shell/fish-shell/is-
sues/7578>)
* lightdm and dm-tool (#7624 <https://github.com/fish-shell/fish-
shell/issues/7624>)
* losetup (#7621 <https://github.com/fish-shell/fish-shell/issues/7621>)
* micro (#7339 <https://github.com/fish-shell/fish-shell/issues/7339>)
* mpc (#7169 <https://github.com/fish-shell/fish-shell/issues/7169>)
* Metasploit's msfconsole, msfdb and msfvenom (#6930
<https://github.com/fish-shell/fish-shell/issues/6930>)
* mtr (#7638 <https://github.com/fish-shell/fish-shell/issues/7638>)
* mysql (#6819 <https://github.com/fish-shell/fish-shell/issues/6819>)
* ncat, nc.openbsd, nc.traditional and nmap (#6873
<https://github.com/fish-shell/fish-shell/issues/6873>)
* openssl (#6845 <https://github.com/fish-shell/fish-shell/issues/6845>)
* prime-run (#7241 <https://github.com/fish-shell/fish-shell/is-
sues/7241>)
* ps2pdf{12,13,14,wr} (#6673 <https://github.com/fish-shell/fish-
shell/issues/6673>)
* pyenv (#6551 <https://github.com/fish-shell/fish-shell/issues/6551>)
* rst2html, rst2html4, rst2html5, rst2latex, rst2man, rst2odt, rst2pseu-
doxml, rst2s5, rst2xetex, rst2xml and rstpep2html (#7019
<https://github.com/fish-shell/fish-shell/issues/7019>)
* spago (#7381 <https://github.com/fish-shell/fish-shell/issues/7381>)
* sphinx-apidoc, sphinx-autogen, sphinx-build and sphinx-quickstart (-
#7000 <https://github.com/fish-shell/fish-shell/issues/7000>)
* strace (#6656 <https://github.com/fish-shell/fish-shell/issues/6656>)
* systemd's bootctl, coredumpctl, hostnamectl (#7428
<https://github.com/fish-shell/fish-shell/issues/7428>), homectl (#7435
<https://github.com/fish-shell/fish-shell/issues/7435>), networkctl (-
#7668 <https://github.com/fish-shell/fish-shell/issues/7668>) and
userdbctl (#7667 <https://github.com/fish-shell/fish-shell/is-
sues/7667>)
* tcpdump (#6690 <https://github.com/fish-shell/fish-shell/issues/6690>)
* tig
* traceroute and tracepath (#6803 <https://github.com/fish-shell/fish-
shell/issues/6803>)
* windscribe (#6788 <https://github.com/fish-shell/fish-shell/is-
sues/6788>)
* wireshark, tshark, and dumpcap
* xbps-* (#7239 <https://github.com/fish-shell/fish-shell/issues/7239>)
* xxhsum, xxh32sum, xxh64sum and xxh128sum (#7103
<https://github.com/fish-shell/fish-shell/issues/7103>)
* yadm (#7100 <https://github.com/fish-shell/fish-shell/issues/7100>)
* zopfli and zopflipng (#6872 <https://github.com/fish-shell/fish-
shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/7075>, #7652 <https://github.com/fish-shell/fish-shell/is-
sues/7652>, #4358 <https://github.com/fish-shell/fish-shell/is-
sues/4358>)
* make completions no longer second-guess make's file detection, fixing
target completion in some cases (#7535 <https://github.com/fish-
shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/7086>, #6879
<https://github.com/fish-shell/fish-shell/issues/6879>, #7187
<https://github.com/fish-shell/fish-shell/issues/7187>).
* Significant performance improvements to completion of the available com-
mands (#7153 <https://github.com/fish-shell/fish-shell/issues/7153>), es-
pecially on macOS Big Sur where there was a significant regression (#7365
<https://github.com/fish-shell/fish-shell/issues/7365>, #7511
<https://github.com/fish-shell/fish-shell/issues/7511>).
* Suffix completion using __fish_complete_suffix uses the same fuzzy match-
ing logic as normal file completion, and completes any file but sorts
files with matching suffix first (#7040 <https://github.com/fish-
shell/fish-shell/issues/7040>, #7547 <https://github.com/fish-shell/fish-
shell/issues/7547>). Previously, it only completed files with matching
suffix.
For distributors
* fish has a new interactive test driver based on pexpect, removing the op-
tional dependency on expect (and adding an optional dependency on pex-
pect) (#5451 <https://github.com/fish-shell/fish-shell/issues/5451>, -
#6825 <https://github.com/fish-shell/fish-shell/issues/6825>).
* The CHANGELOG was moved to restructured text, allowing it to be included
in the documentation (#7057 <https://github.com/fish-shell/fish-shell/is-
sues/7057>).
* fish handles ncurses installed in a non-standard prefix better (#6600
<https://github.com/fish-shell/fish-shell/issues/6600>, #7219
<https://github.com/fish-shell/fish-shell/issues/7219>), and uses vari-
adic tparm on NetBSD curses (#6626 <https://github.com/fish-shell/fish-
shell/issues/6626>).
* The Web-based configuration tool no longer uses an obsolete Angular ver-
sion (#7147 <https://github.com/fish-shell/fish-shell/issues/7147>).
* The fish project has adopted the Contributor Covenant code of conduct (-
#7151 <https://github.com/fish-shell/fish-shell/issues/7151>).
Deprecations and removed features
* The fish_color_match variable is no longer used. (Previously this con-
trolled the color of matching quotes and parens when using read).
* fish 3.2.0 will be the last release in which the redirection to standard
error with the ^ character is enabled. The stderr-nocaret feature 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 favor 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-defined
__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 <https://github.com/fish-shell/fish-
shell/issues/7039>).
* To disable the greeting message permanently it is no longer enough to
just run set fish_greeting interactively as it is no longer implicitly 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 <https://github.com/fish-
shell/fish-shell/issues/7659>).
* With the addition of new categories for debug options, the old numbered
debugging levels have been removed.
For distributors and developers
* fish source tarballs are now distributed using the XZ compression method
(#5460 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/6952>, #6792 <https://github.com/fish-shell/fish-shell/is-
sues/6792>).
* Building on on macOS earlier than 10.13.6 succeeds, instead of failing on
code-signing (#6791 <https://github.com/fish-shell/fish-shell/is-
sues/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 <https://github.com/fish-shell/fish-shell/is-
sues/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 codesigning is en-
abled (#6952 <https://github.com/fish-shell/fish-shell/issues/6952>).
* Running the full interactive test suite now requires Python 3.5+ and the
pexpect package (#6825 <https://github.com/fish-shell/fish-shell/is-
sues/6825>); the expect package is no longer required.
* 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 <https://github.com/fish-shell/fish-shell/issues/6537>).
* The Web-based configuration tool is compatible with Python 3.10 (#7600
<https://github.com/fish-shell/fish-shell/issues/7600>) and no longer re-
quires Python's distutils package (#7514 <https://github.com/fish-
shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/6613>).
* Conflicts between upstream packages for ripgrep and bat, and the fish
packages, have been resolved (#5822 <https://github.com/fish-shell/fish-
shell/issues/5822>).
* Starting fish in a directory without read access, such as via su, no
longer crashes (#6597 <https://github.com/fish-shell/fish-shell/is-
sues/6597>).
* Glob ordering changes which were introduced in 3.1.0 have been reverted,
returning the order of globs to the previous state (#6593
<https://github.com/fish-shell/fish-shell/issues/6593>).
* Redirections using the deprecated caret syntax to a file descriptor (eg
^&2) work correctly (#6591 <https://github.com/fish-shell/fish-shell/is-
sues/6591>).
* Redirections that append to a file descriptor (eg 2>>&1) work correctly
(#6614 <https://github.com/fish-shell/fish-shell/issues/6614>).
* Building fish on macOS (#6602 <https://github.com/fish-shell/fish-
shell/issues/6602>) or with new versions of GCC (#6604
<https://github.com/fish-shell/fish-shell/issues/6604>, #6609
<https://github.com/fish-shell/fish-shell/issues/6609>) is now success-
ful.
* time is now correctly listed in the output of builtin -n, and time --help
works correctly (#6598 <https://github.com/fish-shell/fish-shell/is-
sues/6598>).
* Exported universal variables now update properly (#6612
<https://github.com/fish-shell/fish-shell/issues/6612>).
* status current-command gives the expected output when used with an envi-
ronment override - that is, F=B status current-command returns status in-
stead of F=B (#6635 <https://github.com/fish-shell/fish-shell/is-
sues/6635>).
* test no longer crashes when used with anana or ainfa arguments, erroring
out instead (#6655 <https://github.com/fish-shell/fish-shell/is-
sues/6655>).
* Copying from the end of the command line no longer crashes fish (#6680
<https://github.com/fish-shell/fish-shell/issues/6680>).
* read no longer removes multiple separators when splitting a variable into
a list, restoring the previous behaviour from fish 3.0 and before (#6650
<https://github.com/fish-shell/fish-shell/issues/6650>).
* Functions using --on-job-exit and --on-process-exit work reliably again
(#6679 <https://github.com/fish-shell/fish-shell/issues/6679>).
* Functions using --on-signal INT work reliably in interactive sessions, as
they did in fish 2.7 and before (#6649 <https://github.com/fish-
shell/fish-shell/issues/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 afish_bind_modea and aPWDa (-
#6653 <https://github.com/fish-shell/fish-shell/issues/6653>).
* 256 colors are properly enabled under certain conditions that were incor-
rectly detected in fish 3.1.0 ($TERM begins with xterm, does not include
a256colora, and $TERM_PROGRAM is not set) (#6701
<https://github.com/fish-shell/fish-shell/issues/6701>).
* The Mercurial (hg) prompt no longer produces an error when the current
working directory is removed (#6699 <https://github.com/fish-shell/fish-
shell/issues/6699>). Also, for performance reasons it shows only basic
information by default; to restore the detailed status, set
$fish_prompt_hg_show_informative_status.
* The VCS prompt, fish_vcs_prompt, no longer displays Subversion (svn) sta-
tus by default, due to the potential slowness of this operation (#6681
<https://github.com/fish-shell/fish-shell/issues/6681>).
* Pasting of commands has been sped up (#6713 <https://github.com/fish-
shell/fish-shell/issues/6713>).
* Using extended Unicode characters, such as emoji, in a non-Unicode capa-
ble locale (such as the C or POSIX locale) no longer renders all output
blank (#6736 <https://github.com/fish-shell/fish-shell/issues/6736>).
* help prefers to use xdg-open, avoiding the use of open on Debian systems
where this command is actually openvt (#6739 <https://github.com/fish-
shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/6763>), but may be changed in a future version.
* Copying to the clipboard no longer inserts a newline at the end of the
content, matching fish 2.7 and earlier (#6927 <https://github.com/fish-
shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/6624>, -
#6806 <https://github.com/fish-shell/fish-shell/issues/6806>).
This release also includes:
* several changes to improve macOS compatibility with code signing and no-
tarization;
* 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 <https://github.com/fish-shell/fish-
shell/issues/6564>).
* Fixes a number of problems in compiling and testing on Cygwin (#6549
<https://github.com/fish-shell/fish-shell/issues/6549>) and Solaris-de-
rived systems such as Illumos (#6553 <https://github.com/fish-shell/fish-
shell/issues/6553>, #6554 <https://github.com/fish-shell/fish-shell/is-
sues/6554>, #6555 <https://github.com/fish-shell/fish-shell/issues/6555>,
#6556 <https://github.com/fish-shell/fish-shell/issues/6556>, and #6558
<https://github.com/fish-shell/fish-shell/issues/6558>).
* Fixes the process for building macOS packages.
* Fixes a regression where excessive error messages are printed if Unicode
characters are emitted in non-Unicode-capable locales (#6584
<https://github.com/fish-shell/fish-shell/issues/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 previ-
ous job, for each of the separate commands in a pipeline (#5632
<https://github.com/fish-shell/fish-shell/issues/5632>).
* fish no longer buffers pipes to the last function in a pipeline, improv-
ing many cases where pipes appeared to block or hang (#1396
<https://github.com/fish-shell/fish-shell/issues/1396>).
* An overhaul of error messages for builtin commands, including a removal
of the overwhelming usage summary, more readable stack traces (#3404
<https://github.com/fish-shell/fish-shell/issues/3404>, #5434
<https://github.com/fish-shell/fish-shell/issues/5434>), and stack traces
for test (aka [) (#5771 <https://github.com/fish-shell/fish-shell/is-
sues/5771>).
* fishas 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 <https://github.com/fish-shell/fish-
shell/issues/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 <https://github.com/fish-shell/fish-
shell/issues/159>).
* The fish manual, tutorial and FAQ are now available in man format as
fish-doc, fish-tutorial and fish-faq respectively (#5521
<https://github.com/fish-shell/fish-shell/issues/5521>).
* Like other shells, cd now always looks for its argument in the current
directory as a last resort, even if the CDPATH variable does not include
it or a.a (#4484 <https://github.com/fish-shell/fish-shell/issues/4484>).
* fish now correctly handles CDPATH entries that start with .. (#6220
<https://github.com/fish-shell/fish-shell/issues/6220>) or contain ./ (-
#5887 <https://github.com/fish-shell/fish-shell/issues/5887>).
* The fish_trace variable may be set to trace execution (#3427
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/3845>).
* The fish Web configuration tool (fish_config) prints a list of commands
it is executing, to help understanding and debugging (#5584
<https://github.com/fish-shell/fish-shell/issues/5584>).
* Major performance improvements when pasting (#5866
<https://github.com/fish-shell/fish-shell/issues/5866>), executing lots
of commands (#5905 <https://github.com/fish-shell/fish-shell/is-
sues/5905>), importing history from bash (#6295 <https://github.com/fish-
shell/fish-shell/issues/6295>), and when completing variables that might
match $history (#6288 <https://github.com/fish-shell/fish-shell/is-
sues/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 <https://github.com/fish-
shell/fish-shell/issues/117>).
* Brace expansion now only takes place if the braces include a a,a or a
variable expansion, meaning common commands such as git reset HEAD@{0} do
not require escaping (#5869 <https://github.com/fish-shell/fish-shell/is-
sues/5869>).
* New redirections &> and &| may be used to redirect or pipe stdout, and
also redirect stderr to stdout (#6192 <https://github.com/fish-
shell/fish-shell/issues/6192>).
* switch now allows arguments that expand to nothing, like empty variables
(#5677 <https://github.com/fish-shell/fish-shell/issues/5677>).
* The VAR=val cmd syntax can now be used to run a command in a modified en-
vironment (#6287 <https://github.com/fish-shell/fish-shell/issues/6287>).
* and is no longer recognised as a command, so that nonsensical constructs
like and and and produce a syntax error (#6089 <https://github.com/fish-
shell/fish-shell/issues/6089>).
* mathas exponent operator,a^a, was previously left-associative, but now
uses the more commonly-used right-associative behaviour (#6280
<https://github.com/fish-shell/fish-shell/issues/6280>). This means that
math '3^0.5^2' was previously calculated asa(30.5)2a, but is now calcu-
lated as a3(0.52)a.
* In fish 3.0, the variable used with for loops inside command substitu-
tions could leak into enclosing scopes; this was an inadvertent behaviour
change and has been reverted (#6480 <https://github.com/fish-shell/fish-
shell/issues/6480>).
Scripting improvements
* string split0 now returns 0 if it split something (#5701
<https://github.com/fish-shell/fish-shell/issues/5701>).
* In the interest of consistency, builtin -q and command -q can now be used
to query if a builtin or command exists (#5631 <https://github.com/fish-
shell/fish-shell/issues/5631>).
* math now accepts --scale=max for the maximum scale (#5579
<https://github.com/fish-shell/fish-shell/issues/5579>).
* builtin $var now works correctly, allowing a variable as the builtin name
(#5639 <https://github.com/fish-shell/fish-shell/issues/5639>).
* cd understands the -- argument to make it possible to change to directo-
ries starting with a hyphen (#6071 <https://github.com/fish-shell/fish-
shell/issues/6071>).
* complete --do-complete now also does fuzzy matches (#5467
<https://github.com/fish-shell/fish-shell/issues/5467>).
* complete --do-complete can be used inside completions, allowing limited
recursion (#3474 <https://github.com/fish-shell/fish-shell/issues/3474>).
* count now also counts lines fed on standard input (#5744
<https://github.com/fish-shell/fish-shell/issues/5744>).
* eval produces an exit status of 0 when given no arguments, like other
shells (#5692 <https://github.com/fish-shell/fish-shell/issues/5692>).
* printf prints what it can when input hasnat been fully converted to a
number, but still prints an error (#5532 <https://github.com/fish-
shell/fish-shell/issues/5532>).
* complete -C foo now works as expected, rather than requiring complete
-Cfoo.
* complete has a new --force-files option, to re-enable file completions.
This allows sudo -E and pacman -Qo to complete correctly (#5646
<https://github.com/fish-shell/fish-shell/issues/5646>).
* argparse now defaults to showing the current function name (instead of
argparse) in its errors, making --name often superfluous (#5835
<https://github.com/fish-shell/fish-shell/issues/5835>).
* argparse has a new --ignore-unknown option to keep unrecognized options,
allowing multiple argparse passes to parse options (#5367
<https://github.com/fish-shell/fish-shell/issues/5367>).
* argparse correctly handles flag value validation of options that only
have short names (#5864 <https://github.com/fish-shell/fish-shell/is-
sues/5864>).
* read -S (short option of --shell) is recognised correctly (#5660
<https://github.com/fish-shell/fish-shell/issues/5660>).
* read understands --list, which acts like --array in reading all arguments
into a list inside a single variable, but is better named (#5846
<https://github.com/fish-shell/fish-shell/issues/5846>).
* read has a new option, --tokenize, which splits a string into variables
according to the shellas tokenization rules, considering quoting, escap-
ing, and so on (#3823 <https://github.com/fish-shell/fish-shell/is-
sues/3823>).
* read interacts more correctly with the deprecated $IFS variable, in par-
ticular removing multiple separators when splitting a variable into a
list (#6406 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/5859>).
* fish_indent --write now supports multiple file arguments, indenting them
in turn.
* The default read limit has been increased to 100MiB (#5267
<https://github.com/fish-shell/fish-shell/issues/5267>).
* math now also understands x for multiplication, provided it is followed
by whitespace (#5906 <https://github.com/fish-shell/fish-shell/is-
sues/5906>).
* math reports the right error when incorrect syntax is used inside paren-
theses (#6063 <https://github.com/fish-shell/fish-shell/issues/6063>),
and warns when unsupported logical operations are used (#6096
<https://github.com/fish-shell/fish-shell/issues/6096>).
* functions --erase now also prevents fish from autoloading a function for
the first time (#5951 <https://github.com/fish-shell/fish-shell/is-
sues/5951>).
* jobs --last returns 0 to indicate success when a job is found (#6104
<https://github.com/fish-shell/fish-shell/issues/6104>).
* commandline -p and commandline -j now split on && and || in addition to ;
and & (#6214 <https://github.com/fish-shell/fish-shell/issues/6214>).
* A bug where string split would drop empty strings if the output was only
empty strings has been fixed (#5987 <https://github.com/fish-shell/fish-
shell/issues/5987>).
* eval no long creates a new local variable scope, but affects variables in
the scope it is called from (#4443 <https://github.com/fish-shell/fish-
shell/issues/4443>). source still creates a new local scope.
* abbr has a new --query option to check for the existence of an abbrevia-
tion.
* Local values for fish_complete_path and fish_function_path are now ig-
nored; only their global values are respected.
* Syntax error reports now display a marker in the correct position (#5812
<https://github.com/fish-shell/fish-shell/issues/5812>).
* Empty universal variables may now be exported (#5992
<https://github.com/fish-shell/fish-shell/issues/5992>).
* Exported universal variables are no longer imported into the global
scope, preventing shadowing. This makes it easier to change such vari-
ables for all fish sessions and avoids breakage when the value is a list
of multiple elements (#5258 <https://github.com/fish-shell/fish-shell/is-
sues/5258>).
* A bug where for could use invalid variable names has been fixed (#5800
<https://github.com/fish-shell/fish-shell/issues/5800>).
* A bug where local variables would not be exported to functions has been
fixed (#6153 <https://github.com/fish-shell/fish-shell/issues/6153>).
* The null command (:) now always exits successfully, rather than passing
through the previous exit status (#6022 <https://github.com/fish-
shell/fish-shell/issues/6022>).
* The output of functions FUNCTION matches the declaration of the function,
correctly including comments or blank lines (#5285
<https://github.com/fish-shell/fish-shell/issues/5285>), and correctly
includes any --wraps flags (#1625 <https://github.com/fish-shell/fish-
shell/issues/1625>).
* type supports a new option, --short, which suppress function expansion (-
#6403 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-
shell/fish-shell/issues/6411>).
* The $hostname variable is no longer truncated to 32 characters (#5758
<https://github.com/fish-shell/fish-shell/issues/5758>).
* Line numbers in function backtraces are calculated correctly (#6350
<https://github.com/fish-shell/fish-shell/issues/6350>).
* A new fish_cancel event is emitted when the command line is cancelled,
which is useful for terminal integration (#5973 <https://github.com/fish-
shell/fish-shell/issues/5973>).
Interactive improvements
* New Base16 color options are available through the Web-based configura-
tion (#6504 <https://github.com/fish-shell/fish-shell/issues/6504>).
* fish only parses /etc/paths on macOS in login shells, matching the bash
implementation (#5637 <https://github.com/fish-shell/fish-shell/is-
sues/5637>) and avoiding changes to path ordering in child shells (#5456
<https://github.com/fish-shell/fish-shell/issues/5456>). It now ignores
blank lines like the bash implementation (#5809 <https://github.com/fish-
shell/fish-shell/issues/5809>).
* The locale is now reloaded when the LOCPATH variable is changed (#5815
<https://github.com/fish-shell/fish-shell/issues/5815>).
* read no longer keeps a history, making it suitable for operations that
shouldnat end up there, like password entry (#5904
<https://github.com/fish-shell/fish-shell/issues/5904>).
* dirh outputs its stack in the correct order (#5477
<https://github.com/fish-shell/fish-shell/issues/5477>), and behaves as
documented when universal variables are used for its stack (#5797
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/5625>).
* Builtins now pipe their help output to a pager automatically (#6227
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/5872>).
* When syntax highlighting a string with an unclosed quote, only the quote
itself will be shown as an error, instead of the whole argument.
* Syntax highlighting works correctly with variables as commands (#5658
<https://github.com/fish-shell/fish-shell/issues/5658>) and redirections
to close file descriptors (#6092 <https://github.com/fish-shell/fish-
shell/issues/6092>).
* help works properly on Windows Subsystem for Linux (#5759
<https://github.com/fish-shell/fish-shell/issues/5759>, #6338
<https://github.com/fish-shell/fish-shell/issues/6338>).
* A bug where disown could crash the shell has been fixed (#5720
<https://github.com/fish-shell/fish-shell/issues/5720>).
* fish will not autosuggest files ending with ~ unless there are no other
candidates, as these are generally backup files (#985
<https://github.com/fish-shell/fish-shell/issues/985>).
* Escape in the pager works correctly (#5818 <https://github.com/fish-
shell/fish-shell/issues/5818>).
* Key bindings that call fg no longer leave the terminal in a broken state
(#2114 <https://github.com/fish-shell/fish-shell/issues/2114>).
* Brackets (#5831 <https://github.com/fish-shell/fish-shell/issues/5831>)
and filenames containing $ (#6060 <https://github.com/fish-shell/fish-
shell/issues/6060>) are completed with appropriate escaping.
* The output of complete and functions is now colorized in interactive ter-
minals.
* The Web-based configuration handles aliases that include single quotes
correctly (#6120 <https://github.com/fish-shell/fish-shell/issues/6120>),
and launches correctly under Termux (#6248 <https://github.com/fish-
shell/fish-shell/issues/6248>) and OpenBSD (#6522
<https://github.com/fish-shell/fish-shell/issues/6522>).
* function now correctly validates parameters for --argument-names as valid
variable names (#6147 <https://github.com/fish-shell/fish-shell/is-
sues/6147>) and correctly parses options following --argument-names, as
in a--argument-names foo --description bara (#6186
<https://github.com/fish-shell/fish-shell/issues/6186>).
* History newly imported from bash includes command lines using && or ||.
* The automatic generation of completions from manual pages is better de-
scribed in job and process listings, and no longer produces a warning
when exiting fish (#6269 <https://github.com/fish-shell/fish-shell/is-
sues/6269>).
* In private mode, setting $fish_greeting to an empty string before start-
ing the private session will prevent the warning about history not being
saved from being printed (#6299 <https://github.com/fish-shell/fish-
shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/6316>).
* Ctrl-C always repaints the prompt (#6394 <https://github.com/fish-
shell/fish-shell/issues/6394>).
* When run interactively from another program (such as Python), fish will
correctly start a new process group, like other shells (#5909
<https://github.com/fish-shell/fish-shell/issues/5909>).
* Job identifiers (for example, for background jobs) are assigned more log-
ically (#6053 <https://github.com/fish-shell/fish-shell/issues/6053>).
* A bug where history would appear truncated if an empty command was exe-
cuted was fixed (#6032 <https://github.com/fish-shell/fish-shell/is-
sues/6032>).
New or improved bindings
* Pasting strips leading spaces to avoid pasted commands being omitted from
the history (#4327 <https://github.com/fish-shell/fish-shell/is-
sues/4327>).
* Shift-Left and Shift-Right now default to moving backwards and forwards
by one bigword (words separated by whitespace) (#1505
<https://github.com/fish-shell/fish-shell/issues/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 de-
fault mode and 100ms for Vi mode (#3904 <https://github.com/fish-
shell/fish-shell/issues/3904>).
* The forward-bigword binding now interacts correctly with autosuggestions
(#5336 <https://github.com/fish-shell/fish-shell/issues/5336>).
* The fish_clipboard_* functions support Wayland by using wl-clipboard
<https://github.com/bugaevc/wl-clipboard> (#5450
<https://github.com/fish-shell/fish-shell/issues/5450>).
* The nextd and prevd functions no longer print aHit end of historya, in-
stead using a bell. They correctly store working directories containing
symbolic links (#6395 <https://github.com/fish-shell/fish-shell/is-
sues/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 <https://github.com/fish-shell/fish-
shell/issues/5783>).
* The path-component bindings (like Ctrl-w) now also stop at a:a and a@a,
because those are used to denote user and host in commands such as ssh (-
#5841 <https://github.com/fish-shell/fish-shell/issues/5841>).
* The NULL character can now be bound via bind -k nul. Terminals often gen-
erate this character via control-space. (#3189 <https://github.com/fish-
shell/fish-shell/issues/3189>).
* A new readline command expand-abbr can be used to trigger abbreviation
expansion (#5762 <https://github.com/fish-shell/fish-shell/issues/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 sequence, if
not empty.
* A new binding to prepend sudo, bound to Alt-S by default (#6140
<https://github.com/fish-shell/fish-shell/issues/6140>).
* The Alt-W binding to describe a command should now work better with mul-
tiline prompts (#6110 <https://github.com/fish-shell/fish-shell/is-
sues/6110>)
* The Alt-H binding to open a commandas man page now tries to ignore sudo
(#6122 <https://github.com/fish-shell/fish-shell/issues/6122>).
* A new pair of bind functions, history-prefix-search-backward (and for-
ward), was introduced (#6143 <https://github.com/fish-shell/fish-
shell/issues/6143>).
* Vi mode now supports R to enter replace mode (#6342
<https://github.com/fish-shell/fish-shell/issues/6342>), and d0 to delete
the current line (#6292 <https://github.com/fish-shell/fish-shell/is-
sues/6292>).
* In Vi mode, hitting Enter in replace-one mode no longer erases the prompt
(#6298 <https://github.com/fish-shell/fish-shell/issues/6298>).
* Selections in Vi mode are inclusive, matching the actual behaviour of Vi
(#5770 <https://github.com/fish-shell/fish-shell/issues/5770>).
Improved prompts
* The Git prompt in informative mode now shows the number of stashes if en-
abled.
* The Git prompt now has an option ($__fish_git_prompt_use_informa-
tive_chars) to use the (more modern) informative characters without en-
abling informative mode.
* The default prompt now also features VCS integration and will color the
host if running via SSH (#6375 <https://github.com/fish-shell/fish-
shell/issues/6375>).
* The default and example prompts print the pipe status if an earlier com-
mand in the pipe fails.
* The default and example prompts try to resolve exit statuses to signal
names when appropriate.
Improved terminal output
* New fish_pager_color_ options have been added to control more elements of
the pageras colors (#5524 <https://github.com/fish-shell/fish-shell/is-
sues/5524>).
* Better detection and support for using fish from various system consoles,
where limited colors and special characters are supported (#5552
<https://github.com/fish-shell/fish-shell/issues/5552>).
* fish now tries to guess if the system supports Unicode 9 (and displays
emoji as wide), eliminating the need to set $fish_emoji_width in most
cases (#5722 <https://github.com/fish-shell/fish-shell/issues/5722>).
* Improvements to the display of wide characters, particularly Korean char-
acters and emoji (#5583 <https://github.com/fish-shell/fish-shell/is-
sues/5583>, #5729 <https://github.com/fish-shell/fish-shell/is-
sues/5729>).
* The Vi mode cursor is correctly redrawn when regaining focus under termi-
nals that report focus (eg tmux) (#4788 <https://github.com/fish-
shell/fish-shell/issues/4788>).
* Variables that control background colors (such as
fish_pager_color_search_match) can now use --reverse.
Completions
* Added completions for
* aws
* bat (#6052 <https://github.com/fish-shell/fish-shell/issues/6052>)
* bosh (#5700 <https://github.com/fish-shell/fish-shell/issues/5700>)
* btrfs
* camcontrol
* cf (#5700 <https://github.com/fish-shell/fish-shell/issues/5700>)
* chronyc (#6496 <https://github.com/fish-shell/fish-shell/issues/6496>)
* code (#6205 <https://github.com/fish-shell/fish-shell/issues/6205>)
* cryptsetup (#6488 <https://github.com/fish-shell/fish-shell/is-
sues/6488>)
* csc and csi (#6016 <https://github.com/fish-shell/fish-shell/is-
sues/6016>)
* cwebp (#6034 <https://github.com/fish-shell/fish-shell/issues/6034>)
* cygpath and cygstart (#6239 <https://github.com/fish-shell/fish-
shell/issues/6239>)
* epkginfo (#5829 <https://github.com/fish-shell/fish-shell/issues/5829>)
* ffmpeg, ffplay, and ffprobe (#5922 <https://github.com/fish-shell/fish-
shell/issues/5922>)
* fsharpc and fsharpi (#6016 <https://github.com/fish-shell/fish-
shell/issues/6016>)
* fzf (#6178 <https://github.com/fish-shell/fish-shell/issues/6178>)
* g++ (#6217 <https://github.com/fish-shell/fish-shell/issues/6217>)
* gpg1 (#6139 <https://github.com/fish-shell/fish-shell/issues/6139>)
* gpg2 (#6062 <https://github.com/fish-shell/fish-shell/issues/6062>)
* grub-mkrescue (#6182 <https://github.com/fish-shell/fish-shell/is-
sues/6182>)
* hledger (#6043 <https://github.com/fish-shell/fish-shell/issues/6043>)
* hwinfo (#6496 <https://github.com/fish-shell/fish-shell/issues/6496>)
* irb (#6260 <https://github.com/fish-shell/fish-shell/issues/6260>)
* iw (#6232 <https://github.com/fish-shell/fish-shell/issues/6232>)
* kak
* keepassxc-cli (#6505 <https://github.com/fish-shell/fish-shell/is-
sues/6505>)
* keybase (#6410 <https://github.com/fish-shell/fish-shell/issues/6410>)
* loginctl (#6501 <https://github.com/fish-shell/fish-shell/issues/6501>)
* lz4, lz4c and lz4cat (#6364 <https://github.com/fish-shell/fish-
shell/issues/6364>)
* mariner (#5718 <https://github.com/fish-shell/fish-shell/issues/5718>)
* nethack (#6240 <https://github.com/fish-shell/fish-shell/issues/6240>)
* patool (#6083 <https://github.com/fish-shell/fish-shell/issues/6083>)
* phpunit (#6197 <https://github.com/fish-shell/fish-shell/issues/6197>)
* plutil (#6301 <https://github.com/fish-shell/fish-shell/issues/6301>)
* pzstd (#6364 <https://github.com/fish-shell/fish-shell/issues/6364>)
* qubes-gpg-client (#6067 <https://github.com/fish-shell/fish-shell/is-
sues/6067>)
* resolvectl (#6501 <https://github.com/fish-shell/fish-shell/is-
sues/6501>)
* rg
* rustup
* sfdx (#6149 <https://github.com/fish-shell/fish-shell/issues/6149>)
* speedtest and speedtest-cli (#5840 <https://github.com/fish-shell/fish-
shell/issues/5840>)
* src (#6026 <https://github.com/fish-shell/fish-shell/issues/6026>)
* tokei (#6085 <https://github.com/fish-shell/fish-shell/issues/6085>)
* tsc (#6016 <https://github.com/fish-shell/fish-shell/issues/6016>)
* unlz4 (#6364 <https://github.com/fish-shell/fish-shell/issues/6364>)
* unzstd (#6364 <https://github.com/fish-shell/fish-shell/issues/6364>)
* vbc (#6016 <https://github.com/fish-shell/fish-shell/issues/6016>)
* zpaq (#6245 <https://github.com/fish-shell/fish-shell/issues/6245>)
* zstd, zstdcat, zstdgrep, zstdless and zstdmt (#6364
<https://github.com/fish-shell/fish-shell/issues/6364>)
* Lots of improvements to completions.
* Selecting short options which also have a long name from the completion
pager is possible (#5634 <https://github.com/fish-shell/fish-shell/is-
sues/5634>).
* Tab completion will no longer add trailing spaces if they already exist
(#6107 <https://github.com/fish-shell/fish-shell/issues/6107>).
* Completion of subcommands to builtins like and or not now works correctly
(#6249 <https://github.com/fish-shell/fish-shell/issues/6249>).
* Completion of arguments to short options works correctly when multiple
short options are used together (#332 <https://github.com/fish-
shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/4124>).
* Completion in empty commandlines now lists all available commands.
* Functions listed as completions could previously leak parts of the func-
tion as other completions; this has been fixed.
Deprecations and removed features
* The vcs-prompt functions have been promoted to names without double-un-
derscore, 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
<https://github.com/fish-shell/fish-shell/issues/5586>).
* string replace has an additional round of escaping in the replacement ex-
pression, so escaping backslashes requires many escapes (eg string re-
place -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 <https://github.com/fish-
shell/fish-shell/issues/5556>). As a reminder, the intention behind fea-
ture 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 <https://github.com/fish-shell/fish-
shell/issues/6372>).
For distributors and developers
* fish 3.0 introduced a CMake-based build system. In fish 3.1, both the Au-
totools-based build and legacy Xcode build system have been removed,
leaving only the CMake build system. All distributors and developers 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 docu-
mentation 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 always
uses an internal wcwidth function. It has a number of configuration op-
tions that make it more suitable for general use (#5777
<https://github.com/fish-shell/fish-shell/issues/5777>).
* mandoc can now be used to format the output from --help if nroff is not
installed, reducing the number of external dependencies on systems with
mandoc installed (#5489 <https://github.com/fish-shell/fish-shell/is-
sues/5489>).
* Some bugs preventing building on Solaris-derived systems such as Illumos
were fixed (#5458 <https://github.com/fish-shell/fish-shell/issues/5458>,
#5461 <https://github.com/fish-shell/fish-shell/issues/5461>, #5611
<https://github.com/fish-shell/fish-shell/issues/5611>).
* Completions for npm, bower and yarn no longer require the jq utility for
full functionality, but will use Python instead if it is available.
* The paths for completions, functions and configuration snippets have been
extended. On systems that define XDG_DATA_DIRS, each of the directories
in this variable are searched in the subdirectories fish/vendor_comple-
tions.d, fish/vendor_functions.d, and fish/vendor_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 de-
fault aextraa directory, which now defaults to /usr/local (#5029
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/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
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/4982>).
* read --silent no longer echoes to the tty when run from a non-interactive
script (#5519 <https://github.com/fish-shell/fish-shell/issues/5519>).
* On macOS, path entries with spaces in /etc/paths and /etc/paths.d now
correctly set path entries with spaces. Likewise, MANPATH is correctly
set from /etc/manpaths and /etc/manpaths.d (#5481
<https://github.com/fish-shell/fish-shell/issues/5481>).
* fish starts correctly under Cygwin/MSYS2 (#5426 <https://github.com/fish-
shell/fish-shell/issues/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, in-
stead of once per argument (#5588 <https://github.com/fish-shell/fish-
shell/issues/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 <https://github.com/fish-
shell/fish-shell/issues/5578>, #5574 <https://github.com/fish-shell/fish-
shell/issues/5574>, #5476 <https://github.com/fish-shell/fish-shell/is-
sues/5476>), and ignoring shell aliases, so enterprising users can set up
the wrapping command (via set -g __fish_git_alias_$command $whatitwraps)
(#5412 <https://github.com/fish-shell/fish-shell/issues/5412>).
* Significant performance improvements to core shell functions (#5447
<https://github.com/fish-shell/fish-shell/issues/5447>) and to the kill
completions (#5541 <https://github.com/fish-shell/fish-shell/is-
sues/5541>).
* Starting in symbolically-linked working directories works correctly (-
#5525 <https://github.com/fish-shell/fish-shell/issues/5525>).
* The default fish_title function no longer contains extra spaces (#5517
<https://github.com/fish-shell/fish-shell/issues/5517>).
* The nim prompt now works correctly when chosen in the Web-based configu-
ration (#5490 <https://github.com/fish-shell/fish-shell/issues/5490>).
* string now prints help to stdout, like other builtins (#5495
<https://github.com/fish-shell/fish-shell/issues/5495>).
* Killing the terminal while fish is in vi normal mode will no longer send
it spinning and eating CPU. (#5528 <https://github.com/fish-shell/fish-
shell/issues/5528>)
* A number of crashes have been fixed (#5550 <https://github.com/fish-
shell/fish-shell/issues/5550>, #5548 <https://github.com/fish-shell/fish-
shell/issues/5548>, #5479 <https://github.com/fish-shell/fish-shell/is-
sues/5479>, #5453 <https://github.com/fish-shell/fish-shell/is-
sues/5453>).
* Improvements to the documentation and certain completions.
Known issues
There is one significant known issue that was not corrected before the re-
lease:
* fish does not run correctly under Windows Services for Linux before Win-
dows 10 version 1809/17763, and the message warning of this may not be
displayed (#5619 <https://github.com/fish-shell/fish-shell/issues/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 re-
lease notes below.
Compared to the beta release of fish 3.0b1, fish version 3.0.0:
* builds correctly against musl libc (#5407 <https://github.com/fish-
shell/fish-shell/issues/5407>)
* handles huge numeric arguments to test correctly (#5414
<https://github.com/fish-shell/fish-shell/issues/5414>)
* removes the history colouring introduced in 3.0b1, which did not always
work correctly
There is one significant known issue which was not able to be corrected be-
fore the release:
* fish 3.0.0 builds on Cygwin (#5423 <https://github.com/fish-shell/fish-
shell/issues/5423>), but does not run correctly (#5426
<https://github.com/fish-shell/fish-shell/issues/5426>) and will result
in a hanging terminal when started. Cygwin users are encouraged to con-
tinue 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 per-
form 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
<https://github.com/fish-shell/fish-shell/issues/4230>, #1202
<https://github.com/fish-shell/fish-shell/issues/1202>).
* set x[1] x[2] a b, to set multiple elements of an array at once, is no
longer valid syntax (#4236 <https://github.com/fish-shell/fish-shell/is-
sues/4236>).
* A literal {} now expands to itself, rather than nothing. This makes work-
ing with find -exec easier (#1109 <https://github.com/fish-shell/fish-
shell/issues/1109>, #4632 <https://github.com/fish-shell/fish-shell/is-
sues/4632>).
* Literally accessing a zero-index is now illegal syntax and is caught by
the parser (#4862 <https://github.com/fish-shell/fish-shell/is-
sues/4862>). (fish indices start at 1)
* Successive commas in brace expansions are handled in less surprising man-
ner. For example, {,,,} expands to four empty strings rather than an
empty string, a comma and an empty string again (#3002
<https://github.com/fish-shell/fish-shell/issues/3002>, #4632
<https://github.com/fish-shell/fish-shell/issues/4632>).
* for loop control variables are no longer local to the for block (#1935
<https://github.com/fish-shell/fish-shell/issues/1935>).
* Variables set in if and while conditions are available outside the block
(#4820 <https://github.com/fish-shell/fish-shell/issues/4820>).
* Local exported (set -lx) vars are now visible to functions (#1091
<https://github.com/fish-shell/fish-shell/issues/1091>).
* The new math builtin (see below) does not support logical expressions;
test should be used instead (#4777 <https://github.com/fish-shell/fish-
shell/issues/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 ex-
pected.
* read now uses -s as short for --silent (A la bash); --shellas abbrevia-
tion (formerly -s) is now -S instead (#4490 <https://github.com/fish-
shell/fish-shell/issues/4490>).
* cd no longer resolves symlinks. fish now maintains a virtual path, match-
ing other shells (#3350 <https://github.com/fish-shell/fish-shell/is-
sues/3350>).
* source now requires an explicit - as the filename to read from the termi-
nal (#2633 <https://github.com/fish-shell/fish-shell/issues/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 unintentionally break-
ing stuff (#3000 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/436>).
* The history builtinas --with-time option has been removed; this has been
deprecated in favor of --show-time since 2.7.0 (#4403
<https://github.com/fish-shell/fish-shell/issues/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 re-
moval in the future. All users are encouraged to explore alternatives. 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 break-
ing changes. Feature flags may be specified at launch with fish --features
... or by setting the universal fish_features variable. (#4940
<https://github.com/fish-shell/fish-shell/issues/4940>)
* The use of the IFS variable for read is deprecated; IFS will be ignored
in the future (#4156 <https://github.com/fish-shell/fish-shell/is-
sues/4156>). Use the read --delimiter option instead.
* The function --on-process-exit switch will be removed in future (#4700
<https://github.com/fish-shell/fish-shell/issues/4700>). Use the
fish_exit event instead: function --on-event fish_exit.
* $_ is deprecated and will removed in the future (#813
<https://github.com/fish-shell/fish-shell/issues/813>). Use status cur-
rent-command in a command substitution instead.
* ^ as a redirection deprecated and will be removed in the future. (#4394
<https://github.com/fish-shell/fish-shell/issues/4394>). Use 2> to redi-
rect stderr. This is controlled by the stderr-nocaret feature flag.
* ? as a glob (wildcard) is deprecated and will be removed in the future (-
#4520 <https://github.com/fish-shell/fish-shell/issues/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 bet-
ter migration from POSIX-compliant shells (#4620
<https://github.com/fish-shell/fish-shell/issues/4620>).
* Variables may be used as commands (#154 <https://github.com/fish-
shell/fish-shell/issues/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 evalu-
ated in private mode are not persisted for future sessions. A session
variable $fish_private_mode can be queried to detect private mode and ad-
just the behavior of scripts accordingly to respect the useras wish for
privacy.
* A new wait command for waiting on backgrounded processes (#4498
<https://github.com/fish-shell/fish-shell/issues/4498>).
* math is now a builtin rather than a wrapper around bc (#3157
<https://github.com/fish-shell/fish-shell/issues/3157>). Floating point
computations is now used by default, and can be controlled with the new
--scale option (#4478 <https://github.com/fish-shell/fish-shell/is-
sues/4478>).
* Setting $PATH no longer warns on non-existent directories, allowing for a
single $PATH to be shared across machines (eg via dotfiles) (#2969
<https://github.com/fish-shell/fish-shell/issues/2969>).
* while sets $status to a non-zero value if the loop is not executed (#4982
<https://github.com/fish-shell/fish-shell/issues/4982>).
* Command substitution output is now limited to 10 MB by default, con-
trolled by the fish_read_limit variable (#3822 <https://github.com/fish-
shell/fish-shell/issues/3822>). Notably, this is larger than most operat-
ing systemsa 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 $hostname
reserved variable. This removes the dependency on the hostname executable
(#4422 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/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 immediately
(#4878 <https://github.com/fish-shell/fish-shell/issues/4878>).
* bind has a new --silent option to ignore bind requests for named keys not
available under the current terminal (#4188 <https://github.com/fish-
shell/fish-shell/issues/4188>, #4431 <https://github.com/fish-shell/fish-
shell/issues/4431>).
* complete has a new --keep-order option to show the provided or dynami-
cally-generated argument list in the same order as specified, rather than
alphabetically (#361 <https://github.com/fish-shell/fish-shell/is-
sues/361>).
* exec prompts for confirmation if background jobs are running.
* funced has a new --save option to automatically save the edited function
after successfully editing (#4668 <https://github.com/fish-shell/fish-
shell/issues/4668>).
* functions has a new --handlers option to show functions registered as
event handlers (#4694 <https://github.com/fish-shell/fish-shell/is-
sues/4694>).
* history search supports globs for wildcard searching (#3136
<https://github.com/fish-shell/fish-shell/issues/3136>) and has a new
--reverse option to show entries from oldest to newest (#4375
<https://github.com/fish-shell/fish-shell/issues/4375>).
* jobs has a new --quiet option to silence the output.
* read has a new --delimiter option for splitting input into arrays (#4256
<https://github.com/fish-shell/fish-shell/issues/4256>).
* read writes directly to stdout if called without arguments (#4407
<https://github.com/fish-shell/fish-shell/issues/4407>).
* read can now read individual lines into separate variables without con-
suming the input in its entirety via the new /--line option.
* set has new --append and --prepend options (#1326
<https://github.com/fish-shell/fish-shell/issues/1326>).
* string match with an empty pattern and --entire in glob mode now matches
everything instead of nothing (#4971 <https://github.com/fish-shell/fish-
shell/issues/4971>).
* string split supports a new --no-empty option to exclude empty strings
from the result (#4779 <https://github.com/fish-shell/fish-shell/is-
sues/4779>).
* string has new subcommands split0 and join0 for working with NUL-delim-
ited output.
* string no longer stops processing text after NUL characters (#4605
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/1285>).
* Italics and dim support out of the box on macOS for Terminal.app and
iTerm (#4436 <https://github.com/fish-shell/fish-shell/issues/4436>).
* cd tab completions no longer descend into the deepest unambiguous path (-
#4649 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/4680>).
* Typing normal characters while the completion pager is active no longer
shows the search field. Instead it enters them into the command line, and
ends paging (#2249 <https://github.com/fish-shell/fish-shell/is-
sues/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
<https://github.com/fish-shell/fish-shell/issues/5213>).
* The pager will now show the full command instead of just its last line if
the number of completions is large (#4702 <https://github.com/fish-
shell/fish-shell/issues/4702>).
* Abbreviations can be tab-completed (#3233 <https://github.com/fish-
shell/fish-shell/issues/3233>).
* Tildes in file names are now properly escaped in completions (#2274
<https://github.com/fish-shell/fish-shell/issues/2274>).
* Wrapping completions (from complete --wraps or function --wraps) can now
inject arguments. For example, complete gco --wraps 'git checkout' now
works properly (#1976 <https://github.com/fish-shell/fish-shell/is-
sues/1976>). The alias function has been updated to respect this behav-
ior.
* Path completions now support expansions, meaning expressions like python
~/<TAB> now provides file suggestions just like any other relative or ab-
solute 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 com-
mand substitutions (#4962 <https://github.com/fish-shell/fish-shell/is-
sues/4962>).
* The screen is no longer reset after a BEL, fixing graphical glitches (-
#3693 <https://github.com/fish-shell/fish-shell/issues/3693>).
* vi-mode now supports a;a and a,a motions. This introduces new {for-
ward,backward}-jump-till and repeat-jump{,-reverse} bind functions (#5140
<https://github.com/fish-shell/fish-shell/issues/5140>).
* The *y vi-mode binding now works (#5100 <https://github.com/fish-
shell/fish-shell/issues/5100>).
* True color is now enabled in neovim by default (#2792
<https://github.com/fish-shell/fish-shell/issues/2792>).
* Terminal size variables ($COLUMNS/$LINES) are now updated before
fish_prompt is called, allowing the prompt to react (#904
<https://github.com/fish-shell/fish-shell/issues/904>).
* Multi-line prompts no longer repeat when the terminal is resized (#2320
<https://github.com/fish-shell/fish-shell/issues/2320>).
* xclip support has been added to the clipboard integration (#5020
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/5011>).
* Deleting a one-character word no longer erases the next word as well (-
#4747 <https://github.com/fish-shell/fish-shell/issues/4747>).
* Token history search (Alt-Up) omits duplicate entries (#4795
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/5206>).
* commandline can now be used to set the commandline for the next command,
restoring a behavior in 3.4.1 (#8807 <https://github.com/fish-shell/fish-
shell/issues/8807>).
* Added completions for
* ansible, including ansible-galaxy, ansible-playbook and ansible-vault
(#4697 <https://github.com/fish-shell/fish-shell/issues/4697>)
* bb-power (#4800 <https://github.com/fish-shell/fish-shell/issues/4800>)
* bd (#4472 <https://github.com/fish-shell/fish-shell/issues/4472>)
* bower
* clang and clang++ (#4174 <https://github.com/fish-shell/fish-shell/is-
sues/4174>)
* conda (#4837 <https://github.com/fish-shell/fish-shell/issues/4837>)
* configure (for autoconf-generated files only)
* curl
* doas (#5196 <https://github.com/fish-shell/fish-shell/issues/5196>)
* ebuild (#4911 <https://github.com/fish-shell/fish-shell/issues/4911>)
* emaint (#4758 <https://github.com/fish-shell/fish-shell/issues/4758>)
* eopkg (#4600 <https://github.com/fish-shell/fish-shell/issues/4600>)
* exercism (#4495 <https://github.com/fish-shell/fish-shell/issues/4495>)
* hjson
* hugo (#4529 <https://github.com/fish-shell/fish-shell/issues/4529>)
* j (from autojump #4344 <https://github.com/fish-shell/fish-shell/is-
sues/4344>)
* jbake (#4814 <https://github.com/fish-shell/fish-shell/issues/4814>)
* jhipster (#4472 <https://github.com/fish-shell/fish-shell/issues/4472>)
* kitty
* kldload
* kldunload
* makensis (#5242 <https://github.com/fish-shell/fish-shell/issues/5242>)
* meson
* mkdocs (#4906 <https://github.com/fish-shell/fish-shell/issues/4906>)
* ngrok (#4642 <https://github.com/fish-shell/fish-shell/issues/4642>)
* OpenBSDas pkg_add, pkg_delete, pkg_info, pfctl, rcctl, signify, and vm-
ctl (#4584 <https://github.com/fish-shell/fish-shell/issues/4584>)
* openocd
* optipng
* opkg (#5168 <https://github.com/fish-shell/fish-shell/issues/5168>)
* pandoc (#2937 <https://github.com/fish-shell/fish-shell/issues/2937>)
* port (#4737 <https://github.com/fish-shell/fish-shell/issues/4737>)
* powerpill (#4800 <https://github.com/fish-shell/fish-shell/is-
sues/4800>)
* pstack (#5135 <https://github.com/fish-shell/fish-shell/issues/5135>)
* serve (#5026 <https://github.com/fish-shell/fish-shell/issues/5026>)
* ttx
* unzip
* virsh (#5113 <https://github.com/fish-shell/fish-shell/issues/5113>)
* xclip (#5126 <https://github.com/fish-shell/fish-shell/issues/5126>)
* xsv
* zfs and zpool (#4608 <https://github.com/fish-shell/fish-shell/is-
sues/4608>)
* Lots of improvements to completions (especially darcs (#5112
<https://github.com/fish-shell/fish-shell/issues/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 func-
tionality.
* Improved French translations.
Other fixes and improvements
* Significant performance improvements to abbr (#4048
<https://github.com/fish-shell/fish-shell/issues/4048>), setting vari-
ables (#4200 <https://github.com/fish-shell/fish-shell/issues/4200>, -
#4341 <https://github.com/fish-shell/fish-shell/issues/4341>), executing
functions, globs (#4579 <https://github.com/fish-shell/fish-shell/is-
sues/4579>), string reading from standard input (#4610
<https://github.com/fish-shell/fish-shell/issues/4610>), and slicing his-
tory (in particular, $history[1] for the last executed command).
* Fishas internal wcwidth function has been updated to deal with newer Uni-
code, and the width of some characters can be configured via the fish_am-
biguous_width (#5149 <https://github.com/fish-shell/fish-shell/is-
sues/5149>) and fish_emoji_width (#2652 <https://github.com/fish-
shell/fish-shell/issues/2652>) variables. Alternatively, a new build-time
option INTERNAL_WCWIDTH can be used to use the systemas wcwidth instead
(#4816 <https://github.com/fish-shell/fish-shell/issues/4816>).
* functions correctly supports -d as the short form of --description. (-
#5105 <https://github.com/fish-shell/fish-shell/issues/5105>)
* /etc/paths is now parsed like macOSa bash path_helper, fixing $PATH order
(#4336 <https://github.com/fish-shell/fish-shell/issues/4336>, #4852
<https://github.com/fish-shell/fish-shell/issues/4852>) on macOS.
* Using a read-only variable in a for loop produces an error, rather than
silently producing incorrect results (#4342 <https://github.com/fish-
shell/fish-shell/issues/4342>).
* The universal variables filename no longer contains the hostname or MAC
address. It is now at the fixed location .config/fish/fish_variables (-
#1912 <https://github.com/fish-shell/fish-shell/issues/1912>).
* Exported variables in the global or universal scope no longer have their
exported status affected by local variables (#2611
<https://github.com/fish-shell/fish-shell/issues/2611>).
* Major rework of terminal and job handling to eliminate bugs (#3805
<https://github.com/fish-shell/fish-shell/issues/3805>, #3952
<https://github.com/fish-shell/fish-shell/issues/3952>, #4178
<https://github.com/fish-shell/fish-shell/issues/4178>, #4235
<https://github.com/fish-shell/fish-shell/issues/4235>, #4238
<https://github.com/fish-shell/fish-shell/issues/4238>, #4540
<https://github.com/fish-shell/fish-shell/issues/4540>, #4929
<https://github.com/fish-shell/fish-shell/issues/4929>, #5210
<https://github.com/fish-shell/fish-shell/issues/5210>).
* Improvements to the manual page completion generator (#2937
<https://github.com/fish-shell/fish-shell/issues/2937>, #4313
<https://github.com/fish-shell/fish-shell/issues/4313>).
* suspend --force now works correctly (#4672 <https://github.com/fish-
shell/fish-shell/issues/4672>).
* Pressing Ctrl-C while running a script now reliably terminates fish (-
#5253 <https://github.com/fish-shell/fish-shell/issues/5253>).
For distributors and developers
* fish ships with a new build system based on CMake. CMake 3.2 is the mini-
mum 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 encouraged to migrate to
the CMake build.
* Build scripts for most platforms no longer require bash, using the stan-
dard sh instead.
* The hostname command is no longer required for fish to operate.
a
fish 2.7.1 (released December 23, 2017)
This release of fish fixes an issue where iTerm 2 on macOS would display a
warning about paste bracketing being left on when starting a new fish ses-
sion (#4521 <https://github.com/fish-shell/fish-shell/issues/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).
a
fish 2.7.0 (released November 23, 2017)
There are no major changes between 2.7b1 and 2.7.0. If you are upgrading
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.
a
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
<https://github.com/fish-shell/fish-shell/issues/2847>).
* A new argparse command is available to allow fish script to parse argu-
ments with the same behavior as builtin commands. This also includes the
fish_opt helper command. (#4190 <https://github.com/fish-shell/fish-
shell/issues/4190>).
* Invalid array indexes are now silently ignored (#826
<https://github.com/fish-shell/fish-shell/issues/826>, #4127
<https://github.com/fish-shell/fish-shell/issues/4127>).
* Improvements to the debugging facility, including a prompt specific to
the debugger (fish_breakpoint_prompt) and a status is-breakpoint subcom-
mand (#1310 <https://github.com/fish-shell/fish-shell/issues/1310>).
* string supports new lower and upper subcommands, for altering the case of
strings (#4080 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/4150>), and can be re-
versed with string unescape (#3543 <https://github.com/fish-shell/fish-
shell/issues/3543>).
* History can now be split into sessions with the fish_history variable, or
not saved to disk at all (#102 <https://github.com/fish-shell/fish-
shell/issues/102>).
* Read history is now controlled by the fish_history variable rather than
the --mode-name flag (#1504 <https://github.com/fish-shell/fish-shell/is-
sues/1504>).
* command now supports an --all flag to report all directories with the
command. which is no longer a runtime dependency (#2778
<https://github.com/fish-shell/fish-shell/issues/2778>).
* fish can run commands before starting an interactive session using the
new --init-command/-C options (#4164 <https://github.com/fish-shell/fish-
shell/issues/4164>).
* set has a new --show option to show lots of information about variables
(#4265 <https://github.com/fish-shell/fish-shell/issues/4265>).
Other significant changes
* The COLUMNS and LINES environment variables are now correctly set the
first time fish_prompt is run (#4141 <https://github.com/fish-shell/fish-
shell/issues/4141>).
* completeas --no-files option works as intended (#112
<https://github.com/fish-shell/fish-shell/issues/112>).
* echo -h now correctly echoes -h in line with other shells (#4120
<https://github.com/fish-shell/fish-shell/issues/4120>).
* The export compatibility function now returns zero on success, rather
than always returning 1 (#4435 <https://github.com/fish-shell/fish-
shell/issues/4435>).
* Stop converting empty elements in MANPATH to a.a (#4158
<https://github.com/fish-shell/fish-shell/issues/4158>). The behavior be-
ing changed was introduced in fish 2.6.0.
* count -h and count --help now return 1 rather than produce command help
output (#4189 <https://github.com/fish-shell/fish-shell/issues/4189>).
* An attempt to read which stops because too much data is available still
defines the variables given as parameters (#4180
<https://github.com/fish-shell/fish-shell/issues/4180>).
* A regression in fish 2.4.0 which prevented pushd +1 from working has been
fixed (#4091 <https://github.com/fish-shell/fish-shell/issues/4091>).
* A regression in fish 2.6.0 where multiple read commands in non-interac-
tive scripts were broken has been fixed (#4206 <https://github.com/fish-
shell/fish-shell/issues/4206>).
* A regression in fish 2.6.0 involving universal variables with side-ef-
fects at startup such as set -U fish_escape_delay_ms 10 has been fixed (-
#4196 <https://github.com/fish-shell/fish-shell/issues/4196>).
* Added completions for:
* as (#4130 <https://github.com/fish-shell/fish-shell/issues/4130>)
* cdh (#2847 <https://github.com/fish-shell/fish-shell/issues/2847>)
* dhcpd (#4115 <https://github.com/fish-shell/fish-shell/issues/4115>)
* ezjail-admin (#4324 <https://github.com/fish-shell/fish-shell/is-
sues/4324>)
* Fabricas fab (#4153 <https://github.com/fish-shell/fish-shell/is-
sues/4153>)
* grub-file (#4119 <https://github.com/fish-shell/fish-shell/is-
sues/4119>)
* grub-install (#4119 <https://github.com/fish-shell/fish-shell/is-
sues/4119>)
* jest (#4142 <https://github.com/fish-shell/fish-shell/issues/4142>)
* kdeconnect-cli
* magneto (#4043 <https://github.com/fish-shell/fish-shell/issues/4043>,
#4108 <https://github.com/fish-shell/fish-shell/issues/4108>)
* mdadm (#4198 <https://github.com/fish-shell/fish-shell/issues/4198>)
* passwd (#4209 <https://github.com/fish-shell/fish-shell/issues/4209>)
* pip and pipenv (#4448 <https://github.com/fish-shell/fish-shell/is-
sues/4448>)
* s3cmd (#4332 <https://github.com/fish-shell/fish-shell/issues/4332>)
* sbt (#4347 <https://github.com/fish-shell/fish-shell/issues/4347>)
* snap (#4215 <https://github.com/fish-shell/fish-shell/issues/4215>)
* Sublime Text 3as subl (#4277 <https://github.com/fish-shell/fish-
shell/issues/4277>)
* Lots of improvements to completions.
* Updated Chinese and French translations.
* Improved completions for:
* apt
* cd (#4061 <https://github.com/fish-shell/fish-shell/issues/4061>)
* composer (#4295 <https://github.com/fish-shell/fish-shell/issues/4295>)
* eopkg
* flatpak (#4456 <https://github.com/fish-shell/fish-shell/issues/4456>)
* git (#4117 <https://github.com/fish-shell/fish-shell/issues/4117>, -
#4147 <https://github.com/fish-shell/fish-shell/issues/4147>, #4329
<https://github.com/fish-shell/fish-shell/issues/4329>, #4368
<https://github.com/fish-shell/fish-shell/issues/4368>)
* gphoto2
* killall (#4052 <https://github.com/fish-shell/fish-shell/issues/4052>)
* ln
* npm (#4241 <https://github.com/fish-shell/fish-shell/issues/4241>)
* ssh (#4377 <https://github.com/fish-shell/fish-shell/issues/4377>)
* tail
* xdg-mime (#4333 <https://github.com/fish-shell/fish-shell/issues/4333>)
* zypper (#4325 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/4043>), and improvements
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 manu-
ally 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 <https://github.com/fish-shell/fish-shell/issues/2810>).
* Command substitutions now have access to the terminal, like in other
shells. This allows tools like fzf to work properly (#1362
<https://github.com/fish-shell/fish-shell/issues/1362>, #3922
<https://github.com/fish-shell/fish-shell/issues/3922>).
* In cases where the operating system does not report the size of the ter-
minal, the COLUMNS and LINES environment variables are used; if they are
unset, a default of 80x24 is assumed.
* New French (#3772 <https://github.com/fish-shell/fish-shell/issues/3772>
& #3788 <https://github.com/fish-shell/fish-shell/issues/3788>) and im-
proved German (#3834 <https://github.com/fish-shell/fish-shell/is-
sues/3834>) translations.
* fish no longer depends on the which external command.
Other significant changes
* Performance improvements in launching processes, including major reduc-
tions in signal blocking. Although this has been heavily tested, it may
cause problems in some circumstances; set the FISH_NO_SIGNAL_BLOCK vari-
able to 0 in your fish configuration file to return to the old behaviour
(#2007 <https://github.com/fish-shell/fish-shell/issues/2007>).
* Performance improvements in prompts and functions that set lots of
colours (#3793 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-
shell/issues/3295>), and a --details --verbose option which includes the
function description (#597 <https://github.com/fish-shell/fish-shell/is-
sues/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 dif-
ferent limit with the FISH_READ_BYTE_LIMIT variable.
* read supports a new --silent option to hide the characters typed (#838
<https://github.com/fish-shell/fish-shell/issues/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 op-
tions (#802 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/4103>).
* bind supports a new --list-modes option (#3872 <https://github.com/fish-
shell/fish-shell/issues/3872>).
* bg will check all of its arguments before backgrounding any jobs; any in-
valid arguments will cause a failure, but non-existent (eg recently ex-
ited) jobs are ignored (#3909 <https://github.com/fish-shell/fish-
shell/issues/3909>).
* funced warns if the function being edited has not been modified (#3961
<https://github.com/fish-shell/fish-shell/issues/3961>).
* printf correctly outputs along longa integers (#3352
<https://github.com/fish-shell/fish-shell/issues/3352>).
* status supports a new current-function subcommand to print the current
function name (#1743 <https://github.com/fish-shell/fish-shell/is-
sues/1743>).
* string supports a new repeat subcommand (#3864 <https://github.com/fish-
shell/fish-shell/issues/3864>). string match supports a new --entire op-
tion to emit the entire line matched by a pattern (#3957
<https://github.com/fish-shell/fish-shell/issues/3957>). string replace
supports a new --filter option to only emit lines which underwent a re-
placement (#3348 <https://github.com/fish-shell/fish-shell/issues/3348>).
* test supports the -k option to test for sticky bits (#733
<https://github.com/fish-shell/fish-shell/issues/733>).
* umask understands symbolic modes (#738 <https://github.com/fish-
shell/fish-shell/issues/738>).
* Empty components in the CDPATH, MANPATH and PATH variables are now con-
verted to a.a (#2106 <https://github.com/fish-shell/fish-shell/is-
sues/2106>, #3914 <https://github.com/fish-shell/fish-shell/is-
sues/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
<https://github.com/fish-shell/fish-shell/issues/2855>).
* Some systemsa su implementations do not set the USER environment vari-
able; it is now reset for root users (#3916 <https://github.com/fish-
shell/fish-shell/issues/3916>).
* Under terminals which support it, bracketed paste is enabled, escaping
problematic characters for security and convenience (#3871
<https://github.com/fish-shell/fish-shell/issues/3871>). Inside single
quotes ('), single quotes and backslashes in pasted text are escaped (-
#967 <https://github.com/fish-shell/fish-shell/issues/967>). The
fish_clipboard_paste function (bound to C-v by default) is still the rec-
ommended 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 <https://github.com/fish-shell/fish-
shell/issues/1926>). This behaviour matches other shells mre closely.
* All functions requiring Python work with whichever version of Python is
installed (#3970 <https://github.com/fish-shell/fish-shell/issues/3970>).
Python 3 is preferred, but Python 2.6 remains the minimum version re-
quired.
* The color of the cancellation character can be controlled by the
fish_color_cancel variable (#3963 <https://github.com/fish-shell/fish-
shell/issues/3963>).
* Added completions for:
* caddy (#4008 <https://github.com/fish-shell/fish-shell/issues/4008>)
* castnow (#3744 <https://github.com/fish-shell/fish-shell/issues/3744>)
* climate (#3760 <https://github.com/fish-shell/fish-shell/issues/3760>)
* flatpak
* gradle (#3859 <https://github.com/fish-shell/fish-shell/issues/3859>)
* gsettings (#4001 <https://github.com/fish-shell/fish-shell/issues/4001>)
* helm (#3829 <https://github.com/fish-shell/fish-shell/issues/3829>)
* i3-msg (#3787 <https://github.com/fish-shell/fish-shell/issues/3787>)
* ipset (#3924 <https://github.com/fish-shell/fish-shell/issues/3924>)
* jq (#3804 <https://github.com/fish-shell/fish-shell/issues/3804>)
* light (#3752 <https://github.com/fish-shell/fish-shell/issues/3752>)
* minikube (#3778 <https://github.com/fish-shell/fish-shell/issues/3778>)
* mocha (#3828 <https://github.com/fish-shell/fish-shell/issues/3828>)
* mkdosfs (#4017 <https://github.com/fish-shell/fish-shell/issues/4017>)
* pv (#3773 <https://github.com/fish-shell/fish-shell/issues/3773>)
* setsid (#3791 <https://github.com/fish-shell/fish-shell/issues/3791>)
* terraform (#3960 <https://github.com/fish-shell/fish-shell/issues/3960>)
* usermod (#3775 <https://github.com/fish-shell/fish-shell/issues/3775>)
* xinput
* yarn (#3816 <https://github.com/fish-shell/fish-shell/issues/3816>)
* Improved completions for adb (#3853 <https://github.com/fish-shell/fish-
shell/issues/3853>), apt (#3771 <https://github.com/fish-shell/fish-
shell/issues/3771>), bzr (#3769 <https://github.com/fish-shell/fish-
shell/issues/3769>), dconf, git (including #3743
<https://github.com/fish-shell/fish-shell/issues/3743>), grep (#3789
<https://github.com/fish-shell/fish-shell/issues/3789>), go (#3789
<https://github.com/fish-shell/fish-shell/issues/3789>), help (#3789
<https://github.com/fish-shell/fish-shell/issues/3789>), hg (#3975
<https://github.com/fish-shell/fish-shell/issues/3975>), htop (#3789
<https://github.com/fish-shell/fish-shell/issues/3789>), killall (#3996
<https://github.com/fish-shell/fish-shell/issues/3996>), lua, man (#3762
<https://github.com/fish-shell/fish-shell/issues/3762>), mount (#3764
<https://github.com/fish-shell/fish-shell/issues/3764> & #3841
<https://github.com/fish-shell/fish-shell/issues/3841>), obnam (#3924
<https://github.com/fish-shell/fish-shell/issues/3924>), perl (#3856
<https://github.com/fish-shell/fish-shell/issues/3856>), portmaster (-
#3950 <https://github.com/fish-shell/fish-shell/issues/3950>), python (-
#3840 <https://github.com/fish-shell/fish-shell/issues/3840>), ssh (#3781
<https://github.com/fish-shell/fish-shell/issues/3781>), scp (#3781
<https://github.com/fish-shell/fish-shell/issues/3781>), systemctl (#3757
<https://github.com/fish-shell/fish-shell/issues/3757>) and udisks (#3764
<https://github.com/fish-shell/fish-shell/issues/3764>).
----
fish 2.5.0 (released February 3, 2017)
There are no major changes between 2.5b1 and 2.5.0. If you are upgrading
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 <https://github.com/fish-shell/fish-
shell/issues/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, GCCas g++ 4.8 or later, or LLVMas 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 packages
are no longer published by the fish-shell developers for the following
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 (aSnowLeoparda). 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 required
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 <https://github.com/fish-shell/fish-
shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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_bind-
ings in fish 2.3.0 (#3556 <https://github.com/fish-shell/fish-shell/is-
sues/3556>).
* function now returns an error when called with invalid options, rather
than defining the function anyway (#3574 <https://github.com/fish-
shell/fish-shell/issues/3574>). This was a regression 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 compatibility with Android (#3585 <https://github.com/fish-
shell/fish-shell/issues/3585>), MSYS/mingw (#2360
<https://github.com/fish-shell/fish-shell/issues/2360>), and Solaris (-
#3456 <https://github.com/fish-shell/fish-shell/issues/3456>, #3340
<https://github.com/fish-shell/fish-shell/issues/3340>).
* Like other shells, the test built-in now returns an error for numeric op-
erations on invalid integers (#3346 <https://github.com/fish-shell/fish-
shell/issues/3346>, #3581 <https://github.com/fish-shell/fish-shell/is-
sues/3581>).
* complete no longer recognises --authoritative and --unauthoritative op-
tions, and they are marked as obsolete.
* status accepts subcommands, and should be used like status is-interac-
tive. The old options continue to be supported for the foreseeable future
(#3526 <https://github.com/fish-shell/fish-shell/issues/3526>), although
only one subcommand or option can be specified at a time.
* Selection mode (used with abegin-selectiona) no longer selects a charac-
ter the cursor does not move over (#3684 <https://github.com/fish-
shell/fish-shell/issues/3684>).
* List indexes are handled better, and a bit more liberally in some cases
(echo $PATH[1 .. 3] is now valid) (#3579 <https://github.com/fish-
shell/fish-shell/issues/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 eas-
ily in customised prompt functions (#3641 <https://github.com/fish-
shell/fish-shell/issues/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 identi-
fies them.
* complete accepts empty strings as descriptions (#3557
<https://github.com/fish-shell/fish-shell/issues/3557>).
* command accepts -q/--quiet in combination with --search (#3591
<https://github.com/fish-shell/fish-shell/issues/3591>), providing a sim-
ple way of checking whether a command exists in scripts.
* Abbreviations can now be renamed with abbr --rename OLD_KEY NEW_KEY (-
#3610 <https://github.com/fish-shell/fish-shell/issues/3610>).
* The command synopses printed by --help options work better with copying
and pasting (#2673 <https://github.com/fish-shell/fish-shell/is-
sues/2673>).
* help launches the browser specified by the $fish_help_browser variable if
it is set (#3131 <https://github.com/fish-shell/fish-shell/issues/3131>).
* History merging could lose items under certain circumstances and is now
fixed (#3496 <https://github.com/fish-shell/fish-shell/issues/3496>).
* The $status variable is now set to 123 when a syntactically invalid com-
mand is entered (#3616 <https://github.com/fish-shell/fish-shell/is-
sues/3616>).
* Exiting fish now signals all background processes to terminate, not just
stopped jobs (#3497 <https://github.com/fish-shell/fish-shell/is-
sues/3497>).
* A new prompt_hostname function which prints a hostname suitable for use
in prompts (#3482 <https://github.com/fish-shell/fish-shell/is-
sues/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 agit-adda man page)
(#3678 <https://github.com/fish-shell/fish-shell/issues/3678>).
* A new function edit_command_buffer (bound to Alt-e & Alt-v by default) to
edit the command buffer in an external editor (#1215
<https://github.com/fish-shell/fish-shell/issues/1215>, #3627
<https://github.com/fish-shell/fish-shell/issues/3627>).
* set_color now supports italics (--italics), dim (--dim) and reverse
(--reverse) modes (#3650 <https://github.com/fish-shell/fish-shell/is-
sues/3650>).
* Filesystems with very slow locking (eg incorrectly-configured NFS) will
no longer slow fish down (#685 <https://github.com/fish-shell/fish-
shell/issues/685>).
* Improved completions for apt (#3695 <https://github.com/fish-shell/fish-
shell/issues/3695>), fusermount (#3642 <https://github.com/fish-
shell/fish-shell/issues/3642>), make (#3628 <https://github.com/fish-
shell/fish-shell/issues/3628>), netctl-auto (#3378
<https://github.com/fish-shell/fish-shell/issues/3378>), nmcli (#3648
<https://github.com/fish-shell/fish-shell/issues/3648>), pygmentize (-
#3378 <https://github.com/fish-shell/fish-shell/issues/3378>), and tar (-
#3719 <https://github.com/fish-shell/fish-shell/issues/3719>).
* Added completions for:
* VBoxHeadless (#3378 <https://github.com/fish-shell/fish-shell/is-
sues/3378>)
* VBoxSDL (#3378 <https://github.com/fish-shell/fish-shell/issues/3378>)
* base64 (#3378 <https://github.com/fish-shell/fish-shell/issues/3378>)
* caffeinate (#3524 <https://github.com/fish-shell/fish-shell/issues/3524>)
* dconf (#3638 <https://github.com/fish-shell/fish-shell/issues/3638>)
* dig (#3495 <https://github.com/fish-shell/fish-shell/issues/3495>)
* dpkg-reconfigure (#3521 <https://github.com/fish-shell/fish-shell/is-
sues/3521> & #3522 <https://github.com/fish-shell/fish-shell/is-
sues/3522>)
* feh (#3378 <https://github.com/fish-shell/fish-shell/issues/3378>)
* launchctl (#3682 <https://github.com/fish-shell/fish-shell/issues/3682>)
* lxc (#3554 <https://github.com/fish-shell/fish-shell/issues/3554> & #3564
<https://github.com/fish-shell/fish-shell/issues/3564>),
* mddiagnose (#3524 <https://github.com/fish-shell/fish-shell/issues/3524>)
* mdfind (#3524 <https://github.com/fish-shell/fish-shell/issues/3524>)
* mdimport (#3524 <https://github.com/fish-shell/fish-shell/issues/3524>)
* mdls (#3524 <https://github.com/fish-shell/fish-shell/issues/3524>)
* mdutil (#3524 <https://github.com/fish-shell/fish-shell/issues/3524>)
* mkvextract (#3492 <https://github.com/fish-shell/fish-shell/issues/3492>)
* nvram (#3524 <https://github.com/fish-shell/fish-shell/issues/3524>)
* objdump (#3378 <https://github.com/fish-shell/fish-shell/issues/3378>)
* sysbench (#3491 <https://github.com/fish-shell/fish-shell/issues/3491>)
* tmutil (#3524 <https://github.com/fish-shell/fish-shell/issues/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 version
identifier.
* Automatic cursor changes are now only enabled on the subset of XTerm ver-
sions known to support them, resolving a problem where older versions
printed garbage to the terminal before and after every prompt (#3499
<https://github.com/fish-shell/fish-shell/issues/3499>).
* Improved the title set in Apple Terminal.app.
* Added completions for defaults and improved completions for diskutil (-
#3478 <https://github.com/fish-shell/fish-shell/issues/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 clipboard -
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
<https://github.com/fish-shell/fish-shell/issues/3061>)
* history uses subcommands (history delete) rather than options (history
--delete) for its actions (#3367 <https://github.com/fish-shell/fish-
shell/issues/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 num-
ber of history entries, --show-time option to show timestamps (#3175
<https://github.com/fish-shell/fish-shell/issues/3175>, #3244
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/3236>).
* history delete now correctly handles multiline commands (#31
<https://github.com/fish-shell/fish-shell/issues/31>).
* Vi-style bindings no longer include all of the default emacs-style bind-
ings; instead, they share some definitions (#3068
<https://github.com/fish-shell/fish-shell/issues/3068>).
* If there is no locale set in the environment, various known system con-
figuration files will be checked for a default. If no locale can be
found, en_US-UTF.8 will be used (#277 <https://github.com/fish-
shell/fish-shell/issues/277>).
* A number followed by a caret (e.g. 5^) is no longer treated as a redirec-
tion (#1873 <https://github.com/fish-shell/fish-shell/issues/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 compati-
ble with GNU realpath when run without arguments (#3400
<https://github.com/fish-shell/fish-shell/issues/3400>). It is used only
for systems without a realpath or grealpath utility (#3374
<https://github.com/fish-shell/fish-shell/issues/3374>).
* Improved color handling on terminals/consoles with 8-16 colors, particu-
larly the use of bright named color (#3176 <https://github.com/fish-
shell/fish-shell/issues/3176>, #3260 <https://github.com/fish-shell/fish-
shell/issues/3260>).
* fish_indent can now read from files given as arguments, rather than just
standard input (#3037 <https://github.com/fish-shell/fish-shell/is-
sues/3037>).
* Fuzzy tab completions behave in a less surprising manner (#3090
<https://github.com/fish-shell/fish-shell/issues/3090>, #3211
<https://github.com/fish-shell/fish-shell/issues/3211>).
* jobs should only print its header line once (#3127
<https://github.com/fish-shell/fish-shell/issues/3127>).
* Wildcards in redirections are highlighted appropriately (#2789
<https://github.com/fish-shell/fish-shell/issues/2789>).
* Suggestions will be offered more often, like after removing characters (-
#3069 <https://github.com/fish-shell/fish-shell/issues/3069>).
* history --merge now correctly interleaves items in chronological order (-
#2312 <https://github.com/fish-shell/fish-shell/issues/2312>).
* Options for fish_indent have been aligned with the other binaries - in
particular, -d now means --debug. The --dump option has been renamed to
--dump-parse-tree (#3191 <https://github.com/fish-shell/fish-shell/is-
sues/3191>).
* The display of bindings in the Web-based configuration has been greatly
improved (#3325 <https://github.com/fish-shell/fish-shell/issues/3325>),
as has the rendering of prompts (#2924 <https://github.com/fish-
shell/fish-shell/issues/2924>).
* fish should no longer hang using 100% CPU in the C locale (#3214
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/is-
sues/3050>).
* Prompts which show git repository information (via __fish_git_prompt) are
faster in large repositories (#3294 <https://github.com/fish-shell/fish-
shell/issues/3294>) and slow filesystems (#3083 <https://github.com/fish-
shell/fish-shell/issues/3083>).
* fish 2.3.0 reintroduced a problem where the greeting was printed even
when using read; this has been corrected again (#3261
<https://github.com/fish-shell/fish-shell/issues/3261>).
* Vi mode changes the cursor depending on the current mode (#3215
<https://github.com/fish-shell/fish-shell/issues/3215>).
* Command lines with escaped space characters at the end tab-complete cor-
rectly (#2447 <https://github.com/fish-shell/fish-shell/issues/2447>).
* Added completions for:
* arcanist (#3256 <https://github.com/fish-shell/fish-shell/issues/3256>)
* connmanctl (#3419 <https://github.com/fish-shell/fish-shell/is-
sues/3419>)
* figlet (#3378 <https://github.com/fish-shell/fish-shell/issues/3378>)
* mdbook (#3378 <https://github.com/fish-shell/fish-shell/issues/3378>)
* ninja (#3415 <https://github.com/fish-shell/fish-shell/issues/3415>)
* p4, the Perforce client (#3314 <https://github.com/fish-shell/fish-
shell/issues/3314>)
* pygmentize (#3378 <https://github.com/fish-shell/fish-shell/is-
sues/3378>)
* ranger (#3378 <https://github.com/fish-shell/fish-shell/issues/3378>)
* Improved completions for aura (#3297 <https://github.com/fish-shell/fish-
shell/issues/3297>), abbr (#3267 <https://github.com/fish-shell/fish-
shell/issues/3267>), brew (#3309 <https://github.com/fish-shell/fish-
shell/issues/3309>), chown (#3380 <https://github.com/fish-shell/fish-
shell/issues/3380>, #3383 <https://github.com/fish-shell/fish-shell/is-
sues/3383>),cygport (#3392 <https://github.com/fish-shell/fish-shell/is-
sues/3392>), git (#3274 <https://github.com/fish-shell/fish-shell/is-
sues/3274>, #3226 <https://github.com/fish-shell/fish-shell/issues/3226>,
#3225 <https://github.com/fish-shell/fish-shell/issues/3225>, #3094
<https://github.com/fish-shell/fish-shell/issues/3094>, #3087
<https://github.com/fish-shell/fish-shell/issues/3087>, #3035
<https://github.com/fish-shell/fish-shell/issues/3035>, #3021
<https://github.com/fish-shell/fish-shell/issues/3021>, #2982
<https://github.com/fish-shell/fish-shell/issues/2982>, #3230
<https://github.com/fish-shell/fish-shell/issues/3230>), kill & pkill (-
#3200 <https://github.com/fish-shell/fish-shell/issues/3200>), screen (-
#3271 <https://github.com/fish-shell/fish-shell/issues/3271>), wget (-
#3470 <https://github.com/fish-shell/fish-shell/issues/3470>), and xz (-
#3378 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/3248>).
* Improved compatibility with minor platforms including musl (#2988
<https://github.com/fish-shell/fish-shell/issues/2988>), Cygwin (#2993
<https://github.com/fish-shell/fish-shell/issues/2993>), Android (#3441
<https://github.com/fish-shell/fish-shell/issues/3441>, #3442
<https://github.com/fish-shell/fish-shell/issues/3442>), Haiku (#3322
<https://github.com/fish-shell/fish-shell/issues/3322>) and Solaris .
----
fish 2.3.1 (released July 3, 2016)
This is a functionality and bugfix release. This release does not contain
all the changes to fish since the last release, but fixes a number of is-
sues directly affecting users at present and includes a small number of new
features.
Significant changes
* A new fish_key_reader binary for decoding interactive keypresses (#2991
<https://github.com/fish-shell/fish-shell/issues/2991>).
* fish_mode_prompt has been updated to reflect the changes in the way the
Vi input mode is set up (#3067 <https://github.com/fish-shell/fish-
shell/issues/3067>), making this more reliable.
* fish_config can now properly be launched from the OS X app bundle (#3140
<https://github.com/fish-shell/fish-shell/issues/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 timestamps not be-
ing updated (#2859 <https://github.com/fish-shell/fish-shell/is-
sues/2859>).
* The string builtinas match mode now handles the combination of -rnv
(match, invert and count) correctly (#3098 <https://github.com/fish-
shell/fish-shell/issues/3098>).
* Improvements to TTY special character handling (#3064
<https://github.com/fish-shell/fish-shell/issues/3064>), locale handling
(#3124 <https://github.com/fish-shell/fish-shell/issues/3124>) and termi-
nal environment variable handling (#3060 <https://github.com/fish-
shell/fish-shell/issues/3060>).
* Work towards handling the terminal modes for external commands launched
from initialisation files (#2980 <https://github.com/fish-shell/fish-
shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/3123>).
* Improved completions for apt (#3097 <https://github.com/fish-shell/fish-
shell/issues/3097>), aura (#3102 <https://github.com/fish-shell/fish-
shell/issues/3102>),git (#3114 <https://github.com/fish-shell/fish-
shell/issues/3114>), npm (#3158 <https://github.com/fish-shell/fish-
shell/issues/3158>), string and suspend (#3154 <https://github.com/fish-
shell/fish-shell/issues/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 <https://github.com/fish-
shell/fish-shell/issues/2996>).
* Define a few extra colours on first start (#2987
<https://github.com/fish-shell/fish-shell/issues/2987>).
* Multiple documentation updates.
* Added completions for rmmod (#3007 <https://github.com/fish-shell/fish-
shell/issues/3007>).
* Improved completions for git (#2998 <https://github.com/fish-shell/fish-
shell/issues/2998>).
Known issues
* Interactive commands started from fish configuration files or from the -c
option may, under certain circumstances, be started with incorrect termi-
nal modes and fail to behave as expected. A fix is planned but requires
further testing (#2619 <https://github.com/fish-shell/fish-shell/is-
sues/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 donat ship an appropriate command
(#2932 <https://github.com/fish-shell/fish-shell/issues/2932>).
* Alt-# toggles the current command line between commented and uncommented
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 <https://github.com/fish-shell/fish-
shell/issues/2952>) and RedHat Enterprise Linux/CentOS 5 (#2955
<https://github.com/fish-shell/fish-shell/issues/2955>).
* Avoid confusing the terminal line driver with non-printing characters in
fish_title (#2453 <https://github.com/fish-shell/fish-shell/is-
sues/2453>).
* Improved completions for busctl, git (#2585 <https://github.com/fish-
shell/fish-shell/issues/2585>, #2879 <https://github.com/fish-shell/fish-
shell/issues/2879>, #2984 <https://github.com/fish-shell/fish-shell/is-
sues/2984>), and netctl.
----
fish 2.3b1 (released April 19, 2016)
Significant Changes
* A new string builtin to handlea| strings! This builtin will measure,
split, search and replace text strings, including using regular expres-
sions. 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 situa-
tions. (#2296 <https://github.com/fish-shell/fish-shell/issues/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 modi-
fier. (#1356 <https://github.com/fish-shell/fish-shell/issues/1356>)
* Add new directories for vendor functions and configuration snippets (-
#2500 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/2719>)
* and and or will now bind to the closest if or while, allowing compound
conditions without begin and end (#1428 <https://github.com/fish-
shell/fish-shell/issues/1428>)
* set -ql now searches up to function scope for variables (#2502
<https://github.com/fish-shell/fish-shell/issues/2502>)
* status -f will now behave the same when run as the main script or using
source (#2643 <https://github.com/fish-shell/fish-shell/issues/2643>)
* source no longer puts the file name in $argv if no arguments are given (-
#139 <https://github.com/fish-shell/fish-shell/issues/139>)
* History files are stored under the XDG_DATA_HOME hierarchy (by default,
in ~/.local/share), and existing history will be moved on first use (#744
<https://github.com/fish-shell/fish-shell/issues/744>)
Other notable fixes and improvements
* Fish no longer silences errors in config.fish (#2702
<https://github.com/fish-shell/fish-shell/issues/2702>)
* Directory autosuggestions will now descend as far as possible if there is
only one child directory (#2531 <https://github.com/fish-shell/fish-
shell/issues/2531>)
* Add support for bright colors (#1464 <https://github.com/fish-shell/fish-
shell/issues/1464>)
* Allow Ctrl-J (\cj) to be bound separately from Ctrl-M (\cm) (#217
<https://github.com/fish-shell/fish-shell/issues/217>)
* psub now has a a-sa/aasuffixa option to name the temporary file with that
suffix
* Enable 24-bit colors on select terminals (#2495 <https://github.com/fish-
shell/fish-shell/issues/2495>)
* Support for SVN status in the prompt (#2582 <https://github.com/fish-
shell/fish-shell/issues/2582>)
* Mercurial and SVN support have been added to the Classic + Git (now Clas-
sic + VCS) prompt (via the new __fish_vcs_prompt function) (#2592
<https://github.com/fish-shell/fish-shell/issues/2592>)
* export now handles variables with a a=a in the value (#2403
<https://github.com/fish-shell/fish-shell/issues/2403>)
* New completions for:
* alsactl
* Archlinuxas asp, makepkg
* Atomas apm (#2390 <https://github.com/fish-shell/fish-shell/is-
sues/2390>)
* entr - the aEvent Notify Test Runnera (#2265 <https://github.com/fish-
shell/fish-shell/issues/2265>)
* Fedoraas dnf (#2638 <https://github.com/fish-shell/fish-shell/is-
sues/2638>)
* OSX diskutil (#2738 <https://github.com/fish-shell/fish-shell/is-
sues/2738>)
* pkgng (#2395 <https://github.com/fish-shell/fish-shell/issues/2395>)
* pulseaudioas pacmd and pactl
* rustas rustc and cargo (#2409 <https://github.com/fish-shell/fish-
shell/issues/2409>)
* sysctl (#2214 <https://github.com/fish-shell/fish-shell/issues/2214>)
* systemdas machinectl (#2158 <https://github.com/fish-shell/fish-
shell/issues/2158>), busctl (#2144 <https://github.com/fish-shell/fish-
shell/issues/2144>), systemd-nspawn, systemd-analyze, localectl, time-
datectl
* and more
* Fish no longer has a function called sgrep, freeing it for user cus-
tomization (#2245 <https://github.com/fish-shell/fish-shell/issues/2245>)
* A rewrite of the completions for cd, fixing a few bugs (#2299
<https://github.com/fish-shell/fish-shell/issues/2299>, #2300
<https://github.com/fish-shell/fish-shell/issues/2300>, #562
<https://github.com/fish-shell/fish-shell/issues/562>)
* Linux VTs now run in a simplified mode to avoid issues (#2311
<https://github.com/fish-shell/fish-shell/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 <https://github.com/fish-
shell/fish-shell/issues/2268>)
* A new suspend function (#2269 <https://github.com/fish-shell/fish-
shell/issues/2269>)
* Subcommand completion now works better with split /usr (#2141
<https://github.com/fish-shell/fish-shell/issues/2141>)
* The command-not-found-handler can now be overridden by defining a func-
tion called __fish_command_not_found_handler in config.fish (#2332
<https://github.com/fish-shell/fish-shell/issues/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 component
(#2473 <https://github.com/fish-shell/fish-shell/issues/2473>)
* fish no longer requires /etc/fish/config.fish to correctly start, and now
ships a skeleton file that only contains some documentation (#2799
<https://github.com/fish-shell/fish-shell/issues/2799>)
----
fish 2.2.0 (released July 12, 2015)
Significant changes
* Abbreviations: the new abbr command allows for interactively-expanded ab-
breviations, allowing quick access to frequently-used commands (#731
<https://github.com/fish-shell/fish-shell/issues/731>).
* Vi mode: run fish_vi_mode to switch fish into the key bindings and prompt
familiar to users of the Vi editor (#65 <https://github.com/fish-
shell/fish-shell/issues/65>).
* New inline and interactive pager, which will be familiar to users of zsh
(#291 <https://github.com/fish-shell/fish-shell/issues/291>).
* Underlying architectural changes: the fishd universal variable server has
been removed as it was a source of many bugs and security problems. No-
tably, old fish sessions will not be able to communicate universal vari-
able changes with new fish sessions. For best results, restart all run-
ning 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 ain reversea, instead behaving
as expected (#1567 <https://github.com/fish-shell/fish-shell/is-
sues/1567>).
* The previously-undocumented CMD_DURATION variable is now set for all com-
mands and contains the execution time of the last command in milliseconds
(#1585 <https://github.com/fish-shell/fish-shell/issues/1585>). It is no
longer exported to other commands (#1896 <https://github.com/fish-
shell/fish-shell/issues/1896>).
* if / else conditional statements now return values consistent with the
Single Unix Specification, like other shells (#1443
<https://github.com/fish-shell/fish-shell/issues/1443>).
* A new atop-levela local scope has been added, allowing local variables
declared on the commandline to be visible to subsequent commands. (#1908
<https://github.com/fish-shell/fish-shell/issues/1908>)
Other notable fixes and improvements
* New documentation design (#1662 <https://github.com/fish-shell/fish-
shell/issues/1662>), which requires a Doxygen version 1.8.7 or newer to
build.
* Fish now defines a default directory for other packages to provide com-
pletions. By default this is /usr/share/fish/vendor-completions.d; on
systems with pkgconfig installed this path is discoverable with pkg-con-
fig --variable completionsdir fish.
* A new parser removes many bugs; all existing syntax should keep working.
* New fish_preexec and fish_postexec events are fired before and after job
execution respectively (#1549 <https://github.com/fish-shell/fish-
shell/issues/1549>).
* Unmatched wildcards no longer prevent a job from running. Wildcards used
interactively will still print an error, but the job will proceed and the
wildcard will expand to zero arguments (#1482 <https://github.com/fish-
shell/fish-shell/issues/1482>).
* The . command is deprecated and the source command is preferred (#310
<https://github.com/fish-shell/fish-shell/issues/310>).
* bind supports abind modesa, which allows bindings to be set for a partic-
ular named mode, to support the implementation of Vi mode.
* A new export alias, which behaves like other shells (#1833
<https://github.com/fish-shell/fish-shell/issues/1833>).
* command has a new --search option to print the name of the disk file that
would be executed, like other shellsa command -v (#1540
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/393>), and complete -e
now correctly erases completions (#380 <https://github.com/fish-
shell/fish-shell/issues/380>).
* Completions are now generated from manual pages by default on the first
run of fish (#997 <https://github.com/fish-shell/fish-shell/issues/997>).
* fish_indent can now produce colorized (--ansi) and HTML (--html) output
(#1827 <https://github.com/fish-shell/fish-shell/issues/1827>).
* functions --erase now prevents autoloaded functions from being reloaded
in the current session.
* history has a new --merge option, to incorporate history from other ses-
sions into the current session (#825 <https://github.com/fish-shell/fish-
shell/issues/825>).
* jobs returns 1 if there are no active jobs (#1484
<https://github.com/fish-shell/fish-shell/issues/1484>).
* read has several new options:
* --array to break input into an array (#1540 <https://github.com/fish-
shell/fish-shell/issues/1540>)
* --null to break lines on NUL characters rather than newlines (#1694
<https://github.com/fish-shell/fish-shell/issues/1694>)
* --nchars to read a specific number of characters (#1616
<https://github.com/fish-shell/fish-shell/issues/1616>)
* --right-prompt to display a right-hand-side prompt during interactive
read (#1698 <https://github.com/fish-shell/fish-shell/issues/1698>).
* type has a new -q option to suppress output (#1540
<https://github.com/fish-shell/fish-shell/issues/1540> and, like other
shells, type -a now prints all matches for a command (#261
<https://github.com/fish-shell/fish-shell/issues/261>).
* Pressing f1 now shows the manual page for the current command (#1063
<https://github.com/fish-shell/fish-shell/issues/1063>).
* fish_title functions have access to the arguments of the currently run-
ning argument as $argv[1] (#1542 <https://github.com/fish-shell/fish-
shell/issues/1542>).
* The OS command-not-found handler is used on Arch Linux (#1925
<https://github.com/fish-shell/fish-shell/issues/1925>), nixOS (#1852
<https://github.com/fish-shell/fish-shell/issues/1852>), openSUSE and Fe-
dora (#1280 <https://github.com/fish-shell/fish-shell/issues/1280>).
* Alt+. searches backwards in the token history, mapping to the same behav-
ior as inserting the last argument of the previous command, like other
shells (#89 <https://github.com/fish-shell/fish-shell/issues/89>).
* The SHLVL environment variable is incremented correctly (#1634
<https://github.com/fish-shell/fish-shell/issues/1634> & #1693
<https://github.com/fish-shell/fish-shell/issues/1693>).
* Added completions for adb (#1165 <https://github.com/fish-shell/fish-
shell/issues/1165> & #1211 <https://github.com/fish-shell/fish-shell/is-
sues/1211>), apt (#2018 <https://github.com/fish-shell/fish-shell/is-
sues/2018>), aura (#1292 <https://github.com/fish-shell/fish-shell/is-
sues/1292>), composer (#1607 <https://github.com/fish-shell/fish-
shell/issues/1607>), cygport (#1841 <https://github.com/fish-shell/fish-
shell/issues/1841>), dropbox (#1533 <https://github.com/fish-shell/fish-
shell/issues/1533>), elixir (#1167 <https://github.com/fish-shell/fish-
shell/issues/1167>), fossil, heroku (#1790 <https://github.com/fish-
shell/fish-shell/issues/1790>), iex (#1167 <https://github.com/fish-
shell/fish-shell/issues/1167>), kitchen (#2000 <https://github.com/fish-
shell/fish-shell/issues/2000>), nix (#1167 <https://github.com/fish-
shell/fish-shell/issues/1167>), node/npm (#1566 <https://github.com/fish-
shell/fish-shell/issues/1566>), opam (#1615 <https://github.com/fish-
shell/fish-shell/issues/1615>), setfacl (#1752 <https://github.com/fish-
shell/fish-shell/issues/1752>), tmuxinator (#1863
<https://github.com/fish-shell/fish-shell/issues/1863>), and yast2 (#1739
<https://github.com/fish-shell/fish-shell/issues/1739>).
* Improved completions for brew (#1090 <https://github.com/fish-shell/fish-
shell/issues/1090> & #1810 <https://github.com/fish-shell/fish-shell/is-
sues/1810>), bundler (#1779 <https://github.com/fish-shell/fish-shell/is-
sues/1779>), cd (#1135 <https://github.com/fish-shell/fish-shell/is-
sues/1135>), emerge (#1840 <https://github.com/fish-shell/fish-shell/is-
sues/1840>),git (#1680 <https://github.com/fish-shell/fish-shell/is-
sues/1680>, #1834 <https://github.com/fish-shell/fish-shell/issues/1834>
& #1951 <https://github.com/fish-shell/fish-shell/issues/1951>), man (-
#960 <https://github.com/fish-shell/fish-shell/issues/960>), modprobe (-
#1124 <https://github.com/fish-shell/fish-shell/issues/1124>), pacman (-
#1292 <https://github.com/fish-shell/fish-shell/issues/1292>), rpm (#1236
<https://github.com/fish-shell/fish-shell/issues/1236>), rsync (#1872
<https://github.com/fish-shell/fish-shell/issues/1872>), scp (#1145
<https://github.com/fish-shell/fish-shell/issues/1145>), ssh (#1234
<https://github.com/fish-shell/fish-shell/issues/1234>), sshfs (#1268
<https://github.com/fish-shell/fish-shell/issues/1268>), systemctl (#1462
<https://github.com/fish-shell/fish-shell/issues/1462>, #1950
<https://github.com/fish-shell/fish-shell/issues/1950> & #1972
<https://github.com/fish-shell/fish-shell/issues/1972>), tmux (#1853
<https://github.com/fish-shell/fish-shell/issues/1853>), vagrant (#1748
<https://github.com/fish-shell/fish-shell/issues/1748>), yum (#1269
<https://github.com/fish-shell/fish-shell/issues/1269>), and zypper (-
#1787 <https://github.com/fish-shell/fish-shell/issues/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 <https://github.com/fish-shell/fish-shell/issues/1859>
Specifically, after installing fish 2.1.1 and then rebooting, aVerify Diska
in Disk Utility will report aInvalid number of hard links.a We donat 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 be-
lieved 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 auto-
matically. On most systems, there will be no further action required. 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 vari-
ables 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 <https://github.com/fish-shell/fish-shell/is-
sues/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 <https://github.com/fish-shell/fish-shell/is-
sues/1437>
* fishd uses a secure path for its socket, preventing a local privilege es-
calation attack (closing CVE-2014-2905). #1436 <https://github.com/fish-
shell/fish-shell/issues/1436>
* __fish_print_packages is no longer vulnerable to attacks which would al-
low local privilege escalation and data tampering (closing
CVE-2014-3219). #1440 <https://github.com/fish-shell/fish-shell/is-
sues/1440>
Other fixes
* fishd now ignores SIGPIPE, fixing crashes using tools like GNU Parallel
and which occurred more often as a result of the other fishd changes. -
#1084 <https://github.com/fish-shell/fish-shell/issues/1084> & #1690
<https://github.com/fish-shell/fish-shell/issues/1690>
----
fish 2.1.0
Significant Changes
* Tab completions will fuzzy-match files. #568 <https://github.com/fish-
shell/fish-shell/issues/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.txta|, 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 im-
plemented 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
<https://github.com/fish-shell/fish-shell/issues/110>, #877
<https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/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 back-
grounded. If no job is in the background, it will fail to expand. In par-
ticular, 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
<https://github.com/fish-shell/fish-shell/issues/995>
* VTE based terminals should now know the working directory. #906
<https://github.com/fish-shell/fish-shell/issues/906>
* The autotools build now works on Mavericks. #968
<https://github.com/fish-shell/fish-shell/issues/968>
* The end-of-line binding (ctrl+E) now accepts autosuggestions. #932
<https://github.com/fish-shell/fish-shell/issues/932>
* Directories in /etc/paths (used on OS X) are now prepended instead of ap-
pended, similar to other shells. #927 <https://github.com/fish-
shell/fish-shell/issues/927>
* Option-right-arrow (used for partial autosuggestion completion) now works
on iTerm2. #920 <https://github.com/fish-shell/fish-shell/issues/920>
* Tab completions now work properly within nested subcommands. #913
<https://github.com/fish-shell/fish-shell/issues/913>
* printf supports \e, the escape character. #910 <https://github.com/fish-
shell/fish-shell/issues/910>
* fish_config history no longer shows duplicate items. #900
<https://github.com/fish-shell/fish-shell/issues/900>
* $fish_user_paths is now prepended to $PATH instead of appended. #888
<https://github.com/fish-shell/fish-shell/issues/888>
* Jobs complete when all processes complete. #876 <https://github.com/fish-
shell/fish-shell/issues/876>
For example, in previous versions of fish, sleep 10 | echo Done returns
control immediately, because echo does not read from stdin. Now it does
not complete until sleep exits (presumably after 10 seconds).
* Better error reporting for square brackets. #875
<https://github.com/fish-shell/fish-shell/issues/875>
* fish no longer tries to add /bin to $PATH unless PATH is totally empty. -
#852 <https://github.com/fish-shell/fish-shell/issues/852>
* History token substitution (alt-up) now works correctly inside subshells.
#833 <https://github.com/fish-shell/fish-shell/issues/833>
* Flow control is now disabled, freeing up ctrl-S and ctrl-Q for other
uses. #814 <https://github.com/fish-shell/fish-shell/issues/814>
* sh-style variable setting like foo=bar now produces better error mes-
sages. #809 <https://github.com/fish-shell/fish-shell/issues/809>
* Commands with wildcards no longer produce autosuggestions. #785
<https://github.com/fish-shell/fish-shell/issues/785>
* funced no longer freaks out when supplied with no arguments. #780
<https://github.com/fish-shell/fish-shell/issues/780>
* fish.app now works correctly in a directory containing spaces. #774
<https://github.com/fish-shell/fish-shell/issues/774>
* Tab completion cycling no longer occasionally fails to repaint. #765
<https://github.com/fish-shell/fish-shell/issues/765>
* Comments now work in evalad strings. #684 <https://github.com/fish-
shell/fish-shell/issues/684>
* History search (up-arrow) now shows the item matching the autosuggestion,
if that autosuggestion was truncated. #650 <https://github.com/fish-
shell/fish-shell/issues/650>
* Ctrl-T now transposes characters, as in other shells. #128
<https://github.com/fish-shell/fish-shell/issues/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 $sta-
tus 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 effectively
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 <https://github.com/fish-shell/fish-shell/issues/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
<https://github.com/fish-shell/fish-shell/issues/300>
* New syntax for index ranges (sometimes known as aslicesa) #212
<https://github.com/fish-shell/fish-shell/issues/212>
* fish now supports an ``else if`` statement #134 <https://github.com/fish-
shell/fish-shell/issues/134>
* Process and pid completion now works on OS X #129
<https://github.com/fish-shell/fish-shell/issues/129>
* fish is now relocatable, and no longer depends on compiled-in paths #125
<https://github.com/fish-shell/fish-shell/issues/125>
* fish now supports a right prompt (RPROMPT) through the fish_right_prompt
function #80 <https://github.com/fish-shell/fish-shell/issues/80>
* fish now uses posix_spawn instead of fork when possible, which is much
faster on BSD and OS X #11 <https://github.com/fish-shell/fish-shell/is-
sues/11>
Other Notable Fixes
* Updated VCS completions (darcs, cvs, svn, etc.)
* Avoid calling getcwd on the main thread, as it can hang #696
<https://github.com/fish-shell/fish-shell/issues/696>
* Control-D (forward delete) no longer stops at a period #667
<https://github.com/fish-shell/fish-shell/issues/667>
* Completions for many new commands
* fish now respects rxvtas unique keybindings #657
<https://github.com/fish-shell/fish-shell/issues/657>
* xsel is no longer built as part of fish. It will still be invoked if in-
stalled separately #633 <https://github.com/fish-shell/fish-shell/is-
sues/633>
* __fish_filter_mime no longer spews #628 <https://github.com/fish-
shell/fish-shell/issues/628>
* The ano-execute option to fish no longer falls over when reaching the end
of a block #624 <https://github.com/fish-shell/fish-shell/issues/624>
* fish_config knows how to find fish even if itas not in the $PATH #621
<https://github.com/fish-shell/fish-shell/issues/621>
* A leading space now prevents writing to history, as is done in bash and
zsh #615 <https://github.com/fish-shell/fish-shell/issues/615>
* Hitting enter after a backslash only goes to a new line if it is followed
by whitespace or the end of the line #613 <https://github.com/fish-
shell/fish-shell/issues/613>
* printf is now a builtin #611 <https://github.com/fish-shell/fish-
shell/issues/611>
* Event handlers should no longer fire if signals are blocked #608
<https://github.com/fish-shell/fish-shell/issues/608>
* set_color is now a builtin #578 <https://github.com/fish-shell/fish-
shell/issues/578>
* man page completions are now located in a new generated_completions di-
rectory, instead of your completions directory #576
<https://github.com/fish-shell/fish-shell/issues/576>
* tab now clears autosuggestions #561 <https://github.com/fish-shell/fish-
shell/issues/561>
* tab completion from within a pair of quotes now attempts to aappropriatea
the closing quote #552 <https://github.com/fish-shell/fish-shell/is-
sues/552>
* $EDITOR can now be a list: for example, set EDITOR gvim -f) #541
<https://github.com/fish-shell/fish-shell/issues/541>
* case bodies are now indented #530 <https://github.com/fish-shell/fish-
shell/issues/530>
* The profile switch -p no longer crashes #517 <https://github.com/fish-
shell/fish-shell/issues/517>
* You can now control-C out of read #516 <https://github.com/fish-
shell/fish-shell/issues/516>
* umask is now functional on OS X #515 <https://github.com/fish-shell/fish-
shell/issues/515>
* Avoid calling getpwnam on the main thread, as it can hang #512
<https://github.com/fish-shell/fish-shell/issues/512>
* Alt-F or Alt-right-arrow (Option-F or option-right-arrow) now accepts one
word of an autosuggestion #435 <https://github.com/fish-shell/fish-
shell/issues/435>
* Setting fish as your login shell no longer kills OpenSUSE #367
<https://github.com/fish-shell/fish-shell/issues/367>
* Backslashes now join lines, instead of creating multiple commands #347
<https://github.com/fish-shell/fish-shell/issues/347>
* echo now implements the -e flag to interpret escapes #337
<https://github.com/fish-shell/fish-shell/issues/337>
* When the last token in the useras input contains capital letters, use its
case in preference to that of the autosuggestion #335
<https://github.com/fish-shell/fish-shell/issues/335>
* Descriptions now have their own muted color #279
<https://github.com/fish-shell/fish-shell/issues/279>
* Wildcards beginning with a . (for example, ls .*) no longer match . and
.. #270 <https://github.com/fish-shell/fish-shell/issues/270>
* Recursive wildcards now handle symlink loops #268
<https://github.com/fish-shell/fish-shell/issues/268>
* You can now delete history items from the fish_config web interface #250
<https://github.com/fish-shell/fish-shell/issues/250>
* The OS X build now weak links wcsdup and wcscasecmp #240
<https://github.com/fish-shell/fish-shell/issues/240>
* fish now saves and restores the process group, which prevents certain
processes from being erroneously reported as stopped #197
<https://github.com/fish-shell/fish-shell/issues/197>
* funced now takes an editor option #187 <https://github.com/fish-
shell/fish-shell/issues/187>
* Alternating row colors are available in fish pager through
fish_pager_color_secondary #186 <https://github.com/fish-shell/fish-
shell/issues/186>
* Universal variable values are now stored based on your MAC address, not
your hostname #183 <https://github.com/fish-shell/fish-shell/issues/183>
* The caret ^ now only does a stderr redirection if it is the first charac-
ter of a token, making git users happy #168 <https://github.com/fish-
shell/fish-shell/issues/168>
* Autosuggestions will no longer cause line wrapping #167
<https://github.com/fish-shell/fish-shell/issues/167>
* Better handling of Unicode combining characters #155
<https://github.com/fish-shell/fish-shell/issues/155>
* fish SIGHUPs processes more often #138 <https://github.com/fish-
shell/fish-shell/issues/138>
* fish no longer causes sudo to ask for a password every time
* fish behaves better under Midnight Commander #121
<https://github.com/fish-shell/fish-shell/issues/121>
* set -e no longer crashes #100 <https://github.com/fish-shell/fish-
shell/issues/100>
* fish now will automatically import history from bash, if there is no fish
history #66 <https://github.com/fish-shell/fish-shell/issues/66>
* Backslashed-newlines inside quoted strings now behave more intuitively -
#52 <https://github.com/fish-shell/fish-shell/issues/52>
* Tab titles should be shown correctly in iTerm2 #47
<https://github.com/fish-shell/fish-shell/issues/47>
* scp remote path completion now sometimes works #42
<https://github.com/fish-shell/fish-shell/issues/42>
* The read builtin no longer shows autosuggestions #29
<https://github.com/fish-shell/fish-shell/issues/29>
* Custom key bindings can now be set via the fish_user_key_bindings func-
tion #21 <https://github.com/fish-shell/fish-shell/issues/21>
* All Python scripts now run correctly under both Python 2 and Python 3 #14
<https://github.com/fish-shell/fish-shell/issues/14>
* The aaccept autosuggestiona key can now be configured #19
<https://github.com/fish-shell/fish-shell/issues/19>
* Autosuggestions will no longer suggest invalid commands #6
<https://github.com/fish-shell/fish-shell/issues/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 ainternalized
scriptsa 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 pur-
poses; in particular, for yank, which now works on OS X.
* fish_indent is fixed. In particular, the funced and funcsave functions
work again.
* A SIGTERM now ends the whole execution stack again (resolving #13
<https://github.com/fish-shell/fish-shell/issues/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 a555
yellowa.
New Features
* A history builtin, and associated interactive function that enables
deleting history items. Example usage: * Print all history items begin-
ning with echo: history --prefix echo * Print all history items contain-
ing foo: history --contains foo * Interactively delete some items con-
taining 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 command,
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; thereas a lot of potential for improvement here.
The suggestions are computed on a background pthread, so they never slow
down your typing. The autosuggestion feature 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 (aset_color cyana) or by speci-
fying RGB hex values (aset_color FF3333a); 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 afish_configa. 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 func-
tions, variables, and history; all changes apply immediately to all run-
ning shells. Eventually all configuration ought to be supported via this
mechanism (but in addition to, not instead of, command line mechanisms).
* Man page completions. There is a new function afish_update_completionsa.
This function reads all the man1 files from your manpath, removes the
roff formatting, parses them to find the commands and options, and out-
puts fish completions into ~/.config/fish/completions. It wonat overwrite
existing completion files (except ones that it generated 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. Weave made an effort 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 donat 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, prior-
ity_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 instead of wchar_t *
* fish now spawns pthreads for tasks like syntax highlighting that require
blocking I/O.
* History has been completely rewritten. History files now use an extensi-
ble YAML-style syntax. History amerginga (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 ainstanced,a 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 com-
mands 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 ainternalizeda
into C strings that get compiled in with fish. This substantially reduces
the number of files touched at startup. A consequence is that you cannot
change these functions without recompiling, but often other functions de-
pend on these astandarda 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 compari-
son. This data was collected via dtrace.
before
after
bash
open
9
4
5
fork
28
14
0
stat
131
85
11
lstat
670
0
0
read
332
80
4
write
172
149
0
The large number of forks relative to bash are due to fishas insanely ex-
pensive default prompt, which is unchanged in my version. If we switch to a
prompt comparable to bashas (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.
Weave got some work to do to be as lean as bash, but weare on the right
track.
Terminal Compatibility
fish writes various control sequences to the terminal. Some must be imple-
mented to enable basic functionality, while others enable optional features
and may be ignored by the terminal.
The terminal must be able to parse Control Sequence Introducer (CSI) com-
mands, Operating System Commands (OSC) and optionally Device Control
Strings (DCS). These are defined by ECMA-48. If a valid CSI, OSC or DCS
sequence does not represent a command implemented by the terminal, the ter-
minal must ignore it. For historical reasons, OSC sequences may be termi-
nated with \x07 instead of \e\\.
Control sequences are denoted in a fish-like syntax. Special characters
other than \ are not escaped. Spaces are only added for readability and
are not part of the sequence. Placeholders are written as Ps for a number
or Pt for an arbitrary printable string.
NOTE: fish does not rely on your system's terminfo database. In this docu-
ment, terminfo (TI) codes are included for reference only.
Required Commands
+----------+-------+----------------------+
| Sequence | TI | Description |
+----------+-------+----------------------+
| \r | n/a | Move cursor to the |
| | | beginning of the |
| | | line |
+----------+-------+----------------------+
| \n | cud1 | Move cursor down one |
| | | line. |
+----------+-------+----------------------+
| \e[ Ps A | cuu | Move cursor up Ps |
| | | columns, or one col- |
| | | umn if no parameter. |
+----------+-------+----------------------+
| \e[ Ps C | cuf | Move cursor to the |
| | | right Ps columns, or |
| | | one column if no pa- |
| | | rameter. |
+----------+-------+----------------------+
| \x08 | cub1 | Move cursor one col- |
| | | umn to the left. |
+----------+-------+----------------------+
| \e[ Ps D | cub | Move cursor to the |
| | | left Ps times. |
+----------+-------+----------------------+
| \e[H | cup | Set cursor position |
| | | (no parameters |
| | | means: move to row |
| | | 1, column 1). |
+----------+-------+----------------------+
| \e[K | el | Clear to end of |
| | | line. |
+----------+-------+----------------------+
| \e[J | ed | Clear to the end of |
| | | screen. |
+----------+-------+----------------------+
| \e[2J | clear | Clear the screen. |
+----------+-------+----------------------+
| \e[0c | | Request Primary De- |
| | | vice Attribute. The |
| | | terminal must re- |
| | | spond with a CSI |
| | | command that starts |
| | | with the ? parameter |
| | | byte (so a sequence |
| | | starting with \e[?) |
| | | and has c as final |
| | | byte. |
| | | |
| | | Failure to implement |
| | | this will cause a |
| | | brief pause at |
| | | startup followed by |
| | | a warning. For the |
| | | time being, both can |
| | | be turned off by |
| | | turning off the |
| | | query-terminal |
| | | feature flag. |
+----------+-------+----------------------+
| n/a | am | Soft wrap text at |
| | | screen width. |
+----------+-------+----------------------+
| n/a | xenl | Printing to the last |
| | | column does not move |
| | | the cursor to the |
| | | next line. Verify |
| | | this by running |
| | | printf %0"$COLUMNS"d |
| | | 0; sleep 3 |
+----------+-------+----------------------+
Optional Commands
+----------------------+-------------+---------------------------------+
| Sequence | TI | Description |
+----------------------+-------------+---------------------------------+
| \t | it | Move the cursor to |
| | | the next tab stop |
| | | (A 8 columns). |
| | | This is mainly rele- |
| | | vant if your prompt |
| | | includes tabs. |
+----------------------+-------------+---------------------------------+
| \e[m | sgr0 | Turn off |
| | | bold/dim/italic/un- |
| | | der- |
| | | line/strikethrough/re- |
| | | verse attribute |
| | | modes and select de- |
| | | fault colors. |
+----------------------+-------------+---------------------------------+
| \e[1m | bold | Enter bold mode. |
+----------------------+-------------+---------------------------------+
| \e[2m | dim | Enter dim mode. |
+----------------------+-------------+---------------------------------+
| \e[3m | sitm | Enter italic mode. |
+----------------------+-------------+---------------------------------+
| \e[4m | smul | Enter underline mode. |
+----------------------+-------------+---------------------------------+
| \e[4:2m | Su | Enter double underline |
| | | mode. |
+----------------------+-------------+---------------------------------+
| \e[4:3m | Su | Enter curly underline |
| | | mode. |
+----------------------+-------------+---------------------------------+
| \e[4:4m | Su | Enter dotted underline |
| | | mode. |
+----------------------+-------------+---------------------------------+
| \e[4:5m | Su | Enter dashed underline |
| | | mode. |
+----------------------+-------------+---------------------------------+
| \e[7m | rev | Enter reverse video |
| | | mode (swap foreground |
| | | and background col- |
| | | ors). |
+----------------------+-------------+---------------------------------+
| \e[9m | smxx | Enter strikethrough |
| | | mode |
+----------------------+-------------+---------------------------------+
| \e[23m | ritm | Exit italic mode. |
+----------------------+-------------+---------------------------------+
| \e[24m | rmul | Exit underline mode. |
+----------------------+-------------+---------------------------------+
| \e[29m | rmxx | Exit strikethrough |
| | | mode. |
+----------------------+-------------+---------------------------------+
| \e[38;5; Ps m | setaf | Select foreground |
| | | color Ps from the |
| | | 256-color-palette. |
+----------------------+-------------+---------------------------------+
| \e[48;5; Ps m | setab | Select background |
| | | color Ps from the |
| | | 256-color-palette. |
+----------------------+-------------+---------------------------------+
| \e[58:5: Ps m (note: | Su | Select underline color |
| colons not semi- | | Ps from the |
| colons) | | 256-color-palette. |
+----------------------+-------------+---------------------------------+
| \e[ Ps m | setaf setab | Select fore- |
| | | ground/background |
| | | color. This uses a |
| | | color in the aforemen- |
| | | tioned |
| | | 256-color-palette, |
| | | based on the range |
| | | that contains the pa- |
| | | rameter: 30-37 maps to |
| | | foreground 0-7, 40-47 |
| | | maps to background |
| | | 0-7, 90-97 maps to |
| | | foreground 8-15 and |
| | | 100-107 maps to back- |
| | | ground 8-15. |
+----------------------+-------------+---------------------------------+
| \e[38;2; Ps ; Ps ; | | Select foreground |
| Ps m | | color from 24-bit RGB |
| | | colors. |
+----------------------+-------------+---------------------------------+
| \e[48;2; Ps ; Ps ; | | Select background |
| Ps m | | color from 24-bit RGB |
| | | colors. |
+----------------------+-------------+---------------------------------+
| \e[39m | | Reset foreground color |
| | | to the terminal's de- |
| | | fault. |
+----------------------+-------------+---------------------------------+
| \e[49m | | Reset background color |
| | | to the terminal's de- |
| | | fault. |
+----------------------+-------------+---------------------------------+
| \e[58:2:: Ps : Ps : | Su | Select underline color |
| Ps m (note: colons | | from 24-bit RGB col- |
| not semicolons) | | ors. |
+----------------------+-------------+---------------------------------+
| \e[59m | Su | Reset underline color |
| | | to the default (follow |
| | | the foreground color). |
+----------------------+-------------+---------------------------------+
| \e[ Ps S | indn | Scroll up the content |
| | | (not the viewport) Ps |
| | | lines (called SCROLL |
| | | UP / SU by ECMA-48 and |
| | | "scroll forward" by |
| | | terminfo). When fish |
| | | detects support for |
| | | this feature, status |
| | | test-terminal-features |
| | | scroll-content-up will |
| | | return 0, which en- |
| | | ables the ctrl-l bind- |
| | | ing to use the |
| | | scrollback-push spe- |
| | | cial input function. |
+----------------------+-------------+---------------------------------+
| \e[= Ps u, \e[? Ps u | n/a | Enable the kitty key- |
| | | board protocol. |
+----------------------+-------------+---------------------------------+
| \e[6n | n/a | Request cursor posi- |
| | | tion report. The re- |
| | | sponse must be of the |
| | | form \e[ Ps ; Ps R |
| | | where the first para- |
| | | meter is the row num- |
| | | ber and the second pa- |
| | | rameter is the column |
| | | number. Both start at |
| | | 1. |
| | | |
| | | This is used for trun- |
| | | cating multiline auto- |
| | | suggestions at the |
| | | screen's bottom edge, |
| | | by the scrollback-push |
| | | special input func- |
| | | tion, and inside ter- |
| | | minals that implement |
| | | the OSC 133 |
| | | click_events feature. |
+----------------------+-------------+---------------------------------+
| \e[ \x20 q | Se | Reset cursor style to |
| | | the terminal's de- |
| | | fault. This is not |
| | | used as of today but |
| | | may be in future. |
+----------------------+-------------+---------------------------------+
| \e[ Ps \x20 q | Ss | Set cursor style (DEC- |
| | | SCUSR); Ps is 2, 4 or |
| | | 6 for block, under- |
| | | score or line shape. |
+----------------------+-------------+---------------------------------+
| \e[ Ps q | n/a | Request terminal name |
| | | and version (XTVER- |
| | | SION). This is only |
| | | used for temporary |
| | | workarounds for incom- |
| | | patible terminals. |
+----------------------+-------------+---------------------------------+
| \e[?25h | cvvis | Enable cursor visibil- |
| | | ity (DECTCEM). |
+----------------------+-------------+---------------------------------+
| \e[?1004h | n/a | Enable focus report- |
| | | ing. |
+----------------------+-------------+---------------------------------+
| \e[?1004l | n/a | Disable focus report- |
| | | ing. |
+----------------------+-------------+---------------------------------+
| \e[?1049h | n/a | Enable alternate |
| | | screen buffer. |
+----------------------+-------------+---------------------------------+
| \e[?1049l | n/a | Disable alternate |
| | | screen buffer. |
+----------------------+-------------+---------------------------------+
| \e[?2004h | | Enable bracketed |
| | | paste. |
+----------------------+-------------+---------------------------------+
| \e[?2004l | | Disable bracketed |
| | | paste. |
+----------------------+-------------+---------------------------------+
| \e[?2031h | | Enable unsolicited - |
| | | color theme reporting |
| | | <https://contour-ter- |
| | | minal.org/vt-exten- |
| | | sions/color-palette- |
| | | update-notifica- |
| | | tions/>. When en- |
| | | abled, the terminal |
| | | should send \e[?997;1n |
| | | or \e[?997;2n whenever |
| | | its color theme has |
| | | changed. This prompts |
| | | fish to query for |
| | | background color. |
+----------------------+-------------+---------------------------------+
| \e[?2031l | | Disable unsolicited |
| | | color theme reporting. |
+----------------------+-------------+---------------------------------+
| \e]0; Pt \e\\ | ts | Set terminal window |
| | | title (OSC 0). Used in |
| | | fish_title. |
+----------------------+-------------+---------------------------------+
| \e]2; Pt \e\\ | ts | Set terminal tab title |
| | | (OSC 1). Used in |
| | | fish_tab_title. |
+----------------------+-------------+---------------------------------+
| \e]7;file:// Pt / Pt | | Report working direc- |
| \e\\ | | tory (OSC 7). Since |
| | | the terminal may be |
| | | running on a different |
| | | system than a (remote) |
| | | shell, the hostname |
| | | (first parameter) will |
| | | not be localhost. |
+----------------------+-------------+---------------------------------+
| \e]8;; Pt \e\\ | | Create a hyperlink |
| | | (OSC 8) |
| | | <https://gist.github.com/egmon- |
| | | tkob/eb114294ef- |
| | | bcd5adb1944c9f3cb5feda>. |
| | | This is used in fish's |
| | | man pages. |
+----------------------+-------------+---------------------------------+
| \e]11;?\e\\ | n/a | Query background color. |
| | | |
| | | A valid response would be of |
| | | the form \e]11;rgb: Pt / Pt / |
| | | Pt \e\\ or \e]11;rgba: Pt / Pt |
| | | / Pt / Pt\e\\ where the first |
| | | three parameters consist of one |
| | | to four hex digits each, repre- |
| | | senting red, blue and green |
| | | components. |
| | | |
| | | This is used to populate |
| | | fish_terminal_color_theme, |
| | | which is used to select a theme |
| | | variant optimized for the ter- |
| | | minal's color theme. |
+----------------------+-------------+---------------------------------+
| \e]52;c; Pt \e\\ | | Copy to clipboard (OSC 52). |
| | | Used by fish_clipboard_copy. |
+----------------------+-------------+---------------------------------+
| \e]133;A; | | Mark prompt start (OSC 133), |
| click_events=1\e\\ | | with kitty's click_events ex- |
| | | tension. The click_events ex- |
| | | tension enables mouse clicks to |
| | | move the cursor or select pager |
| | | items, assuming that cursor po- |
| | | sition reporting is available. |
+----------------------+-------------+---------------------------------+
| \e]133;B\e\\ | | Mark prompt end (OSC 133). |
+----------------------+-------------+---------------------------------+
| \e]133;C; cmd- | | Mark command start (OSC 133), |
| line_url= Pt \e\\ | | with kitty's cmdline_url exten- |
| | | sion whose parameter is the |
| | | URL-encoded command line. |
+----------------------+-------------+---------------------------------+
| \e]133;D; Ps \e\\ | | Mark command end (OSC 133); Ps |
| | | is the exit status. |
+----------------------+-------------+---------------------------------+
| \eP+q Pt \e\\ | | Request terminfo capability |
| | | (XTGETTCAP). The parameter is |
| | | the capability's hex-encoded |
| | | terminfo code. |
| | | |
| | | The response must be of the |
| | | form \eP1+q Pt \e\\ ("boolean") |
| | | or \eP1+q Pt = Pt \e\\ |
| | | ("string"). In either variant, |
| | | the first parameter must be the |
| | | same as the request parameter. |
| | | |
| | | fish queries the following |
| | | string capabilities: |
| | | |
| | | * indn |
| | | |
| | | The response's second |
| | | parameter is ignored. |
| | | |
| | | * query-os-name (for |
| | | status terminal-os) |
| | | |
| | | Terminals running on |
| | | Unix should respond with |
| | | the hex encoding of |
| | | $(uname -s) as second |
| | | parameter. |
+----------------------+-------------+---------------------------------+
DCS commands and GNU screen
DCS parsing is optional because fish temporarily switches to the alternate
screen before printing any DCS commands. However, since GNU screen neither
allows turning on the alternate screen buffer by default, nor treats DCS
commands in a compatible way, fish's initial prompt may be garbled by a DCS
payload like +q696e646e. For the time being, fish works around this by
checking for presence of the STY environment variable. If that doesn't
work for some reason, you can add this to your ~/.screenrc:
altscreen on
Or add this to your config.fish:
function GNU-screen-workaround --on-event fish_prompt
commandline -f repaint
functions --erase GNU-screen-workaround
end
Unicode Codepoints
By default, fish outputs the following non-ASCII characters:
A ao A<paragraph> a ac a a| I1/4 a a a a a a a a a
as well as control pictures (U+2400 through U+241F), and locale-specific
ones in translated strings.
Contributing To Fish
This document tells you how you can contribute to fish.
Fish is free and open source software, distributed under the terms of the
GPLv2.
Contributions are welcome, and there are many ways to contribute!
Whether you want to change some of the core Rust source, enhance or add a
completion script or function, improve the documentation or translate some-
thing, this document will tell you how.
Mailing List
Send patches to the public mailing list: -
mailto:~krobelus/fish-shell@lists.sr.ht. Archives are available at -
https://lists.sr.ht/~krobelus/fish-shell/.
GitHub
Fish is available on GitHub, at https://github.com/fish-shell/fish-shell.
First, you'll need an account there, and you'll need a git clone of fish.
Fork it on GitHub and then run:
git clone https://github.com/<USERNAME>/fish-shell.git
This will create a copy of the fish repository in the directory fish-shell
in your current working directory.
Also, for most changes you want to run the tests and so you'd get a setup
to compile fish. For that, you'll require:
* Rust - when in doubt, try rustup
* CMake
* PCRE2 (headers and libraries) - optional, this will be downloaded if
missing
* gettext (only the msgfmt tool) - optional, for translation support
* Sphinx - optional, to build the documentation
Of course not everything is required always - if you just want to con-
tribute something to the documentation you'll just need Sphinx, and if the
change is very simple and obvious you can just send it in. Use your judge-
ment!
Once you have your changes, open a pull request on -
https://github.com/fish-shell/fish-shell/pulls.
Guidelines
In short:
* Be conservative in what you need (keep to the agreed minimum supported
Rust version, limit new dependencies)
* Use automated tools to help you (cargo xtask check)
Commit History
We use a linear, recipe-style <https://www.bitsnbites.eu/git-history-work-
log-vs-recipe/> history. Every commit should pass our checks. We do not
want "fixup" commits in our history. If you notice an issue with a commit
in a pull request, or get feedback suggesting changes, you should rewrite
the commit history and fix the relevant commits directly, instead of adding
new "fixup" commits. When a pull request is ready, we rebase it on top of
the current master branch, so don't be shy about rewriting the history of
commits which are not on master yet. Rebasing (not merging) your pull re-
quest on the latest version of master is also welcome, especially if it re-
solves conflicts.
If you're using Git, consider using jj <https://www.jj-vcs.dev/> to make
this easier.
If a commit should close an issue, add a Fixes #<issue-number> line at the
end of the commit description.
Contributing completions
Completion scripts are the most common contribution to fish, and they are
very welcome.
In general, we'll take all well-written completion scripts for a command
that is publicly available. This means no private tools or personal
scripts, and we do reserve the right to reject for other reasons.
Before you try to contribute them to fish, consider if the authors of the
tool you are completing want to maintain the script instead. Often that
makes more sense, specifically because they can add new options to the
script immediately once they add them, and don't have to maintain one com-
pletion script for multiple versions. If the authors no longer wish to
maintain the script, they can of course always contact the fish maintainers
to hand it over, preferably by opening a PR. This isn't a requirement - if
the authors don't want to maintain it, or you simply don't want to contact
them, you can contribute your script to fish.
Completion scripts should
1. Use as few dependencies as possible - try to use fish's builtins like
string instead of grep and awk, use python to read json instead of jq
(because it's already a soft dependency for fish's tools)
2. If it uses a common unix tool, use POSIX-compatible invocations - ide-
ally it would work on GNU/Linux, macOS, the BSDs and other systems
3. Option and argument descriptions should be kept short. The shorter the
description, the more likely it is that fish can use more columns.
4. Function names should start with __fish, and functions should be kept in
the completion file unless they're used elsewhere.
5. Run fish_indent on your script.
6. Try not to use minor convenience features right after they are available
in fish - we do try to keep completion scripts backportable. If some-
thing has a real impact on the correctness or performance, feel free to
use it, but if it is just a shortcut, please leave it.
Put your completion script into share/completions/name-of-command.fish. If
you have multiple commands, you need multiple files.
If you want to add tests, you probably want to add a littlecheck test. See
below for details.
Contributing documentation
The documentation is stored in doc_src/, and written in ReStructured Text
and built with Sphinx. The builtins and various functions shipped with
fish are documented in doc_src/cmds/.
To build an HTML version of the docs locally, run:
cargo xtask html-docs
will output to target/fish-docs/html or, if you use CMake:
cmake --build build -t sphinx-docs
will output to build/cargo/fish-docs/html/. You can also run sphinx-build
directly, which allows choosing the output directory:
sphinx-build -j auto -b html doc_src/ /tmp/fish-doc/
will output HTML docs to /tmp/fish-doc.
After building them, you can open the HTML docs in a browser and see that
it looks okay.
Code Style
For formatting, we use:
* rustfmt for Rust
* fish_indent (shipped with fish) for fish script
* ruff format for Python
To reformat files, there is an xtask
cargo xtask format --all
cargo xtask format somefile.rs some.fish
Fish Script Style Guide
1. All fish scripts, such as those in the share/functions and tests direc-
tories, should be formatted using the fish_indent command.
2. Function names should be in all lowercase with words separated by under-
scores. Private functions should begin with an underscore. The first
word should be fish if the function is unique to fish.
3. The first word of global variable names should generally be fish for
public vars or _fish for private vars to minimize the possibility of
name clashes with user defined vars.
Configuring Your Editor for Fish Scripts
If you use Vim: Install vim-fish <https://github.com/dag/vim-fish>, make
sure you have syntax and filetype functionality in ~/.vimrc:
syntax enable
filetype plugin indent on
Then turn on some options for nicer display of fish scripts in ~/.vim/ft-
plugin/fish.vim:
" Set up :make to use fish for syntax checking.
compiler fish
" Set this to have long lines wrap inside comments.
setlocal textwidth=79
" Enable folding of block structures in fish.
setlocal foldmethod=expr
If you use Emacs: Install fish-mode <https://github.com/wwwjfy/emacs-fish>
(also available in melpa and melpa-stable) and (setq-default in-
dent-tabs-mode nil) for it (via a hook or in use-packages a:inita block).
It can also be made to run fish_indent via e.g.
(add-hook 'fish-mode-hook (lambda ()
(add-hook 'before-save-hook 'fish_indent-before-save)))
Minimum Supported Rust Version (MSRV) Policy
We support at least the version of rustc available in Debian Stable.
Testing
The source code for fish includes a large collection of tests. If you are
making any changes to fish, running these tests is a good way to make sure
the behaviour remains consistent and regressions are not introduced. Even
if you donat run the tests on your machine, they will still be run via
GitHub Actions.
You are strongly encouraged to add tests when changing the functionality of
fish, especially if you are fixing a bug to help ensure there are no re-
gressions in the future (i.e., we donat reintroduce the bug).
Unit tests live next to the implementation in Rust source files, in inline
submodules (mod tests {}).
System tests live in tests/:
* tests/checks are run by littlecheck <https://github.com/ridiculous-
fish/littlecheck> and test noninteractive (script) behavior, except for
tests/checks/tmux-* which test interactive scenarios.
* tests/pexpects tests interactive scenarios using pexpect <https://pex-
pect.readthedocs.io/en/stable/>
When in doubt, the bulk of the tests should be added as a littlecheck test
in tests/checks, as they are the easiest to modify and run, and much faster
and more dependable than pexpect tests. The syntax is fairly self-explana-
tory. It's a fish script with the expected output in # CHECK: or # CHECK-
ERR: (for stderr) comments. If your littlecheck test has a specific depen-
dency, use # REQUIRE: ... with a POSIX sh script.
The pexpect tests are written in Python and can simulate input and output
to/from a terminal, so they are needed for anything that needs actual in-
teractivity. The runner is in tests/pexpect_helper.py, in case you need to
modify something there.
These tests can be run via the tests/test_driver.py Python script, which
will set up the environment. It sets up a temporary $HOME and also uses it
as the current directory, so you do not need to create a temporary direc-
tory in them.
If you need a command to do something weird to test something, maybe add it
to the fish_test_helper binary (in tests/fish_test_helper.c).
Local testing
The tests can be run on your local system:
cargo build
# Run unit tests
cargo test
# Run system tests
tests/test_driver.py target/debug
# Run a specific system test.
tests/test_driver.py target/debug tests/checks/abbr.fish
Here, the first argument to test_driver.py refers to a directory with fish,
fish_indent and fish_key_reader in it. In this example we're in the root
of the workspace and have run cargo build without --release, so it's a de-
bug build.
To run all tests and linters, use:
cargo xtask check
Contributing Translations
Fish uses GNU gettext to translate messages from English to other lan-
guages. We use custom tools for extracting messages from source files and
to localize at runtime. This means that we do not have a runtime depen-
dency on the gettext library. It also means that some features are not
supported, such as message context and plurals. We also expect all files
to be UTF-8-encoded. In practice, this should not matter much for con-
tributing translations.
Translation sources are stored in the localization/po directory and named
ll_CC.po, where ll is the two (or possibly three) letter ISO 639-1 language
code of the target language (e.g. pt for Portuguese). CC is an ISO 3166
country/territory code, (e.g. BR for Brazil). An example for a valid name
is pt_BR.po, indicating Brazilian Portuguese. These are the files you will
interact with when adding translations.
Adding translations for a new language
Creating new translations requires the Gettext tools. More specifically,
you will need msguniq and msgmerge for creating translations for a new lan-
guage. To create a new translation, run:
build_tools/update_translations.fish localization/po/ll_CC.po
This will create a new PO file containing all messages available for trans-
lation. If the file already exists, it will be updated.
After modifying a PO file, you can recompile fish, and it will integrate
the modifications you made. This requires that the msgfmt utility is in-
stalled (comes as part of gettext). It is important that the localize-mes-
sages cargo feature is enabled, which it is by default. You can explicitly
enable it using:
cargo build --features=localize-messages
Use environment variables to tell fish which language to use, e.g.:
LANG=pt_BR.utf8 fish
or within the running fish shell:
set LANG pt_BR.utf8
For more options regarding how to choose languages, see the corresponding
gettext documentation <https://www.gnu.org/software/gettext/man-
ual/html_node/Locale-Environment-Variables.html>. One neat thing you can
do is set a list of languages to check for translations in the order de-
fined using the LANGUAGE variable, e.g.:
set LANGUAGE pt_BR de_DE
to try to translate messages to Portuguese, if that fails try German, and
if that fails too you will see the English version defined in the source
code.
Modifying existing translations
If you want to work on translations for a language which already has a cor-
responding po file, it is sufficient to edit this file. No other changes
are necessary.
After recompiling fish, you should be able to see your translations in ac-
tion. See the previous section for details.
Editing PO files
Many tools are available for editing translation files, including com-
mand-line and graphical user interface programs. For simple use, you can
use your text editor.
Open up the PO file, for example localization/po/sv.po, and you'll see
something like:
msgid "%s: No suitable job\n"
msgstr ""
The msgid here is the "name" of the string to translate, typically the Eng-
lish string to translate. The second line (msgstr) is where your transla-
tion goes.
For example:
msgid "%s: No suitable job\n"
msgstr "%s: Inget passande jobb\n"
Any %s or %d are placeholders that fish will use for formatting at runtime.
It is important that they match - the translated string should have the
same placeholders in the same order.
Also any escaped characters, like that \n newline at the end, should be
kept so the translation has the same behavior.
Our tests run msgfmt --check-format /path/to/file, so they would catch mis-
matched placeholders - otherwise fish would crash at runtime when the
string is about to be used.
Be cautious about blindly updating an existing translation file. msgid
strings should never be updated manually, only by running the appropriate
script.
Modifications to strings in source files
If a string changes in the sources, the old translations will no longer
work. They will be preserved in the PO files, but commented-out (starting
with #~). If you add/remove/change a translatable strings in a source
file, run build_tools/update_translations.fish to propagate this to all
translation files (localization/po/*.po). This is only relevant for devel-
opers modifying the source files of fish or fish scripts.
Setting Code Up For Translations
All non-debug messages output for user consumption should be marked for
translation. In Rust, this requires the use of the wgettext! or wget-
text_fmt! macros:
streams.out.append(wgettext_fmt!("%s: There are no jobs\n", argv[0]));
All messages in fish script must be enclosed in single or double quote
characters for our message extraction script to find them. They must also
be translated via a command substitution. This means that the following are
not valid:
echo (_ hello)
_ "goodbye"
Above should be written like this instead:
echo (_ "hello")
echo (_ "goodbye")
You can use either single or double quotes to enclose the message to be
translated. You can also optionally include spaces after the opening paren-
theses or before the closing parentheses.
Updating Dependencies
To update dependencies, run build_tools/update-dependencies.sh. This cur-
rently requires updatecli <https://github.com/updatecli/updatecli> and a
few other tools.
Versioning
The fish version is constructed by the build_tools/git_version_gen.sh
script. For developers the version is the branch name plus the output of
git describe --always --dirty. Normally the main part of the version will
be the closest annotated tag. Which itself is usually the most recent re-
lease number (e.g., 2.6.0).
License
License for fish
fish Copyright A(C) 2005-2009 Axel Liljencrantz, 2009- fish-shell contribu-
tors. fish is released under the GNU General Public License, version 2.
fish includes other code licensed under the GNU General Public License,
version 2, including GNU printf.
Copyright A(C) 1990-2007 Free Software Foundation, Inc. Printf (from GNU
Coreutils 6.9) is released under the GNU General Public License, version 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 li-
cense 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 in-
tended to guarantee your freedom to share and change free software - to
make sure the software is free for all its users. This General Public Li-
cense 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 service
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 restric-
tions translate to certain responsibilities for you if you distribute
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 software. If
the software is modified by someone else and passed on, we want its recipi-
ents 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 indi-
vidually obtain patent licenses, in effect making the program proprietary.
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 modification
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", below, refers to
any such program or work, and a "work based on the Program" means either
the Program or any derivative work under copyright 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 limitation 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 Program is cov-
ered only if its contents constitute a work based on the Program (inde-
pendent 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 conspicuously and
appropriately publish on each copy an appropriate copyright 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 recipi-
ents 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 distribute 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 stating
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 includ-
ing an appropriate copyright notice and a notice that there is no war-
ranty (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. (Exception: 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 identifi-
able sections of that work are not derived from the Program, and can be
reasonably considered independent and separate works in themselves, then
this License, and its terms, do not apply to those sections when you
distribute them as separate works. But when you distribute 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 contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or collec-
tive works based on the Program.
In addition, mere aggregation of another work not based on the Program
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, under
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 following:
* 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 interchange; 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 physi-
cally performing source distribution, a complete machine-readable copy
of the corresponding source code, to be distributed under the terms of
Sections 1 and 2 above on a medium customarily used for software in-
terchange; or,
* Accompany it with the information you received as to the offer to dis-
tribute corresponding source code. (This alternative is allowed only
for noncommercial distribution and only if you received the program in
object code or executable form with such an offer, in accord with Sub-
section b above.)
The source code for a work means the preferred form of the work for mak-
ing modifications to it. For an executable work, complete source code
means all the source code for all modules it contains, plus any associ-
ated interface definition files, plus the scripts used to control compi-
lation and installation of the executable. However, as a special excep-
tion, the source code distributed need not include anything that is nor-
mally distributed (in either source or binary form) with the major com-
ponents (compiler, kernel, and so on) of the operating system on which
the executable runs, unless that component itself accompanies the exe-
cutable.
If distribution of executable or object code is made by offering access
to copy from a designated place, then offering equivalent access to copy
the source code from the same place counts as distribution 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 except
as expressly provided under this License. Any attempt otherwise to copy,
modify, sublicense or distribute the Program is void, and will automati-
cally terminate your rights under this License. However, 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 dis-
tributing the Program (or any work based on the Program), you indicate
your acceptance of this License to do so, and all its terms and condi-
tions 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 Pro-
gram), 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 restrictions on the
recipients' exercise of the rights granted herein. You are not responsi-
ble 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), con-
ditions are imposed on you (whether by court order, agreement or other-
wise) 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 consequence you may not distrib-
ute the Program at all. For example, if a patent license would not per-
mit 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 dis-
tribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other circum-
stances.
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 implemented
by public license practices. Many people have made generous contribu-
tions to the wide range of software distributed through that system in
reliance on consistent application of that system; it is up to the au-
thor/donor to decide if he or she is willing to distribute 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 certain
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 incorporates 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 Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and condi-
tions either of that version or of any later version published 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 programs
whose distribution conditions are different, write to the author to ask
for permission. For software which is copyrighted by the Free Software
Foundation, write to the Free Software Foundation; we sometimes make ex-
ceptions for this. Our decision will be guided by the two goals of pre-
serving 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 WARRANTY
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, EI-
THER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS
WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR RE-
DISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAM-
AGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAM-
AGES 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 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 oth-
erwise using this software ("Python") in source or binary form and its as-
sociated 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 deriva-
tive 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 in-
corporates Python or any part thereof, and wants to make the derivative
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 EX-
AMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE 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 MODI-
FYING, DISTRIBUTING, OR OTHERWISE USING PYTHON, OR ANY DERIVATIVE 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 rela-
tionship of agency, partnership, or joint venture between PSF and Licensee.
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.
MIT License
fish includes a copy of Alpine.js, which is copyright 2019-2021 Caleb
Porzio and contributors, and licensed under the MIT License. It also uses
FindRust.cmake, from the Corrosion project, which is copyright 2018 Andrew
Gaspar 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.
fish contains code derived from musl-libc <https://www.musl-libc.org>,
which is copyright 2006-2020 Rich Felker, et al., to implement printf. This
code is used under the terms of 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 "Software"),
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 Soft-
ware 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 MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIA-
BILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
GNU Library General Public License
fish contains code derived from the GNU C Library, licensed under the GNU
Library General Public License. This code is copyright A(C) 1989-1994 Free
Software Foundation, Inc.
The GNU Library General Public License agreement follows.
GNU LIBRARY GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 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.
[This is the first released version of the library GPL. It is
numbered 2 because it goes with version 2 of the ordinary GPL.]
Preamble
The licenses for most software are designed to take away your freedom to
share and change it. By contrast, the GNU General Public Licenses are in-
tended to guarantee your freedom to share and change free software--to make
sure the software is free for all its users.
This license, the Library General Public License, applies to some specially
designated Free Software Foundation software, and to any other libraries
whose authors decide to use it. You can use it for your libraries, 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 service
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 re-
strictions translate to certain responsibilities for you if you distribute
copies of the library, or if you modify it.
For example, if you distribute copies of the library, whether gratis or for
a fee, you must give the recipients all the rights that we gave you. You
must make sure that they, too, receive or can get the source code. If you
link a program with the library, you must provide complete object files to
the recipients so that they can relink them with the library, after making
changes to the library and recompiling it. And you must show them these
terms so they know their rights.
Our method of protecting your rights has two steps: (1) copyright the li-
brary, and (2) offer you this license which gives you legal permission to
copy, distribute and/or modify the library.
Also, for each distributor's protection, we want to make certain that
everyone understands that there is no warranty for this free library. If
the library is modified by someone else and passed on, we want its recipi-
ents to know that what they have is not the original version, 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 companies distributing free software will in-
dividually obtain patent licenses, thus in effect transforming the program
into proprietary software. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
Most GNU software, including some libraries, is covered by the ordinary GNU
General Public License, which was designed for utility programs. This li-
cense, the GNU Library General Public License, applies to certain desig-
nated libraries. This license is quite different from the ordinary one; be
sure to read it in full, and don't assume that anything in it is the same
as in the ordinary license.
The reason we have a separate public license for some libraries is that
they blur the distinction we usually make between modifying or adding to a
program and simply using it. Linking a program with a library, without
changing the library, is in some sense simply using the library, and is
analogous to running a utility program or application program. However, in
a textual and legal sense, the linked executable is a combined work, a de-
rivative of the original library, and the ordinary General Public License
treats it as such.
Because of this blurred distinction, using the ordinary General Public Li-
cense for libraries did not effectively promote software sharing, because
most developers did not use the libraries. We concluded that weaker condi-
tions might promote sharing better.
However, unrestricted linking of non-free programs would deprive the users
of those programs of all benefit from the free status of the libraries
themselves. This Library General Public License is intended to permit de-
velopers of non-free programs to use free libraries, while preserving your
freedom as a user of such programs to change the free libraries that are
incorporated in them. (We have not seen how to achieve this as regards
changes in header files, but we have achieved it as regards changes in the
actual functions of the Library.) The hope is that this will lead to
faster development of free libraries.
The precise terms and conditions for copying, distribution and modification
follow. Pay close attention to the difference between a "work based on the
library" and a "work that uses the library". The former contains code de-
rived from the library, while the latter only works together with the li-
brary.
Note that it is possible for a library to be covered by the ordinary Gen-
eral Public License rather than by this special one.
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any software library which contains a
notice placed by the copyright holder or other authorized party saying it
may be distributed under the terms of this Library General Public License
(also called "this License"). Each licensee is addressed as "you".
A "library" means a collection of software functions and/or data prepared
so as to be conveniently linked with application programs (which use some
of those functions and data) to form executables.
The "Library", below, refers to any such software library or work which has
been distributed under these terms. A "work based on the Library" means
either the Library or any derivative work under copyright law: that is to
say, a work containing the Library or a portion of it, either verbatim or
with modifications and/or translated straightforwardly into another lan-
guage. (Hereinafter, translation is included without limitation in the
term "modification".)
"Source code" for a work means the preferred form of the work for making
modifications to it. For a library, complete source code means all the
source code for all modules it contains, plus any associated interface def-
inition files, plus the scripts used to control compilation and installa-
tion of the library.
Activities other than copying, distribution and modification are not cov-
ered by this License; they are outside its scope. The act of running a
program using the Library is not restricted, and output from such a program
is covered only if its contents constitute a work based on the Library (in-
dependent of the use of the Library in a tool for writing it). Whether
that is true depends on what the Library does and what the program that
uses the Library does.
1. You may copy and distribute verbatim copies of the Library's complete
source code as you receive it, in any medium, provided that you conspicu-
ously and appropriately publish on each copy an appropriate copyright no-
tice and disclaimer of warranty; keep intact all the notices that refer to
this License and to the absence of any warranty; and distribute a copy of
this License along with the Library.
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 Library or any portion of it,
thus forming a work based on the Library, and copy and distribute such mod-
ifications or work under the terms of Section 1 above, provided that you
also meet all of these conditions:
a. The modified work must itself be a software library.
b) You must cause the files modified to carry prominent notices stating
that you changed the files and the date of any change.
c) You must cause the whole of the work to be licensed at no charge to
all third parties under the terms of this License.
d) If a facility in the modified Library refers to a function or a table
of data to be supplied by an application program that uses the facility,
other than as an argument passed when the facility is invoked, then you
must make a good faith effort to ensure that, in the event an applica-
tion does not supply such function or table, the facility still oper-
ates, and performs whatever part of its purpose remains meaningful.
(For example, a function in a library to compute square roots has a pur-
pose that is entirely well-defined independent of the application.
Therefore, Subsection 2d requires that any application-supplied function
or table used by this function must be optional: if the application does
not supply it, the square root function must still compute square
roots.)
These requirements apply to the modified work as a whole. If identifiable
sections of that work are not derived from the Library, and can be reason-
ably considered independent and separate works in themselves, then this Li-
cense, and its terms, do not apply to those sections when you distribute
them as separate works. But when you distribute the same sections as part
of a whole which is a work based on the Library, the distribution of the
whole must be on the terms of this License, whose permissions for other li-
censees extend to the entire whole, and thus to each and every part regard-
less of who wrote it.
Thus, it is not the intent of this section to claim rights or contest 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 Library.
In addition, mere aggregation of another work not based on the Library with
the Library (or with a work based on the Library) on a volume of a storage
or distribution medium does not bring the other work under the scope of
this License.
3. You may opt to apply the terms of the ordinary GNU General Public Li-
cense instead of this License to a given copy of the Library. To do this,
you must alter all the notices that refer to this License, so that they re-
fer to the ordinary GNU General Public License, version 2, instead of to
this License. (If a newer version than version 2 of the ordinary GNU Gen-
eral Public License has appeared, then you can specify that version instead
if you wish.) Do not make any other change in these notices.
Once this change is made in a given copy, it is irreversible for that copy,
so the ordinary GNU General Public License applies to all subsequent copies
and derivative works made from that copy.
This option is useful when you wish to copy part of the code of the Library
into a program that is not a library.
4. You may copy and distribute the Library (or a portion or derivative of
it, under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you 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 soft-
ware interchange.
If distribution of object code is made by offering access to copy from a
designated place, then offering equivalent access to copy the source code
from the same place satisfies the requirement to distribute the source
code, even though third parties are not compelled to copy the source along
with the object code.
5. A program that contains no derivative of any portion of the Library, but
is designed to work with the Library by being compiled or linked with it,
is called a "work that uses the Library". Such a work, in isolation, is
not a derivative work of the Library, and therefore falls outside the scope
of this License.
However, linking a "work that uses the Library" with the Library creates an
executable that is a derivative of the Library (because it contains por-
tions of the Library), rather than a "work that uses the library". The ex-
ecutable is therefore covered by this License. Section 6 states terms for
distribution of such executables.
When a "work that uses the Library" uses material from a header file that
is part of the Library, the object code for the work may be a derivative
work of the Library even though the source code is not. Whether this is
true is especially significant if the work can be linked without the Li-
brary, or if the work is itself a library. The threshold for this to be
true is not precisely defined by law.
If such an object file uses only numerical parameters, data structure lay-
outs and accessors, and small macros and small inline functions (ten lines
or less in length), then the use of the object file is unrestricted, re-
gardless of whether it is legally a derivative work. (Executables contain-
ing this object code plus portions of the Library will still fall under
Section 6.)
Otherwise, if the work is a derivative of the Library, you may distribute
the object code for the work under the terms of Section 6. Any executables
containing that work also fall under Section 6, whether or not they are
linked directly with the Library itself.
6. As an exception to the Sections above, you may also compile or link a
"work that uses the Library" with the Library to produce a work containing
portions of the Library, and distribute that work under terms of your
choice, provided that the terms permit modification of the work for the
customer's own use and reverse engineering for debugging such modifica-
tions.
You must give prominent notice with each copy of the work that the Library
is used in it and that the Library and its use are covered by this License.
You must supply a copy of this License. If the work during execution dis-
plays copyright notices, you must include the copyright notice for the Li-
brary among them, as well as a reference directing the user to the copy of
this License. Also, you must do one of these things:
a) Accompany the work with the complete corresponding machine-readable
source code for the Library including whatever changes were used in the
work (which must be distributed under Sections 1 and 2 above); and, if
the work is an executable linked with the Library, with the complete ma-
chine-readable "work that uses the Library", as object code and/or
source code, so that the user can modify the Library and then relink to
produce a modified executable containing the modified Library. (It is
understood that the user who changes the contents of definitions files
in the Library will not necessarily be able to recompile the application
to use the modified definitions.)
b) Accompany the work with a written offer, valid for at least three
years, to give the same user the materials specified in Subsection 6a,
above, for a charge no more than the cost of performing this distribu-
tion.
c) If distribution of the work is made by offering access to copy from a
designated place, offer equivalent access to copy the above specified
materials from the same place.
d) Verify that the user has already received a copy of these materials
or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the Library"
must include any data and utility programs needed for reproducing the exe-
cutable from it. However, as a special exception, the source code distrib-
uted need not include anything that is normally distributed (in either
source or binary form) with the major components (compiler, kernel, and so
on) of the operating system on which the executable runs, unless that com-
ponent itself accompanies the executable.
It may happen that this requirement contradicts the license restrictions of
other proprietary libraries that do not normally accompany the operating
system. Such a contradiction means you cannot use both them and the Li-
brary together in an executable that you distribute.
7. You may place library facilities that are a work based on the Library
side-by-side in a single library together with other library facilities not
covered by this License, and distribute such a combined library, provided
that the separate distribution of the work based on the Library and of the
other library facilities is otherwise permitted, and provided that you do
these two things:
a) Accompany the combined library with a copy of the same work based on
the Library, uncombined with any other library facilities. This must be
distributed under the terms of the Sections above.
b) Give prominent notice with the combined library of the fact that part
of it is a work based on the Library, and explaining where to find the
accompanying uncombined form of the same work.
8. You may not copy, modify, sublicense, link with, or distribute the Li-
brary except as expressly provided under this License. Any attempt other-
wise to copy, modify, sublicense, link with, or distribute the Library is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such parties re-
main in full compliance.
9. 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 Library or its derivative works. These actions are prohibited by law
if you do not accept this License. Therefore, by modifying or distributing
the Library (or any work based on the Library), you indicate your accep-
tance of this License to do so, and all its terms and conditions for copy-
ing, distributing or modifying the Library or works based on it.
10. Each time you redistribute the Library (or any work based on the Li-
brary), the recipient automatically receives a license from the original
licensor to copy, distribute, link with or modify the Library subject to
these terms and conditions. You may not impose any further restrictions on
the recipients' exercise of the rights granted herein. You are not respon-
sible for enforcing compliance by third parties to this License.
11. If, as a consequence of a court judgment or allegation of patent in-
fringement or for any other reason (not limited to patent issues), condi-
tions 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 consequence you may not distribute the Library at
all. For example, if a patent license would not permit royalty-free redis-
tribution of the Library by all those who receive copies directly or indi-
rectly through you, then the only way you could satisfy both it and this
License would be to refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended 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 integrity of the free
software distribution system which is implemented by public license prac-
tices. Many people have made generous contributions to the wide range of
software distributed through that system in reliance on consistent applica-
tion of that system; it is up to the author/donor to decide if he or she is
willing to distribute software through any other system and a licensee can-
not impose that choice.
This section is intended to make thoroughly clear what is believed to be a
consequence of the rest of this License.
12. If the distribution and/or use of the Library is restricted in certain
countries either by patents or by copyrighted interfaces, the original
copyright holder who places the Library under this License may add an ex-
plicit geographical distribution limitation excluding those countries, so
that distribution is permitted only in or among countries not thus ex-
cluded. In such case, this License incorporates the limitation as if writ-
ten in the body of this License.
13. The Free Software Foundation may publish revised and/or new versions of
the Library 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 Library
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 published by the Free Soft-
ware Foundation. If the Library does not specify a license version number,
you may choose any version ever published by the Free Software Foundation.
14. If you wish to incorporate parts of the Library into other free pro-
grams whose distribution conditions are incompatible with these, write to
the author to ask for permission. For software which is copyrighted by the
Free Software Foundation, write to the Free Software Foundation; we some-
times 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
15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PRO-
VIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MER-
CHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY
PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDIS-
TRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, IN-
CLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE LIBRARY (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 LIBRARY TO OPERATE WITH ANY OTHER
SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POS-
SIBILITY OF SUCH DAMAGES.
AUTHOR
fish-shell developers
COPYRIGHT
fish-shell developers
4.6 Aug 01, 2026 FISH-DOC(1)
WHERE TO GO? | SETUP | CONFIGURATION | RESOURCES | OTHER HELP PAGES | AUTHOR | COPYRIGHT
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+15.1.quarterly>