FISH-DOC(1)

📦

version 4.9.3 · 19 versions

okay bestie, welcome to FISH-DOC(1), aka the official documentation for fish-shell 💖 — yes, that fish. This is literally the whole doc page, so grab a snack 🍓.

A shell is a program that helps you operate your computer by starting other programs. fish offers a command-line interface focused on usability and interactive use. That's the whole elevator pitch, and it ate 💅

Some of the special features of fish are:

Extensive UI: Syntax highlighting (#syntax-highlighting), Autosuggestions (#autosuggestions), tab completion (#tab-completion) and selection lists that can be navigated and filtered. the way this just works 😭
No configuration needed: fish is designed to be ready to use immediately, without requiring extensive configuration. zero setup era ✨
Easy scripting: New functions (#syntax-function) can be added on the fly. The syntax is easy to learn and use.

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

🌸 WHERE TO GO? 🌸

If this is your first time using fish, see the tutorial (<>). please go, it's giving beginner-friendly 👑

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 interactive 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. no cap, keep scrolling 🫶

🎀 SETUP 🎀

This section describes how to install, uninstall, start, and exit fish. It also explains how to make fish the default shell. it's the whole lifecycle bestie 💀

🦋 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

that's it. that's the whole ritual ✨

🦋 Default Shell 🦋

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

The simplest method is to set your terminal emulator (e.g. GNOME Terminal, Apple's Terminal.app, or Konsole) to start fish directly. See its configuration 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 (#envvar-PATH). Some operating systems, including a number of Linux distributions, require the login shell to be Bourne-compatible and to read configuration from /etc/profile. fish may not be suitable as a login shell on these systems. like, genuinely be careful here bestie 😭

To change your login shell to fish:

Add the shell to /etc/shells with:

> command -v fish | sudo tee -a /etc/shells

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. reversible queen 💅

🦋 Uninstalling 🦋

For uninstalling fish: see FAQ: Uninstalling fish (#faq-uninstalling). sad day but ok 🥲

🦋 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 interpreter /bin/bash.

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

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 (#envvar-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 (#envvar-PATH). iconic portable behaviour 👑

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/config.fish.

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

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

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

If you want to see what you changed over fish's defaults, see fish_delta (<>). very "what did I even do" energy 🔍

🧚 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. lowercase lazier, lowercase better 😌

To run commands on exit, use an event handler (#event) 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. bestie go submit that PR, the maintainers will love you for it 🫶

🔥 OTHER HELP PAGES 🔥

🌈 Frequently asked questions 🌈

💀 What is the equivalent to this thing from bash (or other shells)?

See fish for bash users (<>). your muscle memory is safe here, promise 🎀

💀 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 below behave identically - unlike other shells, fish will output value both times:

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

Note that "exported" is not a scope (#variables-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. like, it's a bit, not a level, get it? 💅

💀 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. sneaky empty era 🙈

💀 How do I check whether a variable is not empty?

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

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

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

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

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

💀 Why doesn't `set -Ux` (exported universal variables) seem to work?

A global variable of the same name already exists.

Environment variables such as EDITOR or TZ can be set universally using set -Ux. However, if there is an environment variable already set before fish starts (such as by login scripts or system administrators), it is imported into fish as a global variable. The variable scopes (#variables-scope) 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. the way it just overrides your whole vibe 😭

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

set -gx EDITOR vim

💀 How do I run a command every login? What's fish's equivalent to `.bashrc` or `.profile`?

Edit the file ~/.config/fish/config.fish [1], creating it if it does not exist (Note the leading period).

Unlike .bashrc and .profile, this file is always read, even in non-interactive 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. the more you know 🌈

💀 How do I set my prompt?

The prompt is the output of the fish_prompt function. Put it in ~/.config/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

main character prompt energy, honestly 👑💅

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

>_ 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, bestie. Same energy, different function. 💅

Why does my prompt show a [I]?

Okay so that's the fish_mode_prompt ✨ It's displayed by default when you've activated 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. (Not me. Never me. 🙈)

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

How do I customize my syntax highlighting colors?

Three iconic routes, pick your fave:

Use the web configuration tool started by fish_config 🎀
Alter the fish_color family of environment variables (see the variables-color section) 🌈
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. Bye bye greeting, you will NOT be missed 💖

How do I run a command from history?

Type some part of the command, and then hit the up (↑) or down (↓) arrow keys to navigate through history matches, or press Ctrl+R to open the history in a searchable pager. In this pager you can press Ctrl+R or Ctrl+S to move to older or younger history respectively. Obsessed, honestly.

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

Why doesn't history substitution ("!$" etc.) work?

Because history substitution is an awkward interface that was invented before interactive line editing was even possible 😭 Instead of adding this pseudo-syntax, fish opts for nice history searching and recall features. Switching requires a small change of habits: if you want to modify an old line/word, first recall it, then edit. That's it. That's the whole vibe.

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-arrow.
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 the documentation for more details about line editing in fish.

That being said, you can use Abbreviations to implement history substitution. 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 (''). Truly giving "why are you like this" energy 💀

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" separately. Math is mathing ✨

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. Iconic behaviour, no notes 👑

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 section and the documentation for test and if for more information 💜

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

That means that commands like the above

scp user@ip:/dir/string-*

apt install postgres-*

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

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

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

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

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

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

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. Not cute. Not the vibe. 😭

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

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

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

if status is-interactive
  ...
end

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

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

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

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

It is possible the character is 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 rendering.
Different widths for multiple ambiguous width characters — there is no way for fish to know which width you assign to each character.

RIP to those, they tried 💀

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. Snitching is encouraged here, we're all improving 🌸

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

Careful with that rm -Rf bestie, those are real files and this command does not ask twice. Double check the paths before you hit enter 💅

✨ 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. Buckle up, this is the fun part 🔥

fish is used by giving commands in the fish language — peep The fish Language for the whole rundown on that, bestie. 👑

Help

fish literally has an extensive help system, and it's giving study buddy. Use the help command whenever you need the tea on a specific subject or command. Like, writing help syntax shows you the syntax section of this very documentation. Slay.

fish also has man pages for its commands, and it translates the help pages into man pages. So for example man set will show you the docs for set as a man page. Iconic.

You can also grab help on a specific builtin with the -h parameter. For instance, to get help on the fg builtin, either type fg -h or help fg. Same energy, both work. ✨

The main page can be viewed via help index (or just help) or man fish-doc. And the tutorial? That's help tutorial or man fish-tutorial. Go off. 🎀

Autosuggestions

okay so this is the feature that makes people obsessed with fish. 🦋 fish suggests commands as you type, based on command history, completions, and valid file paths. As you type, you'll see a suggestion offered after the cursor, in a muted gray color — and yes, you can change that color with the fish_color_autosuggestion variable.

To accept the autosuggestion (replacing the command line contents), press right (→) or Ctrl+f. To accept just the first suggested word, press alt+right (→) or alt+f. And if the autosuggestion isn't what you want? Just ignore it, bestie — it won't execute unless you accept it. No cap.

Autosuggestions are a powerful way to quickly summon frequently entered commands, just by typing the first few characters. They're also an efficient technique for navigating through directory hierarchies. Literally so handy. 💅

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 — and fish ate with this one. 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 (that's the pager-toggle-search binding — / in vi mode) opens up a search menu that you can use to filter the list. Chef's kiss. 🔥

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 completions.
mount uses mount points specified in fstab as completions.
apt, rpm and yum show installed or installable packages

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

Completion scripts are loaded on demand, like functions are (see autoloading). The difference is the $fish_complete_path list is used instead of $fish_function_path. Typically you can drop new completions in ~/.config/fish/completions/<name-of-command>.fish and fish will find them automatically. Main character behavior, honestly. ⭐

Syntax highlighting

fish interprets the command line as it is typed and uses syntax highlighting 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 changing 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 accepted. 💜

Example: to make errors highlighted and red, use:

set fish_color_error red --bold

Okay so these are all the variables that change up the highlighting colors in fish — the whole palette, bestie ✨:

fish_color_normal — the default color 💅
fish_color_command — commands like echo
fish_color_builtin — builtin commands like cd and set — this one falls back on the command color if it's unset
fish_color_function — user-defined functions — also falls back on the command color if unset
fish_color_keyword — keywords like if — falls back on the command color if unset too
fish_color_quote — quoted text like "abc"
fish_color_redirection — IO redirections like >/dev/null
fish_color_end — process separators like ; and &
fish_color_error — syntax errors 💀
fish_color_param — ordinary command parameters
fish_color_valid_path — parameters and redirection targets that are filenames (if the file exists) 🦋
fish_color_option — options starting with -, up to the first -- parameter
fish_color_comment — comments like '# important'
fish_color_selection — selected text in vi visual mode
fish_color_operator — parameter expansion operators like * and ~
fish_color_escape — character escapes like \n and \x70
fish_color_autosuggestion — autosuggestions (the proposed rest of a command) ✨
fish_color_cwd — the current working directory in the default prompt
fish_color_cwd_root — the current working directory in the default prompt for the root user 👑
fish_color_user — the username in the default prompt
fish_color_host — the hostname in the default prompt
fish_color_host_remote — the hostname in the default prompt for remote sessions (like ssh)
fish_color_status — the last command's nonzero exit code in the default prompt 😭
fish_color_cancel — the '^C' indicator on a canceled command
fish_color_search_match — history search matches and selected pager items (background only)
fish_color_history_current — the current position in the history for commands like dirh and cdh

So if a variable isn't set, or it's empty after subtracting any --theme=THEME options, fish usually tries $fish_color_normal — with a few little exceptions, and they're giving main character energy:

$fish_color_builtin and $fish_color_function, where they try $fish_color_command first.
$fish_color_keyword, where it tries $fish_color_command first.
$fish_color_option, where it tries $fish_color_param first.

Lowkey obsessed with how the fallbacks cascade, ngl 🫶

For $fish_color_valid_path — if it's got no color of its own and only modifiers, those modifiers get added onto whatever color would've been used anyway (like $fish_color_param). But if valid paths do have a color, it uses that one and then adds in the modifiers from the other color. Slay.

Okay so here's the thing — fish sometimes pops a lil list of choices up in a table, and that table is called the pager 💅

Example: you wanna set the background of each pager row, so you go:

set fish_pager_color_background --background=white

And if you want 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

Here are all the variables that affect the pager colors 👑:

fish_pager_color_progress — the progress bar at the bottom left corner
fish_pager_color_background — the background color of a line
fish_pager_color_prefix — the prefix string, i.e. the string that is to be completed
fish_pager_color_completion — the completion itself, i.e. the proposed rest of the string
fish_pager_color_description — the completion description
fish_pager_color_selected_background — background of the selected completion
fish_pager_color_selected_prefix — prefix of the selected completion
fish_pager_color_selected_completion — suffix of the selected completion
fish_pager_color_selected_description — description of the selected completion
fish_pager_color_secondary_background — background of every second unselected completion
fish_pager_color_secondary_prefix — prefix of every second unselected completion
fish_pager_color_secondary_completion — suffix of every second unselected completion
fish_pager_color_secondary_description — description of every second unselected completion

And when the secondary or selected variables aren't set, or they're empty? The normal variables get used instead 💖 — with one exception: for $fish_pager_color_selected_background, 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. Iconic behaviour honestly.

abbr -a gco git checkout

So after you type gco and hit space or enter, a gco in command position turns into git checkout right there in the command line ✨ And if you actually want a literal gco sometimes, use Ctrl+Space [1].

Abbreviations are lowkey 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 .... expands to cd ../../../. Not me being obsessed with regex abbreviations 😭🔥

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. Bestie, that's the whole point.

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

🪞 Programmable prompt

When it's fish's turn to ask for input (like after it started or the command ended), it'll 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. And for vi mode, the output of fish_mode_prompt gets 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, letting you change it before pushing it to the scrollback. Kinda genius ngl.

fish ships with a few prompts which you can see with fish_config. If you run just fish_config it'll open a web interface [2] where you'll be shown the prompts and can pick which one you want. fish_config prompt show shows 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. Periodt.

You can also change these functions yourself by running funced fish_prompt and funcsave fish_prompt once you're happy with the result (or fish_right_prompt if you want to change that one instead 👀).

[2] The web interface runs purely locally on your computer and requires python to be installed.

👋 Configurable greeting

When it's started interactively, fish tries to run the fish_greeting function. 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. Slay.

🏷️ Programmable title

Most terminals allow setting the text displayed in the titlebar of the terminal window. fish does this by running the fish_title function. It's 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 contain 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's 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

okay so the fish editor is lowkey stacked — copy and paste? yes. searchable history? yes. and a whole pile of editor functions you can bind to whatever special keyboard shortcuts your heart desires. ✨

Like bash and basically every other shell out there, fish ships two sets of keyboard shortcuts (aka key bindings): one inspired by the Emacs text editor, and one by the vi text editor. The default editing mode is Emacs. You can hop over to vi mode by running fish_vi_key_bindings and switch back with fish_default_key_bindings. And if you're feeling creative, you can make your own key bindings too — just create a function and set the fish_key_bindings variable to its name. Like this, bestie:

          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

ngl though — the key bindings that come with fish cover a lot of the shortcuts people love from the respective text editors, but they are not a complete implementation. That's why there's a shortcut to open your current command line in your preferred editor (alt-e by default) for when you seriously need the full power of your editor. 💅

🌸 Shared bindings

Some bindings are shared between Emacs and vi mode, because they're not really text-editing bindings, or because what vi/Vim does with a particular key just doesn't make sense for a shell. Common sense stuff. 🧚

tab — completes the current token. shift-tab completes the current token and starts the pager's search mode. fun fact: tab is the same as ctrl-i.
left (←) and right (→) — move the cursor left or right by one character. If the cursor is already at the end of the line and an autosuggestion is available, right (→) accepts that autosuggestion. 🫶
enter — executes the current commandline, or inserts a newline if it's not complete yet (like when a ) or end is missing).
alt-enter — inserts a newline at the cursor position. Super useful for adding a line to a commandline that's already complete.
alt-left (←) and alt-right (→) — move the cursor left or right by one word. If the command line is empty, they move forward/backward in the directory history instead. And if the cursor is already at the end of the line and an autosuggestion is available, alt-right (→) (or alt-f) accepts the first word in the suggestion.
ctrl-left (←) and ctrl-right (→) — move the cursor left or right by one token. These also accept one token of the autosuggestion — the part they'd move over. iconique.
shift-left (←) and shift-right (→) — move the cursor one word left or right, without stopping on punctuation. These accept one big word of the autosuggestion.
up (↑) and down (↓) (or ctrl-p and ctrl-n for the emacs aficionados 💀) — search the command history for the previous/next command containing the string that was specified on the commandline before the search started. If the commandline was empty when the search started, all commands match. See the history section for more on history searching.
alt-up (↑) and alt-down (↓) — search the command history for the previous/next token containing the token under the cursor before the search started. If the commandline wasn't on a token when the search started, all tokens match. Again, history section for the deets.
ctrl-c — interrupts/kills whatever is running (SIGINT). the classic. 😭
ctrl-d — deletes one character to the right of the cursor. If the command line is empty, ctrl-d will exit fish. bye bestie 👋
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. clean slate vibes ✨
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 inserts the clipboard contents. (see fish_clipboard_copy and fish_clipboard_paste)
alt-d — moves the next word to the Copy and paste (Kill Ring).
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 exists.
alt-l — lists the contents of the current directory, unless the cursor is over a directory argument, in which case the contents of that directory get listed.
alt-o — opens the file at the cursor in a pager. If the cursor is in command position and the command is a script, it opens that script in your editor instead. 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. Result? The output of the command gets 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, prepends 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. (That's also the default, so like… it's already on. slay.)

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 accepts the autosuggestion.
ctrl-b, ctrl-f — move the cursor one character left or right, or accept the autosuggestion, just like the left (←) and right (→) shared bindings (which are available as well).
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, they move forward/backward 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.
alt-backspace — removes one word backwards, and ctrl-backspace removes one argument backwards.
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 unambiguous 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. go wild.

🦋 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's also possible to add all Emacs mode bindings to vi mode by using something like this:

          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 you're in vi mode, the fish_mode_prompt function will display a mode indicator to the left of the prompt. Want it gone? Override it with an empty function. Want the mode displayed somewhere else (like in your right prompt)? Use the output of the fish_default_mode_prompt function. 🎀

Here's the tea on repainting: when a binding switches the mode, it will repaint the mode-prompt if it exists, and the rest of the prompt only if it doesn't. So if you want a mode-indicator in your fish_prompt, you need to erase fish_mode_prompt — e.g. by adding an empty file at ~/.config/fish/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 depending on the mode in supported terminals. This 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. no cap.

If your cursor shape still isn't giving after you set those variables, it's probably not you — it's likely your terminal emulator doesn't support the capabilities necessary to do this. 💅

🎮 Command mode 🎮

Command mode is also known as normal mode. Bestie, it's giving vim energy, and we love that for us.

h — moves the cursor left.
l — moves the cursor right.
k and j — 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. In multi-line commands, they move the cursor up and down respectively.
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, respectively.
~ — 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 (←) and right (→) — extend the selection backward/forward by one character.
h — moves the cursor left.
l — moves the cursor right.
k — moves the cursor up.
j — moves the cursor down.
b and w — extend the selection backward/forward by one word.
d and x — move the selection to the Copy and paste (Kill Ring) and 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 yourself. Iconic, honestly. ✨

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 indistinguishable 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 terminal 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 certain time after seeing an escape character. This is configurable via the fish_escape_delay_ms variable.

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

set -g fish_escape_delay_ms 100

Similarly, to disambiguate other keypresses where you've bound a subsequence 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 previous 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 "Bracketed Paste Mode", so it can tell a paste from manually entered text. In addition, when pasting inside single quotes, pasted single quotes and backslashes are automatically escaped so that the result can be used as a single 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 cursor movement commands that extend the current selection. The variable fish_cursor_selection_mode can be used to configure if that selection should include the character under the cursor (inclusive) or not (exclusive). The default is exclusive, which works well with any cursor shape. For vi mode, and particularly for the block or underscore cursor shapes you may prefer inclusive. 🌈

Footnote [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 several lines long. There are three ways to make a command span more than a single line:

Pressing the enter key while a block of commands is unclosed, such as when one or more block commands such as for, begin or if do not have a corresponding end command.
Pressing alt-enter instead of pressing the enter key.
By inserting a backslash (\) character before pressing the enter key, escaping the newline.

The fish commandline editor works exactly the same in single line mode and in multiline mode. To move between lines use the left and right 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 (↑) and alt-down (↓), a history search is also performed, but instead of searching for a complete commandline, each commandline 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 (↑) 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 function.

Private mode 🕵️‍♀️

fish has a private mode, in which command history will not be written to the history file on disk. To turn it on, either set $fish_private_mode to a non-empty value, or launch with fish --private (or fish -P if you're feeling abbreviate-y).

If you launch fish with -P, it does double duty — it both hides old history and prevents writing history to disk. This is literally so useful for avoiding leaking personal info (think screencasts 👀) or when you're dealing with sensitive stuff.

You can query the variable fish_private_mode (like if test -n "$fish_private_mode" ...) if you'd like to respect the user's wish for privacy and alter the behavior of your own fish scripts. very considerate of you ngl 💅

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 for you, bestie.

Directory history 📜

fish automatically keeps a trail of the recently visited directories with cd, by storing this history in the dirprev and dirnext variables. iconic behavior honestly.

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 (←)
nextd — moves forward through the history. It is bound to alt+right (→)

Directory stack 🥞

Another set of commands — usually also available in other shells like bash — deal with the directory stack. Heads up: stack handling is not automatic, you need explicit calls of the following commands:

dirs — prints the stack
pushd — adds a directory on top of the stack and makes it the current working directory
popd — removes the directory on top of the stack and changes the current working directory

✨ The fish language ✨

This document is a comprehensive overview of fish's scripting language. like, the whole thing. buckle up 🎀

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

The 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. no cap.

Every program on your computer can be used as a command in fish. If the program file is located in one of the PATH directories, you can just type the name of the program to use it. Otherwise the whole filename, including the directory (like /home/me/code/checkers/checkers or ../checkers) is required.

Here is a list of some useful commands:

cd — Change the current directory
ls — List files and directories
man — Display a manual page — try man ls to get help on your "ls" 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 filetype
less — Display the contents of files

Commands and arguments are separated by the space character ' '. Every command ends with either a newline (by pressing the return key) or a semicolon ;. Multiple commands can be written on the same line by 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 directories in the current working directory. By using the -l switch, the behavior of ls is changed to not only display the filename, but also the size, permissions, owner, and modification time of each file. glow-up fr fr ✨

Switches differ between commands and are usually documented on a command's manual page. There are some switches, however, that are common to most commands. For example, --help will usually display a help text, --version will usually display the command version, and -i will often turn on interactive prompting before taking action. Try man your-command-here to get information on your command's switches.

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

Terminology 📖

Here we define some of the terms used on this page and throughout the rest of the fish documentation — group-chat glossary time:

Argument: A parameter given to a command. In echo foo, the "foo" is an argument.
Builtin: A command that is implemented by the shell. Builtins are so closely tied to the operation of the shell that it is impossible to implement them as external commands. In echo foo, the "echo" is a builtin.
Command: A program that the shell can run, or more specifically an external program that the shell runs in another process. External commands are provided on your system, as executable files. In echo foo the "echo" is a builtin command, in command echo foo the "echo" is an external command, provided by a file like /bin/echo.
Function: A block of commands that can be called as if they were a single command. By using functions, it is possible to string together multiple simple commands into one more advanced command.
Job: A running pipeline or command.
Pipeline: A set of commands strung together so that the output of one command is the input of the next command. echo foo | grep foo is a pipeline.
Redirection: An operation that changes one of the input or output streams associated with a job.
Switch or Option: A special kind of argument that alters the behavior of a command. A switch almost always begins with one or two hyphens. In echo -n foo the "-n" is an option.

Quotes 🎀

Sometimes you want to give a command an argument that contains 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. very "one file not two" of you 💅

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 parameter expansion) is performed, and escape sequences (for example, \n) are ignored. Within quotes, whitespace is not used to separate arguments, allowing 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 meaningful escapes in double quotes are \", which escapes a double quote, \$, which escapes a dollar character, \ followed by a newline, which deletes the backslash and the newline, and \\, which escapes the backslash symbol.

Single quotes have no special meaning within double quotes and vice versa. they mind their own business 🧚

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". the way quoting just saves you like that 😭

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 anything up to \X7f is an ASCII character.
\ooo, where ooo is an octal number, represents the ASCII character with the specified value. For example, \011 is the tab character. The highest allowed value is \177.
\uXXXX, where XXXX is a hexadecimal number, represents the 16-bit Unicode character with the specified value. For example, \u9 is the tab character.
\UXXXXXXXX, where XXXXXXXX is a hexadecimal number, represents the 32-bit Unicode character with the specified value. For example, \U9 is the tab character. The highest allowed value is U10FFFF.
\cX, where X is a letter of the alphabet, represents the control sequence generated by pressing the control key and the specified letter. For example, \ci is the tab character. See C0 controls codes on Wikipedia.

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

echo \'hello world\'

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

echo 'hello world'

…outputs hello world (without the apostrophes). In the former case the shell treats the apostrophes as literal ' characters, while in the latter case it treats them as special expansion modifiers. subtle but like, huge 💀

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.

And okay, special case alert 🚨 — a \ that's immediately followed by a literal new line is what we call a "continuation", and what it does is tell fish "bestie ignore that line break, keep going" — input resumes at the start of the next line, and it does not sneak any whitespace in there and it does not terminate a token. Literally just vibes, continuing. ✨

🔀 Input/Output Redirection

Okay so most programs use three input/output (I/O) streams, and you've gotta know them, they're like the main characters:

Standard input (stdin) for reading. Defaults to reading from the keyboard. ⌨️
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 too. 😭

Each stream has a number called the file descriptor (FD): 0 for stdin, 1 for stdout, and 2 for stderr. Those numbers matter, remember them. 🎀

The destination of a stream can be changed using something called redirection. For example, echo hello > output.txt redirects the standard output of the echo command to a text file. Slay, no more screen spam.

So here's the whole menu, and yes you need all of it:

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 these cuties:

A filename to write the output to. Often it's >/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 gets written to that destination descriptor.
An ampersand followed by a minus sign (&-). This closes the file descriptor. Note: this may cause the program to fail because its writes will be unsuccessful. 💀 Like, it'll try to write and there's just nothing there. Respect the warning.

As a convenience (they love us fr fr), 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 equivalent to echo hello > all_output.txt 2>&1. And 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.

Heads up bestie: file descriptors cannot be used with a <? input redirection — only a regular < one. Don't try it, it's not a thing. 🙈

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 descriptor above 2. However, this is supported for external commands. So like, know the difference, it's giving "rules have lore". 📜

[1] Previous versions of fish also allowed specifying this as ^DESTINATION, but that made another character special so it was deprecated and removed. See feature flags. 🪦 RIP to a real one.

🔗 Piping

Another way to redirect streams is a pipe. A pipe connects streams with each other. Usually the standard output of one command gets connected with the standard input of another. You do this by separating commands with the pipe character |. Iconic behaviour honestly.

cat foo.txt | head

The command cat foo.txt sends the contents of foo.txt to stdout. That output is provided as input for the head program, which prints the first 10 lines of its input. Chain them together like a friendship bracelet. 🫶

It's 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] Pretty neat right?

As a convenience, the pipe &| (as well as the |& alias which is also supported by Bash) both redirect stdout and stderr to the same process. Two streams, one destination. 💅

[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!). Yes, back. We love a program that lets you scroll backwards.

🧩 Combining pipes and redirections

You can absolutely use multiple redirections and a pipe at the same time. When you do, they're read in this order:

First the pipe is set up.
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. Timing matters, bestie. ⏰

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

See how the order changes everything? That's the whole vibe check right there. 🔥

🎛️ 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 keep using the commandline and have the job run in the background instead. To create a background job, append an & (ampersand) to your command. That tells 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 control to fish by pressing Ctrl+Z (also referred to as ^Z). Once you're 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. It's like tabbing back into a chat.

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.

Real talk: 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. That's just how it is, don't fight it. 😭

And a cute little detail: if the & character is followed by a non-separating character, it is not interpreted as background operator. Separating characters are whitespace and the characters ;<>&|. Character-level precision, we love to see it. 🎀

🧚 Functions

Functions are programs written in the fish syntax. They group together various commands and their arguments using a single name. Basically a little bundle of commands with a name tag on it. ✨

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. Obsessed with how clean that is. 💜

This is a kind of function known as an alias.

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

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

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

To edit a function, you can use funced <>, and to save a function funcsave <>. This will store it in a function file that fish will autoload when needed. Autoload is such a main character behaviour honestly. 👑

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 systems is --color=auto. An alias around ls might look like this:

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

There are a few important things that need to be noted about aliases, and you gotta listen to these:

Always take care to add the $argv variable to the list of parameters to the wrapped command. This makes sure that if the user specifies any additional parameters to the function, they are passed on to the underlying command. Don't leave $argv out, it's rude to the arguments. 🥺
If the alias has the same name as the aliased command, you need to prefix the call to the program with command to tell fish that the function should not call itself, but rather a command with the same name. If you forget to do so, the function would call itself until the end of time. 💀 Usually fish is smart enough to figure this out and will refrain from doing so (which is hopefully in your interest).

Like, genuinely, the infinite-loop situation is not the cute kind of infinity. Add the command. Periodt. 💅

...and that's lowkey the whole vibe of it. If you want the easiest way to make a function like this, just use the alias command. And here's the thing that makes fish different from other shells: alias just makes functions — fish has no separate concept of an "alias", we literally just use that word for a simple wrapping function like this. alias immediately creates a function, no cap. But bestie, consider using alias --save or funcsave to save the created function into an autoload file instead of recreating the alias each and every time, because re-typing is not the main character energy we're going for. 💅

Want an alternative? Try abbreviations (see the abbreviations section). These are words that get expanded while you type, instead of being actual functions living inside the shell. Different vibe, same slay. ✨

Autoloading functions 🦋

So functions can be defined on the commandline or in a configuration file, but they can also be automatically loaded. The perks are genuinely iconic:

An autoloaded function becomes available automatically to all running shells.
If the function definition is changed, all running shells will automatically reload the altered version, after a while. Self-updating queen. 👑
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 one it finds.

So 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 ~/.config/fish/functions (controlled by the XDG_CONFIG_HOME environment variable).
A directory for functions for all users on the system, usually /etc/fish/functions (really $__fish_sysconfdir/functions).
Directories for other software to put their own functions. These are in the directories under $__fish_user_data_dir (usually ~/.local/share/fish, controlled by the XDG_DATA_HOME environment variable) and in the XDG_DATA_DIRS environment variable, in a subdirectory called fish/vendor_functions.d. The default value for XDG_DATA_DIRS is usually /usr/share/fish/vendor_functions.d and /usr/local/share/fish/vendor_functions.d.

If you are unsure, your functions probably belong in ~/.config/fish/functions. That's the home base, fr fr. 🏠

As we've explained, autoload files are loaded by name, so, while you can put multiple functions into one file, the file will only be loaded automatically once you try to execute the one that shares the name. Sneaky? A little. Intentional? Absolutely.

Autoloading also won't work for event handlers, since fish cannot know that a function is supposed to be executed when an event occurs when it hasn't yet loaded the function. See the event handlers section for more information. 😭

If a file of the right name doesn't define the function, fish will not read other autoload files — instead it will go on to try builtins and finally commands. This is actually a feature, bestie: it allows masking a function defined later in $fish_function_path, e.g. if your administrator has put something into /etc/fish/functions that you want to skip. Blocked. 🙈

If you are developing another program and want to install fish functions for it, install them to the "vendor" functions directory. As this path varies from system to system, you can use pkgconfig to discover it with the output of pkg-config --variable functionsdir fish. Your installation system should support a custom path to override the pkgconfig path, as other distributors may need to alter it easily. Teamwork makes the dream work. 🫶

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 entirely. It's giving "note to self."

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

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

There are no multiline comments. If you want to make a comment span multiple lines, start each line with a #. That's it, that's the trick. ✨

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 and or, and also the familiar &&/|| syntax. Pick your fighter, they're all valid.

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. Cute, efficient, no notes. 💅

Unlike other shells, the condition command ends after the first job — there is no then here. Combiners like and and or extend the condition. (Yes, that's foreshadowing. Keep reading. 👀)

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. We do not stan unquoted substitutions. 😭

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 commands depending on the value of a string. It can take multiple case blocks that are executed when the string matches. They can take wildcards. For example:

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

Unlike other shells or programming languages, there is no fallthrough — the first matching case block is executed and then control jumps out of the switch. One and done, periodt. 💅

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

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

Note that combiners are lazy — only the part that is necessary to determine the final status is run. Efficiency queen.

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. Yeah. Two whole seconds. Gone. ⏳

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! Rude of it, honestly.

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. Sneaky little status gremlin. 💀

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 languages, 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. Both absolute icons. 👑

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

...and that's just the start of it, bestie — there's more coming. 🦋

Command substitution, to steal the output of another command and use it as your own — $(cat /path/to/file)
Brace expansion, to write lists with shared pre- or suffixes in a much shorter way — {/usr,}/bin
Tilde expansion, to turn that little ~ at the start of a path into the path to your home directory — ~/bin

So parameter expansion taps out at 524288 items. Why? Because the OS has a cap on how many arguments any command can take, and 524288 is way above it — this is just a guard so the shell doesn't hang doing useless computation. 💅

🌸 Wildcards ("Globbing") 🌸

When a parameter has an unquoted * star (yes, "asterisk", we're fancy) or a ? question mark in it, fish treats it as a wildcard to match files:

* matches any number of characters (including zero) in a file name — but not /.
** matches any number of characters (including zero), and it also descends into subdirectories. If ** is a segment all by itself, that segment may match zero times, for compatibility with other shells.
? can match any single character except /. Okay so heads up: this is deprecated and can be disabled via the qmark-noglob feature flag, at which point ? will just be an ordinary character.

Wildcard matches are sorted case insensitively. And when the matches contain numbers they're naturally sorted, so the strings '1' '5' and '12' would be sorted like 1, 5, 12. slay. ✨

Hidden files (where the name begins with a dot) are not considered when wildcarding unless the wildcard string has a dot in that place. And wildcards never expand to . (current directory) or .. (parent directory).

Examples, bestie:

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 executed, $status is set to nonzero, and a warning is printed. This behavior is like what bash does with shopt -s failglob. There are exceptions though — 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 🦋

Okay so one of the most important expansions in fish is the "variable expansion". That's 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. iconic.

Some variables like $HOME are already set because fish sets them by default or because fish's parent process passed them to fish when it started it. You can define your own variables by setting them with set <>:

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

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

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

echo $nonexistentvariable
# Prints no output.

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

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

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

That latter syntax {$WORD} is a special case of brace expansion, fyi.

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

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

🎀 Quoting variables 🎀

Variable expansion also happens inside double quoted strings. Inside double quotes ("these"), variables will always expand to exactly one argument. If they're empty or undefined, it'll 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 which case it will use a colon (:) instead [3].

fish variables are all lists, and they get split into elements when they're set — which means it's 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's known as "Word Splitting", where they split the variable when it's 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'`

And that 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 elements will expand to each of those elements separately.

If a variable expands to nothing, it will cancel out any other strings attached to it. See the Combining Lists section for more info.

Most of the time, not quoting a variable is correct. The exception is when you need to ensure 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 (like 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]". no cap.

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 variable 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 functions — it will not work with keywords because they have syntactical importance. 🫶

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 before the outer command can even be started.

If the inner command prints multiple lines, fish will use each separate line as a separate argument to the outer command. Unlike other shells, the value of $IFS is not used [4] — fish splits on newlines.

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 (we're getting there bestie, chill 💅).

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 wanna hand the output of a command to another command that only takes files, not stdin. If it's just one file, a pipe usually does the trick, like:

grep fish myanimallist1 | wc -l

But if you need multiple files, or the command just doesn't read from standard input, that's when process substitution comes in clutch ✨ Other shells let you do foo <(bar) <(baz), and fish does the same thing with the psub command:

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

Basically it makes a temporary file, drops the command's output in there, and prints the filename so the outer command gets it. Iconic behavior, no notes 🎀

💀 Heads up, the memory limit is real: fish has a default limit of 1 GiB on the data it'll read in a command substitution. If you hit that limit the command fails — and we mean the whole command, not just the substitution part. The outer command won't even run. $status gets set to 122. This exists so command substitutions can't tank your system by eating all the memory — your OS typically has a way lower limit anyway, so reading past that is useless and harmful. You can tweak the limit with the fish_read_limit variable (0 means no limit). This limit also applies to the read command.

[4] One exception: setting $IFS to empty disables line splitting. This is deprecated — use string split instead.

🌀 Brace expansion

Curly braces let you write comma-separated lists, and they get expanded so each element becomes its own parameter with the surrounding string glued on. Great for saving keystrokes, and honestly a lifesaver for separating a variable name from the text around it 🫶

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's no , and no variable expansion between the braces, they do not get 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's nothing left between the braces, the whole argument gets removed (peep the Combining Lists section):

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

And if there's nothing between a brace and a comma — or between two commas — that counts as an empty element:

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

Wanna use a literal , as an element? Quote it or escape it, bestie.

Also: the very first character of a command token is never treated as a brace expansion, because it's the start of a compound statement:

> {echo hello, && echo world}
hello,
world

🧩 Combining lists

fish expands lists like brace expansions do:

>_ 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 gets concatenated onto each element. Periodt.

Two lists expand into all the 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

And here's the plot twist 😭 if a list has no elements, then combining the string with no elements means... the entire token vanishes!

>_ set -l c # <- this list is empty!
>_ echo {$c}word
# Output is an empty line - the "word" part is gone

This is actually super useful. Say you wanna go through all the files in all the directories in PATH:

for file in $PATH/*

Since PATH is a list, that expands to all the files in all the directories in it. And if there are no directories in PATH, expanding to no files is genuinely the right answer 🌈

Sometimes you don't want that though — especially because tokens can disappear after expansion. In those cases, double-quote your variables: echo "$c"word.

This happens after command substitution too. To stop tokens from vanishing there, either 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 you only need some of the elements of a list (and reminder: every fish variable is a list), or some of the lines a command substitution spat out. Both are doable in fish — just write 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"

Inside index brackets, fish gets ranges written like a..b (where a and b are indices). They expand into a sequence of indices from a to b (so a a+1 a+2 ... b), counting up if b is bigger and down if a is bigger. Negative indices are also a thing — they count from the end of the list, so -1 is the last element and -2 is the one before it. If an index doesn't exist, the range gets 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 only goes from element 2 to element 5. Clamped, slay.

If the end is negative, the range always goes up: 2..-2 goes from element 2 to 4, and 2..-16 goes nowhere because there's no way to get from the second element to one that doesn't exist while going up. If the start is negative, the range always goes down: -2..1 goes from element 4 to 1, and -16..2 goes nowhere because there's no way to get from an element that doesn't exist to the second element while going down.

A missing starting index in a range defaults to 1 — allowed only if the range is the first index expression of the sequence. Same deal for a missing ending index, which defaults to -1, allowed for the last index in the sequence.

Multiple ranges are fine too, 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]

Same energy works when you're 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 expanding variables, like so:

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

But 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'

And when you're doing indirect variable expansion with multiple $ ($$name), you have to give all the indices up to the variable you actually wanna 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

That ~ (tilde) character at the start of a parameter, followed by a username, expands into that user's home directory. A lone ~, or a ~ followed by a slash, expands 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 expansions above can be combined, and if several of them produce more than one parameter, every possible combination gets created. Iconic combinatorial chaos ✨

When you combine multiple parameter expansions, they're performed in this order:

Command substitutions
Variable expansions
Bracket expansion
Wildcard expansion

Expansions happen from right to left, and nested bracket expansions and command substitutions happen from the inside 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. Ate, no crumbs 🍓

🌈 Table Of Operators 🌈

okay bestie, this is the cheat sheet — every special little symbol fish uses, all in one place. Putting it together, here's your quick reference to fish's operators, all of the special symbols it uses:

$ — Variable expansion — like echo $foo
$() and () — Command substitution — like cat (grep foo bar) or cat $(grep foo bar)
< and > — Redirection, like command > file — e.g. git shortlog -nse . > authors
| — Pipe, connect two or more commands — e.g. foo | grep bar | grep baz
; — End of the command, instead of a newline — e.g. command1; command2
& — Backgrounding — e.g. sleep 5m &
{} — Brace expansion — e.g. ls {/usr,}/bin
&& and || — Combiners — e.g. mkdir foo && cd foo or rm foo || exit
* and ** — Wildcards — e.g. cat *.fish or count **.jpg
\ — Escaping — e.g. echo foo\nbar or echo \$foo
'' and "" — Quoting — e.g. rm "file with spaces" or echo '$foo'
~ — Home directory expansion — e.g. ls ~/ or ls ~root/
# — Comments — e.g. echo Hello # this isn't printed

💖 Shell variables 💖

Variables are a way to save data and pass it around. Obsessed, honestly. 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" — that's the term, iykyk.

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. That's literally it. 🫶

🦋 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, function and local variables. Four! Count 'em.

Universal variables are shared between all fish sessions a user is running on one computer. They are stored on disk and persist even after reboot. iconic behaviour honestly.
Global variables are specific to the current fish session. They can be erased by explicitly requesting set -e.
Function variables are specific to the currently executing function. They are erased ("go out of scope") when the current function ends. Outside of a function, they don't go out of scope.
Local variables are specific to the current block of commands, and automatically erased when a specific block goes out of scope. A block of commands is a series of commands that begins with one of the 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 universal variable of the same name. smallest scope wins, every time 💅

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

okay that last one is a whole mood — shiver sets its own local phrase, so it literally cannot touch avast's phrase. local variables stay in their lane, no cap 😭

# Outputs "Avast, mateys"

🔧 Overriding variables for a single command

Okay so bestie, sometimes you want to override a variable for one single command and then let it go back to normal. You do that with "var=val" statements plopped right before the command:

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

And here's the slay part — unlike other shells, fish will first set the variable and then perform other expansions on the line, so:

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

Multiple elements can be given in a brace expansion:

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

Or with a glob:

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

Unlike other shells, this does not inhibit any lookup (aliases or similar). Calling a command after setting a variable override will result in the exact same command being run.

This syntax is supported since fish 3.1. 💅

🌍 Universal Variables

Universal variables are variables that are shared between all the user's fish sessions on the computer. Every change to universal variables is persistent and instantly propagated across fish sessions. It's giving main character energy that's literally everywhere at once. ✨

Universal variables are stored in the file .config/fish/fish_variables. Do not edit this file directly, because your edits may be overwritten. Edit the variables through fish scripts or by using fish interactively instead.

Also — do not append to universal variables in config.fish, because these variables 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 commands 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 variables are also often called "environment variables".

This also applies to fish — when it starts up, it receives environment variables from its parent (usually the terminal). These typically 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 variables — 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 exist 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 variables can be useful if you need something more specific than Overrides. They are copied to functions so the function can't alter them outside, and still available to commands. Global variables are accessible to functions whether they are exported or not. 🫶

📋 Lists

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

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

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

echo $PATH[3]

List indices start at 1 in fish, not 0 like in other languages. This is because it requires less subtracting of 1 and many common Unix tools like seq work better with it (seq 5 prints 1 to 5, not 0 to 5). An invalid index is silently ignored resulting in no value (not even an empty string, no argument at all). Iconic behaviour honestly.

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 variable, the index will be taken from the end of the list. For example, the index -1 is the last element of the list:

> set fruit apple orange banana
> echo $fruit[-1]
banana

> echo $fruit[-2..-1]
orange
banana

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

As you see, you can use a range of indices, see 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. No cap, they just vibe as themselves. 🦋

🎀 Argument Handling

An important list is $argv, which contains the arguments to a function or script. For example:

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

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

> myfunction first second third
first
third

> myfunction apple cucumber banana
apple
banana

That covers the positional arguments, but commandline tools often get various options and flags, and $argv would contain them intermingled with the positional arguments. Typical unix argument handling allows short options (-h, also grouped like in ls -lah), long options (--help) and allows those options to take arguments (--color=auto or --position anywhere or complete -C"git ") as well as a -- separator to signal the end of options. Handling all of these manually is tricky and error-prone. 😩

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

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

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

    # If -s or --second is given, we print the second argument,
    # not the first and third.
    # (this is also available as _flag_s because of the short version)
    if set -ql _flag_second
        echo $argv[2]
    else
        echo $argv[1]
        echo $argv[3]
    end
end

The options will be removed from $argv, so $argv[2] is the second positional 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-delimited 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 variables. Obsessed, honestly.

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 where the cd builtin goes hunting for your new directory 👀

🌍 Locale Variables

ok so the locale variables — LANG, LC_ALL, LC_MESSAGES, LC_NUMERIC and LC_TIME — set the language option for the shell and for subprograms. want the whole lore? see the section Locale variables and status language (#status-language) 💬

🎨 Color variables

there's a whole squad of variables starting with the prefixes fish_color and fish_pager_color. for the full tea, see Variables for changing highlighting colors (#variables-color) 🌈

fish_term24bit — if this is set to 0, fish will not output 24-bit RGB true-color sequences, and instead uses the nearest color on the 256 color palette (or the 16 color palette, if fish_term256 is 0). see also set_color. the default 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, fish translates 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. set it to 1 if your terminal renders these characters as single-width (typical), or 2 if double-width 📏
fish_emoji_width — controls whether fish assumes emoji render as 2 cells or 1 cell wide. this is necessary because the correct value changed from 1 to 2 in Unicode 9, and some terminals may not be aware 😭 set this if you see graphical glitching related to emoji (or other "special" characters). it defaults to 2 ✨
fish_autosuggestion_enabled — controls if Autosuggestions (#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-rendering argument before running a commandline, allowing you to change it before pushing it to the scrollback. this enables transient prompts (#transient-prompt) 🦋
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 (#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 sequence. 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 (#cmd-bind-escape) ⏱️
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 (#interactive-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 variable 🔍
fish_cursor_selection_mode — controls whether the selection is inclusive or exclusive of the character under the cursor (see Copy and Paste, #killring) ✂️
fish_function_path — determines where fish looks for functions. when fish autoloads a function, it will look for files in these directories 📂
fish_greeting — the greeting message printed on startup. this is printed by a function of the same name that can be overridden for more 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 session name "fish" is used. if set to an empty string, history is not saved to disk (but is still available within the interactive session) 📜
fish_trace — if set and not empty, will cause fish to print commands before they execute, similar to set -x in bash. the trace is printed to the path given by the --debug-output option to fish or the FISH_DEBUG_OUTPUT variable. it goes to stderr by default. 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 universal variable 🛣️
umask — the current file creation mask. the preferred way to change the umask variable is through the umask function. an attempt to set umask to an invalid value will always fail ⚠️

fr fr do not try to be cute with an invalid umask value, it just won't take. the function is the way 💀

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 display the fish documentation 🌐

fish also provides additional information through the values of certain environment variables. most of these variables are read-only and their value can't be changed with set 🔒

_ — the name of the currently running command (though this is deprecated, 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, including 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 otherwise a default of 80x24 will be used. they are updated when the window size changes 📐
fish_kill_signal — the signal that terminated the last foreground job, or 0 if the job exited normally 💀
fish_killring — a list of entries in fish's kill ring (#killring) of cut text ✂️
fish_read_limit — how many bytes fish will process with read or in a command substitution 📖
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 terminal does not report its colors (#term-compat-query-background-color). like status terminal (#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 (#syntax-highlighting) variables whenever the terminal's color theme changes. see here (#fish-config-theme-files) 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 executed 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 unexported variables 🧠

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

💅 The status variable

Okay so every time a process exits, it hands back an exit status to whoever started it (usually the shell, bestie). That number is an integer and it's basically the process's little report card: zero means "all good, no notes", and non-zero means "something went sideways".

fish keeps the exit status of the last process in the last job to exit in the status variable. Iconic of it.

And if fish itself hits a problem while running a command, status can get set to some very specific values:

0 is generally the exit status of commands if they successfully did the thing you asked.
1 is generally the exit status of commands if they failed to do the thing you asked.
121 is generally the exit status of commands if you fed them invalid arguments. 🙈
123 means the command was not executed because the command name contained invalid characters.
124 means 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.

And if a process exits through a signal, the exit status will be 128 plus the number of the signal. Math girlie moment.

Now — the status can be negated with not (or !), which is super useful in a condition. It flips a status of 0 into 1 and any non-zero status into 0. Literally the uno reverse card.

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

For example:

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

Here $status reflects the status of grep, which returns 0 if it found something, negated with not (so 1 if it found something, 0 otherwise). $pipestatus reflects the status of cat (which returns non-zero for example when it couldn't find the file) and grep, without the negation.

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

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. 😭 Rip king.

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. Not naming names but 👀

🌍 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 defined 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 order. 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 different from GNU gettext, which uses a "default" variant of the language 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.

🧰 Builtin commands

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

Builtins that manipulate the shell state — cd changes directory, set sets variables
Builtins for dealing with data, like string for strings and math for numbers, count for counting lines or arguments, path for dealing with path
status for asking about the shell's status
printf and echo for creating output
test for checking conditions
argparse for parsing function arguments
source to read a script in the current shell (so changes to variables stay) and eval to execute a string as script
random to get random numbers or pick a random element from a list
read for reading from a pipe or the terminal

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

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

🔍 Command lookup

When fish is told to run something, it goes through multiple steps to find it. Detective mode fr fr.

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:

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
It tries to resolve it as a builtin.
It tries to find an executable file in PATH.
- If it finds a file, it tells the kernel to run it.
- If the kernel knows how to run the file (e.g. via a #! line — #!/bin/sh or #!/usr/bin/python), it does it.
- If the kernel reports that it couldn't run it because of a missing interpreter, and the file passes a rudimentary check, fish tells /bin/sh to run it.

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

You can use type to see how fish resolved something:

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

🗣️ Querying for user input

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

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

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

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

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

If you run this as show_files /, it will most likely ask you until you press Y/y or N/n. If you run this as show_files / | cat, it will print the files without asking. If you run this as show_files ., it might print something without asking because there are fewer than five files. ✨

🏷️ Shell variable and function names

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

a variable name — bestie it literally cannot be empty 💀 it can only have letters, digits, and underscores, and it may begin and end with any of those. That's the whole vibe check.
a function name — also cannot be empty. It may not begin with a hyphen (-) and may not contain a slash (/). Every other character, including a space, is valid (yes really, spaces go hard here). One more catch: a function name can't be the same as a reserved keyword or an essential builtin like if or set.
a bind mode name (like bind -m abc ...) — must be a valid variable name. No notes. 💅

Other things have other restrictions. For instance what's allowed for file names depends on your system, but at the very least they cannot contain a / (because that's the path separator, duh) or a NULL byte (because that's how UNIX ends strings — iconic but ancient behavior 🧚).

🎀 Configuration files 🎀

When fish starts up, it reads and runs its configuration files. Where those live depends on your build configuration and your environment variables. It's giving "it depends" energy but we'll walk through it together 🫶

The main file is ~/.config/fish/config.fish — or, more precisely, $XDG_CONFIG_HOME/fish/config.fish.

Configuration files are run in this order:

Configuration snippets (named *.fish) in the directories:
- $__fish_config_dir/conf.d (by default, ~/.config/fish/conf.d/)
- $__fish_sysconf_dir/conf.d (by default, /etc/fish/conf.d/)
- Directories for others to ship configuration snippets for their software:
  - the directories under $__fish_user_data_dir (usually ~/.local/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/local/share/fish/vendor_conf.d)

These directories are also accessible in $__fish_vendor_confdirs. > Heads up: changing that in a running fish won't do anything, because by that point the directories have already been read. Sorry bestie, timing is everything 😭

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

System-wide configuration files, where administrators can include initialization for all users on the system — similar to /etc/profile for POSIX-style shells — in $__fish_sysconf_dir (usually /etc/fish/config.fish).
User configuration, usually in ~/.config/fish/config.fish (controlled by the XDG_CONFIG_HOME environment variable, and accessible as $__fish_config_dir).

~/.config/fish/config.fish is sourced after the snippets. Why? So you can copy snippets and override some of their behavior. Main character energy fr 👑

These files are all executed on the startup of every shell. If you want to run a command only on starting an interactive shell, use the exit status of the command status --is-interactive to determine if the shell is interactive. If you want to run a command only when using a login shell, use status --is-login instead. This will speed up the starting of non-interactive or non-login shells — and honestly your startup time is a vibe check everyone notices ⭐

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. Additionally, users of other shells won't benefit from the fish-specific configuration. However, if they are required, you can install them to the "vendor" configuration directory. As this path may vary from system to system, pkg-config should be used to discover it: pkg-config --variable confdir fish.

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

✨ Future feature flags ✨

Feature flags are how fish stages changes that might break scripts. Breaking changes are introduced as opt-in, in a few releases they become opt-out, and eventually the old behavior is removed. It's a whole character arc for the shell 🎬

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, bestie — buckle in 🎢

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-nocaret value will be ignored. The flag made ^ an ordinary character instead of denoting an stderr redirection. Use 2> instead. Periodt.
qmark-noglob — 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 — 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 — 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 formatting anyway, and fish_indent will have done it for you already 💅
remove-percent-self — turns off the special %self expansion. It was introduced 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 --debug=deprecated-test can be used to find offending calls. Detective mode fr 🔍
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-terminfo 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 incompatible 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 effect if it is universal or exported. Timing again, bestie 🕐

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. Obsessed with this feature ngl 🫶

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 time! ✨

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 displayed.
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 errors. 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. Chaos is not a contract, bestie 😌

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

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

🐛 Debugging fish scripts

fish has basic built-in debugging facilities, and they're honestly kind of iconic — they let you stop a script's execution at literally any point you want. When that happens you get dropped into an interactive prompt where you can run any fish command to inspect or change state (and no, there are no special "debug commands" as such, it's just fish being fish 💅). For example, you can check or change the value of any variables using printf and set. Another example: you can run status print-stack-trace to see how the current breakpoint was reached. To resume normal execution of the script, type exit or hit Ctrl+D.

To start a debug session, insert the builtin command breakpoint at the point in a function or script where you want to gain control, then run the function or script. Also — plot twist — the default action of the TRAP signal is to call this builtin, which means a running script can be actively debugged by sending it the TRAP signal (kill -s TRAP <PID>). There's limited support for interactively setting or modifying breakpoints from this debug prompt: it's possible to insert new breakpoints in (or remove old ones from) other functions 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 function/script currently loaded and being executed. Sorry bestie, that one's off the table 🙈

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 specified path. This profile log includes a breakdown of how long each step in the execution took. It's giving detective work ✨

For example:

> fish --profile /tmp/sleep.prof -ic 'sleep 3s'
> cat /tmp/sleep.prof
Time    Sum     Command
3003419 3003419 > sleep 3s

This shows 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 — all 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's also --profile-startup /path/to/logfile.

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 variable.
command or builtin — to tell fish what sort of thing to execute.
time — to time execution.
exec — tells fish to replace itself with a command.
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, which is honestly main character energy. 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 shortened way.
prompt_login — to describe the current login, with user and hostname, and to explain if you are in a chroot or connected via ssh.
prompt_hostname — to give the hostname, shortened for use in the prompt.
fish_is_root_user — to check if the current user is an administrator user like root.
fish_add_path — to easily add a path to $PATH.
alias — to quickly define wrapper functions ("aliases").
fish_delta — to show what you have changed from the default 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. Convenient? We love to see it 💖

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 upstreamed into the fish repo will not work unless the exact same message also exists upstream. Fr fr, it's a whole thing 😭

It requires fish to be built with gettext support. If that support is disabled 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 exported to make them available outside of fish.

For LANGUAGE you can use a list, or use colons to separate multiple languages.

If the status language command was used, its arguments specify the language precedence, and the environment variables are ignored.

Options

_ takes no options. Periodt.

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.
Ungültige Argumente
> _ untranslatable  # No translation in Portuguese, nor in German.
untranslatable

Note that the specific examples may change if translations are added/modified. So don't @ me if Datei becomes something else later 🦋

🎀 `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. It's giving "why type five words when one do trick" ✨

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 expansion occurs after pressing space or enter.

Combining these features, it is possible to create custom syntaxes, where a regular expression recognizes matching tokens, and the expansion function interprets them. See the Examples section. Go off, custom syntax 👑

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

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

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

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

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 into myabbrs.fish, overwriting the whole file so it doesn't leave any duplicates behind, or restore abbreviations you had erased. Lowkey iconic. 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 brand new abbreviation. With no other options, the string NAME gets replaced by EXPANSION. Simple as that, bestie. 🎀

With --position command, the abbreviation will only expand when it's sitting pretty in the command position — not when it's an argument to some other command. With --position anywhere it may expand anywhere in the command line. The default is command.

With --command COMMAND, the abbreviation will only expand when it's used as an argument to the given COMMAND. Multiple --command can be used together, and the abbreviation will expand for each one. An empty COMMAND means it will expand only when there is no command. --command implies --position anywhere and disallows --position command. And 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. iykyk 💅

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 the one that wins. Last one in, no cap. 🔥

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 %. Cute, right? 🎀

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 argument. If the function's exit status is 0 (success), the token will be replaced by the function's output; otherwise the token will be left unchanged. No EXPANSION may be given separately. ✨

The description set by --description=DESCRIPTION will be added to the completion description in the completion pager. Nice little glow-up for your completion menu. 💖

✨ Examples ✨

abbr --add gco git checkout

Adds a new abbreviation where gco will be replaced with git checkout. The classic. Obsessed. 👑

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

Adds a new abbreviation where -C will be replaced with --color. The -- is there so -C gets treated as the name of the abbreviation, instead of being read as an option. 🫶

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

Adds a new abbreviation where L will be replaced with | less, placing the cursor before the pipe. Chef's kiss. 😌

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

This first creates a function last_history_item which outputs the last entered command. It then adds an abbreviation which replaces !! with the result of calling this function. Taken together, this is similar to the !! history expansion feature of bash. Fr fr, it's giving time travel. 🌀

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

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

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

This creates an abbreviation 4DIRS which expands to a multi-line loop "template." The template enters each directory and then leaves it. The cursor is positioned ready to enter the command to run in each directory, at the location of the !, which is itself erased. A whole loop, pre-built, waiting for you. Slay. 🔁

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. Versatility queen. 💅

✨ 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. Perfect for when you gotta move your whole setup somewhere else. 📦

abbr [-l | --list]

Prints the names of all abbreviation. A little name-only vibe check. 👀

abbr [-e | --erase] [ [-c | --command COMMAND]... ] NAME ...

Erases the abbreviation with the given name. For command-specific abbreviations, the --command options must be provided to disambiguate which abbreviation to rename. 🙈 (yes, that's what it says, we simply do not ask questions)

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 function wrapping a command. It has similar syntax to POSIX shell alias. For other uses, it is recommended to define a function <>. 🧚

If you want to ease your interactive use, to save typing, consider using an abbreviation <> instead. Honestly the glow-up your fingers deserve. 💅

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

NAME is the name of the alias
DEFINITION is the actual command to execute. alias automatically appends $argv, so that all parameters used with the alias are passed to the actual command. So generous of it. 🫶

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. Yes, even inside quotes. The quotes do not save you here, bestie. 😭

The following options are available:

-h, --help — Displays help about using this command.
-s, --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'

Notice the backslashes. Do not forget the backslashes. The backslashes are the whole assignment. 😤

See more

The function <> command this builds on.
Functions <#syntax-function>.
Defining aliases <#syntax-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). It's the "only if you ate" of shell operators. ✨

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 <#variables-status> variable. Track it, queen. 👑

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

One line, full pipeline, built-in cleanup plan. We love a responsible icon. 🧹💖

🦋 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 arguments. You pass arguments that define the known options, followed by a literal --, then the arguments to be parsed (which might also include a literal --). 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. It's literally the whole argument-handling situation, handled. 🫶

Each option specification (OPTION_SPEC) is written in the domain specific language described below. All *OPTION_SPEC*s must appear after any argparse flags and before the -- that separates them from the arguments to be parsed. Order matters, bestie. Do not freestyle it. 💅

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. Two variables, one flag, iconic behaviour. ✨

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 corresponding to the values collected when the ARG list is processed. If the flag was not seen the flag variable will not be set. No flag, no variable, no drama. 🎀

Options

The following argparse options are available. They must appear before all *OPTION_SPEC*s:

-n, --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, --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 exclusive options. You give either the short or long version of each option, and you still need to otherwise define the options.
-N, --min-args NUMBER — The minimum number of acceptable non-option arguments. The default is zero.
-X, --max-args NUMBER — The maximum number of acceptable non-option arguments. The default is infinity. Go big, apparently. ♾️
-u, --move-unknown — Allow unknown options, and move them from $argv to $argv_opts. By default, Unknown options are treated as if they take optional arguments (i.e. have option spec =?).

okay so the tea from that last chunk is this: if a group of short options has an unknown short option followed by a known short option, the known short option gets treated as an argument to the unknown one. Like --move-unknown 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 doesn't take any arguments), the known option gets recognised — e.g. argparse --move-unknown h -- -ho will set $_flag_h to -h ✨

-i, --ignore-unknown — Deprecated bestie. 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 distinguish between an unknown option and a non-option argument that starts with a - (since any -- separator in $argv will be removed). 😭
-S, --strict-longopts — this makes parsing long options more strict. 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, those three are parse errors: one must use the syntax --long or --long=<value> to use a long option 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. It modifies 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 --unknown-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, neither _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 option, -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 unknown option.

-s, --stop-nonopt — causes scanning the arguments to stop as soon as the first non-option argument is seen. Among other things, this is useful to implement subcommands that have their own options.
-h, --help — displays help about using this command.

🌸 Usage

To use this command, pass the option specifications (OPTION_SPEC), a mandatory --, 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 arguments and local variables called _flag_OPTION are set so the script can determine 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 specifications 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-unknown) 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 usable 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 _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 arguments 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 entirely 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. 💖

okay so fish ships with a _validate_int function that accepts --min and --max flags. Let's say your command accepts a -m or --max flag and the minimum allowable 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 integer 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, bestie — every single one matters:

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 associated with each occurrence. Each value will be the value given to the option, 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 unbound 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 another 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 specification.

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 --bytess 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 --unknown-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 <# variables-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 <#syntax-job-control> 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 specified 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 matching 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:

okay so picture this job-control moment:

> 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/jsfil…' 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/jsfil…' 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. bestie, this is the whole keyboard-glow-up command.

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 specified 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 insert any keystrokes that have no bindings otherwise. Non-printable characters are ignored by the editor, so this will not result in control sequences 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 repaint 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 <# configuration>. Alternatively, 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 <#vi-mode>, that's the command mode, what vi calls "normal" 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 defining 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 bindings. 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-movement-related operations. If the cursor is at the start of the commandline, 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 division 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 cancelled
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 <#term-compat-indn> command and cursor position reporting <#term-compat-cursor-position-report>.
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 autosuggestion.
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 commandline, accept the current autosuggestion. If the completion pager is active, select the next completion instead.
forward-char-passive — slides the cursor one character to the right, but passively — it does not trigger any non-movement-related operations. If you're already chilling at the end of the commandline, it does not accept the current autosuggestion (if there even is one). Also does not change the selected item in the completion pager, if one's showing. Very demure, very mindful 💅
forward-path-component — bounces one path component to the right; or, if you're at the end of the commandline, it accepts a path component from the current autosuggestion. Slay 🦋
forward-single-char — moves one character right; or, at the end of the commandline, accepts a single char from the current autosuggestion.
forward-word — moves one word to the right, stopping after the end of the current word; or at the end of the commandline, accepts one word from the current autosuggestion.
forward-word-vi — same energy as forward-word, but it 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 — moves one whitespace-delimited word to the right, stopping after the end of the current word; or at the end of the commandline, accepts 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 — brings up the searchable pager on your history (incremental search, iconic behavior 💖); or, if the history pager is already active, it searches further backwards in time.
history-delete — permanently deletes the current history item, either from the history pager or from an active up-arrow history search. Gone gone, no take-backs 😭
history-search-backward — searches the history for the previous match.
history-search-forward — searches the history for the next match.
history-prefix-search-backward — searches the history for the previous prefix match.
history-prefix-search-forward — searches the history for the next prefix match.
history-token-search-backward — searches the history for the previous matching argument.
history-token-search-forward — searches the history for the next matching argument.
history-last-token-search-backward — searches the history for the previous matching last argument.
history-last-token-search-forward — searches 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. Rerun it, bestie 🔁
jump-to-matching-bracket — jumps to the matching bracket if the character under the cursor is a bracket; otherwise, it jumps 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 it offsets the cursor to the right for a left bracket, and offsets the cursor to the left for a right bracket. The offset is applied for both the position we jump from and the position we jump to. In other words, the cursor will continuously jump inside the brackets but won't reach them by 1 character. This input function is useful to emulate ib vi text object. The following brackets are considered: ([{}])
kill-token — moves the next argument to the killring.
kill-line — moves everything from the cursor to the end of the line to the killring.
kill-path-component — moves one path component to the killring.
kill-selection — moves the selected text to the killring.
kill-whole-line — moves the line (including the following newline) to the killring. If the line is the last line, its preceding newline is also removed. Lowkey aggressive but we love her 💀
kill-inner-line — moves the line (without the following newline) to the killring.
kill-word — moves the next word to the killring, stopping after the end of the killed word.
kill-word-vi — moves the next word to the killring, stopping at the start of the next word (like vim's dw).
kill-bigword — moves the next whitespace-delimited word to the killring, stopping after the end of the current word.
kill-bigword-vi — moves the next whitespace-delimited word to the killring, stopping at the start of the next word (like vim's dW).
kill-inner-word — deletes the word under the cursor (like vim's diw).
kill-inner-bigword — deletes the whitespace-delimited word under the cursor (like vim's diW).
kill-a-word — deletes the word under the cursor plus surrounding whitespace (like vim's daw).
kill-a-bigword — deletes the whitespace-delimited word under the cursor plus surrounding whitespace (like vim's daW).
nextd-or-forward-word — if the commandline is empty, it moves forward in the directory history; otherwise it moves one word to the right; or, if you're at the end of the commandline, it accepts one word from the current autosuggestion. Multitasking queen 👑
or — only executes the next function if the previous one did not succeed (note: only some functions report failure). Important caveat, don't forget it 🫶
pager-toggle-search — toggles the search field if the completions pager is visible; or, if used after history-pager, it searches forwards in time.
prevd-or-backward-word — if the commandline is empty, it moves backward in the directory history; otherwise it moves one word to the left.
repaint — reexecutes the prompt functions and redraws the prompt (also available as force-repaint for backwards-compatibility).
repaint-mode — reexecutes the fish_mode_prompt and redraws the prompt. This is useful 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 cursor 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 — removes the current autosuggestion. Returns true if there was a suggestion to remove.
swap-selection-start-stop — goes to the other end of the highlighted text without changing the selection.
transpose-chars — transposes two characters to the left of the cursor. Swap szn ✨
transpose-words — transposes two words to the left of the cursor.
togglecase-char — toggles the capitalisation (case) of the character under the cursor.
togglecase-selection — toggles the capitalisation (case) of the selection.
insert-line-under — adds a new line under the current line.
insert-line-over — adds a new line over the current line.
up-line — moves up one line.
undo and redo — revert or redo the most recent edits on the command line.
upcase-word — makes the current word uppercase.
yank — inserts the latest entry of the killring into the buffer.
yank-pop — rotates to the previous entry of the killring.

✨ Additional functions ✨

The following functions are included as normal functions, but they're particularly useful for input editing:

up-or-search and down-or-search — moves the cursor or searches the history, depending on the cursor position and the current mode.
edit_command_buffer — opens the visual editor (controlled by the VISUAL or EDITOR environment variables) with the current command-line contents. Chef's kiss for long commands 🎀
fish_clipboard_copy — copies the current selection to the system clipboard.
fish_clipboard_paste — pastes the current selection from the system clipboard before the cursor.
fish_commandline_append — appends 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 — prepends the argument to the command-line. If the command-line already 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 technology. They have some limitations that applications running inside them can't workaround. Ngl, it's giving vintage 💀

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 (→) usually sends \e\[C.

Some modern terminals support newer encodings for keys, that allow distinguishing more characters and modifiers, and fish enables as many of these as it can, automatically. Bestie fish is doing her best and honestly? She's thriving 🐟💖

When in doubt, run fish_key_reader — it literally lets you explore what characters your keyboard keys send 💅. And if that tells you that pressing ctrl+i sends tab, then bestie… your terminal does not support these better encodings, and so fish is limited to what it sends. No cap, that's just the vibe check your terminal failed 😭

⌛ Key timeout

So 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 disambiguate between the full sequence and part of it. It's giving "wait, are we done here or…?" 🫶

For example:

bind j,k 'commandline -i foo'
# or `bind jk`

will bind the sequence jk to insert "foo" into the commandline. But 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". The suspense is real 💀

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. Iconic, honestly — it commits ✨

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 example holding alt+a will send an escape character and then an "a". So the escape character has its own timeout configured with fish_escape_delay_ms 👑

🚧 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 delaying 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. It's basically putting your events on "do not disturb" mode 🙈

Event blocks should not be confused with code blocks, which are created with begin, if, while or for. Different thing entirely, bestie, don't mix them up 🎀

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. It stays locked, periodt.
-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. Lowkey tragic, but that's the rules 🌸

🛑 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. Think of it as the "okay I'm out" of loop land 💅

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

🐞 breakpoint - launch debug mode

Synopsis

breakpoint

Description

breakpoint is used to halt a running script and launch an interactive debugging prompt. Main character energy for your script: it gets to stop and think about its life 😌

For more details, see Debugging fish scripts in the fish manual.

There are no parameters for breakpoint. Zero. None. Nada ✨

🧱 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. Like, "no, we're using the real one, not your cute little function" 😤

The following options are available:

-n or --names — Lists the names of all defined builtins. A whole roster, slay 📋
-q or --query BUILTIN — Tests if any of the specified builtins exist. If any exist, it returns 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. It's the switch statement's hype squad 🫶

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 filenames. Quote your wildcards, bestie, or the filesystem will get involved 🙈

Note that fish does not fall through on case statements. Only the first matching case is executed. No accidental cascade, we're not C here 💅

Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter. Yes, it's extra work, but it's how it goes 😭

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 banana is". And honestly? Same 🍌💀

📁 cd - change directory

Synopsis

cd [( -L | --no-dereference ) | ( -P | --dereference )] [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. The classic. The moment.

The PWD environment variable is updated with the new working directory, and the previous directory is added to the directory history. Keeping receipts, always 🧾

If DIRECTORY is given, it will become the new directory. If no parameter is given, the HOME environment variable will be used. Home sweet home 🏠

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. Order matters, bestie ⭐

The new directory name is partially resolved to remove redundant segments (. or ..).

cd defaults to treating symbolic links as real directories, and not resolving them to their underlying targets. The $PWD special variable will contain the path that was supplied. This default behaviour can be enforced with the -L or --no-dereference option. Keep the link, keep the illusion 🦋

The -P or --dereference option resolves all symbolic links first. This was the default in fish versions before 3.0.0. Old school 👑

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. It just knows ✨

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. Shared lore across every shell, iykyk 💖

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. Niche but iconic 🎀

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

cd -P /tmp/link
# resolves /tmp/link to its target before recording the directory

🕰️ 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. Fancy, right? 💅 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. Group-chat-level sharing, but for directories 🫶

🏃 command - run a program

Synopsis

command [OPTIONS] [COMMANDNAME [ARG ...]]

Description

NOTE: This page documents the fish builtin command. To see the documentation 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. It's the "I said what I said" of the shell 😤

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. Every single one, no gatekeeping 👑
-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 (deprecated). A quiet icon, but on the way out 💀
-s or --search (or -v) — Prints the external command that would be executed, or prints nothing if no file with the specified name could be found in PATH.
-h or --help — Displays help about using this command.

✨ Examples ✨

command ls runs the ls program — yes, even if an ls function is also sitting there existing 💅
command -s ls prints out the path to the ls program
command -q git; and command git log runs git log only if git is actually a thing on your system
command -sq git, command -q git and command -vq git all return true (0) if a git command could be found, and they print absolutely nothing 🫶

🌸 `commandline` — set or get the current command line buffer 🌸

Synopsis

commandline [OPTIONS] [CMD]

Description

So commandline is your little window into the command line buffer itself — you can read what's in there, or overwrite it. Iconic, honestly 🎀

With no parameters at all, commandline returns the current value of the command line.

With CMD specified, the command line buffer gets erased and replaced with the contents of CMD. Poof, gone, new text 💅

Here are the options, bestie:

-C, --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 position. If one of the options -j, -p or -t is given, the position is relative to the respective substring instead of the entire command line buffer.
-B, --selection-start — Get the current position of the selection start in the buffer.
-E, --selection-end — Get the current position of the selection end in the buffer.
-f, --function — Causes any additional arguments to be interpreted as input functions, and puts them into the queue, so that they will be read before any additional actual key presses are. This option cannot be combined with any other option. See bind <> for a list of input functions.
-h, --help — Displays help about using this command.

The next batch changes how commandline updates the command line buffer:

-a, --append — Do not remove the current commandline, append the specified string at the end of it.
-i, --insert, --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. it's giving mind-reading 🧚
-r, --replace — Remove the current commandline and replace it with the specified string (this is the default).

And these ones change what part of the commandline gets printed or updated:

-b, --current-buffer — Select the entire commandline, not including any displayed autosuggestion (default).
-j, --current-job — Select the current job — a job here is one pipeline. Stops at logical operators or terminators (;, &, and newlines).
-p, --current-process — Select the current process — a process here is one command. Stops at logical operators, terminators, and pipes.
-s, --current-selection — Selects the current selection.
-t, --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.

Then there's the group that changes how commandline prints the current buffer:

-c, --cut-at-cursor — Only print selection up until the current cursor position. If combined with --tokens-expanded, this will print up until the last completed token — excluding the token the cursor is in. This is typically 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, --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. 🚫 (like, fr, don't)

Heads up: 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. sneaky but it works 💀

Finally, the options that output metadata about the commandline state:

-L, --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, --search-mode — Evaluates to true if the commandline is performing a history search.
-P, --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" message).
--is-valid — Returns true when the commandline is syntactically valid and complete. If it is, it would be executed when the execute bind function is called. If the commandline is incomplete, return 2; if erroneous, return 1.
--showing-suggestion — Evaluates to true (i.e. returns 0) when the shell is currently showing an automatic history completion/suggestion, available to be consumed 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 automatically). lowkey so useful 🦋

Example

commandline -j $history[3] replaces the job under the cursor with the third item from the command line history. so clutch ✨

So if the commandline contains

>_ echo $flounder >&2 | less; and echo $catfish

(with the cursor on the "o" of "flounder"):

echo $flounder >& is the first process, less the second, 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 you the current process (aka 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 possible 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. it's the whole tab-completion economy 💅

For an introduction to writing your own completions, see Writing your own completions <> in the fish manual.

The following options are available:

-c, --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, --path COMMAND — Specifies that COMMAND is the absolute path of the command (optionally containing wildcards).
-e, --erase — Deletes the specified completion. bye bye 🦋
-s, --short-option SHORT_OPTION — Adds a short option to the completions list.
-l, --long-option LONG_OPTION — Adds a GNU-style long option to the completions list.
-o, --old-option OPTION — Adds an old-style short or long option (see below for details).
-a, --arguments ARGUMENTS — Adds the specified option arguments to the completions list.
-k, --keep-order — Keeps the order of ARGUMENTS instead of sorting alphabetically. Multiple complete calls with -k result in arguments of the later ones displayed first. no alphabetical erasure here, the order stays periodt 💖
-f, --no-files — This completion may not be followed by a filename.
-F, --force-files — This completion may be followed by a filename, even if another applicable complete specified --no-files.
-r, --require-parameter — This completion must have an option argument, i.e. may not be followed 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, --exclusive — Short for -r and -f.
-d, --description DESCRIPTION — Add a description for this completion, to be shown in the completion pager. the little glow-up text ✨
-w, --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, --condition CONDITION — This completion should only be used if the CONDITION (a shell command) returns 0. This makes it possible to specify completions that should only be used in some cases. If multiple conditions are specified, fish will try them in the order they are specified until one fails or all succeeded.
-C, --do-complete STRING — Makes complete try to find all possible completions for the specified 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 completions. WHEN can be auto (the default, colorize if the output is a terminal <>), always, or never. 🌈
-h, --help — Displays help about using this command.

okay so command-specific tab-completions in fish are built on the whole options and arguments concept. An option is a parameter that starts with a hyphen, like -h, -help or --help. Arguments are parameters that don't start with a hyphen. fish speaks three styles of options — literally the same three styles as the GNU getopt library — and they are:

Short options, like -a. These are a single character long, come with a single hyphen in front, and can be grouped together (like -la, which is equivalent to -l -a). Option arguments can be given by gluing the value onto the option (-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, get a single hyphen in front, and may not be grouped together. Option arguments are specified by default after a space (-foo null) or after = (-foo=null).
GNU-style long options, like --colors. These can be more than one character long, come with two hyphens up front, and can't be grouped together. Option arguments may be specified after a = (--quoting-style=shell), or, if --require-parameter is given, in the following parameter (--quoting-style shell).

Multiple commands and paths can be handed over in one call so you define the same completions for multiple commands. ✨

Multiple command switches and wrapped commands can also be given, to define multiple completions in a single call.

Invoking complete multiple times for the same command adds the new definitions on top of whatever completions already exist for that command.

When -a or --arguments is specified alongside long, short, or old-style options, the arguments you listed 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, those arguments get 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. A description given this way overrides a description given with -d or --description.

Descriptions given with --description are also used to group options given with -s, -o or -l. Options that share 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 cause the specified command to inherit completions from another command, "wrapping" that other command. The wrapping command can also have additional completions. A command can wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically 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, you can either erase all completions for a specific command by specifying complete -c COMMAND -e, or specify a specific completion option to delete. 💅

When complete is called without anything that would define or erase completions (options, arguments, wrapping, ...), it shows matching completions instead. So complete with no arguments shows all loaded completions, and complete -c foo shows all loaded completions for foo. Since completions are autoloaded <#syntax-function-autoloading>, you'll have to trigger them first. 🙈

🪟 Cygwin / MSYS2 / Windows

On Windows, binary executables have a .exe extension, but that extension is not required when calling an application (and only if the name isn't ambiguous — i.e. there isn't also a script called myprog sitting in the same directory as myprog.exe).

To unify completions between Windows and other OSes, on Cygwin/MSYS2/Windows, 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 you also use the .exe extension on the command 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 specified 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 several 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 specified as a single-character old-style option instead of as a short-style option; 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 it does, contains exits with code 0; if not, it exits with code 1.

The following options are available:

-i, --index — print the index (the number of the element in the set) of the first matching element.
-h, --help — displays help about using this command.

Options must be passed before KEY. All arguments after KEY will be considered a value, regardless of whether they start with a - or not, including --. If KEY itself starts with a -, use a -- argument to separate it from the options.

See the examples below. 👀

Example

If animals is a list of animals, the following will test if animals contains "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 the function hasargs is being run 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 as an option to itself. Instead it treats it as a normal string to check. 💅

contains -i foo -q -- foo

This returns 3, since all arguments after the key are considered a value.

🔁 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's 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

🔢 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 number 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. Not one. Zero. It's giving minimalism.

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 history is highlighted using the color defined in the fish_color_history_current 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.

📚 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 — clears the directory stack instead of printing it out. bye bye stack bestie 💅
-h or --help — shows you help about using this command, and that's it.

dirs does not accept any arguments. nope, none, don't even try it 🙈

🎀 disown — remove a process from the list of jobs

Synopsis

disown [PID ...]

Description

disown removes the specified job <#syntax-job-control> from the list of jobs. The job itself keeps existing, but fish just... stops keeping track of it. no cap, it's giving "you're dead to me" but the process is still fully alive 😭 This makes 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 get sent a hang-up signal when fish terminates, which usually causes the job to terminate — disown is the thing that lets these processes carry on regardless, main character energy 👑

If no process is specified, the most recently-used job is removed (like bg and fg do). 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's sent a signal to continue running, and a warning is printed. Heads up: it is not possible to use the bg builtin to continue a job once it's 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. iconic behaviour honestly 🦋

disown (jobs -p) removes all jobs from the job list without terminating them. chef's kiss ✨

🌸 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 a STRING of text. that's it. that's the whole vibe 🎀

The following options are available:

-n — do not output a newline.
-s — do not separate arguments with spaces.
-E — disable interpretation of backslash escapes (this is the default).
-e — enable interpretation of backslash escapes.

Unlike other shells, this echo accepts -- to signal the end of the options. slay for boundaries 💅

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

⭐ 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's not 0 and else is given, COMMANDS_FALSE will be executed. it's giving "plan B" energy 🙈

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 — special functions called event handlers <#event>. The arguments are passed to the event handlers as function arguments. lowkey the group chat of fish internals 💜

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. sorry bestie, no cross-shell gossip 🫶

🦋 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 status after it will be the status returned by the most recent command. so like, end is not the main character here, it's just closing the door politely 🚪✨

💜 eval — evaluate the specified commands

Synopsis

eval [COMMANDS ...]

Description

eval evaluates the specified parameters as a command. If more than one parameter 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 instead.

If no piping or other compound shell constructs are required, variable-expansion-as-command, as in set cmd ls -la; $cmd, is also an option. options on options bestie 😌

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. it's literally the "I'm leaving and not coming back" of builtins 😭

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 exits, 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. plot twist: you thought it was over but it's not 🫶

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 general, the set builtin should be used instead. ngl it's giving "old reliable from another era" 🧚

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

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 <#cartesian-product>. Quote it, like so:

export PATH="$PATH:/opt/bin"

Or just use set, which avoids this:

set -gx PATH $PATH /opt/bin

See more

The set command.

🌈 false — return an unsuccessful result

Synopsis

false

Description

false sets the exit status to 1. that's it. anti-slaying on purpose 💀

✨ fg — bring job to foreground

Synopsis

fg [PID]

Description

The fg builtin brings the specified job <#syntax-job-control> to the foreground, resuming it if it's 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. bringing things to the front like a true main character 👑

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 <#intro> 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. ok so this is the moment where we meet the icon herself 🌸

The following options are available:

-c or --command=COMMAND — evaluate the specified commands instead of reading from the commandline. Any additional positional arguments are used as $argv.
-C or --init-command=COMMANDS — evaluate specified commands after reading the configuration but before executing command specified by -c or reading interactive input.
-d or --debug=DEBUG_CATEGORIES — enables debug output and specify a pattern for matching debug categories. See Debugging below for details.
-o or --debug-output=DEBUG_FILE — specifies a file path to receive the debug output, including categories and fish_trace <#envvar-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 <#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, --features=FEATURES — turns on one or more feature flags, comma-separated bestie.

The fish exit status is, like, generally the exit status of the last foreground command. That's the vibe. 💅

🐛 Debugging

So fish has extensive support for debugging fish scripts, but plot twist: you can also debug and instrument its internals. Iconic, honestly.

You turn it on with the --debug option. Like, this command turns on debugging for background IO thread events, on top of the default categories — which are debug, error, warning, and warning-path:

> fish --debug=iothread

Wanna know what categories exist? fish --print-debug-categories lists them all, no cap. The --debug option takes a comma-separated list of categories and supports glob syntax 🦋. This one turns on debugging for complete, history, history-file, and profile-history, plus the default categories:

> fish --debug='complete,*history*'

Debug messages go to stderr by default. Note that if fish_trace is set, execution tracing also outputs to stderr by default. You can send it to a file instead with the --debug-output option:

> fish --debug='complete,*history*' --debug-output=/tmp/fish.log --init-command='set fish_trace on'

You can also change these options via the FISH_DEBUG and FISH_DEBUG_OUTPUT variables. The categories enabled via --debug get added to the ones enabled by $FISH_DEBUG, so you can disable them by prefixing with - — reader-*,-ast* enables reader debugging and disables ast debugging, periodt.

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, bestie:

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

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 the simple girl's 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 you pass the --path switch).

By default it's safe to use fish_add_path in config.fish, or you can use it once, interactively, and the paths stay in future because of universal variables. It's a "do what I mean" style command — it tries to do the right thing by default and follows your lead on what you've already set up (like, it'll use a global fish_user_paths if you already have that). If you need more control, consider modifying the variable yourself, no biggie.

Directories are normalized with realpath. Trailing slashes are ignored and relative paths are made absolute (but symlinks are not resolved). If a directory is already included, it's not added again and stays in the same place — unless you give the --move switch. 💫

Directories are added in the order they're given, and they're prepended to the path unless --append is given. If $fish_user_paths is used, that means they're 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 that 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. Considerate queen behaviour. 🫶

If an argument is not an existing directory, fish_add_path just ignores it.

Options

-a, --append — add directories to the end of the variable.
-p, --prepend — add directories to the front of the variable (this is the default).
-g, --global — use a global fish_user_paths.
-U, --universal — use a universal fish_user_paths — this is the default if it doesn't already exist.
-P, --path — manipulate PATH directly.
-m, --move — move already-included directories to the place they would be added — by default they'd be left in place and not added again.
-v, --verbose — print the set command used, plus some more warnings, like when a path is skipped because it doesn't exist or isn't a directory. Verbose mode is automatically enabled when fish_add_path is used interactively and the output goes to the terminal.
-n, --dry-run — print the set command that would be used, without executing it.
-h, --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 used when fish asks for input in response to a breakpoint command. Yes, that's the actual name, iykyk. 🧚

The exit status of commands inside fish_breakpoint_prompt will not modify the value of $status outside of the fish_breakpoint_prompt function. So cute, so contained. 💜

fish ships with a default version of this function that displays the function name and line number of the current execution context.

Example

A simple prompt that's 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. Iconic.

If stdin is not a terminal (see isatty), it reads all input from there and copies it. If it is a terminal, it uses the current commandline — or the current selection if there is one. ✨

It's 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, bestie.

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

🌸 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. The reverse slay. 💅

If its stdout is not a terminal (see isatty), it outputs everything there, as-is, without any additional newlines. If it is a terminal, it puts the text in the commandline instead.

If it outputs to the commandline, it automatically escapes the output if the cursor is currently inside single-quotes, so it's suitable for single-quotes (meaning it escapes ' and \). 🎀

It's 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)

🌈 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. The dramatic entrance, basically. 💀

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, main character energy. 👑

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:

okay so you can absolutely swap in your own little handler, and here’s the vibe:

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

💖 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 literally the configure-fish tool, bestie.

With no arguments, or with the browse command, it starts the web-based configuration interface. That web interface lets you view your functions, variables and history, and make changes to your prompt and color configuration. It starts a local web server and opens a browser window. When you’re finished, close the browser window and press Enter 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 (#envvar-fish_terminal_color_theme) will be applied (also whenever that variable changes). To override fish_terminal_color_theme (#envvar-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 (#variables-universal). A theme set this way will not update as fish_terminal_color_theme (#envvar-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 directory, 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 (#term-compat-query-background-color) (where fish_terminal_color_theme (#envvar-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 (#configuration) to set the prompt.

fish_config prompt save saves the current prompt to an autoloaded (#syntax-function-autoloading) file.

fish_config prompt save default chooses the default prompt and saves it.

🦋 fish_darcs_prompt - output Darcs information for use in a prompt

Synopsis

fish_darcs_prompt

   function fish_prompt
        printf '%s' $PWD (fish_darcs_prompt) ' $ '
   end

Description

The fish_darcs_prompt function displays information about the current Darcs repository, if any.

Darcs (https://darcs.net/) must be installed.

The prompt always shows the VCS name (configurable via $fish_prompt_darcs_name, default darcs) as there are no branches/channels; it can be unset to remove it entirely. If the repository has unrecorded changes, status counts are shown for each change type:

$fish_color_darcs_normal, default green (the prompt label color)
$fish_color_darcs_rebasing, default yellow (used when a rebase is in progress)

To match Darcs’s logo green:

set fish_color_darcs_normal 72ff01

The Darcs status symbols:

$fish_prompt_darcs_status_added, default +
$fish_prompt_darcs_status_modified, default *
$fish_prompt_darcs_status_removed, default -
$fish_prompt_darcs_status_moved, default →
$fish_prompt_darcs_status_untracked, default …
$fish_prompt_darcs_status_conflict, default !

Colors for these symbols can be set with the corresponding variables ($fish_color_darcs_added & so on), which are unset by default so the terminal’s foreground color is used.

$fish_prompt_darcs_status_order can be used to change the order the status symbols appear in. It defaults to added removed modified moved conflict untracked.

See also fish_vcs_prompt (<>), which will call all supported version control prompt functions, including Git, Mercurial, & Darcs.

Example

A simple prompt that displays darcs info:

function fish_prompt
    ...
    printf '%s %s$' $PWD (fish_darcs_prompt)
end

🌈 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 (#emacs-mode).

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 (#envvar-fish_function_path) for functions and fish_complete_path (#envvar-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, otherwise 0.

Options

The following options are available:

-f or --no-functions — Skips checking functions
-c or --no-completions — Skips checking completions
-C or --no-config — Skips 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 default 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, including 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 default value is " (%s)".

Ngl bestie, there are so many customization options here, and you can control all of them either with git options or with fish variables. And listen — git options, where available, take precedence over the fish variable with the same function. 👑 They can be set on a per-repository or global basis, set with the git config command, while fish variables get set as usual with the set command. Two roads, same destination, but git wins the tiebreak. 💅

Boolean options (the ones that enable or disable stuff) understand "1", "yes" or "true" to mean true — and every other value means false. Periodt.

$__fish_git_prompt_show_informative_status or the git option bash.showInformativeStatus — set it to 1, true or yes to enable the "informative" display, which shows 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 (✚ instead of * for the dirty state, for example), and if you are only interested 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_showuntrackedfiles or the git option bash.showUntrackedFiles.

$__fish_git_prompt_showdirtystate or the git option bash.showDirtyState — 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.showUntrackedFiles — 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 determine 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 characters 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/revert/bisect or cherry-pick is in progress
$__fish_git_prompt_char_cleanstate (✔ in informative mode) — the character to be used when nothing else applies
$__fish_git_prompt_color_cleanstate (no default)

Variables used with showdirtystate:

$__fish_git_prompt_char_dirtystate (*, ✚) — the number of "dirty" changes, i.e. unstaged files with changes
$__fish_git_prompt_char_invalidstate (#, ✖) — the number of "unmerged" changes, e.g. additional changes to already added files
$__fish_git_prompt_char_stagedstate (+, ●) — 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 ($, ⚑)
$__fish_git_prompt_color_stashstate (same as color_flags)

Variables used with showuntrackedfiles:

$__fish_git_prompt_char_untrackedfiles (%, …) — 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 (>, ↑) — the character for the commits this repository is ahead of upstream
$__fish_git_prompt_char_upstream_behind (<, ↓) — the character for the commits this repository is behind upstream
$__fish_git_prompt_char_upstream_diverged (<>, ↓↑) — 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 example, 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. Easy.

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

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. Main character energy: it knows when to show up and when to stay home. 💅

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 Mercurial repository, if any. 🌸

Mercurial (hg) must be installed, no cap.

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 options, which can be controlled with fish variables. 😭

$fish_color_hg_clean, $fish_color_hg_modified and $fish_color_hg_dirty — 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 '✚'
$fish_prompt_hg_status_modified, default '*'
$fish_prompt_hg_status_copied, default '⇒'
$fish_prompt_hg_status_deleted, default '✖'
$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 order 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. It reads commands from standard input or the given filenames and outputs them to standard 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, --no-indent — literally just don't indent anything bestie 💅 it still reformats so each job gets its own line, but no nesting vibes.
--only-indent — no reformatting at all, it only indents each line. That's the whole gig.
--only-unindent — opposite queen behavior: no reformatting, it just unindents each line.
-c, --check — doesn't indent anything, it just vibe-checks: returns 0 if the code is already indented the way fish_indent would do it, and otherwise returns the number of failed files 😭 also it prints the failed filenames if it's not reading from standard input.
-v, --version — shows the current fish version and then dips out. periodt.
--ansi — colorizes the output using ANSI escape sequences, pulling the colors defined in the environment (like fish_color_command <#envvar-fish_color_command>). cute output slay.
--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 info about the parsed statements to standard error. this one is likely only interesting to people working on the fish source code 🫶 iykyk.
-h, --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 checks if the current user is root 👑 it's lowkey useful for your prompt, so you can display something different when the user is root, for example.

Example

A simple example, served fresh:

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 the bestie that explains how you would bind a certain key sequence ✨ by default it prints the bind <> command for one key sequence that it reads interactively over standard input.

The following options are available:

-c, --continuous — begins a session where multiple key sequences can be inspected 💅 by default the program exits after capturing a single key sequence.
-h, --help — displays help about using this command.
-V, --verbose — explains what sequence was received in addition to the decoded key. extra detail, we love it.
-v, --version — displays the current fish version and then exits.

Usage Notes

okay so real talk: fish_key_reader intentionally disables handling of many signals 🙈 to terminate fish_key_reader when it's in --continuous mode, do one of these:

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 outputs indicators about the current vi editor mode, displayed to the left of the regular prompt. Define your own function to customize how the mode indicator looks 💖 the $fish_bind_mode variable can be used to determine the current mode — it's gonna 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 entirely:

function fish_mode_prompt; end
funcsave fish_mode_prompt

fish_mode_prompt gets executed when the vi mode changes. If it produces any output, that output is displayed and used ⭐ if it doesn't, the other prompt functions (fish_prompt <> and fish_right_prompt <>) get executed as well, just in case they contain a mode display.

If fish_transient_prompt <#envvar-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

🫶 heads up bestie: 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 gives you a way to produce option specifications that are suitable for use with the argparse <> command 🎀 you can, of course, write the option specifications 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, --short ALPHANUM — takes a single letter or number used as the short flag in the option being defined. Either this option or the --long option must be provided.
-l, --long LONG-NAME — takes a string used as the long flag in the option being defined. This option is optional and has no default 🫶 if no long flag is defined, then only the short flag will be allowed when parsing arguments 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, --optional-val — the option being defined can take a value, but that value is optional rather than required. If the option is seen more than once when parsing arguments, only the last value seen is saved 💅 that means the resulting flag variable created by argparse will have zero elements if no value was given with the option, else it will have exactly one element.
-r, --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. That means the resulting flag variable created by argparse will have exactly one element.
-m, --multiple-vals — the value of each instance of the option is accumulated. If --optional-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. That 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, --delete — the option and any values will be deleted from the $argv_opts variables set by argparse (and, as with other options, it will also be deleted from $argv).
-v, --validate COMMAND OPTION... — this option must be the last one, and it requires one of -o, -r, or -m 😤 all the remaining arguments are interpreted as a fish script to run to validate the value of the argument — see the argparse documentation for more details. ngl, note that the interpretation of COMMAND OPTION... is similar to eval, so you may need to quote or escape special characters twice if you want them interpreted literally when the validate script is run.
-h, --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 defined:

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 its output is used as the prompt 💅 main character energy fr fr.

The exit status of commands within fish_prompt will not modify the value of $status <#variables-status> outside of the fish_prompt function 🫶 good to know.

If fish_transient_prompt <#envvar-fish_transient_prompt> is set to 1, fish_prompt --final-rendering is run before executing the commandline.

If SHELL_PROMPT_PREFIX <#envvar-SHELL_PROMPT_PREFIX> or SHELL_PROMPT_SUFFIX <#envvar-SHELL_PROMPT_SUFFIX> are set, they're automatically 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 you can choose with the fish_config command 🎀 go pick one, it's giving customization.

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 🦋 symmetrical queen.

😭 multiple lines are not supported in fish_right_prompt.

If fish_transient_prompt <#envvar-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
    date '+%m/%d/%y'
end

🫶 `fish_should_add_to_history` — decides if a command gets to be in your history

Synopsis ✨

fish_should_add_to_history

function fish_should_add_to_history
    ...
end

Description 💖

So fish_should_add_to_history runs right before fish tucks a command into your history, and its return status is the vibe check that decides if it actually goes in.

Return 0 and boom — command is saved, it's iconic, it's staying. Return literally anything else and nope, not saved. But bestie, the plot twist: in that case the command can still be recalled for one command. So it's not totally gone, it's just not moving in.

The first argument to fish_should_add_to_history is the commandline. And heads up: history is added before a command is run, so like… status (#envvar-status) can't be checked. That's on purpose — it's so that commands that don't finish, like exec (execute command in current process, #cmd-exec) and long-running commands, are available in new sessions immediately. iykyk.

If fish_should_add_to_history doesn't exist, fish will save a command to history unless it starts with a space. But if the function does exist, it takes over all of the duties — which means commands starting with a space get saved unless fish_should_add_to_history says otherwise. Yeah. That's a whole thing. 👑

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. Commands 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` — turns exit codes into 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 into their corresponding human-friendly signals, if one exists. This is lowkey perfect for prompts, paired up with the $status and $pipestatus variables. Chef's kiss. 😚

Example ⭐

>_ sleep 5
^C⏎
>_ fish_status_to_signal $status
SIGINT

🧚 `fish_svn_prompt` — shows off your Subversion info in the 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 Subversion repository, if any. Slay.

Subversion (https://subversion.apache.org/) — that's svn — must be installed. Non-negotiable.

There are numerous customization options, and you control them all with fish variables. Periodt.

__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 whole bunch 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 (#cmd-fish-vcs-prompt) — it calls all the supported version control prompt functions, including git, Mercurial and Subversion. One function to rule them all. 👑

Example 🌈

A simple prompt that displays svn info:

function fish_prompt
    ...
    printf '%s %s$' $PWD (fish_svn_prompt)
end

🎀 `fish_tab_title` — sets your terminal tab's title

Synopsis ✨

fish_title
fish_tab_title

function fish_title
    ...
end

function fish_tab_title
    ...
end

Description 💖

The fish_title function gets executed before and after a new command is executed or put into the foreground, and the output becomes the titlebar message.

The first argument to fish_title contains the most recently executed foreground command as a string, if any.

This requires that your terminal supports programmable titles (#term-compat-osc-0) and that the feature is turned on.

To disable setting the title, use an empty function (see below). Yes, just. Nothing. Iconic behaviour honestly.

To set the terminal tab title to something other than the terminal window title, define the fish_tab_title function — it works like fish_title but overrides it.

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` — sets your terminal's title

Synopsis ✨

fish_title
fish_tab_title

function fish_title
    ...
end

function fish_tab_title
    ...
end

Description 💜

(Yes bestie, this one looks a lot like the last one — that's just how the docs are built. No cap, it's the same deal:)

The fish_title function gets executed before and after a new command is executed or put into the foreground, and the output is used as the titlebar message.

The first argument to fish_title contains the most recently executed foreground command as a string, if any.

This requires that your terminal supports programmable titles (#term-compat-osc-0) and that the feature 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` — builds completions out of manual pages

Synopsis ✨

fish_update_completions

Description 💅

fish_update_completions parses the manual pages installed on your system and attempts to create completion files in the fish configuration directory. Free completions, basically. We love a resourceful queen. 👑

This does not overwrite custom completions. Your hand-crafted stuff stays untouched, as it should.

There are no parameters for fish_update_completions. None. Zero. Nada.

🌈 `fish_vcs_prompt` — all your version control info, in your 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 (#cmd-fish-git-prompt)
fish_hg_prompt (#cmd-fish-hg-prompt)
fish_darcs_prompt (#cmd-fish-darcs-prompt)
fish_svn_prompt (#cmd-fish-svn-prompt)

If a VCS isn't installed, the respective function does nothing. It just minds its business.

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 (#cmd-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` — sets up 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. Vim girlies, this one's for you.

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 (#vi-mode).

Differences from Vim ⭐

fish's vi mode aims to be familiar to vim users, but there are some differences. Bet.

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. Not me learning this the hard way 💀

Examples 🌸

To start using vi key bindings:

fish_vi_key_bindings

or set -g fish_key_bindings fish_vi_key_bindings in config.fish (#configuration).

🧚 `for` — runs a set of commands multiple times

Synopsis ✨

for VARNAME in [VALUES ...]; COMMANDS ...; end

okay so for?? it's a loop construct, bestie 💅 it runs the commands you give it (COMMANDS) over and over, multiple times. Every single iteration, the local variable VARNAME gets a fresh new value from VALUES. And if VALUES is empty? Then COMMANDS don't get executed at all — not even once, nada, nothing 🙈

VARNAME stays visible when the loop terminates, and it'll contain the last value that got assigned to it. If VARNAME doesn't already exist, it gets set in the local scope. For our purposes, if the for block lives inside a function, there must be a local variable with the same name. And if the for block is not nested inside a function, then global and universal variables of that same name get used if they exist.

Much like set, for does not modify $status — but the evaluation of its subordinate commands totally 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 🌸

VARNAME was local to the for block in releases prior to 3.0.0. Which means if you did something like this:

for var in a b c
    if break_from_loop
        break
    end
end
echo $var

then the last value assigned to var when the loop terminated would not be available outside the loop 😭. What echo $var would write depended entirely on what it was set to before the loop ran. Likely nothing.

🦋 funced — edit a function interactively

Synopsis

funced [OPTIONS] NAME

Description

funced gives you an interface to edit the definition of the function NAME.

If the $VISUAL environment variable is set, that's what gets used as the program to edit the function. If $VISUAL is unset but $EDITOR is set, that one gets used instead. Otherwise, a built-in editor is used. Heads up though: to enter a literal newline in the built-in editor you gotta press alt+enter. Pressing enter signals that you're 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 gets created in the user's function directory.

If there's no function called NAME, a new function gets created with the specified name.

-e command, --editor command — open the function body inside the text editor given by the command (for example, -e vi). The special command fish uses the built-in editor (same as specifying -i).
-i, --interactive — force opening the function body in the built-in editor even if $VISUAL or $EDITOR is defined.
-s, --save — automatically save the function after successfully editing it.
-h, --help — displays help about using this command.

💖 Example 💖

Say you wanna modify your prompt. Run:

>_ funced fish_prompt

This opens up your editor, letting you 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. That function then gets automatically loaded by current and future fish sessions. This can be useful to commit functions you created interactively so they stick around permanently. 💅

If you've 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 get executed when the name of the function is given as a command.

The following options are available:

-a NAMES, --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 they're still available there (unless --inherit-variable argv was used or one of the given NAMES is argv). See also Argument Handling.
-d DESCRIPTION, --description DESCRIPTION — a description of what the function does, suitable as a completion description.
-w WRAPPED_COMMAND, --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 function name, this will be ignored.
-e EVENT_NAME, --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, --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 skipping 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, --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 substitution, 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, --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, --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 example, ctrl-c sends SIGINT to the foreground process group, which will not be fish if you're running another command at the time. Observing a signal will prevent fish from exiting in response to that signal.
-S, --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 variables or the scope at the time of function declaration! At this time, fish does not have any concept of closures, and variable lifetimes are never extended. In other words, by using --no-scope-shadowing 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, --inherit-variable NAME — snapshots the value of the variable NAME and defines a local variable 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.

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

Care should be taken when creating a function with the same name as an existing shell builtin or common program. If the function behaves differently, it is very common for problems to occur within fish or in scripts written by others 😭. Consider writing an abbreviation if you're wanting to replace one tool with another for interactive use.

🌈 Example 🌈

function ll
    ls -l $argv
end

will run the ls command, using the -l option, while passing on any additional 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

okay so what this lil beauty does 💅 — it runs mkdir, and if that works out, it changes your current working directory to the one it just created. iconic behavior honestly.

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

and this one will beep 🎀 when your most recent job finishes. no cap, it just does.

🦋 Notes

Events are only received from the current fish process — there's literally no way to send events from one fish process to another. so like, don't try it bestie 😭

🌸 See more

For more explanation of how functions fit into fish, see Functions <#syntax-function>.

💜 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. that's the whole vibe ✨

The following options are available:

-a or --all — Lists all the functions, even the ones whose name starts with an underscore 🙈 (you know, the shy ones).
-c or --copy OLDNAME NEWNAME — Creates a new function named NEWNAME, using the definition of the OLDNAME function. a lil clone situation 👯
-d or --description DESCRIPTION — Changes the description of this function. give it a glow-up ✨
-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 function was created via source <>, and n/a if the function isn't available. (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.

⚠️ bestie pls do NOT assume that only five lines will be written, since we may add additional information to the output in the future. five is just what you get today.

--no-details — Turns off function path reporting, so just the definition will be printed. keep it simple 🎀
-n or --names — Lists the names of all defined functions. just names, no lore.
-q or --query — Tests if the specified functions exist. a lil vibe check 👀
-v or --verbose — Make some output more verbose. spill more tea 🍵
-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 function 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. so the clone is body-only, no personality transfer 😌

Only one function's description can be changed in a single invocation of functions -d. one at a time, bestie.

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. so like, count of the missing ones 🔥

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 <#syntax-function>.

🎀 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 <#envvar-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 terminal 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 <#history-search>. it's the group chat archive of your shell, fr fr 💬

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 explicitly 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 function. 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 asking 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. Ordinarily fish ignores history changes from sessions started after the current one. This command applies those changes immediately. merging the timelines basically ⏳
save — Immediately writes all changes to the history file. The shell automatically saves the history file; this option is provided for internal use and should not normally need to be used by the user. so like, hands off unless you know what you're doing 🫶
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. 💀 this one's forever, bestie.
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. sneaky lil queued-up entries 👀

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 currently 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 subcommand. Note that the match is case-insensitive by default. If you really 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 strftime 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 terminated by a NUL character rather than a newline. This allows the output 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 entries. 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 — decides when the history entries get their cute little syntax-highlight colors. WHEN can be auto (the default — colorize if the output is a terminal), always, or never.
-h or --help — shows you the help for this command. Iconic of it honestly.

🌸 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

So by default, your interactive commands get logged to $XDG_DATA_HOME/fish/fish_history — which is typically ~/.local/share/fish/fish_history. Yes bestie, everything you type lives there. 💀

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 corresponds 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. And an empty string means history will not be stored at all — this is similar to the private session features in web browsers. Incognito mode but make it shell. 🙈

You can change fish_history at any time (by using set -x fish_history "session_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 similar 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 importing 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 presentation. Very mindful, very demure. 🫶

🦋 Notes

If you specify both --prefix and --contains the last flag seen is used. Last one wins, no cap.

Note that for backwards compatibility each subcommand can also be specified as a long option. For example, rather than history search you can type history --search. Those long options are deprecated and will be removed in a future release. So like… don't get attached. 😭

⭐ `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 accessed 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. Mother said make good choices!! And 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 wildcard and regular expression matches
path - manipulate and check paths — can check paths for permissions, existence 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). History lesson AND a utility, we love a multitasker. 💜

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. Silent but deadly (in a polite way).

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. Don't get it twisted bestie.

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%. Yes girl, math is mathing. 😭

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 substitution, the column header that is usually printed is omitted, making it easier 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(). She does it all. 💅

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 evaluated. 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 escaped 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 because it tries to give sin the arguments 3 and 5. When in doubt, use parentheses. Fr fr, just use them.

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 internally 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. She's a humble queen, know her limits. 🙈

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 specified number of decimal places.
-b BASE or --base BASE — sets the numeric base used for output (math always understands hexadecimal 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, ceiling. 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 available.

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. Aesthetic AND functional, we stan. ✨

🦋 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, bestie:

e — Euler's number
pi — π, you know this one. Half of Tau
tau — equivalent to 2π, 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, and yes, there are a lot of them:

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 operations 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 360°).

💖 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 multiplied 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 expressions. 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 expression.

🏃 `nextd` — move forward through directory history

Synopsis

nextd [-l | --list] [POS]

Description

nextd moves forwards POS positions in the history of visited directories <#directory-history>; 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 variables 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

🎀 `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 optional 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

🛤️ `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 recommended when the output goes to the terminal or a command substitution.

All subcommands also accept a -z or --null-in switch, which makes them accept 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 automatically 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 removing 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 "filename".

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) removed, 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 ...]

Okay bestie, path dirname gives you the dirname for the path you hand it. It's literally the part before the last /, with trailing slashes ignored. Another way to say it? It's the chunk that is not the basename (again, ignoring extra slashes like they're yesterday's drama).

It returns 0 if there was a dirname, meaning the path wasn't empty and wasn't 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. That's the part after — and including — the last ., unless that . came right after a /, or the basename is . or ... In those cases there is no extension and it prints an empty line. No cap.

If the filename ends in a ., then only a . is printed. That's it, that's the whole vibe.

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 the given paths that match the checks you asked for. In every case, the paths need to exist — nonexistent paths are always filtered out. Sorry, ghost files, you're not passing this vibe check.

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, respectively.
-d, -f and -l are short for --type=dir, --type=file and --type=link, respectively. 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" (referring 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. That's because a path that's both writable and executable makes sense — but a path that's both a directory and a file does not. Links count as the type of the linked-to file, so links to files count as files, and links to directories count as directories.

The filter options can be given as multiple options or comma-separated: path filter -t dir,file and path filter --type dir --type file are equivalent.

With --invert, the meaning of the filtering is flipped — 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. Protecting the command from confusion, iconic behavior honestly.

It returns 0 if at least one path passed the filter.

With --all, it returns 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. Silent but judging.

When --all is 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 producing 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 it does not produce any output. It's the quiet friend who just nods yes or no.

--quiet can still be passed for compatibility, but it's 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 — aka the beginning of the 1st of January 1970. Time travel but make it filesystem metadata.

With --relative (or -R), it prints the number of seconds since the modification time. It only reads the current time once at the start, so if multiple paths are given, all the times are relative to the start of path mtime -R running.

If you want to know whether 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. Cleanup era.

Unlike realpath or path resolve, it does not make the paths absolute. It also does not resolve any symlinks. Because of that, it can operate on non-existent paths. It's working with the string, not doing a full detective arc through your filesystem.

Since it operates on paths as strings and doesn't resolve symlinks, it works sort of like pwd -L and cd. For example, 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. if any given path wasn't already 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: squashes duplicate /, collapses ../ with earlier components, and removes . components. Then it turns that path into the absolute path starting from the filesystem root /. Full main character transformation.

It's similar to realpath, since it creates the "real", canonical version of the path. However, for paths that can't be resolved — like if they don't exist or form a symlink loop — it will resolve as far as it can and normalize the rest. It doesn't just give up dramatically.

Because it resolves symlinks, it works sort of like pwd -P. For example, path resolve 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. if 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 new extension. The extension is the part after — and including — the last ., unless that . followed a / or the basename is . or ... In those cases there is no previous extension, and the new one is added. Glow-up for your filenames.

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

So path sort hands you back the paths you gave it, but sorted. ✨ And the sort order is exactly the same order as globs — alphabetically, but with runs of numerical digits compared numerically. So 10-foo comes after 2-bar because ten is bigger than two, bestie. Math slays. 💅

Hit it with --reverse or -r and the whole thing flips. 🔄

With --key= only that chunk of the path gets compared — like, --key=dirname means only the dirname is compared, --key=basename means only the basename, and --key=path compares the entire path (this is the default, iykyk).

With --unique or -u the sort gets deduplicated, which means only the first of a run that shares the same key is kept. So if you're sorting by basename, only the first of each basename survives. 🫶

The sort is stable, so sorting first by basename and then by dirname works and gets the files grouped according to directory. Iconic behaviour, no cap.

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 literally designed to be easy to combine — with itself, with other tools, and with fish. 🦋

Which is why:

path's output is automatically split by fish if it goes into a command substitution, so just doing (path ...) handles all paths correctly, even those containing newlines
path has --null-in to handle null-delimited input (typically automatically 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 yanks the top directory off the directory stack and changes the working directory to the new top directory. 🎀 Use pushd to add directories to the stack in the first place.

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

⏪ prevd — move backward through directory history

Synopsis

prevd [-l | --list] [POS]

Description

prevd moves backwards POS positions in the history of visited directories. 🕰️ And if you've hit the beginning of the history? It prints a warning. Rude but fair.

If the -l or --list flag is specified, the current history is also displayed. 👀

Heads up bestie: 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.

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

🖨️ printf — display text according to a format string

Synopsis

printf FORMAT [ARGUMENT ...]

Description

NOTE: This page documents the fish builtin printf. To see the documentation on any non-fish versions, use command man printf.

printf uses the format string FORMAT to print the ARGUMENT arguments. Basically it takes format specifiers in the format string and swaps each one out for 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. fr fr, it just keeps going.

Unlike echo, printf does not append a new line unless you specify it as part of the string. 😤

It doesn't support any options, so there's 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 escapes 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're okay with losing information, silence errors with 2>/dev/null.

A number between the % and the format letter specifies the width. The result 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. Trooper behaviour honestly. 🫡

It will also return non-zero if no argument at all was given, in which case it prints nothing.

This printf has been imported from the printf in GNU Coreutils version 6.9. If you'd 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 expects 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.

📎 Footnotes

[1] In fact, while fish's echo supports --, POSIX forbids it, so other implementations 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 of the current hostname, for use in the prompt. It'll print just the first component of the hostname — everything 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

Synopsis

prompt_login

Description

prompt_login is a function to describe the current login. It'll 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 that prints the current working directory in a way that's suitable for prompts. It replaces the home directory with "~" and shortens every path component but the last one 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, --dir-length MAX — Causes the components to be shortened to MAX characters each. This overrides fish_prompt_pwd_dir_length.
-D, --full-length-dirs NUM — Keeps NUM components (counted from the right) as full length without shortening. This overrides fish_prompt_pwd_full_dirs.
-h, --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 ✨

okay so bestie, some shells — literally ksh and bash, e.g. — have this syntax that's a mix between command substitution and piping, and it's 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 — nope, it goes 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, gorgeous:

-f, --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, --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, --suffix SUFFIX — Append SUFFIX to the filename.
-h, --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 <#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

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. Literally its whole job. 💅

The following options are available:

-L, --logical — Output the logical working directory, without resolving symlinks (default behavior).
-P, --physical — Output the physical working directory, with symlinks resolved.
-h, --help — Displays help about using this command.

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

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 statistically 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 example, for use in command substitutions. Cute, right? 💖

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 storing 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, --universal — Sets a universal variable. The variable will be immediately available to all the user's fish instances on the machine, and will be persisted across restarts of the shell.
-f, --function — Sets a variable scoped to the executing function. It is erased when the function ends.
-l, --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, --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, --unexport — Prevents the variables from being exported to child processes (default behaviour).
-x, --export — Exports the variables to child processes.

The following options control the interactive mode:

-c CMD, --command CMD — Sets the initial string in the interactive mode command buffer to CMD.
-s, --silent — Masks characters written to the terminal, replacing them with asterisks. This is useful for reading things like passwords or other sensitive information.
-p PROMPT_CMD, --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 PROMPT_STR, --prompt-str PROMPT_STR — Uses the literal PROMPT_STR as the prompt for the interactive mode.
-R RIGHT_PROMPT_CMD, --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, --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 DELIMITER, --delimiter DELIMITER — Splits on DELIMITER. DELIMITER will be used as an entire string to split on, not a set of characters.
-n NCHARS, --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 tokenization 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 <#envvar-IFS> (like fish's tokenizer). The -t -or --tokenize variants perform quote removal, so e.g. a\ b is stored as a b. However variables and command substitutions are not expanded.
-a, --list — Stores the result as a list in a single variable. This option is also available as --array for backwards compatibility.
-z, --null — Marks the end of the line with the NUL character, instead of newline. This also disables interactive mode.
-L, --line — Reads each line into successive variables, and stops after each variable has been filled. This cannot be combined with the --null option, or options to control splitting like --delimiter.

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 complete remainder is assigned to the last variable.

If no option to determine how to split like --delimiter, --line or --tokenize 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 removed 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.

ok so if you don't hand read any variable names at all, it flips into a whole special mode 👀 — it just redirects standard input straight to standard output, which is lowkey perfect for command substitution. Like, this fish command right here reads your password from the console instead of you hardcoding it into the command itself, which keeps it from showing up in fish's history:

mysql -uuser -p(read)

When it's running in this mode, read does not split the input in any way — the text gets redirected to standard output with no further processing or manipulation. Zero. None. Periodt. 💅

If you pass -l or --list, only one variable name is allowed, and the tokens get stored as a list inside that variable. 🎀

And because the shell needs protecting from eating up too many system resources, read will only consume a maximum of 100 MiB (104857600 bytes) 🌸 — if the terminator hasn't shown up before you hit that limit, VARIABLE gets set to empty and the exit status is set to 122 💀. You can change that limit with the fish_read_limit variable; set it to 0 (zero) and the limit is fully removed. ✨

🍓 Example 🍓

read has a few separate uses, bestie.

This one 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 you give 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 exactly like the shell's argument passing does 🔥:

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, go peek at 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. Wanna see the docs for any non-fish versions? Run command man realpath. 🫶

realpath follows all the symbolic links it encounters for the PATH you gave it, then prints the absolute path it resolved. fish ships a realpath-alike builtin, and the whole point is to enrich systems where no such command is installed by default. 🧚

If a realpath command does exist, that one will be preferred. If you want to force the fish implementation, builtin realpath explicitly uses it. 👑

The following options are available:

-s, --no-symlinks — don't resolve symlinks; only make the paths absolute, squash multiple slashes, and remove trailing slashes.
-h, --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 gets set to N if you gave one. And if return is invoked outside of a function or a dot script, it's equivalent to exit. 😌

It's often added inside a conditional block like an if statement or a switch statement, so you can conditionally stop the executing function and hand control back to the caller — it can also be used to specify the exit status of a function. 💅

If you're at the top level of a script, it exits with the given status, just like exit. If you're 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 [(-f | --function) (-l | --local) (-g | --global) (-U | --universal)]
    [(-x | --export) (-u | --unexport)]
set (-S | --show) (-L | --long) [NAME ...]

set [-Uflg] [-xu] [--no-event] NAME [VALUE ...]
set [-Uflg] [--no-event] NAME[[INDEX ...]] [VALUE ...]
set (-a | --append) (-p | --prepend) [-Uflg] [--no-event] NAME VALUE ...
set (-e | --erase) [-Uflg] [--no-event] NAME[[INDEX]] ...

set (-q | --query) [-Uflg] [-xu] NAME[[INDEX]] ...

💬 Description 💬

set manipulates shell variables. That's the whole gig. 💖

If you give it both NAME and VALUE, set assigns any values to the variable NAME. Variables in fish are lists, so multiple values are totally allowed. You can specify one or more variable INDEX, including ranges (not for all options though 👀).

If no VALUE is given, the variable gets set to the empty list.

If set runs with no arguments at all, it prints the names and values of all shell variables in sorted order. Passing scope or export flags filters that down to only matching variables — so set --local would only show local variables. ✨

With --erase and optionally a scope flag, set erases the matching variable (or the variable of that name in the smallest possible scope).

With --show, set describes the variable names you gave it, explaining how they've been defined — which scope, which values, which options. 🎀

The following options control variable scope:

-U or --universal — sets a universal variable. It'll be immediately available to all the user's fish instances on the machine, and it gets persisted across restarts of the shell.
-f or --function — sets a variable scoped to the executing function. It gets erased when the function ends.
-l or --local — sets a locally-scoped variable in this block. It gets erased when the block ends. Outside of a block, this is the same as --function.
-g or --global — sets a globally-scoped variable. Globals are available to all functions running in the same shell, and 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 — treats the specified variable as a path variable; the variable gets split on colons (:) and will be displayed joined by colons when quoted (echo "$PATH") or exported.
--unpath — causes the 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. 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 INDEX 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), it checks only variables that match. Doesn't 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's 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 handlers are usually set up for a reason. Possible uses include modifying 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 becomes a list with zero elements. 🦋

If the variable name is one or more list elements, like PATH[1 3 7], only those list elements you specified get changed. If you specify a negative index when expanding or assigning to a list variable, the index gets calculated from the end of the list. For example, 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 isn't 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 variable with the narrowest scope will be updated.
If a variable's scope isn't explicitly set and there's no existing variable by that name, the variable will be local to the currently executing function. Note that this is different from using the -l or --local flag — with those, the variable is local to the most-inner currently executing block, while without them the variable is local to the function as a whole. If no function is executing, the variable gets 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 isn't 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. periodt.

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

💅 Exit status

In assignment mode, set does not modify the exit status, but passes along whatever status <#envvar-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 variables did not exist or was a special read-only variable <#variables-special>.

🎀 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 controls the color and styling of text in the terminal. It writes non-printing color and text style escape sequences to standard output.

VALUE describes the 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 defaults, 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 standard-brightness colors on many terminals. brblack has higher brightness than black - towards gray. slay the palette 🌈

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 values can be in lower or uppercase.

If fish_term24bit <#envvar-fish_term24bit> is set to 0, fish will translate RGB values to the nearest color on the 256-color palette. If fish_term256 <#envvar-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 <#envvar-fish_term256> is set to 0, fish prefers the first named color specified.

The following options are available:

-f, --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, --background COLOR — Sets the background color.
--underline-color COLOR — Set the underline color.
-c, --print-colors — Prints the given colors or a colored list of the 16 named colors. It cannot be used with --foreground.
-o, --bold — Sets bold mode.
-d, --dim — Sets dim mode.
-i, --italics, or -iSTATE, --italics=STATE — Sets italics mode. The state can be on (default), or off.
-r, --reverse, or -rSTATE, --reverse=STATE — Sets reverse mode. The state can be on (default), or off.
-s, --strikethrough, or -sSTATE, --strikethrough=STATE — Sets strikethrough mode. The state can be on (default), or off.
-u, --underline, or -uSTYLE, --underline=STYLE — Set the underline mode; supported styles are single (default), double, 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 <#variables-color> that contain only this option are treated like missing / empty color variables, i.e. fish will use the fallback color instead. fish_config theme choose <> erases all color variable <#fish-config-color-variables> 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 <#envvar-fish_terminal_color_theme> changes.
-h, --help — Displays help about using this command.

🌸 Notes 🌸

Using set_color normal will reset all colors and modes to the terminal's default.
In contrast, set_color --foreground normal will only reset the foreground color and leave all the other colors and modes unchanged.
Because of the risk of confusion, set_color --reset is recommended over set_color normal.
Setting the background color only affects subsequently written characters. fish provides no way to set the background color for the entire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides. Look for a config option.
Some terminals use the --bold escape sequence to switch to a brighter color set rather than increasing the weight of text.
If you use set_color in a 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 colorize 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 perform the commands (i.e. fish < FILE) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the argv variable <#envvar-argv>. 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 <#envvar-PATH>.

If no file is specified and a file or pipeline is connected to standard input, 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 version of fish.

source creates a new local scope <#variables-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, --is-command-substitution — Returns 0 if fish is currently executing a command substitution.
is-block, -b, --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, --is-interactive — returns 0 if fish is interactive, like, actually connected to a keyboard. That's it, that's the check 💅
is-interactive-read, --is-interactive-read — returns 0 if fish is running an interactive read builtin that's hooked up to a keyboard.
is-login, -l, --is-login — returns 0 if fish is a login shell, meaning fish should do login things like setting up PATH. Very "first day of school" energy 🎒
is-full-job-control, --is-full-job-control — returns 0 if full job control is enabled.
is-interactive-job-control, --is-interactive-job-control — returns 0 if interactive job control is enabled.
is-no-job-control, --is-no-job-control — returns 0 if no job control is enabled. zero vibes, but valid 😌
current-command — prints the name of the currently-running function or command, just like the deprecated _ variable. rip to a real one 🫡
current-commandline — prints the entirety of the currently-running commandline, inclusive of all jobs and operators. the whole thing, no cuts 🔥
filename, current-filename, -f, --current-filename — prints the filename of the currently-running script. if the current script was called via a symlink, this returns the symlink. if the current script got here by piping into source, then this returns -. slay, very meta 🌀
basename — prints just the filename of the running script, with no path components before it. just the name, no lore ✨
dirname — prints just the path to the running script, without the actual filename itself. heads up: this can be relative to PWD (including just "."), depending on how the script was called. it's the same as passing the filename to dirname(3). super useful if you want to grab other files sitting in the current script's directory or similar 🗂️
fish-path — prints the absolute path to the currently executing instance of fish. it's a best-effort attempt, and the exact output is down to whatever the platform hands fish. in some cases you might only get "fish". no cap, that's just how it is 🙈
function, current-function — prints the name of the currently called function if it's able to. when it's missing, it displays "Not a function" (or the equivalent translated string). brutal but honest 💀
line-number, current-line-number, -n, --current-line-number — prints the line number of the currently running script. for when you need exactly where you are 📍
stack-trace, print-stack-trace, -t, --print-stack-trace — prints a stack trace of all function calls on the call stack. forensic girlboss behaviour 🕵️‍♀️
job-control, -j, --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. window shopping but for flags 🛍️
test-feature FEATURE — returns 0 when FEATURE is enabled, 1 if it's disabled, and 2 if it isn't recognized at all. three whole moods 🎭
build-info — prints info on how fish was built: which architecture, which build system or profile was used, etc. mainly useful for debugging. nerd lore unlocked 🔧
get-file FILE — prints a file embedded in the fish binary at compile time. this includes the default set of functions and completions, plus 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... — lists the files embedded in the fish binary at compile time. only files whose path starts with the optional FILE argument get 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). quick heads up: this is not available during early startup, only starting from when the first interactive prompt is shown — possibly via the builtin read — so that's 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 isn't available. it's giving "ask me later" 😭
test-terminal-feature FEATURE — returns 0 when the terminal was detected to support the given feature. like status terminal, this only works once the first interactive prompt is shown. currently the only available FEATURE is scroll-content-up. an error will be printed when you pass it an unrecognized feature 🚨
language — show or modify message localization settings. when invoked with no arguments, the current language settings are shown. available subcommands:
- list-available — prints the language names for which fish has translations. these names can be used with the set subcommand.
- set — sets the language precedence for fish's messages. it overrides language settings configured via environment variables, but it only applies 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 those languages. so, we allow specifying a list here, with translations taken from the first specified language that 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 specified languages have a translation available for a message, the message will be shown in English. layered like an outfit, honestly 👗
- unset — undoes the effects of the set subcommand. language settings get taken from environment variables again. rewind time ⏪

📝 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. so like, enjoy them while they last 🫶

you can only specify one subcommand per invocation, even if you use the flag form of the subcommand. one at a time, bestie, we're not doing a mega-combo here 🚫

🧵 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. that's the whole brand, honestly ✨

STRING arguments are taken from the command line — unless standard input is connected to a pipe or a file, in which case they're read from standard input, one STRING per line. it is an error to supply STRING arguments on the command line and on standard input. pick a lane, babe 😤

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

most subcommands accept a -q or --quiet switch, which suppresses the usual output but still exits with the documented status. in that case these commands will quit early, without reading all of the available input. you asked for silence, you get silence 🤫

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 you're trying to collect multiline output from another command into a variable. 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 former evaluates to zero or one elements, whereas the quoted command substitution always evaluates to one element due to string interpolation. subtle but iconic 💅

if invoked with multiple arguments instead of input, string collect preserves each argument separately, where the number of output arguments equals the number of arguments given to string collect. one in, one out, no funny business 🫡

any trailing newlines on the input are trimmed, just as with "$(cmd)" substitution. 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. keeping the ghost slot occupied 👻

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

Okay so string escape escapes each STRING in one of several ways, bestie. Pick your flavor:

--style=script — the default. It alters the string so 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.
-n, --no-quoted — if you give this, that simplifying quoted format from --style=script is not used.

Exit status for string escape: 0 if at least one string was escaped, or 1 otherwise.

--style=var — makes sure the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded.
--style=url — makes sure 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 example, 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 ...]

These join their 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. For example, 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 being interpreted as flags. Otherwise, any strings starting with - will be treated as flag arguments, meaning they will most likely result in the command 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 unwelcome 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 (<# expand-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.

-q, --quiet — quiet flag.
-V, --visible — use the visible width of the arguments instead of plain character count. That means it discounts escape sequences fish knows about, accounts for $fish_emoji_width and $fish_ambiguous_width, counts each line (separated by \n) on its own, and with a carriage return (\r) counts only the widest stretch on a line. The whole point 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 🐟🐟🐟🐟
# 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. That means in conjunction with the -q flag you can readily test whether a string is already lowercase. Cute, right? 🎀

-q, --quiet — quiet flag; combined with the exit status, it makes that lowercase test super easy.

🔥 "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 substrings. Only the first match for each STRING is reported unless -a or --all is given, in which case all matches are reported.

-a, --all — report all matches for each STRING, not just the first one.
-e, --entire — each matching string is printed including 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 specified the --regex flag. The --entire flag is a way to avoid having to complicate 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 entire STRING before it will be reported.
-i, --ignore-case — make matching case-insensitive.
-g, --groups-only — only the capturing groups will be reported, meaning the full match will be skipped. This is incompatible with --entire 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.
-n, --index — each match is reported as a 1-based start position and a length.
-q, --quiet — quiet flag.

By default, PATTERN is interpreted as a glob pattern matched against each entire STRING argument. A glob pattern is only considered a valid match if it matches the entire STRING.

-r, --regex — PATTERN is interpreted as a Perl-compatible regular expression, which does not have to match the entire STRING. For a regular expression containing capturing groups, multiple items will be reported 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 (like (?<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 element, 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.

-v, --invert — selected lines will be only those which do not match the given glob pattern or regular expression.
-m MAX, --max-matches MAX — 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 limited and fixed number of outputs that might be found considerably before the input stream has been exhausted. If combined with --invert or -v, it considers 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

🐟 the `"pad"` subcommand 🐟

string pad [-r | --right] [-C | --center] [(-c | --char) CHAR] [(-w | --width) INTEGER]
           [STRING ...]

okay so string pad takes every STRING you hand it and stretches it out to the visible width you want, by adding CHAR on the left side. and when we say "visible width" we mean the width of all the visible characters added together — escape sequences don't count, and it accounts for fish_emoji_width and fish_ambiguous_width. it's literally the number of columns STRING takes up in a terminal. 💅

the escape sequences it respects are the ones fish knows about and how fish computes its own output. ngl your terminal might support more escapes than that, or it might not support some of the ones fish knows about. 🙈

-C, --center — puts the padding on both sides of the string, before and after. if perfectly centering is impossible (because the amount of padding needed is an odd number), the extra padding goes on the left — unless --right is also given, bestie.
-r, --right — adds the padding after the string instead of before.
-c, --char — pads with CHAR instead of whitespace. slay.
-w, --width — pad out to at least this width. (the output is padded to the max width of all the input strings by default, so this sets a floor.)

✨ Examples ✨

>_ string pad -w 10 abc abcdef
       abc
    abcdef

>_ string pad --right --char=🐟 "fish are pretty" "rich. "
fish are pretty
rich.  🐟🐟🐟🐟

>_ 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 too — like, printf %10s\n works exactly like string pad -w10. icon behavior.
string length with the --visible option shows you what fish thinks the width actually is. use it to vibe check. 🔍

🎀 the `"shorten"` subcommand 🎀

string shorten [(-c | --char) CHARS] [(-m | --max) INTEGER]
               [-N | --no-newline] [-l | --left] [-q | --quiet] [STRING ...]

string shorten chops each STRING down to the visible width you give it and slaps an ellipsis on there to show something got cut. and "visible width"?? same deal as before: the width of all the visible characters added together, escape sequences excluded, accounting for fish_emoji_width and fish_ambiguous_width — i.e. the number of terminal columns STRING occupies. 💅

same disclaimer as always: the escape sequences reflect what fish knows about and how it computes output. your terminal might support more, or might not support what fish knows. 🙈

-m, --max — truncate at this width. if you don't give it, the lowest non-zero width among all the input strings gets used. and a max of 0 means no shortening at all ever — every STRING prints exactly as-is.
-N, --no-newline — only use the first line of each STRING (or the last line, if --left is also given), adding an ellipsis if it was multiline. heads up: this only works for *STRING*s passed as arguments — multiple lines coming in on stdin just get read as separate *STRING*s instead. 😭
-c, --char — use CHAR instead of an ellipsis. this can be empty, or more than one character. go off.
-l, --left — remove text from the left instead, so you get the longest suffix of the string that fits. combined with --no-newline, it takes from the last line rather than the first.
-q, --quiet — string shorten only runs for the return value: if anything would get shortened it returns 0, otherwise 1.

the default ellipsis is …. but if fish thinks your system can't handle it because of your locale, it uses ... instead. 💀

the return value is 0 if any shortening happened, and 1 if it didn't.

🌸 Examples 🌸

>_ string shorten foo foobar
# No width was given, we infer, and "foo" is the shortest.
foo
fo…

>_ 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 "…".
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 multiline…

>_ 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-e…

>_ git branch | string match -rg '^\* (.*)' | string shorten -m20 --left
# Taking 20 columns from the right instead:
…in-path-with-expand

🫶 See also 🫶

string pad does the literal inverse of this — adding padding to a specific width instead of eating it away. ✨
the printf command can do simple padding too, for example printf %10s\n works like string pad -w10.
string length with the --visible option shows you what fish thinks the width is.

💜 the `"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. periodt.

-m, --max — caps the number of outputted characters (the newline doesn't count). this option works all on its own or hand-in-hand with --count. if both --count and --max are present, max chars get outputted — unless the final repeated string ends up smaller than max, in which case the string keeps repeating until count has been reached. both --count and --max accept a number greater than or equal to zero, and zero means nothing gets outputted at all. 🙈
-N, --no-newline — the output won't end with a newline character.
-q, --quiet — quiet mode, bestie.

the first argument is interpreted as COUNT if --count or --max weren't explicitly specified. and the exit status? 0 if the yielded string isn't empty, 1 otherwise.

🔥 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

🦋 the `"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 basically string match's sibling — it finds non-overlapping matching substrings and swaps them out for a replacement string, then prints the result. by default, PATTERN is treated as a literal substring to match against. no cap. 👑

-r, --regex — PATTERN is interpreted as a Perl-compatible regular 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}. this is the good stuff.
-a, --all — replace every match, not just the first.
-f, --filter — each input string is printed only if a replacement was actually done. super useful when you'd otherwise reach for this idiom: a_cmd | string match pattern | string replace pattern new_pattern. instead you can just write a_cmd | string replace --filter pattern new_pattern. ate. 💅
-i, --ignore-case — match case-insensitively.
-m, --max-matches MAX — string replace stops all processing after MAX lines of input have matched the pattern. with --filter or -f, that means the output will be MAX lines long. think of it as an "early exit" optimization when you're chewing through long input but only expect a limited, fixed number of outputs that might show up way before the stream runs out.
-q, --quiet — quiet, only the exit status matters.

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

🧚 the `"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 every STRING on the separator SEP — and yes, SEP can be an empty string. 💀

-m, --max — do at most MAX splits on each STRING.
-r, --right — split right-to-left instead. this is only useful combined with -m or --max, iykyk.
-n, --no-empty — empty results get excluded from consideration (so hello\n\nworld expands to two strings, not three).
-f, --fields FIELDS — print out specific fields. FIELDS is a comma-separated string of field numbers and/or spans. every field is one-indexed, and they get printed on separate lines. if a given field doesn't exist, the command exits with status 1 and prints nothing at all — unless --allow-empty is used.
-a, --allow-empty — lets missing fields be a vibe instead of a whole error.
-q, --quiet — quiet mode.

exit status: 0 if at least one split was performed, or 1 otherwise.

also go look at the --delimiter option of the read command, it's the cousin of all this. 🫶

string split0 splits every STRING on the zero byte (NUL). options are exactly the same as string split, except there's no separator to give — it's always NUL.

now here's the important part: split0 has the iconic property that its output is not split any further when it's used in a command substitution — which means the command substitution can produce elements that contain newlines. this is most useful with Unix tools that produce zero bytes, like find -print0 or sort -z. see the split0-ish examples below. ✨

⚠️ careful bestie: commandline arguments cannot include NULs, so you probably want to pipe into string split0 rather than passing things via a command substitution. fr fr.

👑 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

Bestie, these are the examples where NUL bytes are doing the heavy lifting, so newlines in your data don't ruin everything 💅

>_ # 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, like the world's tiniest scissors 🎀

Where the substring starts and ends can be set with -s/--start and -e/--end, each 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 set with -l or --length. If you don't specify a length or an end, the substring just keeps going to the end of each STRING. Slay.

Exit status: 0 if at least one substring operation was performed, 1 otherwise.

Heads up: --length is mutually exclusive with --end. Pick a lane, bestie 💀

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 gets yeeted. If -r or --right is given, only trailing whitespace gets trimmed. 🫧

The -c or --chars switch makes it remove the set of characters in CHARS instead of whitespace. Listen closely, because this is the part people get wrong: it's a set of characters, not a string. If you pass -c foo, it removes any "f" or "o", not just "foo" as a whole. Not the same thing at all 🙈

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. It's giving shouting, but make it fashion 👑

Exit status: 0 if at least one string was converted to uppercase, else 1. Which means: combined with the -q flag, you can readily test whether a string is already uppercase. Vibe check in one command, iykyk ✨

🧚 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. Ngl, this section is lowkey the cheat sheet 👑

In contrast to these classics, string reads input either from stdin or as arguments. string also does not deal with files, so it requires redirections 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 variable. 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 former evaluates to zero or one elements whereas the quoted command substitution always evaluates to one element due to string interpolation. Subtle but iconic 💅

If invoked with multiple arguments instead of input, string collect preserves 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)" substitution. 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. Protect the baby 🥺

🌸 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. Pick your fighter ✨

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

--style=var ensures the string can be used as a variable name by hex encoding 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 example, doing string unescape --style=var (string escape --style=var $str) will return the original string. There is no support for unescaping --style=regex. Sad but true 😭

🌈 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 being interpreted as flags. Otherwise, any strings starting with - will be treated as flag arguments, meaning they will most likely result in the command 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 unwelcome surprises. Fr fr, just always do it 🙈

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 <# expand-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. Not our fault, bestie 💀

⭐ 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

Okay so this one takes all your STRING arguments and smushes them into one single string, separated by SEP (that's for string join) or by the zero byte, a.k.a. NUL (that's for string join0). Exit status: 0 if at least one join was performed, or 1 otherwise. Slay.

-n, --no-empty — leaves empty strings out of the party entirely. Like, string join -n + a b "" c would expand to a+b+c, not a+b++c. Bestie, the empty string gets no invite 💅
-q, --quiet — don't print the strings at all, just set the exit status like described above. Silent but it's still doing the work 🫶

⚠️ WARNING: put a -- before your positional arguments so they don't get read as flags. Otherwise any string starting with - gets treated as a flag argument, which means the command will most likely just fail. And this is also true if you pass a variable that expands to such a string instead of a literal string — so like, $markdown_list will absolutely betray you. If you don't need to append flag arguments at the end of the command, just always use -- to avoid unwelcome surprises, fr fr.

string join0 also adds a trailing NUL. This is most useful with tools that accept NUL-delimited input, such as sort -z. Iconic behavior.

But here's the tea 😭: because Unix uses NUL as the string terminator, passing the output of string join0 as an argument to a command (via a command substitution <#expand-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. That's just a limitation of Unix' argument passing. Not our fault, not fish's fault, it's the OS's vibe.

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 instead. That means it discounts escape sequences fish knows about, and it accounts 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) it counts only the widest stretch on a line. The whole intent here is to measure the number of columns the STRING would occupy in the current terminal. It's giving "actually accurate terminal math" ✨

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 🐟🐟🐟🐟
        # 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. And that means — in conjunction with the -q flag — you can readily test whether a string is already lowercase. Tiny lowercase detector, we love her 🎀

🔥 `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 the matching substrings. Only the first match for each STRING gets reported — unless you give it -a or --all, in which case literally every match gets reported, no crumbs left behind 💅

If you specify -e or --entire, then each matching string is printed including any prefix or suffix that wasn't matched by the pattern (equivalent to grep without the -o flag). You can, obviously, get the same result by prepending and appending * or .* depending on whether or not you've specified the --regex flag — but the --entire flag is a way to avoid having to complicate the pattern in that fashion and to make the intent of the string match clearer. Without --entire and --regex, a PATTERN will need to match the entire STRING before it will be reported. Whole thing or nothing, periodt.

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 gets skipped. This is incompatible with --entire and --invert, and it requires --regex. It's useful as a simple cutting tool instead of string replace, so you can choose "this part" of a string. Like a little scalpel ✂️

If --index or -n is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire STRING argument. A glob pattern is only considered a valid match if it matches the entire STRING.

If --regex or -r is given, PATTERN is interpreted as a Perl-compatible regular expression, which does not have to match the entire STRING. For a regular expression containing capturing groups, multiple items will be reported 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. Big regex girl energy 🌈

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 element, 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. It's a whole little variable factory and honestly? obsessed 😭

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 limited and fixed number of outputs that might be found considerably before the input stream has been exhausted. If combined with --invert or -v, it considers 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. And "width" here means the width of all visible characters added together, excluding escape sequences and accounting for fish_emoji_width <#envvar-fish_emoji_width> and fish_ambiguous_width <#envvar-fish_ambiguous_width>. It's the amount of columns in a terminal the STRING occupies. Basically it's doing the math so your columns line up and look immaculate ✨

The escape sequences reflect what fish knows about, and how it computes its output. Your terminal might support more escapes, or not support escape sequences that fish knows about. Just so you know 👀

-C, --center — pads both before and after the string, so it's all centered and cute 🎀. If it can't be perfect (because the padding you need is an odd number, ugh), the extra padding goes on the left — unless you also passed --right.
-r, --right — pads after the string instead. Right-aligned era 💅.
-c, --char — pad with CHAR instead of whitespace. Your padding, your rules ✨.

The output gets padded to the maximum width of all the input strings. And if you give -w or --width, it uses at least that. Lowkey the whole point.

Examples 🍓

>_ string pad -w 10 abc abcdef
       abc
    abcdef

>_ string pad --right --char=🐟 "fish are pretty" "rich. "
fish are pretty
rich.  🐟🐟🐟🐟

>_ string pad -w$COLUMNS (date)
# Prints the current time on the right edge of the screen.

🌈 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. Iconic. It's giving copy-paste but make it a builtin 💖.

-m, --max — limits the number of outputted characters (excluding the newline). You can use this all by itself or together with --count. If both --count and --max are around, max characters will be outputted — unless the final repeated string size is less than max, in which case the string keeps repeating until count has been reached. Both --count and --max accept a number greater than or equal to zero, and if it's zero, nothing gets outputted. Yes, nothing. Empty. The void 🕳️.

The first argument is interpreted as COUNT if --count or --max weren't explicitly specified. Sneaky but slay.

If -N or --no-newline is given, the output won't have a newline character at the end.

Exit status: 0 if the 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 instead of just matching, it replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched. No regex gremlins unless you ask 🧚.

-r, --regex — PATTERN gets interpreted as a Perl-compatible regular 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}. Chef's kiss 🔥.
-f, --filter — each input string is printed only if a replacement was done. Super useful when you'd otherwise use this idiom: a_cmd | string match pattern | string replace pattern new_pattern. Instead you can just write a_cmd | string replace --filter pattern new_pattern. Pipeline glow-up ✨.
-m MAX, --max-matches MAX — string replace stops all processing after MAX lines of input have matched the specified pattern. With --filter or -f, that means the output will be MAX lines long. It's basically an "early exit" optimization when you're processing long inputs but expecting a limited, fixed number of outputs that might show up way before the input stream runs out. Efficient queen 👑.

(Also -i / --ignore-case is listed up there in the synopsis, just so you know it exists — that's all this page says about it 🫶.)

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 slaps an ellipsis on it to show it got cut. "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's literally the number of columns in a terminal that the STRING occupies 🖥️.

The escape sequences reflect what fish knows about and how it computes its output. Heads up though: your terminal might support more escapes, or not support escape sequences that fish knows about. So it's a vibe, not a guarantee 💀.

-m, --max — truncate at the given width. If you don't give it, the lowest non-zero width of all input strings is used. A max of 0 means no shortening at all — every STRING prints as-is. Zero = hands off 🙈.
-N, --no-newline — only the first line (or the last line with --left) of each STRING is used, and an ellipsis is added if it was multiline. Important: this only works for *STRING*s given as arguments — multiple lines given on stdin will be interpreted as separate *STRING*s instead. Noted 📌.
-c, --char — add CHAR instead of an ellipsis. This can also be empty or more than one character. Go wild.
-l, --left — remove text from the left instead, so this prints the longest suffix of the string that fits. With --no-newline, it takes from the last line instead of the first. Left gang rise up 💅.
-q, --quiet — string shorten only runs for the return value: if anything would be shortened it returns 0, else 1. Silent but telling 🤫.

The default ellipsis is …. But if fish thinks your system is incapable because of your locale, it uses ... instead. Locale-dependent drama, love that for us 😭.

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
fo…

>_ 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 "…".
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 multiline…

>_ 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-e…

>_ git branch | string match -rg '^\* (.*)' | string shorten -m20 --left
# Taking 20 columns from the right instead:
…in-path-with-expand

🦋 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 — plot twist — can be an empty string 😳.

-m, --max — at most MAX splits are done on each STRING.
-r, --right — splitting happens right-to-left. This is only useful in combination with -m or --max, so don't bother otherwise.
-n, --no-empty — empty results are excluded from consideration (so hello\n\nworld expands to two strings, not three).

Exit status: 0 if at least one split was performed, or 1 otherwise.

-f, --fields — print out specific fields instead. FIELDS is a comma-separated string of field numbers and/or spans. Each field is one-indexed, and gets printed on separate lines. If a given field doesn't exist, the command exits with status 1 and prints nothing — unless --allow-empty is used. No field, no output, no cap 💀.

Also see the --delimiter option of the read command, bestie 👀.

string split0 splits each STRING on the zero byte (NUL). Options are the same as string split — except there's no separator argument, obviously, since NUL is the whole personality.

split0 has the important property that its output is not further split when used in a command substitution, which lets the command substitution produce elements containing newlines. This is most useful with Unix tools that produce zero bytes, like find -print0 or sort -z. See the split0 examples below 🔥.

Be aware that command line arguments cannot include NULs, so you probably want to pipe into string split0, not pass it a command substitution. Big caveat, don't get caught out 🙈.

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

Okay so string split splits each STRING on the separator SEP — and yes, SEP can literally be an empty string, no cap. If you throw in -m or --max, it does at most MAX splits on each STRING. If -r or --right is there, the splitting runs right-to-left — which is only actually useful when you pair it with -m or --max. And with -n or --no-empty, empty results get excluded from consideration (think hello\n\nworld expanding into two strings, not three). Exit status: 0 if at least one split happened, or 1 otherwise. 💅

Use -f or --fields to print out specific fields. FIELDS is a comma-separated string of field numbers and/or spans. Each field is one-indexed and gets printed on its own separate line. If a given field doesn't exist, the command exits with status 1 and prints nothing — unless you used --allow-empty. 🫶

Also go check out the --delimiter option of the read command, iykyk.

string split0 splits each STRING on the zero byte (NUL). Options are the same as string split, except there's no separator argument given.

split0 has this iconic property where its output does not get further split when it's used in a command substitution — so the substitution can produce elements containing newlines. That's most useful with Unix tools that spit out zero bytes, like find -print0 or sort -z. See the 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 set 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. The default start value is 1. The length of the substring can be set with -l or --length. If the length or end isn't specified, the substring just keeps going to the end of each STRING. Exit status: 0 if at least one substring operation happened, 1 otherwise. And heads up — --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 the leading whitespace gets removed. If -r or --right is given, only the trailing whitespace gets trimmed.

The -c or --chars switch makes it remove the set of characters in CHARS instead of whitespace. And it's a set of characters, not a string — so if you pass -c foo, it'll remove any f or o, not just foo as a whole. Lowkey important. 😭

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 (the default) alters the string so it can be passed back to eval to produce the original argument again. By default, all special characters get escaped and quotes are used to simplify the output when possible. If -n or --no-quoted is given, that simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.

--style=var makes sure the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded.

--style=url makes sure the string can be used as a URL by hex encoding any character which isn't 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 isn't properly formatted, it gets ignored. For example, doing string unescape --style=var (string escape --style=var $str) will return the original string. There's 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. Which means — when you pair it with the -q flag, you can readily test whether a string is already 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 won't suspend the shell if it's a login shell. That requirement is bypassed if the --force option is given, or if the shell isn't 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 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 globs — but those need to be escaped or quoted, so you don't get regular glob expansion using filenames. 🌈

Note that fish does not fall through on case statements. Only the first matching case is executed. Periodt.

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 isn't taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter. 😭

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're true, 1 if they're false.

The first form (test) is preferred. For compatibility with other shells, the second form is available too: a matching pair of square brackets ([ [EXPRESSION] ]).

When you use a variable or command substitution as an argument with test, you should almost always enclose it in double-quotes — because 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 <#featureflags>, 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 doesn't support 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 — true if FILE exists and it's owned by the current user 👑 like, yes bestie, this one is yours
-p FILE — true if FILE is a named pipe 🎀 pipe girlies rise
-r FILE — true if FILE is marked as readable 👀
-s FILE — true if the size of FILE is greater than zero 🍓 (so like… it's got content)
-S FILE — true if FILE is a socket 🧦
-t FD — true if the file descriptor FD is a terminal (TTY) 💻
-u FILE — true if FILE has the set-user-ID bit set 🔥
-w FILE — true if FILE is marked as writable; note that this does not check if the filesystem is read-only ⚠️ so don't come for me if it lies to you
-x FILE — true if FILE is marked as executable ✨

Operators to compare files and directories

FILE1 -nt FILE2 — true if FILE1 is newer than FILE2, or if FILE1 exists and FILE2 does not 🕐 "newer than" and also "the only one that showed up"
FILE1 -ot FILE2 — true if FILE1 is older than FILE2, or if FILE2 exists and FILE1 does not 🕰️ the reverse vibe
FILE1 -ef FILE1 — true if FILE1 and FILE2 refer to the same file 🫶 (and yes, that's exactly how the manpage writes it, no I will not be "fixing" it — copy it exactly)

Operators for text strings

STRING1 = STRING2 — true if the strings STRING1 and STRING2 are identical 💯
STRING1 != STRING2 — true if the strings STRING1 and STRING2 are not identical 🙅
-n STRING — true if the length of STRING is non-zero 📏
-z STRING — true if the length of STRING is zero 🫥

Operators to compare and examine numbers

NUM1 -eq NUM2 — true if NUM1 and NUM2 are numerically equal 🟰
NUM1 -ne NUM2 — true if NUM1 and NUM2 are not numerically equal 🚫
NUM1 -gt NUM2 — true if NUM1 is greater than NUM2 ⬆️
NUM1 -ge NUM2 — true if NUM1 is greater than or equal to NUM2 ⏫
NUM1 -lt NUM2 — true if NUM1 is less than NUM2 ⬇️
NUM1 -le NUM2 — true if NUM1 is less than or equal to NUM2 ⏬

Both integers and floating point numbers are supported. 🧮 yes, decimals too, she's versatile

Operators to combine expressions

COND1 -a COND2 — true if both COND1 and COND2 are true 🤝 and-logic, we love her
COND1 -o COND2 — true if either COND1 or COND2 are true 🌈 or-logic, chaotic but valid

Expressions can be inverted using the ! operator:

! EXPRESSION — true if EXPRESSION is false, and false if EXPRESSION is true 🙃 the flip, the reversal, the "not me"

Expressions can be grouped using parentheses.

( EXPRESSION ) — returns the value of EXPRESSION 🫶

careful bestie — parentheses will usually require escaping with \ (so they appear as $ and $) to avoid being interpreted as a command substitution. 💀 do not let fish think you're running a command, she will run it

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.) 🫶 quote your variables, it's self care

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-require-arg feature flag (#featureflags) — if $MANPATH is unset, if test -n $MANPATH will be false. 👀 so like, heads up for future you

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. 🧚 the full girlboss boolean

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 (#envvar-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. The following exceptions apply: 🎀 so, mostly POSIX, but with opinions

The < and > operators for comparing strings are not implemented. 🚫 nope, not here
With test-require-arg, the zero- and one-argument modes will behave differently. In cases such as this, one can use command test to explicitly use the system's standalone test rather than this builtin test. 🔁 when in doubt, go get the real one

⏱️ 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. 👈 like, literally type that, bestie

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 results can not currently be redirected. 😭 not redirectable, we're just vibing with that

For checking timing after a command has completed, check $CMD_DURATION (#variables-special). 🕐

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. 🫶 so if you want fish functions or blocks timed, it's gotta be this one

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 (#envvar-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 separately. So a program with four threads using all CPU for a second will have a time of 4 seconds. 🔥 four cores go brrr

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

The "fish" time is how much CPU was spent in fish, the "external" time how much was spent in external commands. 🐟 vs 🌍

So in this example, since string is a builtin, everything that string repeat did is accounted to fish. Any time it spends doing syscalls like write() is accounted for in the fish/sys time. 💅 builtin behaviour, she's homegrown

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. 🌈 parallel slay, the numbers go over 100% and that's fine

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 recommended to define an event handler (#event). 🎀 like, genuinely, the event system is the moment

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. 🫥 that's the "pretend you didn't see it" mode

If ARG is not present and -p has been supplied, then the trap commands associated 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. 🛑 so like, you're catching it, she stays

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. 💖 that's it, that's the whole job

: (a single colon) is an alias for the true command. 🎀 tiny icon, same energy

🔍 type — locate a command and describe its type

Synopsis

type [OPTIONS] NAME [...]

Description — okay so real talk bestie, this page is about the fish builtin type. If you want the docs for some non-fish version, go run command man type instead, iykyk 💅

With no options at all, type tells you how each NAME would be interpreted if you used it as a command name. Cute, right? 🎀

Here's the whole menu of options:

-a, --all — prints all of the possible definitions of the names you gave it. Not just the winner, the whole friend group 🌈
-s, --short — don't print function definitions when you're using it with no options, or with -a/--all. Keep it brief ✨
-f, --no-functions — suppresses function lookup entirely. Functions? Never heard of her 🙈
-t, --type — prints function, builtin, or file if NAME is a shell function, a builtin, or a disk file respectively 👑
-p, --path — prints the path to NAME if NAME resolves to an executable file in PATH <#envvar-PATH>; prints the path to the script containing the definition of the function NAME if NAME resolves to a function loaded from a file on disk (i.e. not interactively defined at the prompt); and prints nothing otherwise 🦋
-P, --force-path — returns the path to the executable file NAME, presuming NAME is found in the PATH <#envvar-PATH> environment variable, or nothing otherwise. --force-path explicitly resolves only the path to executable files in PATH <#envvar-PATH>, regardless of whether NAME is shadowed by a function or builtin with the same name. It's giving main character energy, no shadowing allowed 💀
-q, --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 function definitions. WHEN can be auto (the default, colorize if the output is a terminal <>), always, or never 🎨
-h, --help — displays help about using this command. The classic 🫶

Heads up bestie: the -q, -p, -t and -P flags (and their long flag aliases) are mutually exclusive. Only one of them at a time, please — pick a lane, periodt ✋

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

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. So it's either reading the vibes or setting the vibes 🔮

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

-b, --socket-buffers — the maximum size of socket buffers.
-c, --core-size — the maximum size of core files created. By setting this limit to zero, core dumps can be disabled.
-d, --data-size — the maximum size of a process' data segment.
-e, --nice — controls the maximum nice value; on Linux, this value is subtracted from 20 to give the effective value.
-f, --file-size — the maximum size of files created by a process.
-i, --pending-signals — the maximum number of signals that may be queued.
-l, --lock-size — the maximum size that may be locked into memory.
-m, --resident-set-size — the maximum resident set size.
-n, --file-descriptor-count — the maximum number of open file descriptors.
-q, --queue-size — the maximum size of data in POSIX message queues.
-r, --realtime-priority — the maximum realtime scheduling priority.
-s, --stack-size — the maximum stack size.
-t, --cpu-time — the maximum amount of CPU time in seconds.
-u, --process-count — the maximum number of processes available to the current user.
-w, --swap-size — the maximum swap space available to the current user.
-v, --virtual-memory-size — the maximum amount of virtual memory available to the shell.
-y, --realtime-maxtime — the maximum contiguous realtime CPU time in microseconds.
-K, --kernel-queues — the maximum number of kqueues (kernel queues) for the current user.
-P, --ptys — the maximum number of pseudo-terminals for the current user.
-T, --threads — the maximum number of simultaneous threads for the current user.

Ngl, not all these limits are available in all operating systems — consult the documentation for setrlimit in your operating system. Some of these flags are lowkey OS-dependent, so don't come for me if one's missing 🥲

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. Iconic trio honestly ✨

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

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

-H, --hard — sets hard resource limit.
-S, --soft — sets soft resource limit.

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

The following additional options are also understood by ulimit:

-a, --all — prints all current limits. The whole spreadsheet, bestie 📋
-h, --help — displays help about using this command.

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

fish ulimit supports GNU-style long options for all switches. Very demure, very mindful 💅
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 unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish. We're just not doing the guessing game 🙅
fish ulimit does not support getting or setting multiple limits in one command, except reporting all values using the -a switch. One thing at a time, periodt ⭐

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. Think of it as the bouncer at the door of your file permissions 🚪

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. Two whole ways to say the same thing, and yes it's confusing, we know 😭

Access rights are explained in the manual page for the chmod(1) program. Go read that one too, iykyk 📖

With no parameters, the current file creation mode mask is printed as an octal number.

-S, --symbolic — prints the umask in symbolic form instead of octal form ✨
-p, --as-command — outputs the umask in a form that may be reused as input. Copy-paste friendly, we love to see it 🎀
-h, --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. Yeah. That's a real thing on this page. We said what we said.

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. Locked down, no crumbs 💅

🌸 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. So you can't edit the whole group chat, but you can DM one member 🙈

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. It's the "bestie hold on, I'm not done yet" of shell builtins 🫶

If a PID is specified, the command waits for the job that the process with that process ID belongs to.
If a PROCESS_NAME is specified, the command waits for the jobs that the matched processes belong to.
If neither a pid nor a process name is specified, the command waits for all background jobs.

If the -n or --any flag is provided, the command returns as soon as the first job completes. If it is not provided, it returns after all jobs complete. First one done wins vs. everybody finish up, your choice 👑

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 finish. Group project energy, but this time everyone actually shows up 🌈

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. Selective waiting, we love a queen with boundaries 💀

🌀 `while` — perform a set of commands multiple times

Synopsis

while CONDITION; COMMANDS; end

Description

Okay so while just keeps running CONDITION over and over, and every time it comes back with exit status 0, it runs COMMANDS. That's the whole vibe. 🔁

The exit status of the while loop is whatever the exit status was on the last iteration of the COMMANDS that actually ran — or 0 if literally none of them ran. (This matches other shells and is POSIX-compatible, so no cap there, it's just facts. 💅)

You can use and or or for complex conditions. And if you want even more complex control, you can do while true containing a break. Main character energy, honestly.

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. Not me being dramatic, that's just the whole design philosophy bestie. 😌

Many things are similar — they both fundamentally expand commandlines to execute commands, have pipes, redirections, variables, globs, use command output in various ways. This document is there to quickly show you the differences. ✨

🔄 Command substitutions

fish spells command substitutions as $(command) or (command), but not `command`. Goodbye backticks, you will not be missed. 💀

In addition, it only splits them on newlines instead of $IFS. If you want to split on something else, use string split, string split0 or string collect. If those are used as the last command in a command substitution the splits they create are carried over. So:

for i in (find . -print0 | string split0)

will correctly handle all possible filenames. Obsessed with her, fr fr. 🎀

📦 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 variable 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". And set foo=bar will print an error. So like. Don't. 🙈

See Shell variables <#variables> for more.

[1] zsh also does not perform word splitting by default (the SH_WORD_SPLIT option controls this)

🎁 Variable defaults (`${my_variable:-"default value"}`)

fish doesn't have ${my_variable:-fallback} for providing default values to unset variables. Instead, you can set default values by checking whether the variable has been set yet:

# Ensure XDG_CONFIG_HOME is set or use a default value
set -q XDG_CONFIG_HOME || set XDG_CONFIG_HOME $HOME/.config
# now use XDG_CONFIG_HOME as normal

🌈 Wildcards (globs)

fish only supports the * and ** glob (and the deprecated ? glob) as syntax. If a glob doesn't match it fails the command (like with bash's failglob) unless the command is for, set or count or the glob is used with an environment override (VAR=* command), in which case it expands to nothing (like with bash's nullglob option). Glow-up behaviour, honestly. ✨

Globbing doesn't happen on expanded variables, so:

set foo "*"
echo $foo

will not match any files. Nope, not even a little.

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 often 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. She ate that. 🎵💅

See Wildcards <#expand-wildcard> for more.

🎀 Quoting

fish has two quoting styles: "" and ''. Variables are expanded in double-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 <#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. Iconic, frankly.

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). The whole toolkit, bestie. 🧰

🔮 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 expressed without. E.g. instead of:

source (command | psub)

Use:

command | source

as fish's source can read from stdin. Chef's kiss. 👑

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

Read/interpret the string, with special rules, up to the terminator. [2]
Write the resulting string to a temporary file.
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 concept, and are simpler and compose nicer. Periodt. 💅

You can also pipe multiple things to a command, like so:

{ cat packages1; echo fish; } | pacman --sync -

[2] For example, the "EOF" is just a convention, the terminator can be an arbitrary string, something like "THISISTHEEND" also works. And using <<- trims leading tab characters (but not other whitespace), so you can indent the lines, but only with tabs. Substitutions (variables, commands) are done on the heredoc by default, but not if the terminator is quoted: cat << "EOF".

🧪 Test (`test`, `[`, `[[`)

fish has a POSIX-compatible test or [ builtin. There is no [[ and test does not accept == as a synonym for =. It can compare floating point numbers, however. Slay. 🔥

set -q can be used to determine if a variable exists or has a certain number of elements (set -q foo[2]).

➗ Arithmetic Expansion

fish does not have $((i+1)) arithmetic expansion, computation is 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 <#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

okay so this shows a few differences 👀:

fish gives you set_color to color text. It can use the 16 named colors and also RGB sequences (so you could also use set_color 5555FF) — yes bestie, hex-ish RGB in your prompt, slay 💅
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 — go peek at it, it's literally right there 🫶

fish does not have $PS2 for continuation lines, instead it leaves the lines indented to show that the commandline isn't complete yet. no continuation prompt era, we just vibe with indentation ✨

🌸 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 — no more do/done/then/fi double-bookings, it's giving minimalism 💅

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 ! instead. that's it, that's the whole plot 🎀

🦋 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 environment you can use fish -c 'your code here' to do so explicitly. no cap, that's the move 🫡

() subshells are often confused with {} grouping, which does not use a subshell. When you just need to group, you can use begin; end in fish:

(foo; bar) | baz
# when it should really have been:
{ foo; bar; } | baz
# becomes
begin; foo; bar; end | baz

the pipe will be run in the same process, so while read loops can set variables outside:

foo | while read bar
    set -g VAR VAL
    baz &
end

echo $VAR # will print VAL
jobs # will show "baz"

subshells are also frequently confused with command substitutions, which bash writes as `command` or $(command) and fish writes as $(command) or (command). bash also uses subshells to implement them. iykyk 🤓

👑 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 interactive or what the current linenumber is. This replaces $- and $BASH_LINENO and other variables.
seq(1) can be used as a replacement for {1..10} range expansion. If your OS doesn't ship a seq fish includes a replacement function.

💜 Other facilities

bash has set -x or set -o xtrace to print all commands that are being executed. In fish, this would be enabled by setting fish_trace.

Or, if your intention is to profile how long each line of a script takes, you can use fish --profile — see the page for the fish command. ⭐

🧚 Tutorial

💖 Why fish?

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

If you want to make your command line more productive, more useful, and more fun, without learning a bunch of arcane syntax and configuration options, then fish might be just what you're looking for! 👑

🎀 Getting started

Once installed, just type in fish into your current shell to try it out!

You will be greeted by the standard fish prompt, which means you are all set up and can start using fish:

> fish
Welcome to fish, the friendly interactive shell
Type help for instructions on how to use fish
you@hostname ~>

This prompt that you see above is the fish default prompt: it shows your username, hostname, and working directory. 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 example 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 typing a few letters:

> rsync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo

To accept the autosuggestion, hit right (→) or ctrl+f. To accept a single word of the autosuggestion, alt+→. If the autosuggestion is not what you want, just ignore it. bestie it will not be offended 🫶

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". iconic behavior honestly ⭐

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

That right there? That's variable substitution, bestie ✨ — the shell sees $HOME and swaps in the actual value. And it totally works inside double quotes too, 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 a regular everyday command to set variables: set, which takes a variable name and then its value. Slay 💅

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

(Peep the quotes 👀: without them, Mister and Noodle would've been two separate arguments, and $name would've become a list of two elements. Iconic little detail.)

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

You can erase (or "delete") a variable with -e or --erase:

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

For more, see Variable expansion <#expand-variable>.

💖 Exports (Shell Variables) 💖

Sometimes you need a variable to be available to an external command, usually as a setting. For example, lots of programs like git or man read the $PAGER variable to figure out your preferred pager (that's the program that lets you scroll text — yw 🫶). Other variables used this way include $BROWSER, $LANG (to configure your language), and $PATH. You'll notice these are written in ALLCAPS, but honestly that's just a convention, bestie.

To hand a variable over to an external command, it needs to be "exported". You do this 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. 💀

And it goes the other way too! If fish is started by something else, it inherits that parent's exported variables. So if your terminal emulator starts fish and it exports $LANG set to en_US.UTF-8, fish will receive that setting. And whatever started your terminal emulator also gave it some variables that it'll then pass on, unless it specifically decides not to. This is literally 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 (scope <#variables-scope>)! Usually you'd make them global via set -gx MyVariable SomeValue.

For more, see Exporting variables <#variables-export>.

🌈 Lists 🌈

So the set command above used quotes to make sure Mister Noodle was one argument. If it had been two arguments, then name would've been a list of length 2. And actually — plot twist — all variables in fish are really lists, that can contain any number of values, or none at all. Obsessed. 💅

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

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

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

Variables whose name ends in "PATH" are automatically split on colons to become lists. They're 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, periodt.

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 <#expand-brace>. 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'll be no argument:

> set empty # no argument
> echo $empty/this_is_gone # prints an empty line

If you quote the list, it'll be used as one string and so you'll get one argument even if it's empty. 🎀

For more, see Lists <#variables-lists>. For more on combining lists with strings (or even other lists), see cartesian products <#cartesian-product> and Variable expansion <#expand-variable>.

🦋 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 <#expand-wildcard>.

🎀 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 <#redirects> and Pipes <#pipes>.

✨ Command Substitutions ✨

Command substitutions use the output of one command as an argument to another. Unlike other shells, fish does not use backticks for command substitutions. Instead, it uses parentheses 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's meant to be multiple arguments on a single line. To split it on spaces too, use string split.

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

If you need a command substitution's 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 <#expand-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. Fr fr. 💅

💀 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 usually returns 0, and set --query arglbargl boogagoogoo usually returns 2.

There's also a $pipestatus list variable for the exit statuses [1] of processes in a pipe.

For more, see The status variable <#variables-status>.

[1] or "stati" if you prefer, or "statū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. Iconic chaining. 🔥

fish also supports and, or, and not. The first two are job modifiers and have lower precedence. Example usage:

> cp file1 file1_bak && cp file2 file2_bak; and echo "Backup successful"; or echo "Backup failed"
Backup failed

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

cp file1 file1_bak && cp file2 file2_bak
and echo "Backup successful"
or echo "Backup failed"

🧚 Conditionals (If, Else, Switch) 🧚

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

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

To compare strings or numbers or check file properties (whether a file exists or is writeable and such), use test, like

if test "$fish" = "flounder"
    echo FLOUNDER
end

# or

if test "$number" -gt 5
    echo $number is greater than five
else
    echo $number is five or less
end

# or

# This test is true if the path /etc/hosts exists
# - it could be a file or directory or symlink (or possibly something else).
if test -e /etc/hosts
    echo We most likely have a hosts file
else
    echo We do not have a hosts file
end

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

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

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

There's also a switch command, and honestly? it's giving structured programming realness:

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. no accidental fallthrough drama, we love to see it 💅

For more, see Conditions (#syntax-conditional).

✨ 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 — instead they all live in a single list called $argv. Obsessed, honestly. 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, bestie!). fish starts out with a whole squad 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 (#syntax-function).

[2] There is a function called alias, but it's just a shortcut to make functions. fish also provides abbreviations (#abbreviations), through the abbr command.

🔁 Loops 🔁

While loops, iconic behaviour incoming:

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 (#syntax-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. main character energy for your terminal fr fr ✨

You can define your own prompt straight from the command line:

> function fish_prompt; echo "New Prompt % "; end
New Prompt % _

Then, if you're happy with it, you can save it to disk by typing funcsave fish_prompt. This saves the prompt in ~/.config/fish/functions/fish_prompt.fish. (Or, if you want, you can create that file manually from the start — you do you 🫶)

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

💰 `$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. huge glow-up, no cap.

fish takes care to set $PATH to a default, but typically it is just inherited 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 (#variables-path), 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. splitting behaviour is a whole personality trait 💅

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 directories to the path if they aren't already included. It does this by modifying 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. unconditional appends are the villain of this story, don't do it 😭

🚀 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. work smarter not harder, bestie 🌿

If you want to organize your configuration, fish also reads commands in .fish files in ~/.config/fish/conf.d/. See Configuration Files (#configuration) for the details.

🦋 Autoloading Functions 🦋

When fish encounters a command, it attempts to autoload a function for that command, by looking for a file with the name of that command in ~/.config/fish/functions/.

For example, if you wanted to have a function ll, you would add a text file ll.fish to ~/.config/fish/functions:

> cat ~/.config/fish/functions/ll.fish
function ll
    ls -lh $argv
end

This is the preferred way to define your prompt as well:

> cat ~/.config/fish/functions/fish_prompt.fish
function fish_prompt
    echo (pwd) "> "
end

See the documentation for funced and funcsave for ways to create these files automatically, and $fish_function_path (#syntax-function-autoloading) to control their location. automagic file creation, we stan ✨

💜 Universal Variables 💜

A universal variable is a variable whose value is shared across all instances of fish, now and in the future — even after a reboot. You can make a variable universal with set -U:

> set -U EDITOR vim

Now in another shell:

> echo $EDITOR
vim

You only need to set universal variables once interactively. There is no need to add them to your config files (#configuration). For more details, see Universal Variables (#variables-universal). set it and forget it, honestly iconic 🌈

👑 Ready for more? 👑

If you want to learn more about fish, there is lots of detailed documentation (#intro), the official gitter channel (https://gitter.im/fish-shell/fish-shell), an official mailing list (https://lists.sourceforge.net/lists/listinfo/fish-users), and the github page (https://github.com/fish-shell/fish-shell/). go off, learn everything, become the fish expert you were born to be 🦋💖

🧚 Writing your own completions 🧚

To specify a completion, use the complete command. complete takes as a parameter the name of the command to specify a completion for. For example, to add a completion for the program myprog (or myprog.exe on Cygwin/MSYS2 (#completions-cygwin)), 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 complete -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 command. The switches -s, -l and -o are used to specify a short switch (single character, such as -l), a gnu style long switch (such as --color) and an old-style long switch (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 offered directly attached like that, so they aren't given in this case:

> myprog -o <TAB>

Usually options require a parameter, so you would give --require-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, on top of whatever arguments you specified — so you've gotta shut that off. Either kill file completion for one specific option:

complete -c myprog -s o -l output --no-files -ra "yes no"

or do it with a specific condition:

complete -c myprog -f --condition '__fish_seen_subcommand_from somesubcommand'

or just disable file completions globally for the whole command:

complete -c myprog -f

And if you've already disabled them globally but you want them back for one little guy, you re-enable them 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

And as a bigger, juicier example, here's a commented excerpt of the completions 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'

If you wanna see how to write your own completions, go study share/completions in the fish-shell source tree 🫶

🌸 Useful functions for writing completions 🌸

fish ships with a bunch of functions that are super handy when you're writing command-specific completions. Most of these names start with the string __fish_. Heads up though: these functions are internal to fish, meaning their name and interface might change in future fish versions — so don't get too attached 😭 A few of them are described here.

Functions starting with __fish_print_ print a newline-separated list of strings. For example, __fish_print_filesystems prints a list of all known file systems. Functions starting 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 — does path completion on STRING, allowing only directories, and giving them the description DESCRIPTION.
__fish_complete_path STRING DESCRIPTION — does path completion on STRING, giving them the description DESCRIPTION.
__fish_complete_groups — prints a list of all user groups, with the group's members as the description.
__fish_complete_pids — prints a list of all process IDs, with the command name as the description.
__fish_complete_suffix SUFFIX — does file completion, but sorts files ending in SUFFIX first. Super useful when you pair it with complete --keep-order.
__fish_complete_users — prints a list of all users, with their full name as the description.
__fish_print_filesystems — prints a list of all known file systems. rn this is a static list, and it's not dependent on what file systems the host operating system actually understands.
__fish_print_hostnames — prints a list of all known hostnames. This function searches the fstab for nfs servers, ssh for known hosts, and checks the /etc/hosts file.
__fish_print_interfaces — prints a list of all known network interfaces.

🦋 Where to put completions 🦋

Completions can be defined on the commandline or in a configuration file — but plot twist, they can also be loaded automatically ✨ fish automatically searches through any directories in the list variable $fish_complete_path, and any completions defined there are auto-loaded whenever they're needed. A completion file has to have a filename made of the name of the command to complete plus the suffix .fish.

By default, fish searches the following for completions, using the first available file that it finds:

A directory for end-users to keep their own completions, usually ~/.config/fish/completions (controlled by the XDG_CONFIG_HOME environment variable);
A directory for systems administrators to install completions for all users on the system, usually /etc/fish/completions;
A user-specified directory for third-party vendor completions, 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 completions for their software, usually /usr/share/fish/vendor_completions.d;
The completions shipped with fish, which are stored in the fish program and can be seen with status list-files; and
Completions automatically generated from the operating system's manual, usually stored in ~/.cache/fish/generated_completions (controlled by the XDG_CACHE_HOME environment variable).

These paths are controlled by parameters set at build, install, or run time, and they may totally vary from the defaults listed above, so don't come for me if yours look different 🙈

This wide search can lowkey be confusing. If you're unsure, your completions probably belong in ~/.config/fish/completions. 💅

If you've written new completions for a common Unix command, pls consider sharing your work by submitting it via the instructions in Further help and development <#more-help>. bestie behavior only 💖

And if you're developing another program and you'd like to ship completions with it, install them to the "vendor" completions directory. Since this path may vary from system to system, the pkgconfig framework should be used to discover this path with the output of pkg-config --variable completionsdir fish.

🎀 Writing your own prompt 🎀

Warning: This document uses formatting to show what a prompt would look like. If you're viewing this in the man page, you probably wanna switch to looking at the html version instead. Run help custom-prompt to view it in a web browser.

fish ships a bunch of prompts that you can view with the fish_config command, and sooo many users have shared their prompts online. iconic behavior honestly.

But you can also write your own, or adjust an existing prompt — and honestly it's a really good way to get comfortable with 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 <#vi-mode> is used.

These functions get run, and whatever they print is displayed as the prompt (minus one trailing newline).

If the SHELL_PROMPT_PREFIX <#envvar-SHELL_PROMPT_PREFIX> or SHELL_PROMPT_SUFFIX <#envvar-SHELL_PROMPT_SUFFIX> environment variables are set, they're automatically prepended and appended to the left prompt. cute right?

Here, we're just gonna 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 <#envvar-PWD>) and a > symbol to show where the prompt ends. The > is quoted <#quotes> because otherwise it would mean a redirection <#redirects>.

Because we used echo, it adds spaces between the two, so it ends up looking like this (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 -- tells string that no options can come after it, just in case we extend this later with something that can start with a -.

There are other ways to remove the space too — including echo -s and printf.

🌈 Adding color 🌈

This prompt is functional, but ngl it's 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, plus other formatting options including bold and italics. obsessed.

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

And yeah, you can write your own escape sequences by hand, but it's so much easier to just use set_color 💅

✨ Shortening the working directory ✨

Okay so this is fine, but our PWD <#envvar-PWD> can be a bit long, and honestly? We are typically only interested in the last few directories. Lowkey nobody needs to see the whole saga. We can shorten this with the prompt_pwd <> helper that'll hand 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, bestie. 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 <#variables-status>. 🎀 It's a whole number from 0 to 255, and usually it's 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. Like, why flex a zero, yk?

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 <#variables-scope> so it'll 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. ✨ Poof.

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). Iconic behavior tbh.

✨ Transient prompt ✨

To enable transient prompt functionality, set the fish_transient_prompt <#envvar-fish_transient_prompt> variable to 1:

set -g fish_transient_prompt 1

With this set, fish re-runs prompt functions with a --final-rendering argument 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/functions/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. Bestie we are literally just getting started 💅

fish offers more helper functions:
- prompt_login to describe the user/hostname/container or prompt_hostname to describe just the host
- fish_is_root_user to help with changing the symbol for root.
- fish_vcs_prompt to show version control information (or fish_git_prompt / fish_hg_prompt / fish_svn_prompt to limit it to specific systems)
You can add a right prompt by changing fish_right_prompt <> or a vi mode prompt by changing fish_mode_prompt <>.
Some prompts have interesting or advanced features
- Add the time when the prompt was printed
- Show various integrations like python's venv
- Color the parts differently.

You can look at fish's sample prompts for inspiration. Open up fish_config <>, find one you like and pick it. For example:

fish_config prompt show # <- shows all the sample prompts
fish_config prompt choose disco # <- this picks the "disco" prompt for this session
funced fish_prompt # <- opens fish_prompt in your editor, and reloads it once the editor exits

✨ Design ✨

This is a description of the design principles that have been used to design fish. The fish design has three high level goals. These are:

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.
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.
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 situation where two features are related but not identical, one of them should be removed, and the other should be made powerful and general enough to handle all common use cases of either feature.

Rationale: Related features make the language larger, which makes it harder to learn. It also increases the size of the source code, making the program harder to maintain and update.

Examples:

Here documents are too similar to using echo inside of a pipeline.
Subshells, command substitution and process substitution are strongly related. fish only supports command substitution, the others can be achieved either using a block or the psub shellscript function.
Having both aliases and functions is confusing, especially since both of them have limitations and problems. fish functions have none of the drawbacks of either syntax.
The many Posix quoting styles are silly, especially $.

✨ The law of responsiveness ✨

The shell should attempt to remain responsive to the user at all times, even in the face of contended or unresponsive filesystems. It is only acceptable to block in response to a user initiated action, such as running a command.

Rationale: Bad performance increases user-facing complexity, because it trains users to recognize and route around slow use cases. It is also incredibly frustrating.

Examples:

Features like syntax highlighting and autosuggestions must perform all of their disk I/O asynchronously.
Startup should minimize forks and disk I/O, so that fish can be started even if the system is under load.

✨ Configurability is the root of all evil ✨

Every configuration option in a program is a place where the program is too stupid to figure out for itself what the user really wants, and should be considered a failure of both the program and the programmer who implemented it. 💀 Yeah, they said it.

Rationale: Different configuration options are a nightmare to maintain, since the number of potential bugs caused by specific configuration combinations quickly becomes an issue. Configuration options often imply assumptions about the code which change when reimplementing the code, causing issues 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 default, which might make some things unreadable. The proper solution would be for text color preferences to be defined centrally by the user for all programs, and for the terminal emulator to send these color properties to fish.
fish does not allow you to set the number of history entries, different language substyles or any number of other common shell configuration options.

A special note on the evils of configurability is the long list of very useful features found in some shells, that are not turned on by default. Both zsh and bash support command-specific completions, but no such completions are shipped with bash by default, and they are turned off by default in zsh. Other features that zsh supports that are disabled by default include 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 intuitive and powerful program. Implementation issues should only be considered once a user interface has been designed.

Rationale: This design rule is different than the others, since it describes how one should go about designing new features, not what the features should be. The problem with focusing on what can be done, and what is easy to do, is that too much of the implementation is exposed. This means that the user must know a great deal about the underlying system to be able to guess how the shell works, it also means that the language will often be rather low-level.

Examples:

There should only be one type of input to the shell, lists of 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 commands, should be possible to use in any position in a pipeline, and should support any I/O redirection.
Instead of forking when performing command substitution to provide a fake variable scope, all fish commands are performed from the same process, and fish instead supports true scoping.
All blocks end with the end built-in.

🎀 The law of discoverability

okay so bestie, the whole point of this law: a program should be designed to make its features as easy as possible to discover for the user. that's it, that's the law ✨

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

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 different 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 remember the new information until the next time they use the same program. 😭 rough.

Examples:

Everything should be tab-completable, and every tab completion should have a description.
Every syntax error and error in a built-in command should contain an error message describing what went wrong and a relevant help page. Whenever possible, errors should be flagged red by the syntax 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.9.3 (released September 08, 2026)

This release fixes another macOS issue where dead keys, for example the two-key sequence ",space on the US International keyboard layout would incorrectly insert space (#12979 — https://github.com/fish-shell/fish-shell/issues/12979). 💀

🦋 fish 4.9.2 (released September 05, 2026)

This release corrects the fix for macOS terminals from 4.9.1 (#12973 — https://github.com/fish-shell/fish-shell/issues/12973)

🧚 fish 4.9.1 (released September 04, 2026)

This release fixes the following problems identified in fish 4.9.0:

On non-default keyboard layouts, fish executed bindings for physical keys instead of only bindings for the layout's key. For example, on the Dvorak layout, typing s would insert ; because there is a default binding for ; (#12968 — https://github.com/fish-shell/fish-shell/issues/12968). not that 😭
When typing space to accept a character entered via certain IMEs, fish would insert a space instead of the desired character, which has been fixed (#12974 — https://github.com/fish-shell/fish-shell/issues/12974).
On macOS terminals, keys like option-l would execute bindings for alt-l instead of the historical behavior of inserting a character (like @ on a German layout) (#12973 — https://github.com/fish-shell/fish-shell/issues/12973).

👑 fish 4.9.0 (released September 03, 2026)

Interactive improvements

To mitigate issues in Konsole version v26.07.80's implementation of the kitty keyboard protocol, fish no longer requests that protocol on Konsole. The omit-term-workarounds feature flag (anchor #featureflags) can be turned on to enable the kitty keyboard protocol on Konsole again (#12948 — https://github.com/fish-shell/fish-shell/issues/12948).
On some terminals like kitty, keys like shift-space and space can now be mapped independently (#12898 — https://github.com/fish-shell/fish-shell/issues/12898).
Fixed slow tab completion in directories that contain slow-to-resolve symlinks (e.g. links to network-mounted files) (#12905 — https://github.com/fish-shell/fish-shell/issues/12905).
Abbreviations can now be given a description, which will be displayed in the completion pager (#11291 — https://github.com/fish-shell/fish-shell/issues/11291). obsessed.
Vi mode commands like cF and cT now work correctly (#12947 — https://github.com/fish-shell/fish-shell/issues/12947).

Scripting improvements

List indexing can now be nested in more cases; for example $foo[$bar[1] 2] is now allowed (#12903 — https://github.com/fish-shell/fish-shell/issues/12903).
Escaped square brackets (e.g. \133 for [) are no longer considered a slicing operator (#7969 — https://github.com/fish-shell/fish-shell/issues/7969).
Variables containing a closing square brackets and used to index into another variable will no longer close the slice early (#12819 — https://github.com/fish-shell/fish-shell/issues/12819).
Builtin help pages now respect an override of the man function (#12886 — https://github.com/fish-shell/fish-shell/issues/12886).
Commands like status=123 echo $status now throw an error instead of silently ignore the variable override (#7790 — https://github.com/fish-shell/fish-shell/issues/7790).

Regression fixes:

(From 4.6.0) Chinese and Japanese translation of error messages owned by the C library were broken (#12895 — https://github.com/fish-shell/fish-shell/issues/12895).
(From 4.3.2) Erasing read-only variables with set --erase was accidentally allowed.
(From 4.0.0) Builtin fg was not working on NetBSD (#12929 — https://github.com/fish-shell/fish-shell/issues/12929).

💜 fish 4.8.1 (released July 14, 2026)

Interactive improvements

On non-macOS platforms, alt-backspace, alt-delete, alt-left and alt-right operate on words again instead of tokens (#12122 — https://github.com/fish-shell/fish-shell/issues/12122) eliminating cross-platform differences in input handling. 🫶
Builtin and function commands can now be colored separately via new variables fish_color_builtin (anchor #envvar-fish_color_builtin) and fish_color_function (anchor #envvar-fish_color_function) (#12837 — https://github.com/fish-shell/fish-shell/issues/12837).
Add fish_darcs_prompt <> for Darcs (https://darcs.net/) repository status.
Fixed a crash in commandline --current-process when the cursor is inside a &| pipe (#12868 — https://github.com/fish-shell/fish-shell/issues/12868).
Since prompt marking (via OSC 133, anchor #term-compat-osc-133) causes an issue in Konsole's (https://apps.kde.org/konsole/) default configuration, prompt marking had been disabled for Konsole in 4.8.0. Now the omit-term-workarounds feature flag (anchor #featureflags) can be enabled to enable prompt marking on Konsole again (#12859 — https://github.com/fish-shell/fish-shell/issues/12859).

Regression fixes:

(From 4.8.0) abbr --position=anywhere completions are no longer offered in argument position, to avoid cluttering the completion pager (#12838 — https://github.com/fish-shell/fish-shell/issues/12838).
(From 4.8.0) pacman -Q short option completions (#12857 — https://github.com/fish-shell/fish-shell/issues/12857).

🍓 fish 4.8.0 (released June 24, 2026)

Notable improvements and fixes

Translatable messages defined in Rust source code can and should now be translated using Fluent (https://projectfluent.org/) instead of GNU gettext. For now, GNU gettext continues to be used for translating messages defined in fish scripts. To make Fluent easy to work with, we have added tooling based on the new fluent-ftl-tools (https://codeberg.org/danielrainer/fluent-ftl-tools) library. See Contributing Translations (anchor #localization) (#11928 — https://github.com/fish-shell/fish-shell/issues/11928).

Deprecations and removed features

Builtin complete's <> --command and --path options no longer unescape their argument.

Interactive improvements

History search would sometimes forget about commands after those were re-run in concurrent sessions. This has been fixed (#10300 — https://github.com/fish-shell/fish-shell/issues/10300).
fish_hg_prompt, fish_git_prompt and fish_fossil_prompt now strip control characters from VCS state read off disk, matching prompt_pwd.
Abbreviations with --position=anywhere can now be completed in argument position, not just in command position (#12630 — https://github.com/fish-shell/fish-shell/issues/12630).
Path component movement (ctrl-w) skips escaped characters.
Completion of short option groups will now handle --condition correctly (#12821 — https://github.com/fish-shell/fish-shell/issues/12821).
Fixed an issue where ctrl-c might fail to cancel certain functions (#12802 — https://github.com/fish-shell/fish-shell/issues/12802).
On the first run after upgrading from an older version, fish will try harder to check if the current theme matches a historical default. If it does match, fish won't create ~/.config/fish/conf.d/fish_frozen_theme.fish when upgrading from fish < 4.3. In particular, on systems where fish version 3.x was installed originally, fish will now avoid creating that file on upgrade (#12725 — https://github.com/fish-shell/fish-shell/issues/12725).

Scripting improvements

cd supports the -L and -P options, like other shells, to allow specifying whether symbolic links (symlinks) are resolved when changing directories (#7206 — https://github.com/fish-shell/fish-shell/issues/7206).
cd with a relative path will now retry using the real current directory, if $PWD has been moved (#12700 — https://github.com/fish-shell/fish-shell/issues/12700).
Nested brace expansions now strip unquoted leading and trailing spaces from entries consistently (#12794 — https://github.com/fish-shell/fish-shell/issues/12794).
bind <> shows the files where bindings were defined (#12504 — https://github.com/fish-shell/fish-shell/issues/12504).

Other improvements

fish no longer creates the __fish_initialized universal variable on startup. If you don't expect to need to downgrade to earlier versions, you can remove it with set --erase __fish_initialized. This means that fish now only creates universal variables if instructed by the user.

For distributors and developers

With the exception of the $CMAKE_INSTALL_PREFIX/share/fish/man directory, fish no longer installs files to $CMAKE_INSTALL_PREFIX/share/fish. In particular, this means that both $CMAKE_INSTALL_PREFIX/share/fish/completions and $CMAKE_INSTALL_PREFIX/share/fish/functions should no longer exist. These directories have been ignored since fish 4.2. If another package installs fish scripts there, they should be corrected to install to extra_completionsdir (typically $CMAKE_INSTALL_PREFIX/share/fish/vendor_completions.d), extra_functionsdir (typically $CMAKE_INSTALL_PREFIX/share/fish/vendor_functions.d) or extra_confdir (typically $CMAKE_INSTALL_PREFIX/share/fish/vendor_functions.d) instead. See also the output of

for var in completions functions conf; pkgconf fish --variable="$var"dir; end

🩹 Regression fixes

(from 4.4.0) Vi mode c,W key binding was being messy and wrongly deleted trailing spaces — issue #12790 (https://github.com/fish-shell/fish-shell/issues/12790) 💀
(from 4.4.0) Vi mode x in builtin read — issue #12724 (https://github.com/fish-shell/fish-shell/issues/12724) ✨
(from 4.3.3) Repeated Tab would sometimes insert smartcase completions redundantly, like, twice. awkward. 🙈
(from 4.3.0) Pressing Escape during command execution could insert garbage text into the command line — issue #12379 (https://github.com/fish-shell/fish-shell/issues/12379) 😭

🐟 fish 4.7.1 (released May 08, 2026)

This release fixes a regression in 4.7.0 that caused the web config (fish_config) to fail to start — issue #12717 (https://github.com/fish-shell/fish-shell/issues/12717). short king of a release, but it mattered 💖

🐟 fish 4.7.0 (released May 05, 2026)

🗑️ Deprecations and removed features

The default theme (i.e. the fish_color_* variables) is no longer set in non-interactive shells.

✨ Interactive improvements

prompt_pwd now strips control characters.
Repaint events (as triggered by changes to color variables or by event handlers running commandline -f repaint) no longer reset the completion pager and other transient UI states — issue #12683 (https://github.com/fish-shell/fish-shell/issues/12683) 🫶
fish_color_valid_path now respects background and underline colors — issue #12622 (https://github.com/fish-shell/fish-shell/issues/12622) 🎀
funced will no longer lose work if there are parse errors multiple times without new changes to the file. bestie it remembers. iconic.
Fixed a case where directory completions were sorted in a surprising order — issue #12695 (https://github.com/fish-shell/fish-shell/issues/12695) 🦋
When at the command token, the alt+o binding will now open read-only files too — issue #12671 (https://github.com/fish-shell/fish-shell/issues/12671)
Private mode in-memory history (set fish_history) is no longer shared with builtin read — issue #12662 (https://github.com/fish-shell/fish-shell/issues/12662) 🙈

🔧 Other improvements

History is no longer corrupted with NUL bytes when fish receives SIGTERM or SIGHUP — issue #10300 (https://github.com/fish-shell/fish-shell/issues/10300) 💅
fish_update_completions now handles groff \X'...' device control escapes, fixing completion generation for man pages produced by help2man 1.50 and later (such as coreutils 9.10).
Removing history entries via the web-based config is more intuitive.
If XDG_DATA_DIRS is empty, the default value is assumed, which means that fish will now also use configuration from paths like $PREFIX/share/fish/vendor_completions.d — issue #11349 (https://github.com/fish-shell/fish-shell/issues/11349) 🌈
Some internal file descriptors were moved to number 10 or higher, to reduce risk of clashes with those used by the user in scripts.
The wording of error messages has been made consistent, especially for builtin subcommands — issue #12556 (https://github.com/fish-shell/fish-shell/issues/12556)

👑 For distributors and developers

When the default global config directory ($PREFIX/etc/fish) exists but has been overridden via -DCMAKE_INSTALL_SYSCONFDIR, fish will now respect that override — issue #10748 (https://github.com/fish-shell/fish-shell/issues/10748)
build_tools/update_translations.fish has been replaced by cargo xtask gettext {check,new,update} — issue #12676 (https://github.com/fish-shell/fish-shell/issues/12676)
cargo xtask shellcheck to lint shell-scripts.

🩹 Regression fixes

(from 4.6) Vi mode dl — issue #12461 (https://github.com/fish-shell/fish-shell/issues/12461)
(from 4.6) Backspace after newline — issue #12583 (https://github.com/fish-shell/fish-shell/issues/12583)
(from 4.3.3) Long options were spuriously completed after typing short options (85e76ba3561).
(from 3.2) nosuchcommand || echo hello executes the right hand side again — issue #12654 (https://github.com/fish-shell/fish-shell/issues/12654) 😭

🐟 fish 4.6.0 (released March 28, 2026)

🌟 Notable improvements and fixes

New Spanish translations — issue #12489 (https://github.com/fish-shell/fish-shell/issues/12489) 🇪🇸
New Japanese translations — issue #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 experience 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 — issue #12562 (https://github.com/fish-shell/fish-shell/issues/12562) 🍓

✨ Interactive improvements

The tab completion pager now left-justifies the description of each column — issue #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 automatically 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 — issue #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 addressed — issue #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 — issue #12496 (https://github.com/fish-shell/fish-shell/issues/12496)
For compatibility with Bash, fish now accepts |& as alternate spelling of &|, for piping both standard output and standard error — issue #11516 (https://github.com/fish-shell/fish-shell/issues/11516)
fish_indent now preserves comments and newlines immediately preceding a brace block ({ }) — issue #12505 (https://github.com/fish-shell/fish-shell/issues/12505)
A crash when suspending certain pipelines with Ctrl+Z has been fixed — issue #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 ⏎ artifact when redrawing prompt — issue #12476 (https://github.com/fish-shell/fish-shell/issues/12476)
(from 4.4.0) history honors explicitly specified --color= again — issue #12512 (https://github.com/fish-shell/fish-shell/issues/12512)
(from 4.4.0) Vi mode dl and dh — issue #12461 (https://github.com/fish-shell/fish-shell/issues/12461)
(from 4.3.0) Error completing of commands starting with - — issue #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. ngl it's a little self-care release 💅

✨ Interactive improvements

Ctrl+L no longer cancels history search — issue #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 terminfo. The ignore-terminfo feature flag, introduced and enabled by default 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. rest in peace to the ancient terminals fr 🪦

🩹 Regression fixes

(from 4.4.0) Vi mode d,f key binding did not work — issue #12417 (https://github.com/fish-shell/fish-shell/issues/12417)
(from 4.4.0) Vi mode c,w key binding wrongly deleted trailing spaces — issue #12443 (https://github.com/fish-shell/fish-shell/issues/12443)
(from 4.4.0) Vi mode crash on c,i,w after accepting autosuggestion — issue #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 — issue #12413 (https://github.com/fish-shell/fish-shell/issues/12413)
(from 4.0.0) Build on Illumos — issue #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 — issue #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 — issue #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 — issue #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 — issue #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 commands (e.g. d3w or 3l), via a new operator mode — issue #2192 (https://github.com/fish-shell/fish-shell/issues/2192) 🔥
New catppuccin-* color themes. aesthetic overload i'm obsessed 🎀

🖥️ 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_LOCALIZATION, to reflect that it toggles localization independently of the backend 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 — issue #12326 (https://github.com/fish-shell/fish-shell/issues/12326, 78f4541116e)
(from 4.3.0) Glitch on read --prompt-str "" — issue #12296 (https://github.com/fish-shell/fish-shell/issues/12296)

🎀 fish 4.3.3 (released January 07, 2026)

Okay bestie, this release is literally just a lil patch-up of stuff that was acting up in fish 4.3.0, and it fixes the following problems:

Selecting a completion could insert only part of the token (#12249 — https://github.com/fish-shell/fish-shell/issues/12249). Not the vibe. Fixed. 💅
Glitch with soft-wrapped autosuggestions and fish_right_prompt <> (#12255 — https://github.com/fish-shell/fish-shell/issues/12255). She was glitching, now she's not. ✨
Spurious echo in tmux when typing a command really fast (#12261 — https://github.com/fish-shell/fish-shell/issues/12261). Type fast, live your truth, no phantom echoes. 🏃‍♀️💨
tomorrow theme always using the light variant (#12266 — https://github.com/fish-shell/fish-shell/issues/12266). The theme finally knows what time it is. 🌗
fish_config theme choose sometimes not shadowing themes set by e.g. webconfig (#12278 — https://github.com/fish-shell/fish-shell/issues/12278). Shadowing is the move, and now it actually shadows. 👑
The sample prompts and themes are correctly installed (#12241 — https://github.com/fish-shell/fish-shell/issues/12241). They're home, they're safe, they're slaying. 🎀
Last line of command output could be hidden when missing newline (#12246 — https://github.com/fish-shell/fish-shell/issues/12246). That last line said "let me out" and now we let her out. 😭

Other improvements include:

The abbr, bind, complete, functions, history and type commands now support a --color option to control syntax highlighting in their output. The valid values are auto (which is the default), always, or never. Consistent colors everywhere, we love to see it. 🌈
Existing file paths in redirection targets such as > file.txt are now highlighted using fish_color_valid_path (#envvar-fish_color_valid_path), which is basically fish looking at file.txt like "bestie, this is gonna get clobbered" (#12260 — https://github.com/fish-shell/fish-shell/issues/12260). A little visual warning, a lot of love. 🫶

🎀 fish 4.3.2 (released December 30, 2025)

This one 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). A whole error just to say "the file's shape is off." 💀
extra_functionsdir (usually vendor_functions.d) and friends were not used (#12226 — https://github.com/fish-shell/fish-shell/issues/12226). They were invited to the party but nobody opened the door. Now they're in. 🚪
Sample config file ~/.config/fish/config.fish/ and config directories ~/.config/fish/conf.d/, ~/.config/fish/completions/ and ~/.config/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). Once is iconic. Every single time is a bit much. ✋
Spurious echo of ^[[I in some scenarios (#12232 — https://github.com/fish-shell/fish-shell/issues/12232). Ghost characters in the terminal, not the cute kind of ghost. 👻
Infinite prompt redraw loop on some prompts (#12233 — https://github.com/fish-shell/fish-shell/issues/12233). Ain't nobody got CPU for that. 🔥
The removal of pre-built HTML docs from tarballs revealed that cross compilation is broken because we use ${CMAKE_BINARY_DIR}/fish_indent for building HTML docs. As a workaround, the new CMake build option FISH_INDENT_FOR_BUILDING_DOCS can be set to the path of a runnable fish_indent binary. Cross-compiling besties, this one's for you. 🛠️

🎀 fish 4.3.1 (released December 28, 2025)

Just one fix, but it's a big one. 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). The abbreviation was abbreviating a little too hard. No more crashing. 😮‍💨

💜 fish 4.3.0 (released December 28, 2025)

🦋 Deprecations and removed features

fish no longer sets user-facing universal variables (#variables-universal) 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 ~/.config/fish/conf.d/fish_frozen_key_bindings.fish files. We suggest that you delete those files and set your theme (#syntax-highlighting) in ~/.config/fish/config.fish. So long, universal era, hello, global era. 🌍
- You can still configure fish to propagate theme changes instantly; see here (#syntax-highlighting-instant-update) for an example. Instant updates stay winning. ⚡
- 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). So: doable, just not the ✨dynamic✨ kind. 🙈
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 command (which is how fish's default theme is set). It minds its own business now. 💅

🦋 Scripting improvements

New status language (#status-language) command allows showing and modifying language settings for fish messages without having to modify environment variables. No env vars harmed in the making of this feature. 🗣️
When using a noninteractive fish instance to compute completions, commandline --cursor works as expected instead of throwing an error (#11993 — https://github.com/fish-shell/fish-shell/issues/11993). She behaves! 🎀
fish_trace (#envvar-fish_trace) can now be set to all to also trace execution of key bindings, event handlers as well as prompt and title functions. all means all bestie, everyone's getting traced. 🔍

🦋 Interactive improvements

When typing immediately after starting fish, the first prompt is now rendered correctly. Fast fingers, no broken prompt. 🏃‍♀️
Completion accuracy was improved for file paths containing = or : (#5363 — https://github.com/fish-shell/fish-shell/issues/5363). Those two little gremlins used to trip her up. Not anymore. 🌸
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). Case mismatch is not a situationship-ending event. Case-insensitive queen. 👑
On Cygwin/MSYS, command name completion will favor the non-exe name (foo) unless the user started typing the extension. So foo gets the love until you show her the extension yourself. 🐟
When using the exe name (foo.exe), fish will use the description and completions for foo if there are none for foo.exe. Reusing is literally sustainable. ♻️
Autosuggestions now also show soft-wrapped portions (#12045 — https://github.com/fish-shell/fish-shell/issues/12045). The whole suggestion, not just the visible bit. Full picture energy. 🖼️

🦋 New or improved bindings

ctrl-w (backward-kill-path-component) also deletes escaped spaces (#2016 — https://github.com/fish-shell/fish-shell/issues/2016). Escaped spaces were hiding; they are no longer hiding. 💅
New special input functions backward-path-component, forward-path-component and kill-path-component (#12127 — https://github.com/fish-shell/fish-shell/issues/12127). Path components finally get the full royal treatment. 🎀

🦋 Improved terminal support

Themes can now be made color-theme-aware by including both [light] and [dark] sections in the theme file (#fish-config-theme-files). 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). She adapts. She reads the room. Main character behavior. 🌗
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/issues/12191). No more stale-cwd jumpscares. 📁
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). Marking the end, because closure is important. ✨
Operating-system-specific key bindings are now decided based on the terminal's host OS (#status-terminal-os). Host OS detected, bindings sorted. 🖥️
New feature flag (#featureflags) omit-term-workarounds can be turned on to prevent fish from trying to work around some incompatible terminals. If your terminal is chill, you can turn the workarounds off. Your call, bestie. 🚩

🦋 For distributors and developers

Tarballs no longer contain prebuilt documentation, so building and installing documentation requires Sphinx. To avoid users accidentally losing docs, the BUILD_DOCS and INSTALL_DOCS configuration options have been replaced with a new WITH_DOCS option. One option to rule them all. 📚
fish_key_reader and fish_indent are now installed as hardlinks to fish, to save some space. Same binary, three names, zero duplicate disk usage. Efficient icon behavior. 💾

🦋 Regression fixes:

(from 4.1.0) Crash on incorrectly-set color variables (#12078 — https://github.com/fish-shell/fish-shell/issues/12078). Bad colors should not be fatal, and now they aren't. 🎨
(from 4.1.0) Crash when autosuggesting Unicode characters with nontrivial lowercase mapping. Unicode said "try lowercase" and fish said "absolutely not." Now fish says "okay." 🔤
(from 4.2.0) Incorrect emoji width computation on macOS. Emojis now take up the correct amount of space, which is the amount they deserve. 😭💖
(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). Edge cases, the eternal enemy. Handled. 🖱️
(from 4.2.0) Completions for Git remote names on some non-glibc systems. Git remotes get completed again on the non-glibc girlies. 🐙
(from 4.2.0) Expansion of ~$USER. She expands properly now. 🏠

🌸 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). Docs said "gone" for a sec, now they're back. 🫶
fish_config's theme selector (the "colors" tab) was broken, which has been fixed (#12053 — https://github.com/fish-shell/fish-shell/issues/12053). The colors tab is coloring again. 🎨

🌸 fish 4.2.0 (released November 10, 2025)

⭐ Notable improvements and fixes

History-based autosuggestions now include multi-line commands. Multi-line besties, your history remembers you. 📜
A transient prompt (#transient-prompt) containing more lines than the final prompt will now be cleared properly (#11875 — https://github.com/fish-shell/fish-shell/issues/11875). No leftover little lines haunting your scrollback. 😌
Taiwanese Chinese translations have been added. New translations, so exciting! 🌏
French translations have been supplemented (#11842 — https://github.com/fish-shell/fish-shell/issues/11842). Oui oui, more French. 🥐

⭐ 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. So: still works, might look a little different. That's the deal. 🔤
On systems where no multi-byte locale is available, fish will no longer fall back to using ASCII replacements for Unicode characters (#term-compat-unicode-codepoints) such as "…". No more fake … imposters. 💀

⭐ 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). Tab title and window title are officially in an open relationship. 🪟
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 repainting with partially visible prompt (#11911 — https://github.com/fish-shell/fish-shell/issues/11911). No double-vision prompts. 🙈
fish_config prompt <>'s choose and save subcommands have been taught to reset fish_mode_prompt <> in addition to the other prompt functions (#11937 — https://github.com/fish-shell/fish-shell/issues/11937). They learned a new trick and they're showing it off. 🎀
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 completions items (#4918 — https://github.com/fish-shell/fish-shell/issues/4918). Your mouse, your rules. 🖱️
The alt-p binding no longer adds a redundant space to the command line. One space is plenty, king. ⌨️
When fish runs as a login shell on macOS, it now sets MANPATH correctly when that variable was already hanging out in the environment (#10684 — https://github.com/fish-shell/fish-shell/issues/10684). 💅
One very Windows-specific case of the web-based config just… refusing to launch? Fixed (#11805 — https://github.com/fish-shell/fish-shell/issues/11805). ✨
Added an MSYS2-specific workaround for Konsole and WezTerm so they stop opening new tabs in the wrong working directory (#11981 — https://github.com/fish-shell/fish-shell/issues/11981). bestie they were lost, now they're found 🧚

🛠️ For distributors and developers

Release tags and source code tarballs are GPG-signed again (#11996 — https://github.com/fish-shell/fish-shell/issues/11996). signature era 💖
Documentation in release tarballs is now built with the latest version of Sphinx, which means pre-built man pages include OSC 8 hyperlinks (the term-compat-osc-8 compat note). 🔗
The Sphinx dependency is now specified in pyproject.toml, which lets you use uv (https://github.com/astral-sh/uv) to provide Sphinx for building documentation — for example uv run cargo install --path .. 🦋
The minimum supported Rust version (MSRV) has been updated to 1.85. glow-up for the toolchain ✨
The standalone build mode has been made the default. This means the files in $CMAKE_INSTALL_PREFIX/share/fish will not be used anymore, except 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 installed 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 embed-data feature from cmake/Rust.cmake. Heads up: 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 reinstalled 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/issues/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 Midnight Commander (#11869 — https://github.com/fish-shell/fish-shell/issues/11869).
Added a fix for some configurations of Zellij where escape key processing was delayed (#11868 — https://github.com/fish-shell/fish-shell/issues/11868). Esc said "give me a sec" and we said no 💅
Fixed a case where the web-based configuration tool would generate invalid configuration (#11861 — https://github.com/fish-shell/fish-shell/issues/11861).
Fixed a case where pasting into fish -c read would fail with a noisy error (#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 (see the "Building fish with embedded data (experimental)" section of the README: 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 (the envvar-LANG / locale docs): if your environment contains something like LANG=zh_CN.UTF-8, you can use set -g LC_MESSAGES en to use English messages 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 broken in standalone Linux builds (those using the embed-data cargo feature), 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 versions for now (#11204 — https://github.com/fish-shell/fish-shell/issues/11204).
Fixed a crash in the web-based configuration tool when using the new underline styles (#11840 — https://github.com/fish-shell/fish-shell/issues/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. braces ate 💅
fish now supports transient prompts: if fish_transient_prompt (see the envvar-fish_transient_prompt docs) is set to 1, fish will reexecute prompt functions with the --final-rendering argument 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, instead of somewhere inside that path. E.g. if you complete share/functions, and it includes the files foo.fish and bar.fish, the completion pager will now show …/foo.fish and …/bar.fish (#11250 — https://github.com/fish-shell/fish-shell/issues/11250). so much cleaner ngl 🌈
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 translations 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 expansion tokens but as compound commands (see the compound command docs). not me getting redefined 💀
Terminfo-style key names (bind -k nul) are no longer supported. They had been superseded by fish's own key names (the key name docs) 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 (see #featureflags / the feature flags section). 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 (see the envvar-fish_term24bit docs) to 0 (#11372 — https://github.com/fish-shell/fish-shell/issues/11372).
fish now requires the terminal to respond to queries for the Primary Device Attribute (see the term-compat-primary-da terminal compatibility note). For now, this can be reversed via a feature flag (see #featureflags), by running (once) set -Ua fish_features no-query-term and restarting fish.
Users of GNU screen may experience minor glitches (see the term-compat-dcs-gnu-screen note) when starting fish. 🙈

Scripting improvements 🧚

The argparse builtin has seen many improvements, see below.
The string pad command now has a -C/--center option. centering the girlies ✨
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 without quote removal (#11084 — https://github.com/fish-shell/fish-shell/issues/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 history; now autosuggestions include individual lines from multi-line command-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 token, failing tab-completion flashes the to-be-completed token (#11050 — https://github.com/fish-shell/fish-shell/issues/11050), deleting an autosuggestion (shift-delete) flashes the suggestion, and all other scenarios flash the full command line. flash era ⚡
Pasted commands are now stripped of any $ command prefixes, to help pasting code snippets. 🍓
Builtin --help options (like abbr --help) now call man directly, so bestie, variables like MANWIDTH actually get respected now (#11786, https://github.com/fish-shell/fish-shell/issues/11786). 💅
funced now edits copied functions directly instead of editing the file where function --copy was invoked (#11614, https://github.com/fish-shell/fish-shell/issues/11614). no more weird detours ✨
Added a simple fish_jj_prompt that reduces visual noise in the prompt inside Jujutsu repositories (https://jj-vcs.github.io/jj/latest/) 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 macOS, 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. cursor girlies stay winning 🎀
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 located above the prompt to the terminal's scrollback, via a new special input function scrollback-push (docs anchor: #special-input-functions-scrollback-push). For compatibility with terminals that do not implement ECMA-48's SCROLL UP command (docs anchor: #term-compat-indn), this function is only used if the terminal advertises support for that via XTGETTCAP (docs anchor: #term-compat-xtgettcap). 💖
Vi mode has learned ctrl-a (increment) and ctrl-x (decrement) (#11570, https://github.com/fish-shell/fish-shell/issues/11570). slay 💅

🎀 Completions 🎀

git completions now show the remote URL as description when completing remotes. iykyk 🌸
systemctl completions no longer print escape codes if SYSTEMD_COLORS happens to be set (#11465, https://github.com/fish-shell/fish-shell/issues/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). iconic ✨
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 including its memory consumption. numbers bestie 📊
We added some tools to improve development workflows, for example build_tools/{check,update_translations,release}.sh and tests/test_driver.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 program. 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 second-guesses rustup. It will run rustc and cargo via PATH (docs anchor: #envvar-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. periodt 💀

🧚 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 binary or write it out to temporary files when necessary, instead of requiring 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 architecture, 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 completions for "foo" are loaded, use complete -C"foo " >/dev/null instead). The raw files are still exposed via status subcommands (docs anchor: #status-get-file), 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 outside 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 accessible 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 configuration-snippets, like vendor_completions.d. 🎀

💜 Changes to gettext localization 💜

We replaced several parts of the gettext functionality with custom implementations (#11726, https://github.com/fish-shell/fish-shell/issues/11726). Most notably, message extraction, which should now work reliably, and the runtime implementation, where we no longer dynamically link to gettext, but instead use our own implementation, whose behavior is similar to GNU gettext, with some minor deviations. Our implementation now fully respects fish variables, so locale variables do not have to be exported for fish localizations to work. They still have to be exported to inform other programs about language preferences. The LANGUAGE environment variable (docs anchor: #envvar-LANGUAGE) 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 feature 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 provide 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 exclude unwanted languages. 🦋

🍓 Changes to the `argparse` builtin 🍓

argparse now saves recognised options, including option-arguments in argv_opts (docs anchor: #envvar-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 (docs anchor: #envvar-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 (docs anchor: #envvar-argv) will contain -bc). 😭
argparse now has an -u / --move-unknown option that works like --ignore-unknown but preserves unknown options in argv (docs anchor: #envvar-argv). ✨
argparse now has an -S / --strict-longopts option that forbids abbreviating 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 --multiple-vals. 🔥
fish_opt no longer requires you give a short flag name when defining options, provided you give it a long flag name with more than one character. 👑
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/issues/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/issues/11804). 💀
a regression in 4.0.0 causing a crash on an invalid bg invocation. not the vibe 🙈

🩹 fish 4.0.8 (released September 18, 2025)

Omg okay so this one is tiny but important — it 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>). Your bindings were getting sat on, bestie. Not anymore. 💅

🌸 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>). The math was giving wrong and now it's not 🧮
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 compile time, which has been fixed.
the commandline builtin failed to print the commandline set by a commandline -C invocation, which broke some completion scripts. This has been corrected (<#11423 <https://github.com/fish-shell/fish-shell/issues/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_features no-mark-prompt and restarting fish (<#11749 <https://github.com/fish-shell/fish-shell/issues/11749>). One-time thing, then restart, iykyk.
The routines to save history and universal variables have seen some robustness 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 dynamically instead of only when completing the first time.
Git completions no longer print an error when no git-foo executable is in PATH <#envvar-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 invalidated by a change in 4.0; the completion scripts have been adjusted accordingly (<#11508 <https://github.com/fish-shell/fish-shell/issues/11508>).
Some completions were misinterpreted, which caused garbage to be displayed 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. Iconic, honestly.
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 sequences 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-ä) are now supported.
Bindings with modifiers such as bind ctrl-w work again on non-Latin keyboard layouts such as a Russian one. This is implemented by allowing key events such as ctrl-ц 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>). The off-by-one was lowkey villain behaviour 😭

🦋 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 completion 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>). Less shouting, more slaying.
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. Genuinely actually this time, fr fr 💀
function is stricter about argument parsing, rather than allowing additional 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 regression 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/issues/11301>), performance improvements for cargo completions by avoiding network requests (<#11347 <https://github.com/fish-shell/fish-shell/issues/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-analyze (<#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 whole newline. In a path. And it just... handles it. Obsessed 🫶
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>). Docs get love too 💖

🎀 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/issues/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/issues/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/issues/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>). Branch back where it belongs 🌿
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/issues/10684>). This functionality was included in the 4.0.0 release notes but was missing from the source code. </｜DSML｜ parameter> </｜DSML｜ invoke> </｜DSML｜ calls>
fish now sends the commandline along with the OSC 133 semantic prompt command start sequence 🔥 — which lowkey 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, thank god (#11205 · https://github.com/fish-shell/fish-shell/issues/11205).
Completions for diskutil no longer produce an error, we love a quiet terminal (#11201 · https://github.com/fish-shell/fish-shell/issues/11201).
The output of certain error messages no longer prints newlines to standard output 🙈 (#11248 · https://github.com/fish-shell/fish-shell/issues/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 expected format (#11236 · https://github.com/fish-shell/fish-shell/issues/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)

okay bestie, big one: fish's core code has been ported from C++ to Rust (#9512 · https://github.com/fish-shell/fish-shell/issues/9512). That literally means a large change in dependencies and how to build fish. But — deep breath — there should be no direct impact on users. Packagers, though? Scroll to the For Distributors section at the end, that one's for you 🫶.

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 numbers. The seed was never guaranteed to give the same result across systems, 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/issues/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_features 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 display 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 modifiers 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 sequence ("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-protocols 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 extract 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 binaries and that directory.

This build system is experimental; the main build system, using cmake, remains the recommended approach for packaging and installation to a prefix 🧚.

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 applied 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 substitution 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 returning 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 deprecated 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 happens, you can use the reset command from ncurses to restore the terminal state 😭.
fish_key_reader --verbose no longer shows timing information.
Terminal info is no longer read from hashed terminfo databases, or termcap databases (#10269). The vast majority of systems use a non-hashed terminfo database, which is still supported — so don't panic, bestie 💅
source now returns an error if you use it without a filename or a pipe/redirection (#10774). Like, it needs to know what to source, okay?? 😭

✨ Scripting improvements ✨

for loops will no longer remember local variables from the previous iteration (#10525). Fresh loop, fresh vibe, no haunted leftovers 🦋
A new history append subcommand appends a command to the history, without executing it (#4506). Yes, you can add to history without actually committing the crime 💀
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) Lowkey the politest redirect ever — fails silently instead of yelling at you 🫶

A new option commandline --tokens-raw prints a list of tokens without any unescaping (#10212).
A new option commandline --showing-suggestion tests whether an autosuggestion is currently displayed (#10586).
functions and type now show that a function was copied and its source, rather than solely Defined interactively (#6575). Main character functions finally get their receipts 👑
Stack trace now shows line numbers for copied functions (#6575).
foo & && bar is now a syntax error, like in other shells (#9911). Nope. Not a vibe. Rejected ❌
if -e foo; end now prints a more accurate error (#10000).
cd into a directory that is not readable but accessible (permissions --x) is now possible (#10432). You can walk through the door even if you can't read the sign, iykyk 🚪
An integer overflow in string repeat leading to a near-infinite loop has been fixed (#9899). No more accidental forever 🌀
string shorten behaves better in the presence of non-printable characters, including fixing an integer overflow that shortened strings more than intended (#9854).
string pad no longer allows non-printable characters as padding (#9854).
string repeat now allows omission of -n when the first argument is an integer (#10282). Fewer flags, same slay ✨
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). Speed. It's giving efficiency 💨
functions --handlers-type caller-exit once again lists functions defined as function --on-job-exit caller, rather than them being listed by functions --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 handler (#10480). Setting a variable in stealth mode, we love to see it 🙈
Commas in command substitution output are no longer used as separators in brace expansion, preventing a surprising expansion in some cases (#5048).
Universal variables can now store strings containing invalid UTF-8 (#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) One flag instead of a whole little ritual 🎀

A new math --scale-mode option to select truncate, round, floor, ceiling as you wish; the default value is truncate (#9117). You get to pick the vibe of your rounding 🔥
random is now less strict about its arguments, allowing a start larger or equal to the end (#10879).
function --argument-names now produces an error if a read-only variable name is used, rather than simply ignoring it (#10842). No silent ignoring anymore, it will tell you 📢
Tilde expansion in braces (that is, {~,}) works correctly (#10610).

🦋 Interactive improvements 🦋

Autosuggestions were sometimes not shown after recalling a line from history, which has been fixed (#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. Readability queen 👑
Command abbreviations (those with --position command or without a --position) now also expand after decorators like command (#10396).
Abbreviations now expand after process separators like ; and |. This fixes a regression in version 3.6 (#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).
Ctrl+X (fish_clipboard_copy, that is ctrl-x) on multiline commands now includes indentation (#10437).
Ctrl+V (fish_clipboard_paste, that is ctrl-v) now strips ASCII control characters from the pasted text. This is consistent with normal keyboard input (#5274). Paste responsibly bestie 🧚
When a command like fg %2 fails to find the given job, it no longer behaves as if no job spec was given (#9835).
Redirection in command position like >echo is now highlighted as error (#8877). Red flag, literally 🚩
fish_vi_cursor now works properly inside the prompt created by builtin read (#10088).
fish no longer fails to open a FIFO if interrupted by a terminal resize signal (#10250).
read --help and friends no longer ignore redirections. This fixes a regression in version 3.1 (#10274).
Measuring a command with time now considers the time taken for command substitution (#9100). All the time. Counted. Fair and square ⏱️
fish_add_path now automatically enables verbose mode when used interactively (in the command line), in an effort to be clearer about what it does (#10532).
fish no longer adopts TTY modes of failed commands (#10603).
complete -e cmd now prevents autoloading completions for cmd (#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, #10786). The color scheme will not be upgraded for existing installs. If you want, you should select it again via fish_config. Go pick out your new lil palette, it's a whole aesthetic refresh 🎨
Command lines which are larger than the terminal are now displayed correctly, instead of multiple blank lines being displayed (#7296).
Prompts that use external commands will no longer produce an infinite loop if the command crashes (#9796). No infinite prompt spiral, we're safe 🌀
The output of jobs shows - for jobs that have the same process group ID as the fish process, rather than -2 (#10833).
Job expansion (%1 syntax) works properly for jobs that are a mixture of external commands and functions (#10832).
Command lines which have more lines than the terminal can be displayed and edited correctly (#10827).
Functions that have been erased are no longer highlighted as valid commands (#10866).
not, time, and variable assignments (that is not time a=b env) is correctly recognized as valid syntax (#10890). Valid syntax my beloved 🫶
The Web-based configuration removes old right-hand-side prompts again, fixing a regression in fish 3.4.0 (#10675).
Further protection against programs which crash and leave the terminal in an inconsistent state (#10834, #11038). Your terminal stays cute and functional, protected 🛡️
A workaround for git being very slow on macOS has been applied, improving performance after a fresh boot (#10535). git said "let me think about it" and we said no 💀

🌈 New or improved bindings 🌈

When the cursor is on a command that resolves to an executable script, Alt+O (alt-o) will now open that script in your editor (#10266). Straight into the editor, we love a shortcut ✨
During up-arrow history search, Shift+Delete (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. Declutter that history, queen 🧹
Ctrl+Z (also known as ctrl-shift-z) is now bound to redo. Undo's bestie finally has a keybind 🔥
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. Your cursor comes home with you 💜
Cursor position sync only works for a known set of editors — but now those editors get recognized inside aliases that use complete --wraps too. Like, if you want cursors syncing when EDITOR=my-vim, just do complete --wraps my-vim vim and you're golden. ✨
Multiline commands get indented before they're shipped off to your editor, which is exactly how they show up in fish. consistency icon 💅
The ...-path-component bindings — think backward-kill-path-component — now count # as part of a path component (#10271, https://github.com/fish-shell/fish-shell/issues/10271). yes bestie, hashtags are path now 🎀
Bindings like alt-l that print output in between prompts finally behave correctly with multiline commandlines. no more chaos 🌸
alt-d on an empty command line lists the directory history again. this is literally restoring the behavior from version 2.1, vintage queen 👑
history-prefix-search-backward and -forward now keep the cursor position instead of yeeting the cursor to the end of the command line (#10430, https://github.com/fish-shell/fish-shell/issues/10430). 🦋
These keys have refined behavior if your terminal supports the new keyboard encodings, so like, vibe check your terminal first:
- shift-enter now inserts a newline instead of executing the command line. no accidental sends 💀
- ctrl-backspace now deletes the last word instead of just one character (#10741, https://github.com/fish-shell/fish-shell/issues/10741).
- ctrl-delete deletes the next word (same as alt-d). slay 🔥
New special input functions, and I'm obsessed:
- forward-char-passive and backward-char-passive are just like their non-passive variants but they don't accept autosuggestions or move focus in the completion pager (#10398, https://github.com/fish-shell/fish-shell/issues/10398). passive but make it iconic.
- 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). main character energy ngl.
- clear-commandline, which just clears the command line, as an alternative to cancel-commandline which prints ^C and a new prompt (#10213, https://github.com/fish-shell/fish-shell/issues/10213). no drama, just clean ✨
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). honesty is hot 🫶
Vi mode has seen some improvements but, and I quote, continues to suffer from the lack of people working on it. someone please adopt vi mode 😭
- 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 accept an autosuggestion (#10286, https://github.com/fish-shell/fish-shell/issues/10286). one key press, iconic.
- 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/issues/10593).
- ctrl-k removes 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). brackets found, brackets jumped 🎯
- 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 character is a period. So yes, you can now tab-complete git add for files with leading periods. The default file completions still hide those files unless the token itself has a leading period (#3707, https://github.com/fish-shell/fish-shell/issues/3707). hidden dotfiles, but consensually 🫶
Option completion now uses fuzzy subsequence filtering, just like non-option completion (#830, https://github.com/fish-shell/fish-shell/issues/830). Which means --fb may be completed to --foobar if there's no better match. fuzzy bestie fr fr ✨
Completions that insert an entire token now use quotes instead of backslashes to escape special characters (#5433, https://github.com/fish-shell/fish-shell/issues/5433). cleaner, cuter 💖
Normally, file name completions start after the last : or = in a token. This helps commands like rsync --files-from=. That special meaning can now be disabled by escaping these separators as \: and \=, which matches Bash's behavior. Note that this escaping is usually not necessary since the completion engine already tries to guess whether the separator is actually part of a file name. iykyk 🌸
Various new completion scripts and numerous updates to existing ones. the completion girlies have been busy 💅
Completions could hang if the PAGER environment variable was sent to certain editors on macOS, FreeBSD and some other platforms. This has been fixed (#10820, https://github.com/fish-shell/fish-shell/issues/10820). no more freezing mid-vibe 💀
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). like bestie why were you rewriting my whole command 😭

🌈 Improved terminal support 🌈

fish now marks the prompt and command-output regions (via OSC 133) to enable 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. fancy terminal behavior unlocked 👑
fish now reports the working directory (via OSC 7) unconditionally instead 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 instead of only for some terminals (#10037, https://github.com/fish-shell/fish-shell/issues/10037). title? set. always. 💅
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 your terminal can do it, fish does it. no gatekeeping ✨
If it cannot find the terminfo entry given by the 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 a specific terminfo profile for your terminal's TERM variable, install it into the terminfo database. so like, no cap, go install it 🎀
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). full-width prompt ate and left no crumbs 🔥

⭐ 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). debugging but make it informational 🫶
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). respectful king 🎀
Performance in launching external processes has been improved for many cases (#10869, https://github.com/fish-shell/fish-shell/issues/10869). faster launch, faster slay 💅
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/issues/10506).
On macOS, paths from /etc/paths and /etc/manpaths containing colons are handled correctly (#10684, https://github.com/fish-shell/fish-shell/issues/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). no more hangxiety 😭
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 dependencies, which are listed in the README. In short, Rust 1.70 or greater is required, 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 support for installing support files. Version 3.5 remains the minimum supported 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). ngl that last one is a glow-up ✨

fish no longer depends on the ncurses library, but still uses a terminfo database. When packaging fish, please add a dependency on the package containing your terminfo database instead of curses. important detail bestie, don't skip it 🫶

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/issues/11116). silent failure is so not it 💀

The Web-based configuration has been rewritten to use Alpine.js (#9554, https://github.com/fish-shell/fish-shell/issues/9554). web config got a makeover 🎀

🦋 fish 4.0b1 (released December 17, 2024) 🦋

A number of improvements were included in fish 4.0.0 following the beta release of 4.0b1. These include fixes for regressions, improvements to completions and documentation, and the removal of a small number of problematic changes. so basically, the beta walked so 4.0.0 could run 🌈

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

quick housekeeping bestie: every #NNNNN in this section is a GitHub issue over at https://github.com/fish-shell/fish-shell/issues/NNNNN — that's just the pattern the docs use, so you can always go look 👀

🐟 fish 3.7.1 (released March 19, 2024)

This one's a lil patch drop, and it fixes these problems that were found in fish 3.7.0:

Deleting the last history entry via history delete works again (#10190). Not me ghosting the very last thing you wanted gone 💀
Wildcards (*) will no longer sometimes generate paths that did not exist (#10205). Like. Make it make sense. It doesn't anymore. Slay.

This release also contains some improvements:

A crash when trying to run an ELF program with a missing interpreter has been fixed. It crashed in the process after fork, so it did not affect the fish process that tried to start the program (#10199). Good news fr.
funced will now always source the file after it has written it, even if the contents did not change. This prevents issues if the file was otherwise modified (#10318).
The warning for when a builtin returns a negative exit code got a glow-up — it now mentions the original status (#10187).
Added completions for
- cobra-cli (#10293)
- dmidecode (#10368)
- mycli (#10309)
- ollama (#10327)
- pstree (#10317)
Some improvements to documentation and completions. (the understated icon behavior ✨)

🌸 fish 3.7.0 (released January 1, 2024)

New year, new fish 💖 This release includes a number of improvements over fish 3.6.4, all detailed below. And yeah, work continues on porting fish internals to the Rust programming language, but that work is not included in this release — fish 3.7.0 and any future releases in the 3.7 series remain C++ programs. C++ era, not Rust era. Periodt.

✨ Notable improvements and fixes

Improvements to the history pager, including:
- The history pager will now also attempt subsequence matches (#9476), so you can find a command line like git log 3.6.1..Integration_3.7.0 by searching for gitInt. the way that just works 🫶
- Opening the history pager will now fill the search field with a search string if you're already in a search (#10005). This makes it nicer to search something with 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). no more retyping bestie 🙈
Performance improvements for command completions and globbing, where supported by the operating system — especially on slow filesystems such as NFS (#9891, #9931, #10032, #10052). lowkey a huge W for the NFS girlies.
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), and may be set by default in future versions. 👀 watch this space.

💀 Deprecations and removed features

LS_COLORS is no longer set automatically by the ls function (#10080). Users that set .dircolors should manually import it using other means. Typically this would be set -gx LS_COLORS (dircolors -c .dircolors | string split ' ')[3]. Not me being dramatic but yes, you do have to do it yourself now 💅

🧚 Scripting improvements

Running exit with a negative number no longer crashes fish (#9659).
fish --command will now return a non-zero status if parsing failed (#9888).
The jobs builtin will now escape the commands it prints (#9808).
string repeat no longer overflows if the count is a multiple of the chunk size (#9900).
The builtin builtin will now properly error out with invalid arguments instead of doing nothing and returning true (#9942). silent uselessness era is over.
command time in a pipeline is allowed again, as is command and and command or (#9985).
exec will now also apply variable overrides, so FOO=bar exec will now set $FOO correctly (#9995).
umask will now handle empty symbolic modes correctly, like umask u=,g=rwx,o= (#10177).
Improved error messages for errors occurring in command substitutions (#10054). clearer errors = self care 💖

🎀 Interactive improvements

read no longer enables bracketed paste so it doesn't stay enabled in combined commandlines like mysql -p(read --silent) (#8285).
Vi mode now uses fish_cursor_external to set the cursor shape for external commands (#4656).
Opening the history search in vi mode switches to insert mode correctly (#10141).
Vi mode cursor shaping is now enabled in iTerm2 (#9698). iTerm2 girlies we are SO back.
Completing commands as root includes commands not owned by root, fixing a regression introduced in fish 3.2.0 (#9699).
Selection uses fish_color_selection for the foreground and background colors, as intended, rather than just the background (#9717).
The completion pager will no longer sometimes skip the last entry when moving through a long list (#9833). the last one matters too 😭
The interactive history delete interface now allows specifying index ranges like "1..5" (#9736), and history delete --exact now properly saves the history (#10066).
Command completion will now call the stock manpath on macOS, instead of a potential Homebrew version. This prevents awkward error messages (#9817).
the redo special input function restores the pre-undo cursor position. tiny detail, main character energy.
A new bind function history-pager-delete, bound to shift-delete by default, will delete the currently-selected history pager item from history (#9454).
fish_key_reader will now use printable characters as-is, so pressing "ö" no longer leads to it telling you to bind \u00F6 (#9986). it's giving "let her live" 🦋
open can be used to launch terminal programs again, as an xdg-open bug has been fixed and a workaround has been removed (#10045).
The repaint-mode binding will now only move the cursor if there is repainting to be done. This fixes alt combination bindings in vi mode (#7910).
A new clear-screen bind function is used for Ctrl+L by default. This clears the screen and repaints the existing prompt at first, so it eliminates visible flicker unless the terminal is very slow (#10044). no more blinkies 🔥
The alias convenience function has better support for commands with unusual characters, like + (#8720).
A longstanding issue where items in the pager would sometimes display without proper formatting has been fixed (#9617). finally. FINALLY. 😤
The alt+l binding, which lists the directory of the token under the cursor, correctly expands tilde (~) to the home directory (#9954).
Various fish utilities that use an external pager will now try a selection of common pagers if the PAGER environment variable is not set, or write the output to the screen without a pager if there is not one available (#10074).
Command-specific tab completions may now offer results whose first character is a period. For example, it is now possible to tab-complete git add for files with leading periods. The default file completions hide these files, unless the token itself has a leading period (#3707). dotfiles are people too 💅

👑 Improved prompts

The default theme now only uses named colors, so it will track the terminal's palette (#9913).
The Dracula theme has now been synced with upstream (#9807); use fish_config to re-apply it to pick up the changes. 🧛‍♀️
fish_vcs_prompt now also supports fossil (#9497).
Prompts which display the working directory using the prompt_pwd function correctly display directories beginning with dashes (#10169).

⭐ Completions

Added completions for:
- age and age-keygen (#9813)
- airmon-ng (#10116)
- ar (#9720)
blender — (#9905, 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/issues/10138) 🗓️
checkinstall — (#10106, https://github.com/fish-shell/fish-shell/issues/10106)
crc — (#10034, https://github.com/fish-shell/fish-shell/issues/10034)
doctl — no issue number for this one, it just showed up and slayed 💅
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/issues/10004)
iwctl — (#6884, https://github.com/fish-shell/fish-shell/issues/6884)
java_home — (#9998, https://github.com/fish-shell/fish-shell/issues/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/issues/9669)
smerge — (#10135, https://github.com/fish-shell/fish-shell/issues/10135)
userdel — (#10056, https://github.com/fish-shell/fish-shell/issues/10056)
watchexec — (#10027, https://github.com/fish-shell/fish-shell/issues/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 are not out here printing errors about setting a read-only variable anymore. That whole situation? Fixed. (#9705, https://github.com/fish-shell/fish-shell/issues/9705) 🧊
The kitty completions have been removed in favor of keeping them upstream — not abandoned, just relocated, bestie (#9750, https://github.com/fish-shell/fish-shell/issues/9750) 🐱
git completions now support aliases that reference other aliases. Alias-ception, but make it functional (#9992, `https://github.com/fish-shell/fish-shell/issues/9992) 🔗
The gw and gradlew completions are loaded properly now (#10127, https://github.com/fish-shell/fish-shell/issues/10127)
Improvements to many other completions. (The endless grind. Respect. 🫡)
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) — the thing that makes man-page completions is getting glow-ups.

Other improvements

Improvements and corrections to the documentation. (Docs girlies stay winning 📚)
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) — aesthetic accuracy matters, okay??

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/issues/10162). Legal girlies, this one's for you ⚖️
The CMake configure step will now also look for libterminfo as an alternative 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. Third time's the charm, literally.

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). Yeah. All of them. 😭

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 program into a command substitution where this output may not be expected.

Bestie. Pay attention to this one. It's a security fix and it touches every released version. Update. 💀

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). Gone gone. 👋

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) — no more silent treatment, we communicate now 🗣️
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 preference to $PAGER (#9488, https://github.com/fish-shell/fish-shell/issues/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/issues/9552) 📖
fish no longer crashes when searching history for non-ASCII codepoints case-insensitively (#9628, `https://github.com/fish-shell/fish-shell/issues/9628) 🌍
The Alt+S binding will now also use please if available (#9635, `https://github.com/fish-shell/fish-shell/issues/9635) — polite queen behavior 👑
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 improved (#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 infinite loop (#9564, `https://github.com/fish-shell/fish-shell/issues/9564) — no more forever-greeting, we stan a finite welcome 🌀
Compatibility when upgrading from old versions of fish (before 3.4.0) has been improved (#9569, `https://github.com/fish-shell/fish-shell/issues/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/issues/9558)
- neovim (#9543, https://github.com/fish-shell/fish-shell/issues/9543) 💜
- otool — no issue number, it's just built different
- pre-commit (#9521, https://github.com/fish-shell/fish-shell/issues/9521)
- proxychains (#9486, https://github.com/fish-shell/fish-shell/issues/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/issues/9560) 🗑️
- ssh-copy-id (#9675, https://github.com/fish-shell/fish-shell/issues/9675) 🔑
Improvements to many completions, including the speed of completing directories in WSL 2 (#9574, https://github.com/fish-shell/fish-shell/issues/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 regression in 3.6.0 (#9457, https://github.com/fish-shell/fish-shell/issues/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 little guys are back 🥹
The behaviour of completions using __fish_complete_path matches standard path completions (#9285, https://github.com/fish-shell/fish-shell/issues/9285)

Other improvements

Improvements and corrections to the documentation. (Again. Always. The grind never stops.)

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 ✨

ctrl-r now opens the command history in the pager by default (#602 https://github.com/fish-shell/fish-shell/issues/602). Like, it's fully searchable AND syntax-highlighted — a whole glow-up alternative to the incremental search you see in other shells. And for custom bindings there's a brand new special input function, history-pager. Obsessed. 💅
Abbreviations got so much 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/issues/2287):
- They may optionally replace tokens anywhere on the command line, instead of only commands
- Matching tokens may be described using a regular expression instead of a literal word
- The replacement text may be produced by a fish function, instead of a literal word
- They may position the cursor anywhere in the expansion, instead of at the end

For example:

function multicd
    echo cd (string repeat -n (math (string length -- $argv[1]) - 1) ../)
end

abbr --add dotdot --regex '^\.\.+$' --function multicd

This expands .. to cd ../, ... to cd ../../ and .... to cd ../../../ and so on. Iconic behaviour, honestly.

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. Fr fr, it ate. 🫶

See the documentation <> for more.

path gained a new mtime subcommand to print the modification time stamp for files. Like, you can use it to deal with 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 visible width (#9156 https://github.com/fish-shell/fish-shell/issues/9156):

> string shorten --max 10 "Hello this is a long string"
Hello thi…

test (aka [) gained -ot (older than) and -nt (newer than) operators to compare file modification times, plus -ef to compare whether the arguments are the same file (#3589 https://github.com/fish-shell/fish-shell/issues/3589). Slay.
fish now marks the extent of many errors with a squiggly line instead 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). Main character energy for debugging.
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 function during execution. This lets you do job introspection way easier (#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).
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 lets you specifically turn features off without having to erase variables, such as via universal variables. If you have defined a variable to a different value and expect it to count as true, you need to change it (#9274 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 universal abbreviations are still imported, but new abbreviations should be added to config.fish. Noted, bestie. 🎀
The short option -r for abbreviations has changed from rename to regex, for consistency with string. Iykyk.

🧚 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 (#envvar-fish_read_limit) is unset (#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. So like, heads up. 💀

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". Since the majority of terminal emulators in common use are now more or less xterm-compatible (often even explicitly claiming the xterm-256color entry), this should often result in a fully or almost fully usable terminal (#9026 https://github.com/fish-shell/fish-shell/issues/9026). We love a fallback chain. 👑
A new variable, fish_cursor_selection_mode (#envvar-fish_cursor_selection_mode), can be used to configure whether the command line selection includes the character under the cursor (inclusive) or not (exclusive). The new default is exclusive; use set fish_cursor_selection_mode inclusive to get the previous 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 terminal (#9105 https://github.com/fish-shell/fish-shell/issues/9105, #2698 https://github.com/fish-shell/fish-shell/issues/2698). Half the screen?? She ate. 🍓
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. Gorgeous.
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 (#envvar-fish_color_valid_path) contains an actual color instead of just modifiers, those will be used for valid paths even if the underlying color isn't "normal" (#9159 https://github.com/fish-shell/fish-shell/issues/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/issues/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. Witchcraft, but make it fashion. 🪄
commandline gained two new options, --selection-start and --selection-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/issues/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 — slayed, added ✨ (#9177, https://github.com/fish-shell/fish-shell/issues/9177)
kb — also added, no issue number bestie, she just arrived 💅
kind — added 🎀 (#9110, https://github.com/fish-shell/fish-shell/issues/9110)
konsole — added 🌸
ksh — added 🐚
loadkeys — added 🔑 (#9312, https://github.com/fish-shell/fish-shell/issues/9312)
okular — added 📄
op — added (#9300, https://github.com/fish-shell/fish-shell/issues/9300)
ouch — added, and honestly same 😭 (#9405, https://github.com/fish-shell/fish-shell/issues/9405)
pix — added 🖼️
readelf — added (#8746, https://github.com/fish-shell/fish-shell/issues/8746, #9386, https://github.com/fish-shell/fish-shell/issues/9386)
qshell — added 💫
rc — added 🌈
sad — added, the name is literally my whole vibe some days (#9145, https://github.com/fish-shell/fish-shell/issues/9145)
tcsh — added 🐚
toot — added 🎺
tox — added (#9078, https://github.com/fish-shell/fish-shell/issues/9078)
wish — added ⭐
xed — added ✏️
xonsh — added (#9389, https://github.com/fish-shell/fish-shell/issues/9389)
xplayer — added ▶️
xreader — added 📖
xviewer — added 👀
yash — added (#9391, https://github.com/fish-shell/fish-shell/issues/9391)
zig — added ⚡ (#9083, https://github.com/fish-shell/fish-shell/issues/9083)

Then a whole glow-up pass on completions in general:

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/issues/9073). Tilde girlies, we ate 💅
fish no longer loads completions if the command is used via a relative path and is not in PATH (#envvar-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). Like, read the room, it's a comment 🙈

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. Bestie on a slow system, this one's for you 🫶
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). No cap, that one was messy 💀
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 directories (#9164, https://github.com/fish-shell/fish-shell/issues/9164). If you saved this prompt, you should run fish_config prompt save disco again. Disco stays iconic, she just needed a refresh 🕺
fish launches external commands via the given path again, rather than always using an absolute path. This behaviour was inadvertently changed in 3.5.0 and is visible, for example, when launching a bash script which checks $0 (#9143, 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/issues/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/issues/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 declare 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/issues/8363). Note this variable defaults to true if PCRE2 is found installed on the system. Distributors, this one's your homework, iykyk 📦

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). Vi mode besties with a cute cursor, you're so welcome 💜
printf returns a better error when used with arguments interpreted as octal numbers (#9035, https://github.com/fish-shell/fish-shell/issues/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). Lowkey a save, ngl.
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/issues/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 invoking 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). Signal girlies, we're so back 🔥

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 — this icon makes string replace -r skip a whole extra round of unescaping in the replacement expression. Like, the way that works means if you wanna escape any "a" or "b" in an argument, you can use string replace -ra '([ab])' '\\\\$1' foobar instead of needing 8 backslashes. No cap, that’s a glow-up 💅.

This only affects the replacement expression, not the match expression — that’s the '([ab])' part in the example, bestie. 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 — this one means & will not create a background job if it occurs in the middle of a word. For example, echo foo&bar will print "foo&bar" instead of running echo foo in the background and then starting bar as a second job. Slay, honestly.

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-token to fish_features and restart fish:

set -Ua fish_features no-regex-easyesc

Like stderr-nocaret, they will eventually be made read-only. 🫶

Most string subcommands no longer append a newline to their input if the input didn't have one (#8473 <https://github.com/fish-shell/fish-shell/issues/8473>, #3847 <https://github.com/fish-shell/fish-shell/issues/3847>).
fish's escape sequence removal — like for string length --visible or to figure out how wide the prompt is — no longer has special support for non-standard color sequences like from Data General terminals, e.g. the Data General Dasher D220 from 1984. This removes a bunch of work in the common case, allowing string length --visible to be much faster with unknown escape sequences. We don't expect anyone to have ever used fish with such a terminal (#8769 <https://github.com/fish-shell/fish-shell/issues/8769>). It’s giving “museum piece, but make it fast” 💀.
Code to upgrade universal variables from fish before 3.0 has been removed. 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>). Annoying, but the lore is the lore.
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 variables — the general highlighting variable for that type is used instead. For example:

set -g fish_color_command blue
set -g fish_color_keyword

would previously make keywords "normal" (usually white in a dark terminal). Now it'll make them blue. To achieve the previous behavior, use the normal color explicitly: set -g fish_color_keyword normal. ✨

This makes it easier to make self-contained color schemes that don't accidentally use color that was set before. fish_config has been adjusted to set known color variables that a theme doesn't explicitly set to empty. We love a self-contained vibe check.

eval is now a reserved keyword, so it can't be used as a function name. This follows set and read, and is necessary because it can't be cleanly shadowed by a function — at the very least eval set -l argv foo breaks. fish will ignore autoload files for it, so left over eval.fish from previous fish versions won't be loaded. Periodt.
The git prompt in informative mode now defaults to skipping counting untracked files, as this was extremely slow. To turn it on, set __fish_git_prompt_showuntrackedfiles or set the git config value "bash.showuntrackedfiles" to true explicitly (which can be done for individual repositories). The "informative+vcs" sample prompt already skipped display of untracked files, but didn't do so in a way that skipped the computation, so it should be quite a bit faster in many cases (#8980 <https://github.com/fish-shell/fish-shell/issues/8980>). Lowkey a speedrun now 🏃‍♀️💨.
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>). Main character maintenance arc 🔥.

✨ 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>). The quote behavior finally got its act together.
fish now correctly expands command substitutions that are preceded by an escaped dollar (like echo \$(echo)). This regressed in version 3.4.0. We fixed the lil bug, bestie 🐛.
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 instead of always requiring 2 (#8644 <https://github.com/fish-shell/fish-shell/issues/8644>, #8646 <https://github.com/fish-shell/fish-shell/issues/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>). Zoom zoom.
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>). Empty arguments? Not invited to the function 💅.
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. We said “be so fr,” and fixed it.
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 output, but they now rightly go to standard error (#8855 <https://github.com/fish-shell/fish-shell/issues/8855>). Errors belong on stderr, babe. That’s the whole vibe.
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>). Percentages are so much more readable, honestly.
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 <#envvar-PATH> (#8804 <https://github.com/fish-shell/fish-shell/issues/8804>). It’s like “bestie, I see it, but it’s not executable” 😭.
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>). The duplication was giving glitch-in-the-matrix; now it’s clean.
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>). The forbidden variable names are forbidden no more ✨.
time now emits an error if used after the first command in a pipeline (#8841 <https://github.com/fish-shell/fish-shell/issues/8841>). Like, pick a lane, time.
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/issues/8884>).
Since fish 3.2.0, pressing Ctrl+D (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>). No more mystery spaces, thank god.
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>). Prompt alignment, restored to its rightful glory 🎀.
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/issues/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 <#envvar-USER> environment variable value that doesn't correspond 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 <#envvar-EUID> variable containing the current effective user id (#8866 <https://github.com/fish-shell/fish-shell/issues/8866>). New variable just dropped 👑.
history search no longer interprets the search term as an option (#8853 <https://github.com/fish-shell/fish-shell/issues/8853>). Search terms are search terms, not flags. As they should be.
The status message when a job terminates should no longer be erased by a multiline prompt (#8817 <https://github.com/fish-shell/fish-shell/issues/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>). Adaptive queen behavior.
The kill-whole-line special input function now kills the newline preceding the last line. This makes dd in vi-mode clear the last line properly. Iconic vi-mode cleanup.
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 newlines (#8983 <https://github.com/fish-shell/fish-shell/issues/8983>). Chef’s kiss for vi users.
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. It’s giving “space explorer but make it terminal” 🚀✨.

✨ Completions ✨

New completions dropped, and honestly? The glow-up is real 💅
- archlinux-java (#8911 — https://github.com/fish-shell/fish-shell/issues/8911)
- apk (#8951 — https://github.com/fish-shell/fish-shell/issues/8951)
- brightnessctl (#8758 — https://github.com/fish-shell/fish-shell/issues/8758)
- efibootmgr (#9010 — https://github.com/fish-shell/fish-shell/issues/9010)
- fastboot (#8904 — https://github.com/fish-shell/fish-shell/issues/8904)
- optimus-manager (#8913 — https://github.com/fish-shell/fish-shell/issues/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/issues/8760)
- wg-quick (#8687 — https://github.com/fish-shell/fish-shell/issues/8687)
Big one: complete can now be handed multiple --condition options. They get tried in the order you gave them, and the completion only becomes available if all of them succeed — basically as if they were joined with &&. Why do we care? Caching, bestie 🧚 fish's complete system stashes the return value of every condition for as long as the commandline doesn't change, so this can cut down 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).
Sometimes the build process found the wrong libintl on macOS. That's been corrected, no cap (#5244 — https://github.com/fish-shell/fish-shell/issues/5244).
The paths for completions, functions, and configuration snippets now include the subdirectories fish/vendor_completions.d, fish/vendor_functions.d, and fish/vendor_conf.d (respectively) within XDG_DATA_HOME (or ~/.local/share if not defined) (#8887 — https://github.com/fish-shell/fish-shell/issues/8887, #7816 — https://github.com/fish-shell/fish-shell/issues/7816).

🦋 fish 3.4.1 (released March 25, 2022) 🦋

This release fixes the following problems that were identified in fish 3.4.0:

There was an error printed after upgrading, where old instances could pick up a newer version of the fish_title function. 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, which is bound to alt-right by default, was inadvertently changed to move like forward-bigword. That's 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're upgrading from version 3.3.1 or before, please also review the release notes for 3.4.0 (they're included below 👇).

🌈 fish 3.4.0 (released March 12, 2022) 🌈

⭐ Notable improvements and fixes ⭐

fish's command substitution syntax got extended: $(cmd) now means the same thing as (cmd), but you can use it inside double quotes to stop the results from getting line-split (#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 from 3.3.0, fish_config gained a theme subcommand so you can show and pick from the sample themes (meaning color schemes) right there 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 ~/.config/fish/themes/.
set and read learned a new option, --function, to set a variable in the function's top scope. This should feel like a more familiar way of scoping variables, and it dodges the 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 for string length makes it use that kind of visible width. Super useful for getting 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 it takes to expand the glob 🔥
Autosuggestions can now be turned off by setting $fish_autosuggestion_enabled to 0, and (almost) all highlighting can be turned off by choosing the new "None" theme. The exception is necessary colors, like the ones that 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 configuration. 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).

⚠️ Heads up bestie: that git override is a real security thing, not a vibe. Don't undo it casually.

💀 Deprecations and removed features 💀

A new feature flag, ampersand-nobg-in-token, makes & only act as the background operator if it's followed by a separator. In combination with qmark-noglob, this lets you enter most URLs at the command line without quoting or escaping (#7991 — https://github.com/fish-shell/fish-shell/issues/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 it's given no variable names. Meaning if set -q $foo will not enter the if-block if $foo is empty or unset. If you want the previous behavior back, 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 outputs one empty argument in a command substitution that has no output (#8054 — https://github.com/fish-shell/fish-shell/issues/8054). This lets commands like test -n (echo -n | string collect --allow-empty) 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 lets string match 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, which fixes the common user error of appending to it in config.fish when it's 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 was preventing all syntax checks from running on commands given to fish -c (#8171 — https://github.com/fish-shell/fish-shell/issues/8171). This includes checks such as exec not being allowed in a pipeline, and $$ not being a valid variable. Generally, another error was generated anyway.
fish_indent now correctly reformats tokens that end with a backslash followed by a newline (#8197 — https://github.com/fish-shell/fish-shell/issues/8197).
commandline gained an --is-valid option to check if the command line is syntactically valid and complete. This allows a basic implementation of transient prompts (#8142 — https://github.com/fish-shell/fish-shell/issues/8142).
💅 commandline gained a --paging-full-mode option so you can check whether the pager is showing, like, all the possible lines — no "7 more rows" message energy. (#8485, https://github.com/fish-shell/fish-shell/issues/8485)
List expansion now correctly reports an error when you use it with all zero indexes. (#8213, https://github.com/fish-shell/fish-shell/issues/8213)
Running fish with a directory instead of a script as the argument, like fish ., no longer sends you into an infinite loop. It errors out immediately instead, which is honestly so much better. (#8258, https://github.com/fish-shell/fish-shell/issues/8258)
Some error messages that happen after fork, like "text file busy", have been replaced with bespoke error messages for fish, like "File is currently open for writing". This also restores error messages with current glibc versions 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 when you use the --no-symlinks option. (#8281, https://github.com/fish-shell/fish-shell/issues/8281)
When you try 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. That has been corrected 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 before the loop was entered. Since the variable had not actually changed or been set, this was a spurious event, and it 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 you're in hex or octal bases. (#8417, https://github.com/fish-shell/fish-shell/issues/8417)
dirs always produces an exit status of 0 now, 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/issues/8494)
Tilde characters (~) produced by custom completions are no longer escaped when applied to the command line. This makes it way 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/issues/8519)
abbr -q returns the correct exit status when given multiple abbreviation names as arguments. (#8431, https://github.com/fish-shell/fish-shell/issues/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 options 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/issues/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 tokenizer 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/issues/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, and instead run inside fish's own process group. This more closely matches other shells, and improves Ctrl+C reliability inside a command substitution. (#8172, https://github.com/fish-shell/fish-shell/issues/8172)
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. This makes it easier to suppress 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 completion 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/issues/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/issues/8557)
Pasting text containing quotes from the clipboard trims spaces more appropriately. (#8550, https://github.com/fish-shell/fish-shell/issues/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, including 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 enqueues an event. (#8628, https://github.com/fish-shell/fish-shell/issues/8628)

🦋 New or improved bindings 🦋

escape can now be bound without breaking arrow key bindings. (#8428, https://github.com/fish-shell/fish-shell/issues/8428)
The alt-h binding (to open a command's manual page) now also ignores command. (#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 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 — tracked in #8416 <https://github.com/fish-shell/fish-shell/issues/8416> ✨
ethtool — tracked in #8283 <https://github.com/fish-shell/fish-shell/issues/8283> 💅
exif — tracked in #8246 <https://github.com/fish-shell/fish-shell/issues/8246> 🎀
findstr — tracked in #8481 <https://github.com/fish-shell/fish-shell/issues/8481> 🦋
git-sizer — tracked in #8156 <https://github.com/fish-shell/fish-shell/issues/8156> 🌸
gnome-extensions — tracked in #8732 <https://github.com/fish-shell/fish-shell/issues/8732> 💖
gping — tracked in #8181 <https://github.com/fish-shell/fish-shell/issues/8181> ⭐
isatty — tracked in #8609 <https://github.com/fish-shell/fish-shell/issues/8609> 🔥
istioctl — tracked in #8343 <https://github.com/fish-shell/fish-shell/issues/8343> 🫶
kmutil — listed here with no issue link attached 🫶
kubectl — tracked in #8734 <https://github.com/fish-shell/fish-shell/issues/8734> 👑
matlab — tracked in #8505 <https://github.com/fish-shell/fish-shell/issues/8505> 🌈
mono — tracked in #8415 <https://github.com/fish-shell/fish-shell/issues/8415>, and related tools csharp, gacutil, gendarme, ikdasm, ilasm, mkbundle, monodis, monop, sqlsharp and xsp are tracked in #8452 <https://github.com/fish-shell/fish-shell/issues/8452> 💀
Angular's ng — tracked in #8111 <https://github.com/fish-shell/fish-shell/issues/8111> 🙈
nodeenv — tracked in #8533 <https://github.com/fish-shell/fish-shell/issues/8533> 🍓
octave — tracked in #8505 <https://github.com/fish-shell/fish-shell/issues/8505> 🧚
pabcnet_clear — tracked in #8421 <https://github.com/fish-shell/fish-shell/issues/8421> 💜
qmk — tracked in #8180 <https://github.com/fish-shell/fish-shell/issues/8180> ✨
rakudo — tracked in #8113 <https://github.com/fish-shell/fish-shell/issues/8113> 💅
rc-status — tracked in #8757 <https://github.com/fish-shell/fish-shell/issues/8757> 🎀
roswell — tracked in #8330 <https://github.com/fish-shell/fish-shell/issues/8330> 🦋
sbcl — tracked in #8330 <https://github.com/fish-shell/fish-shell/issues/8330> 🌸
starship — tracked in #8520 <https://github.com/fish-shell/fish-shell/issues/8520> 💖
topgrade — tracked in #8651 <https://github.com/fish-shell/fish-shell/issues/8651> ⭐
wine, wineboot and winemaker — tracked in #8411 <https://github.com/fish-shell/fish-shell/issues/8411> 🔥
wslpath — from Windows Subsystem for Linux (WSL), tracked in #8364 <https://github.com/fish-shell/fish-shell/issues/8364> 🫶
color — Windows' color, tracked in #8483 <https://github.com/fish-shell/fish-shell/issues/8483>; plus attrib, attributes, choice, clean, cleanmgr, cmd, cmdkey, comp, forfiles, powershell, reg, schtasks, and setx, tracked in #8486 <https://github.com/fish-shell/fish-shell/issues/8486> 👑
zef — tracked in #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 submodules (#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 includes 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/issues/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 upgrading. (#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 universal variable changes (#8088 <https://github.com/fish-shell/fish-shell/issues/8088>). ✨
A superfluous error that was produced when setting the PATH or CDPATH environment variables to include colon-delimited components that do not exist was removed (#8095 <https://github.com/fish-shell/fish-shell/issues/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/issues/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-invoke 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 performance 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) responses (#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 provided, matching the documentation. (#7938 <https://github.com/fish-shell/fish-shell/issues/7938>). ⭐
fish produces more specific errors when a command in a command substitution wasn't found or is not allowed. This now prints something like "Unknown command" instead of "Unknown error while evaluating command substitution". 🔥
fish_indent now lets inline variable assignments (FOO=BAR command) use line continuation instead of smooshing everything onto one line ([#7955](https://github.com/fish-shell/fish-shell/issues/7955)).
fish got a whole new --no-config option that turns configuration files off. This applies to your user-specific config and the systemwide config.fish (typically in /etc/fish/config.fish), plus 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 universal 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, so you can actually use it 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)). Before this, the value held the process group ID — but in scripts that was literally 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 getting -1 when the exit was caused by a signal.
process-exit event handlers for PID 0 were also getting JOB_EXIT events; that's fixed now.
job-exit event handlers can now be created with any of the PIDs from the job. The handler gets the last PID in the job as its second argument, instead of the process group.
Trying to set an empty variable name with set no longer works (those variables couldn't be used in expansions anyway, so like… bye).
fish_add_path handles an undefined PATH environment variable correctly ([#8082](https://github.com/fish-shell/fish-shell/issues/8082)).

✨ Interactive improvements ✨

Commands you type before the previous command finishes now get properly syntax highlighted. no cap, the colors keep up with you 💅
fish now automatically creates config.fish and the configuration directories in $XDG_CONFIG_HOME/fish (by default ~/.config/fish) if they don't already exist ([#7402](https://github.com/fish-shell/fish-shell/issues/7402)).
$SHLVL is no longer incremented in non-interactive shells. Translation: it won't balloon to values bigger than 1 just because your environment happens to run some scripts in $SHELL during 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 flashing is already enough of a heads-up, and the bell is just 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 about where a function is defined anymore, all thanks to the new functions --no-details option ([#7879](https://github.com/fish-shell/fish-shell/issues/7879)).
There's a brand new variable, fish_killring, holding entries from the killring ([#7445](https://github.com/fish-shell/fish-shell/issues/7445)). obsessed.
fish --private prints a note about 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 tries to lock history or universal variable files on remote filesystems, including NFS and Samba mounts. ⚠️ Heads up: in rare cases, updates to these files may get dropped if separate fish instances modify them at the same time ([#7968](https://github.com/fish-shell/fish-shell/issues/7968)).
wait and on-process-exit work correctly with jobs that have already exited ([#7210](https://github.com/fish-shell/fish-shell/issues/7210)).
__fish_print_help (the thing behind --help output for fish's builtins) now respects the LESS environment variable, and if it isn't set, it uses better default pager settings ([#7997](https://github.com/fish-shell/fish-shell/issues/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 the 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)). we love accessibility 🌸
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 it's started without any locale information, which improves how emoji and other non-ASCII text display on misconfigured systems ([#8031](https://github.com/fish-shell/fish-shell/issues/8031)). If you want to allow a C locale, set the variable fish_allow_singlebyte_locale to 1.
The Web-based configuration and documentation now feature a dark mode if the browser requests it ([#8043](https://github.com/fish-shell/fish-shell/issues/8043)). 🌙 iconic.
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 inside fish_prompt now exits properly ([#8033](https://github.com/fish-shell/fish-shell/issues/8033)).
When you try to run 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)). it's giving helpful bestie energy 🫶

🎀 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, following GNU readline's behavior. Same deal: 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, which means it supports 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 let you toggle the presence of a prefix/suffix on the current commandline ([#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 sitting 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 colors, 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)). Ngl though, it's still slower than the non-informative version by its very nature. In particular it's IO-bound, so it will be very slow on slow disks or network mounts. 😭
The sample prompts got updated. Some duplicated prompts — like the various classic variants — and 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 only take effect when selected, and existing installed prompts stay unchanged. 🕺
There's 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 the 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/issues/7900))
- sv ([#8069](https://github.com/fish-shell/fish-shell/issues/8069))
Improvements to plenty of completions! (the completion girlies were busy ✨)
Commands that wrap cd (using complete --wraps cd) get the same completions as cd ([#4693](https://github.com/fish-shell/fish-shell/issues/4693)).
The --force-files option to complete works for bare arguments now, not just options ([#7920](https://github.com/fish-shell/fish-shell/issues/7920)).
Completion descriptions for functions don't include the whole function definition anymore, 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/issues/6001), [#7992](https://github.com/fish-shell/fish-shell/issues/7992)).
When there are multiple completion candidates, fish inserts their shared prefix. That prefix used to be computed in a case-insensitive way, which resulted in the wrong case showing up in the completion pager. Fixed by only inserting prefixes with matching case ([#7744](https://github.com/fish-shell/fish-shell/issues/7744)). 💅

✨ Improved terminal support ✨

fish doesn't try to detect a missing new line at startup anymore, which means no more random ⏎ showing up when your terminal gets resized at exactly the wrong second — a thing that lowkey happens all the time in tiling window managers (#7893 <https://github.com/fish-shell/fish-shell/issues/7893>). 💅
fish handles it way better when it and your terminal just disagree on how wide characters are. Specifically: those staircase effects with right prompts? Should be gone in most cases now (#8011 <https://github.com/fish-shell/fish-shell/issues/8011>). 🦋
If your prompt eats up the entire line, that last character should stop getting chopped off in certain terminals (#8002 <https://github.com/fish-shell/fish-shell/issues/8002>). no cap.
fish's reflow handling is now disabled by default for kitty (#7961 <https://github.com/fish-shell/fish-shell/issues/7961>).
The default prompt no longer throws errors when you're on a dumb terminal (#7904 <https://github.com/fish-shell/fish-shell/issues/7904>). 🫶
Terminal size variables get updated for window size change signal handlers (SIGWINCH). iconic.
Pasting inside a multi-line command, on a terminal that supports bracketed paste, actually works instead of erroring out (#7782 <https://github.com/fish-shell/fish-shell/issues/7782>). 🎀
set_color now produces an error when you use it with invalid arguments, instead of empty output — which interacted so badly with Cartesian product expansion. bye to that era 💀

🌈 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, bestie:

The command-not-found handler used suggestions from pacman on Arch Linux, but this caused major slowdowns on some systems, so it's 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 wouldn't receive keystrokes correctly — fish is now way more robust in these situations (#7853 <https://github.com/fish-shell/fish-shell/issues/7853>). 💪
Arguments longer than 1024 characters no longer trigger excessive CPU usage on macOS (#7837 <https://github.com/fish-shell/fish-shell/issues/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/issues/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 regression introduced in fish 3.2.1, #7842 <https://github.com/fish-shell/fish-shell/issues/7842>). slay.

If you are upgrading from version 3.1.2 or before, please also review the release notes for 3.2.1 and 3.2.0 (included below). 👀

🌸 fish 3.2.1 (released March 18, 2021)

This release of fish fixes the following problems identified in fish 3.2.0:

Commands in key bindings are run with fish's internal terminal modes, instead of the terminal modes typically used for commands. This fixes a bug introduced in 3.2.0 where text would unexpectedly appear on the terminal, especially when pasting (#7770 <https://github.com/fish-shell/fish-shell/issues/7770>).
Prompts which use the internal __fish_print_pipestatus function will display correctly rather than carrying certain modifiers (such as bold) further than intended (#7771 <https://github.com/fish-shell/fish-shell/issues/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 system 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_tokenizer_state error (#7782 <https://github.com/fish-shell/fish-shell/issues/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 constantly (#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/issues/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/issues/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+/. this is the moment fr fr
Builtins can now output before all data is read. For example, string replace no longer has to read all of stdin before it can begin to output. This makes it usable also for pipes where the previous 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:

…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 you having to press tab again (#6924 <https://github.com/fish-shell/fish-shell/issues/6924>). ate.
fish is less aggressive about resetting terminal modes, such as flow control, after every command. Although flow control remains off by default, enterprising users can now enable it with stty (#2315 <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 producing 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 interactively, 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 design on fishshell.com. aesthetic ✨
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 operating systems limit the number of arguments to commands, larger values are unlikely to work anyway, and this helps to avoid hangs. 🫶
A brand new "fish for bash users" doc page exists now, and it's literally the quickest lil overview of the scripting differences between bash and fish (#2382 <https://github.com/fish-shell/fish-shell/issues/2382>) 🫶 — also the completion tutorial got moved out into its own whole 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] can be omitted now, bestie — $start and $end just 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 three of those literally print the full list $var. Slay 💅

When globbing, a segment that's exactly ** may now match zero directories. So like, **/foo can match foo right there in the current directory (#7222 <https://github.com/fish-shell/fish-shell/issues/7222>) 🌸

💖 Scripting improvements 💖

type, _ (gettext), . (source) and : (no-op) are builtins now, purely for performance reasons (#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/issues/6854>) ⚡
set and backgrounded jobs no longer overwrite $pipestatus (#6820 <https://github.com/fish-shell/fish-shell/issues/6820>), which highkey makes it way better 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 got shortened — it only mentions the scopes in which a variable actually exists (#6944 <https://github.com/fish-shell/fish-shell/issues/6944>). Also it now shows if a variable is a path variable ✨
New variable alert 🚨: 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>) 🦋
New subcommand string pad lets you extend 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, kinda like cut -f (#6770 <https://github.com/fish-shell/fish-shell/issues/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 — it just treats it as empty instead (#7343 <https://github.com/fish-shell/fish-shell/issues/7343>) 💜
string subcommands now quit early when you use them 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 it's not given an argument (not even a format string) 🙈
The true and false builtins ignore any arguments, just 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>) ✨
New fish_job_summary function gets 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>). You can now customize the default behaviour by redefining it 🫶
status gained new dirname and basename convenience subcommands — they give you just the directory of the running script or the name of it, so common tasks like running (dirname (status filename)) are way simpler now (#7076 <https://github.com/fish-shell/fish-shell/issues/7076>, #1818 <https://github.com/fish-shell/fish-shell/issues/1818>) 🌸
Broken pipelines are handled way more smoothly now 🧊 — specifically, a bad redirection mid-pipeline means the job keeps running but with the broken file descriptor replaced by a closed file descriptor. That's better error recovery and way more in line with how other shells behave (`#7038 <https://github.com/fish-shell/fish-shell/issues/7038>).
jobs --quiet PID no longer prints "no suitable job" if the job for PID doesn't exist (like, because it already 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, like in config.fish (#7183 <https://github.com/fish-shell/fish-shell/issues/7183>) 🧟‍♀️✨
The command, jobs and type builtins support --query as the long form of -q, matching other builtins. The long form --quiet is deprecated now (#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 local-exported variables, so you don't need --no-scope-shadowing in validation functions anymore 🎀
complete takes the first argument as the name of the command if the --command/-c option isn't used — so complete git is treated like complete --command git, and you can show the loaded completions for specific commands with complete COMMANDNAME (#7321 <https://github.com/fish-shell/fish-shell/issues/7321>) 👑
set_color -b (with no 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 can't 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/issues/7376>, #7732 <https://github.com/fish-shell/fish-shell/issues/7732>) 🌈
test -t — the one that tests whether file descriptors are connected to a terminal — works for file descriptors 0, 1, and 2 (#4766 <https://github.com/fish-shell/fish-shell/issues/4766>). Ngl it can still return incorrect results in other cases though (#1228 <https://github.com/fish-shell/fish-shell/issues/1228>) 😭
Trying to execute scripts with Windows line endings (CRLF) produces a sensible error now (`#2783 <https://github.com/fish-shell/fish-shell/issues/2783>) 💀
Trying to execute commands with arguments that exceed the operating system 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 triggers 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 produces 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/issues/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 potentially-sensitive entries to the history; that's 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>) 🦋
New fish_status_to_signal function for transforming exit statuses to signal names (#7597 <https://github.com/fish-shell/fish-shell/issues/7597>, #7595 <https://github.com/fish-shell/fish-shell/issues/7595>) 🚨
The fallback realpath builtin supports the -s/--no-symlinks option, like GNU realpath (#7574 <https://github.com/fish-shell/fish-shell/issues/7574>) 🌸
functions and type now explain when a function was defined via source instead of just saying Defined in - 💅
Significant performance improvements when globbing, appending to variables, or in math ⚡🔥
echo no longer interprets options at the beginning of an argument (e.g. echo "-n foo") (#7614 <https://github.com/fish-shell/fish-shell/issues/7614>) 🙈
fish now finds user configuration even if the HOME environment variable isn't set (`#7620 <https://github.com/fish-shell/fish-shell/issues/7620>) 🏠✨
fish no longer crashes when started from a Windows-style working directory (e.g. F:\path) (`#7636 <https://github.com/fish-shell/fish-shell/issues/7636>) 💀
fish -c now reads the remaining arguments into $argv (`#2314 <https://github.com/fish-shell/fish-shell/issues/2314>) 🫶
pwd now supports the long options --logical and --physical, so it plays nice with how other implementations do it (#6787 — https://github.com/fish-shell/fish-shell/issues/6787). consistency queen 💅
fish --profile now only starts profiling after fish is ready to execute commands, i.e. after all configuration is done. There's a brand new --profile-startup option that only profiles the startup-and-configuration process (#7648 — https://github.com/fish-shell/fish-shell/issues/7648). no more mystery numbers from your config files, we love to see it ✨
Builtins now return a maximum exit status of 255, instead of potentially overflowing. In particular, this affects exit, return, functions --query, and set --query (#7698 — https://github.com/fish-shell/fish-shell/issues/7698, #7702 — https://github.com/fish-shell/fish-shell/issues/7702). capped, contained, no chaos 🫶
It is no longer an error to run a builtin with closed stdin. For example, count <&- now prints 0, instead of failing. she's chill about it now 😌
Blocks, functions, and builtins no longer permit redirecting to file descriptors other than 0 (standard input), 1 (standard output) and 2 (standard error). For example, echo hello >&5 is now an error. This prevents corruption of internal state (#3303 — https://github.com/fish-shell/fish-shell/issues/3303). > seriously, don't try to sneak into fd 5, that's how the vibes get corrupted 💀

🦋 Interactive improvements

fish will now always attempt to become process group leader in interactive mode (#7060 — https://github.com/fish-shell/fish-shell/issues/7060). This helps avoid hangs in certain circumstances, and allows tmux's current directory introspection to work (#5699 — https://github.com/fish-shell/fish-shell/issues/5699). main character energy, taking charge of the group 👑
The interactive reader now allows ending a line in a logical operator (&& and ||) instead of complaining about a missing command. (This was already syntactically valid, but interactive sessions didn't know about it yet.) overdue but iconic 🎀
The prompt is reprinted after a background job exits (#1018 — https://github.com/fish-shell/fish-shell/issues/1018). she's back, she never left 🫶
fish no longer inserts a space after a completion ending in ., , or - is accepted, improving completions for tools that provide dynamic completions (#6928 — https://github.com/fish-shell/fish-shell/issues/6928). tiny change, massive slay 🌸
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). second time's the charm fr fr ✨
help string match/replace/<subcommand> will show the help for string subcommands (#6786 — https://github.com/fish-shell/fish-shell/issues/6786). the help actually helps now, groundbreaking 🌈
fish_key_reader sets the exit status to 0 when used with --help or --version (#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). uniform, tidy, obsessed ⭐
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 actually produced by the last run command. receipts for your exit codes, iykyk 🔥
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). > heads up bestie: the old way of nuking the greeting may not work anymore, do the set -U thing 🙈
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). no thoughts, no events, head empty 💀
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). she says goodbye properly now 😭
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 command with syntax errors (#6880 — https://github.com/fish-shell/fish-shell/issues/6880, #6816 — https://github.com/fish-shell/fish-shell/issues/6816). catching the oopsie in real time 🫶
The debugging system has now fully switched from the old numbered level to the new named category system introduced in 3.1. A number of new debugging categories have been added, including config, path, reader and screen (#6511 — https://github.com/fish-shell/fish-shell/issues/6511). See the output of fish --print-debug-categories for the full list. names > numbers, always 💅
The warning about read-only filesystems has been moved to a new "warning-path" debug category and can be disabled by setting a debug category of -warning-path (#6630 — https://github.com/fish-shell/fish-shell/issues/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). the little -o said "not today" before, now it behaves 💅
fish's debugging can now also be enabled via the FISH_DEBUG and FISH_DEBUG_OUTPUT environment variables. This helps with debugging when no commandline options can be passed, like when fish is called in a shebang (#7359 — https://github.com/fish-shell/fish-shell/issues/7359). env variable debugging is so big brain 🧚
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 closing 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/issues/6926). The directory containing the history file was already private, so there should not have been any private data revealed. your embarrassing typos are between you and fish only 💜
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 depends on locale (#6757 — https://github.com/fish-shell/fish-shell/issues/6757). aligned columns, we stan 🎀
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 appropriate 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/issues/3537). Ctrl+C but make it fast 🔥
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/issues/6861). the background job lives to see another day 😌
Autosuggestions work properly after ctrl-c cancels the current command line (#6937 — https://github.com/fish-shell/fish-shell/issues/6937). she remembers. she always remembers ✨
History search is now case-insensitive unless the search string contains an uppercase character (#7273 — https://github.com/fish-shell/fish-shell/issues/7273). smart case, smart queen 👑
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). if it exists, leave it alone, we're being efficient 🌸
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). we don't wait forever for anyone, not even xdg-open 💅
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/issues/6951). tight, neat, no stray gaps 🎀
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). short option said "read the docs", and now it is the docs ⭐
History search now flashes when it found no more results (#7362 — https://github.com/fish-shell/fish-shell/issues/7362). visual feedback, because silence is scary 😭
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, reverse, italic and background modifiers, to better show their effect (#7314 — https://github.com/fish-shell/fish-shell/issues/7314). show off those modifiers, they worked hard 🦋
The fish Web configuration tool (fish_config) shows prompts correctly on Termux for Android (#7298 — https://github.com/fish-shell/fish-shell/issues/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 History 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). sorry Source Code Pro, it's not you, it's your bug 🙈
funcsave gained a new --directory option to specify the location of the saved function (#7041 — https://github.com/fish-shell/fish-shell/issues/7041). save it wherever, we're flexible 💖
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). right tool, right place, no cap 🌈
Resuming a piped job by its number, like fg %1, works correctly now (#7406). And resumed jobs actually show the right title in the terminal emulator (#7444). no more mystery tabs 🎀
Commands run from key bindings now use the same TTY modes as normal commands (#7483).
Autosuggestions pulled from history are now case-sensitive (#3978). yes bestie she knows the difference now 💅
$status from completion scripts is no longer passed outside the completion — which keeps the status display in your prompt showing the last command's status (#7555). iconic behavior honestly.
Updated localisations for pt_BR (#7480).
fish_trace output now starts with -> (like fish --profile does), which makes the depth way more visible (#7538). iykyk.
Resizing the terminal window no longer produces a corrupted prompt (#6532, #7404). thank god 😭
functions produces an error rather than crashing on certain invalid arguments (#7515).
A crash in completions with inline variable assignment (eg A= b) has been fixed (#7344).
fish_private_mode may now be changed dynamically using set (#7589), and history is kept in memory in private mode (but not stored permanently) (#7590). so you get your scrollback vibes without the permanent paper trail ✨
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). lowkey so useful.
Importing bash history, or reporting errors with recursive globs (**), no longer hangs (#7407, #7497).
bind now shows \x7f for the del key instead of a literal DEL character (#7631).
Paths containing variables or tilde expansion are only suggested when they are still valid (#7582).
Syntax highlighting can now color a command as invalid even if it's executed quickly (#5912). she's fast and accurate 💖
Redirection targets are no longer highlighted as an error if they contain variables which will likely be defined by the current commandline (#6654).
fish is now more resilient against broken terminal modes (#7133, #4873).
fish handles being in control of the TTY without owning its own process group better, avoiding some hangs in special configurations (#7388).
Keywords can now be colored differently by setting the fish_color_keyword variable (fish_color_command is used as a fallback) (#7678). new color drop 🌈
Just like fish_indent, the interactive reader will indent continuation lines that follow a line ending in a backslash, |, && or || (#7694).
Commands with a trailing escaped space are saved in history correctly (#7661).
fish_prompt no longer mangles Unicode characters in the private-use range U+F600-U+F700 (#7723).
The universal variable file, fish_variables, can be made a symbolic link without it being overwritten (#7466). link it, bestie 🫶
fish is now more resilient against mktemp failing (#7482).

🎀 New or improved bindings 🎀

As mentioned above, the 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). the way that just works now.
Ctrl+z is now available for binding (#7152).
Also, using the cancel special input function (bound to Escape by default) right after fish picked an unambiguous completion will undo that pick (#7433). bestie said never mind 💀
fish_clipboard_paste (Ctrl+v) trims indentation from multiline commands, because fish already indents (#7662). double-indent was giving chaos.
Vi mode bindings now support dh, dl, c0, cf, ct, cF, cT, ch, cl, y0, ci, ca, yi, ya, di, da, d;, d,, o, O and Control+left/right keys to navigate by word (#6648, #6755, #6769, #7442, #7516). vi girlies we are SO back 👑
Vi mode bindings support ~ (tilde) to toggle the case of the selected character (#6908).
The functions up-or-search and down-or-search (up and down) can cross empty lines, and they don't activate search mode if the search fails — which makes them easier to use for moving between lines in some situations. no more getting stuck in search jail 🙈
If a history search fails to find a match, the cursor is no longer moved. this is genuinely so useful when you accidentally start 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). the names finally match the vibes.
A new special input function forward-single-char moves one character to the right, and if an autosuggestion is available, it only takes a single character from it (#7217, #4984). baby steps ✨
Special input functions can now be joined with or as a modifier (adding to and), though only some commands set an exit status (#7217). this includes suppress-autosuggestion, to reflect whether an autosuggestion was suppressed (#1419).
A new function __fish_preview_current_file, bound to Alt+o, opens the current file at the cursor in a pager (#6838, #6855). peek at the source, bestie 💜
edit_command_buffer (Alt+e and Alt+v) passes the cursor position to the external editor if the editor is recognized (#6138, #6954). your editor lands exactly where you were, no cap.
__fish_prepend_sudo (Alt+s) now toggles a sudo prefix (#7012) and avoids shifting the cursor (#6542).
__fish_prepend_sudo (Alt+s) now uses the previous commandline if the current one is empty, to simplify rerunning the previous command with sudo (#7079). zero retyping era 🔥
__fish_toggle_comment_commandline (Alt+#) now uncomments and presents the last comment from history if the commandline is empty (#7137).
__fish_whatis_current_token (Alt+w) prints descriptions for functions and builtins (#7191, #2083). she tells you what things ARE now 🧚
The definition of "word" and "bigword" for movements was refined, fixing (eg) vi mode's behavior with e on the second-to-last char, and bigword's behavior with single-character words and non-blank non-graphical characters (#7353, #7354, #4025, #7328, #7325).
fish's clipboard bindings now also support Windows Subsystem for Linux via PowerShell and clip.exe (#7455, #7458), and will properly copy newlines in multi-line commands.
Using the *-jump special input functions before typing anything else no longer crashes fish.
Completing variable overrides (foo=bar) could replace the entire thing with just the completion in some circumstances. This has been fixed (#7398).

🌸 Improved prompts 🌸

The default and example prompts print the correct exit status for commands prefixed with not (#6566). the small details ate.
git prompts include all untracked files in the repository, not just the ones in the current directory (#6086).
The git prompts correctly show stash states (#6876, #7136) and clean states (#7471).
The Mercurial prompt correctly shows untracked status (#6906), and by default only shows the branch, for performance reasons. A new variable $fish_prompt_hg_show_informative_status can be set to enable more information. your call, bestie 🦋
The fish_vcs_prompt passes its arguments to the various VCS prompts that it calls (#7033).
The Subversion prompt was broken in a number of ways in 3.1.0 and has been restored (#6715, #7278). she's back and better 💖
💖 A brand-new helper function, fish_is_root_user, makes checking for superuser privilege way simpler — no more pretending you're a detective (#7031 — https://github.com/fish-shell/fish-shell/issues/7031, #7123 — https://github.com/fish-shell/fish-shell/issues/7123).
🎨 New colorschemes just dropped: 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 directory history (#3550 — https://github.com/fish-shell/fish-shell/issues/3550) leading to graphical glitches — have been fixed. no more cursed visuals bestie.
🐍 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). Heads up: 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). it's giving rainbow, respectfully.
💭 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 removed (#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 (especially flags). (#7237 — https://github.com/fish-shell/fish-shell/issues/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/issues/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), upcoming 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 cursor shape changing.
🐱 fish no longer attempts to modify the terminal size via TIOCSWINSZ, improving 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/issues/7220)
- alias (#7035 — https://github.com/fish-shell/fish-shell/issues/7035)
- alternatives (#7616 — https://github.com/fish-shell/fish-shell/issues/7616)
- apk (#7108 — https://github.com/fish-shell/fish-shell/issues/7108)
- asciidoctor (#7000 — https://github.com/fish-shell/fish-shell/issues/7000)
- avifdec and avifenc (#7674 — https://github.com/fish-shell/fish-shell/issues/7674)
- bluetoothctl (#7438 — https://github.com/fish-shell/fish-shell/issues/7438)
- cjxl and djxl (#7673 — https://github.com/fish-shell/fish-shell/issues/7673)
- cmark (#7000 — https://github.com/fish-shell/fish-shell/issues/7000)
- create_ap (#7096 — https://github.com/fish-shell/fish-shell/issues/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/issues/6620)
- dotnet (#7558 — https://github.com/fish-shell/fish-shell/issues/7558)
- downgrade (#6751 — https://github.com/fish-shell/fish-shell/issues/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/issues/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/issues/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, rst2pseudoxml, 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/issues/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/issues/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. bestie that's the good stuff.
- Completion scripts for custom Git subcommands like git-xyz are now loaded with Git completions. The completions can now be defined directly on the subcommand (using complete git-xyz), and completion for git xyz will work. (#7075 — https://github.com/fish-shell/fish-shell/issues/7075, #7652 — https://github.com/fish-shell/fish-shell/issues/7652, #4358 — https://github.com/fish-shell/fish-shell/issues/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. iconique behaviour honestly.
📝 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 commands (#7153 — https://github.com/fish-shell/fish-shell/issues/7153), especially 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 matching 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 optional dependency on expect (and adding an optional dependency on pexpect) (#5451 — https://github.com/fish-shell/fish-shell/issues/5451, #6825 — https://github.com/fish-shell/fish-shell/issues/6825).
The CHANGELOG moved over to restructured text so it could actually be included in the documentation, and honestly? slay (#7057 — https://github.com/fish-shell/fish-shell/issues/7057).
fish handles ncurses installed in a non-standard prefix way better now (#6600 — https://github.com/fish-shell/fish-shell/issues/6600, #7219 — https://github.com/fish-shell/fish-shell/issues/7219), and it uses variadic tparm on NetBSD curses (#6626 — https://github.com/fish-shell/fish-shell/issues/6626). lowkey iconic tbh.
The Web-based configuration tool no longer uses an obsolete Angular version (#7147 — https://github.com/fish-shell/fish-shell/issues/7147). we love to see the glow-up 💅
The fish project has adopted the Contributor Covenant code of conduct (#7151 — https://github.com/fish-shell/fish-shell/issues/7151). bestie behaviour fr fr 🫶

Deprecations and removed features 💀

The fish_color_match variable is no longer used. (Before, it controlled the color of matching quotes and parens when you used read.)
fish 3.2.0 is gonna be the last release where redirection to standard error with the ^ character is enabled. The stderr-nocaret feature flag is getting changed to "on" in future releases. so get your ^ habits sorted now ok 😭
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).
The long-form option --quiet on command, jobs and type is deprecated, in favor of --query (see above).
The fish_command_not_found event is no longer emitted — instead there's a function of that name. By default it will call a previously-defined __fish_command_not_found_handler. If you want 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 brand 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, because it's no longer implicitly a universal variable. Use set -U fish_greeting, or disable it in config.fish with set -g fish_greeting. no cap, that one trips people up 🙈
The long-deprecated and honestly non-functional -m/--read-mode options to read were removed back 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). good riddance 💀
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). smaller tarballs, we cheer 🎉
The fish source tarball contains an example FreeDesktop entry and icon. cute AND practical.
The CMake variable MAC_CODESIGN_ID can now be set to "off" to disable code-signing (#6952 — https://github.com/fish-shell/fish-shell/issues/6952, #6792 — https://github.com/fish-shell/fish-shell/issues/6792).
Building on macOS earlier than 10.13.6 now succeeds, instead of failing on code-signing (#6791 — https://github.com/fish-shell/fish-shell/issues/6791). she's resilient 💪
The pkg-config file now uses variables to make sure the paths it uses 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/issues/6778).
A brand-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 it's available — unless Mac codesigning is enabled (#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/issues/6825); the expect package is no longer required. bye bestie 👋
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). it's giving 2021, move on hun 🧚
The Web-based configuration tool is compatible with Python 3.10 (#7600 — https://github.com/fish-shell/fish-shell/issues/7600) and no longer requires 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. so long, legend 🫡

fish 3.1.2 (released April 29, 2020) 🎀

This release of fish fixes one major issue that was discovered in fish 3.1.1:

Commands such as fzf and enhancd, when used with eval, would hang. Turns out eval was buffering output way too aggressively, and that's been fixed (#6955 — https://github.com/fish-shell/fish-shell/issues/6955). no more mystery hangs, we're so back 😭

If you're 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). read the lore, bestie 📚

fish 3.1.1 (released April 27, 2020) 🎀

This release of fish fixes a number of major issues that were discovered in fish 3.1.0. buckle up, it's a long one:

Commands which involve .( ... | psub) now work correctly, because a bug in the function --on-job-exit option got 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). peace was restored 🤝
Starting fish in a directory without read access — like via su — no longer crashes (#6597 — https://github.com/fish-shell/fish-shell/issues/6597).
The glob ordering changes that 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 (e.g. ^&2) work correctly (#6591 — https://github.com/fish-shell/fish-shell/issues/6591).
Redirections that append to a file descriptor (e.g. 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 newer 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 successful. compiler girlies rise 🙌
time is now correctly listed in the output of builtin -n, and time --help works correctly (#6598 — https://github.com/fish-shell/fish-shell/issues/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 environment override — that is, F=B status current-command returns status instead of F=B (#6635 — https://github.com/fish-shell/fish-shell/issues/6635). the way that one was bugging people, obsessed that it's fixed.
test no longer crashes when used with nan or inf arguments — it errors out instead (#6655 — https://github.com/fish-shell/fish-shell/issues/6655).
Copying from the end of the command line no longer crashes fish (#6680 — https://github.com/fish-shell/fish-shell/issues/6680). we do not stan a crashy clipboard 🍓
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. so like, don't be shocked ok 🫠
Functions using --on-variable work reliably with variables which are set implicitly (rather than with set), such as fish_bind_mode and PWD (#6653 — https://github.com/fish-shell/fish-shell/issues/6653).
256 colors are properly enabled under certain conditions that were incorrectly detected in fish 3.1.0 ($TERM begins with xterm, does not include "256color", and $TERM_PROGRAM is not set) (#6701 — https://github.com/fish-shell/fish-shell/issues/6701). ALL the colors, as she deserves 🌈
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) status by default, because that operation has the potential to be slow (#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). zoom zoom ✨
Using extended Unicode characters, such as emoji, in a non-Unicode capable locale (such as the C or POSIX locale) no longer renders all output blank (#6736 — https://github.com/fish-shell/fish-shell/issues/6736). imagine a world with no emoji rendering, couldn't be me 😭
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/issues/6763), but may be changed in a future version. so like, heads up 🫶
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). she's free 💜

This release also includes:

several changes to improve macOS compatibility with code signing and notarization;
several improvements to completions; and
several content and formatting improvements to the documentation.

If you're upgrading from version 3.0.0 or before, please also review the release notes for 3.1.0 and 3.1b1 (included below). more lore incoming 📖

Errata for fish 3.1

okay so quick correction notice bestie 📝 fish 3.1 introduced a brand-new builtin called time. And because of the way it's implemented, this builtin is a reserved word (like test, function, and the others in that exclusive little club), and functions can no longer be named time. That was not made clear in the fish 3.1b1 changelog. now you know 💅

fish 3.1.0 (released February 12, 2020)

Compared to the beta release of fish 3.1b1, fish version 3.1.0 does all of this:

Fixes a regression where spaces after a brace were removed even though brace expansion wasn't even occurring (#6564 https://github.com/fish-shell/fish-shell/issues/6564).
Fixes a bunch of problems with compiling and testing on Cygwin (#6549 https://github.com/fish-shell/fish-shell/issues/6549) and Solaris-derived systems such as Illumos (#6553 https://github.com/fish-shell/fish-shell/issues/6553, #6554 https://github.com/fish-shell/fish-shell/issues/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 get 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're upgrading from version 3.0.0 or before, please also review the release notes for 3.1b1 (included below 👇).

fish 3.1b1 (released January 26, 2020)

Notable improvements and fixes

A new $pipestatus variable contains a list of exit statuses of the previous job, for each of the separate commands in a pipeline (#5632 https://github.com/fish-shell/fish-shell/issues/5632). iconic honestly.
fish no longer buffers pipes to the last function in a pipeline, which improves many cases where pipes appeared to block or hang (#1396 https://github.com/fish-shell/fish-shell/issues/1396). no more mysterious hanging, we love to see it ✨
A full overhaul of error messages for builtin commands, including 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/issues/5771).
fish's debugging arguments have been significantly improved. The --debug-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). yes that's literally this page, hi 🫶
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 "." (#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/issues/3845).
The fish Web configuration tool (fish_config) prints a list of commands it is executing, to help with 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/issues/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/issues/6288). speed. we love speed 🔥

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 "," 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/issues/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 environment (#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). finally, natural selection for syntax 💀
math's exponent operator, ^, 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 as (3^0.5)^2, but is now calculated as 3^(0.5^2).
In fish 3.0, the variable used with for loops inside command substitutions 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 directories 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 hasn't 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/issues/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 shell's tokenization rules, considering quoting, escaping, and so on (#3823 https://github.com/fish-shell/fish-shell/issues/3823).
read interacts more correctly with the deprecated $IFS variable, in particular 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, 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/issues/5906).
math reports the right error when incorrect syntax is used inside parentheses (#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/issues/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 || on top of ; and &, bestie. More separators, more slay. (#6214 <https://github.com/fish-shell/fish-shell/issues/6214>)
There was this cursed bug where string split would just drop empty strings if the output was only empty strings? Yeah. Fixed. (#5987 <https://github.com/fish-shell/fish-shell/issues/5987>)
Big one: eval no longer creates a new local variable scope 💀 it affects the variables in the scope it's called from. source still creates a new local scope though, so don't mix them up. (#4443 <https://github.com/fish-shell/fish-shell/issues/4443>)
abbr got a brand new --query option so you can check whether an abbreviation exists. Vibe check for your abbreviations, honestly.
Local values for fish_complete_path and fish_function_path are now ignored — only their global values are respected. Periodt.
Syntax error reports now put the marker in the correct position. No more pointing at the wrong letter like a confused little guy. (#5812 <https://github.com/fish-shell/fish-shell/issues/5812>)
Empty universal variables may now be exported. Yes, empty ones. (#5992 <https://github.com/fish-shell/fish-shell/issues/5992>)
Exported universal variables are no longer imported into the global scope, which prevents shadowing 🫶 This makes it way easier to change those variables for all your fish sessions, and avoids breakage when the value is a list of multiple elements. (#5258 <https://github.com/fish-shell/fish-shell/issues/5258>)
Ummm there was a bug where for could use invalid variable names. Fixed, obviously. (#5800 <https://github.com/fish-shell/fish-shell/issues/5800>)
A bug where local variables would not be exported to functions has been fixed. That one was lowkey annoying. (#6153 <https://github.com/fish-shell/fish-shell/issues/6153>)
The null command (:) now always exits successfully, instead of passing through the previous exit status. So clean, so iconic. (#6022 <https://github.com/fish-shell/fish-shell/issues/6022>)
The output of functions FUNCTION now matches the declaration of the function, correctly including comments or blank lines (#5285 <https://github.com/fish-shell/fish-shell/issues/5285>), and it also correctly includes any --wraps flags (#1625 <https://github.com/fish-shell/fish-shell/issues/1625>).
type supports a new option, --short, which suppresses 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. Finding your function's home address, basically.
type --force-path with an argument that cannot be found now correctly outputs nothing, exactly 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 now. (#6350 <https://github.com/fish-shell/fish-shell/issues/6350>)
A cute new fish_cancel event is emitted when the command line is cancelled — super 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 configuration 🌈 (#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/issues/5637>) and avoiding changes to path ordering in child shells (#5456 <https://github.com/fish-shell/fish-shell/issues/5456>). It now also ignores blank lines, just like bash does. (#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, which makes it suitable for operations that shouldn't end up there — like password entry, bestie 🙈 (#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's going to a terminal. Cute and also useful.
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. Way less dramatic, way more accurate.
Syntax highlighting works correctly with variables as commands (#5658 <https://github.com/fish-shell/fish-shell/issues/5658>) and with 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. Thank goodness. (#5720 <https://github.com/fish-shell/fish-shell/issues/5720>)
fish will not autosuggest files ending with ~ unless there are no other candidates, since 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. Slay.
The output of complete and functions is now colorized in interactive terminals 🎀
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/issues/6147>) and correctly parses options following --argument-names, as in --argument-names foo --description bar. (#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 described in job and process listings, and no longer produces a warning when exiting fish. (#6269 <https://github.com/fish-shell/fish-shell/issues/6269>)
In private mode, setting $fish_greeting to an empty string before starting the private session will prevent the warning about history not being saved from being printed. (#6299 <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 do. (#5909 <https://github.com/fish-shell/fish-shell/issues/5909>)
Job identifiers (for example, for background jobs) are assigned more logically now. (#6053 <https://github.com/fish-shell/fish-shell/issues/6053>)
A bug where history would appear truncated if an empty command was executed was fixed. (#6032 <https://github.com/fish-shell/fish-shell/issues/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/issues/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 (the thing that differentiates between the escape key and an alt-combination) has been reduced to 30ms — down from 300ms for the default mode and 100ms for Vi mode. Snappy. (#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 "Hit end of history", and instead use a bell. They also correctly store working directories containing symbolic links. (#6395 <https://github.com/fish-shell/fish-shell/issues/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 : and @, 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 generate 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 that describes a command should now behave way better when your prompt is multiline, no cap (#6110 — https://github.com/fish-shell/fish-shell/issues/6110) ✨
the Alt-H binding that opens a command's man page now tries to ignore sudo — iconique (#6122 — https://github.com/fish-shell/fish-shell/issues/6122) 💅
a whole new pair of bind functions dropped: history-prefix-search-backward (and its forward twin), so go off bestie (#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), plus d0 to delete the current line (#6292 — https://github.com/fish-shell/fish-shell/issues/6292) 🦋
in Vi mode, hitting Enter in replace-one mode no longer wipes your prompt, we love to see it (#6298 — https://github.com/fish-shell/fish-shell/issues/6298) 🌸
selections in Vi mode are now inclusive, which literally matches how actual Vi behaves — accuracy slay (#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 you've enabled that 🍓
the Git prompt now has an option ($__fish_git_prompt_use_informative_chars) so you can use the (more modern) informative characters without turning informative mode on — big brain energy 💜
the default prompt now also features VCS integration AND will color the host if you're running via SSH (#6375 — https://github.com/fish-shell/fish-shell/issues/6375) 🌈
the default and example prompts now print the pipe status if an earlier command in the pipe fails 👑
the default and example prompts try to resolve exit statuses to signal names when that's appropriate — thoughtful fr fr 🫶

✨ Improved terminal output ✨

brand new fish_pager_color_ options have been added so you can control even more elements of the pager's colors (#5524 — https://github.com/fish-shell/fish-shell/issues/5524) 🎨
better detection and support for running fish from all sorts of system consoles, the ones where limited colors and special characters are what you get (#5552 — https://github.com/fish-shell/fish-shell/issues/5552) 💀
fish now tries to guess whether your system supports Unicode 9 (and displays emoji as wide), which means you don't gotta set $fish_emoji_width in most cases anymore (#5722 — https://github.com/fish-shell/fish-shell/issues/5722) 🙈
improvements to how wide characters display, especially Korean characters and emoji (#5583 — https://github.com/fish-shell/fish-shell/issues/5583, #5729 — https://github.com/fish-shell/fish-shell/issues/5729) 🌸
the Vi mode cursor is correctly redrawn when you regain focus under terminals 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 — yes bestie 🔥

🦋 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/issues/6488)
- csc and csi (#6016 — https://github.com/fish-shell/fish-shell/issues/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/issues/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/issues/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/issues/6067)
- resolvectl (#6501 — https://github.com/fish-shell/fish-shell/issues/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, generally 💅
selecting short options that also have a long name from the completion pager? now possible, bestie (#5634 — https://github.com/fish-shell/fish-shell/issues/5634) ✨
tab completion will no longer add trailing spaces if they're already there (#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 you use multiple short options together (#332 — https://github.com/fish-shell/fish-shell/issues/332) 🌸
activating completion in the middle of an invalid completion doesn't move the cursor anymore, so fixing your mistake is way easier (#4124 — https://github.com/fish-shell/fish-shell/issues/4124) 🫶
completion in empty commandlines now lists all the available commands — go look 👑
functions listed as completions could previously leak parts of the function as other completions; that's been fixed, thank goodness 😭

💀 Deprecations and removed features 💀

the vcs-prompt functions got promoted to names without the double-underscore, so __fish_git_prompt is now fish_git_prompt, __fish_vcs_prompt is now fish_vcs_prompt, __fish_hg_prompt is now fish_hg_prompt and __fish_svn_prompt is now fish_svn_prompt. Shims at the old names have been added, and the variables 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 expression, so escaping backslashes requires many escapes (eg string replace -ra '([ab])' '\\\\\\\$1' a). The new feature flag regex-easyesc can be used to disable this, so that the same effect can be achieved with string replace -ra '([ab])' '\\\\$1' a (#5556 — https://github.com/fish-shell/fish-shell/issues/5556). As a reminder, the intention behind feature flags is that this will eventually become the default and then the only option, so scripts should be updated — fr fr go update them 🙈
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 Autotools-based build and the legacy Xcode build system have been removed, leaving only the CMake build system. All distributors and developers must install CMake — non-negotiable 🫶
fish now depends on the common tee external command, for the psub process substitution function 🌸
the documentation is now built with Sphinx. The old Doxygen-based documentation system has been removed. Developers, and distributors who wish to rebuild the documentation, must install Sphinx ✨
the INTERNAL_WCWIDTH build option has been removed, since fish now always uses an internal wcwidth function. It has a number of configuration options 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 isn't installed, which reduces the number of external dependencies on systems that have mandoc installed (#5489 — https://github.com/fish-shell/fish-shell/issues/5489) 🎀
some bugs that were preventing builds on Solaris-derived systems such as Illumos got 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's available — glow up 🌈
the paths for completions, functions and configuration snippets got extended, big glow-up ✨ — on systems that define XDG_DATA_DIRS, each of the directories in this variable are searched in the subdirectories fish/vendor_completions.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 default “extra” 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. tiny lil patch, but she matters 💅

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/issues/5647>). no cap, this one was giving chaos 🙈

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). yes bestie, read all of them, it's a whole saga 🫶

🐟 fish 3.0.1 (released February 11, 2019)

This release of fish fixes a number of major issues discovered in fish 3.0.0. okay so 3.0.0 had some moments, and 3.0.1 is the apology tour 😭

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>). highkey the correct behaviour 💖
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>). spaces in paths are the villain of this entire genre fr fr 💀
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. she's an icon, she shows up whether or not you invited her 👑
The error when a command is not found is now printed a single time, instead of once per argument (#5588 <https://github.com/fish-shell/fish-shell/issues/5588>). thank god, one (1) single error, as a treat 🌸
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/issues/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/issues/5541>). speed, slay ⚡
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>). tidy queen 🎀
The nim prompt now works correctly when chosen in the Web-based configuration (#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>) not her eating CPU for no reason bestie 😭
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/issues/5479>, #5453 <https://github.com/fish-shell/fish-shell/issues/5453>).
Improvements to the documentation and certain completions.

Known issues

There is one significant known issue that was not corrected before the release:

fish does not run correctly under Windows Services for Linux before Windows 10 version 1809/17763, and the message warning of this may not be displayed (#5619 <https://github.com/fish-shell/fish-shell/issues/5619>). so like… she's broken and she won't tell you she's broken 🙈💀

If you are upgrading from version 2.7.1 or before, please also review the release notes for 3.0.0 and 3.0b1 (included below).

🐟 fish 3.0.0 (released December 28, 2018)

fish 3 is a major release, which introduces some breaking changes alongside improved functionality. Although most existing scripts will continue to work, they should be reviewed against the list contained in the 3.0b1 release notes below. read the list, bestie, don't just vibe through it 💅

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. rip the history colouring, she was pretty but she was messy 🦋

There is one significant known issue which was not able to be corrected before 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 continue using 2.7.1 until a release which corrects this is available. like, hanging terminal, full stop, not a drill 🫠

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

okay so this is the part where you sit down and pay attention, because these are the "your scripts might act different now" receipts 🔥

Process and job expansion has largely been removed. % will no longer perform these expansions, except for %self for the PID of the current shell. Additionally, job management commands (disown, wait, bg, fg and kill) will expand job specifiers starting with % (#4230 <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/issues/4236>).
A literal {} now expands to itself, rather than nothing. This makes working with find -exec easier (#1109 <https://github.com/fish-shell/fish-shell/issues/1109>, #4632 <https://github.com/fish-shell/fish-shell/issues/4632>). she ate that one fr ✨
Literally accessing a zero-index is now illegal syntax and is caught by the parser (#4862 <https://github.com/fish-shell/fish-shell/issues/4862>). (fish indices start at 1) 🚨 do not come for the 1-indexing, she is who she is 💅
Successive commas in brace expansions are handled in less surprising manner. For example, {,,,} expands to four empty strings rather than an empty string, a comma and an empty string again (#3002 <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 expected.
read now uses -s as short for --silent (à la bash); --shell’s abbreviation (formerly -s) is now -S instead (#4490 <https://github.com/fish-shell/fish-shell/issues/4490>). muscle memory betrayal, truly 😭
cd no longer resolves symlinks. fish now maintains a virtual path, matching other shells (#3350 <https://github.com/fish-shell/fish-shell/issues/3350>).
source now requires an explicit - as the filename to read from the terminal (#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 breaking stuff (#3000 <https://github.com/fish-shell/fish-shell/issues/3000>). protecting you from yourself, lovingly 🫶
The fish_user_abbreviations variable is no longer used; abbreviations will be migrated to the new storage format automatically. she moves on her own, don't worry 🦋
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 builtin’s --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 removal 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. so like… enjoy them while they're here, but don't get attached 💀🌸

okay so a whole new feature flags mechanism got added for staging deprecations and breaking changes, bestie. 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/issues/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 current-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 redirect 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 better migration from POSIX-compliant shells (#4620 <https://github.com/fish-shell/fish-shell/issues/4620>). slay, honestly
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 evaluated in private mode are not persisted for future sessions. A session variable $fish_private_mode can be queried to detect private mode and adjust the behavior of scripts accordingly to respect the user’s wish for privacy. main character energy, but make it private 🙈
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/issues/4478>). the way that math ate 🧮
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, controlled by the fish_read_limit variable (#3822 <https://github.com/fish-shell/fish-shell/issues/3822>). Notably, this is larger than most operating systems’ argument size limit, so trying to pass argument lists this size to external commands has never worked. 10 MB bestie, that's the cap 💀
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 dynamically-generated argument list in the same order as specified, rather than alphabetically (#361 <https://github.com/fish-shell/fish-shell/issues/361>). order matters, periodt 💅
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/issues/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 consuming the input in its entirety via the new /--line option. (yes, that slash is literally what the page says, don't come for me)
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/issues/4779>).
string has new subcommands split0 and join0 for working with NUL-delimited 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>). this one is so convenient fr fr
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/issues/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>). obsessed
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/issues/1976>). The alias function has been updated to respect this behavior.
Path completions now support expansions, meaning expressions like python ~/<TAB> now provides file suggestions just like any other relative or absolute path. (This includes support for other expansions, too.) 🌸
Autosuggestions try to avoid arguments that are already present in the command line.
Notifications about crashed processes are now always shown, even in command substitutions (#4962 <https://github.com/fish-shell/fish-shell/issues/4962>).
The screen is no longer reset after a BEL, fixing graphical glitches (#3693 <https://github.com/fish-shell/fish-shell/issues/3693>). no more flicker bestie
vi-mode now supports ‘;’ and ‘,’ motions. This introduces new {forward,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>). thank god honestly 😭
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 — it's literally restoring a behavior that existed back in 3.4.1, we love a comeback era (#8807 — https://github.com/fish-shell/fish-shell/issues/8807). 🫶
Added completions for… okay brace yourself bestie, this list is LONG:
- 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/issues/4174)
- conda (#4837 — https://github.com/fish-shell/fish-shell/issues/4837)
- configure (for autoconf-generated files only, iykyk)
- 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/issues/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)
- OpenBSD's pkg_add, pkg_delete, pkg_info, pfctl, rcctl, signify, and vmctl (#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/issues/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/issues/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 functionality
Improved French translations 🇫🇷

🔧 Other fixes and improvements

Significant performance improvements to abbr (#4048 — https://github.com/fish-shell/fish-shell/issues/4048), setting variables (#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/issues/4579), string reading from standard input (#4610 — https://github.com/fish-shell/fish-shell/issues/4610), and slicing history (in particular, $history[1] for the last executed command). It's giving speedrun energy fr fr 🏎️
fish's internal wcwidth function has been updated to deal with newer Unicode, and the width of some characters can be configured via the fish_ambiguous_width (#5149 — https://github.com/fish-shell/fish-shell/issues/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 system's 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 macOS' 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). No more quiet chaos bestie 💀
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). Iconic behavior tbh 👑

🛠️ For distributors and developers

fish ships with a new build system based on CMake. CMake 3.2 is the minimum required version. Although the autotools-based Makefile and the Xcode project are still shipped with this release, they will be removed in the near future. All distributors and developers are encouraged to migrate to the CMake build. Get ahead of the curve bestie ⭐
Build scripts for most platforms no longer require bash, using the standard sh instead.
The hostname command is no longer required for fish to operate.

🍒 fish 2.7.1 (released December 23, 2017)

This release of fish fixes an issue where iTerm 2 on macOS would display a warning about paste bracketing being left on when starting a new fish session (#4521 — https://github.com/fish-shell/fish-shell/issues/4521). Not the warning we wanted, so it's gone 🙈

If you are upgrading from version 2.6.0 or before, please also review the release notes for 2.7.0 and 2.7b1 (included below).

🍓 fish 2.7.0 (released November 23, 2017)

There are no major changes between 2.7b1 and 2.7.0. If you are 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. ✨

🌸 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). She's the main character now 💅
A new argparse command is available to allow fish script to parse arguments 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 subcommand (#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 reversed 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). Privacy slay 🦋
Read history is now controlled by the fish_history variable rather than the --mode-name flag (#1504 — https://github.com/fish-shell/fish-shell/issues/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). The way she spills the tea ☕

🌈 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).
complete's --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 "." (#4158 — https://github.com/fish-shell/fish-shell/issues/4158). The behavior being changed was introduced in fish 2.6.0.
count -h and count --help now return 1 rather than produce command help output (#4189 — https://github.com/fish-shell/fish-shell/issues/4189).
read stopping early still sets stuff, bestie — an attempt to read which stops because too much data is available still defines the variables given as parameters (#4180). so like, don't count on nothing happening 💀
pushd +1 is alive again 🌈 — a regression in fish 2.4.0 which prevented pushd +1 from working has been fixed (#4091).
read in scripts, unfixed no more 😭 — a regression in fish 2.6.0 where multiple read commands in non-interactive scripts were broken has been fixed (#4206).
universal variables that do side-effect stuff at startup — a regression in fish 2.6.0 involving universal variables with side-effects at startup such as set -U fish_escape_delay_ms 10 has been fixed (#4196). she's stable again, periodt 💅
Added completions for 🎀
- as (#4130)
- cdh (#2847)
- dhcpd (#4115)
- ezjail-admin (#4324)
- Fabric's fab (#4153)
- grub-file (#4119)
- grub-install (#4119)
- jest (#4142)
- kdeconnect-cli
- magneto (#4043, #4108)
- mdadm (#4198)
- passwd (#4209)
- pip and pipenv (#4448)
- s3cmd (#4332)
- sbt (#4347)
- snap (#4215)
- Sublime Text 3's subl (#4277)
Lots of improvements to completions. like. a lot. the tab key is eating good tonight 🔥
Updated Chinese and French translations. 🦋
Improved completions for:
- apt
- cd (#4061)
- composer (#4295)
- eopkg
- flatpak (#4456)
- git (#4117, #4147, #4329, #4368)
- gphoto2
- killall (#4052)
- ln
- npm (#4241)
- ssh (#4377)
- tail
- xdg-mime (#4333)
- zypper (#4325)

💡 quick heads up before we keep going: every one of those #1234 thingies is an issue number, and it lives at https://github.com/fish-shell/fish-shell/issues/ + the number. so #4180 → https://github.com/fish-shell/fish-shell/issues/4180. iykyk, but now you do know 🫶

fish 2.6.0 (released June 3, 2017)

Since the beta release of fish 2.6b1, fish version 2.6.0 contains a number of minor fixes, new completions for magneto (#4043), and improvements to the documentation. little glow-up era ✨

Known issues

🍎 the AppleScript browser thing, ugh — Apple macOS Sierra 10.12.5 introduced a problem with launching web browsers from other programs using AppleScript. This affects the fish Web configuration (fish_config); users on these platforms will need to manually open the address displayed in the terminal, such as by copying and pasting it into a browser. This problem will be fixed with macOS 10.12.6. so close 😭

If you are upgrading from version 2.5.0 or before, please also review the release notes for 2.6b1 (included below). no skipping, bestie 💖

fish 2.6b1 (released May 14, 2017)

Notable fixes and improvements

disown dropped and it's iconic 👑 — jobs running in the background can now be removed from the list of jobs with the new disown builtin, which behaves like the same command in other shells (#2810).
command substitutions can see the terminal now 🖥️ — command substitutions now have access to the terminal, like in other shells. this allows tools like fzf to work properly (#1362, #3922). fzf girlies we are SO back.
no terminal size? we guess. if the operating system doesn't report the size of the terminal, the COLUMNS and LINES environment variables are used; if they are unset, a default of 80x24 is assumed. 80x24 is so retro-core 💾
translation glow-up 🌸 — new French (#3772 & #3788) and improved German (#3834) translations.
no more which dependency — fish no longer depends on the which external command. we're independent, we're free 🦋

Other significant changes

speed, speed, speed ⚡ — performance improvements in launching processes, including major reductions in signal blocking. Although this has been heavily tested, it may cause problems in some circumstances; set the FISH_NO_SIGNAL_BLOCK variable to 0 in your fish configuration file to return to the old behaviour (#2007).
prompts and colour-heavy functions got faster 🎨 — performance improvements in prompts and functions that set lots of colours (#3793).
the Delete key stops committing crimes — the Delete key no longer deletes backwards (a regression in 2.5.0). it was giving unhinged behaviour, honestly 💀
functions got receipts 🧾 — functions supports a new --details option, which identifies where the function was loaded from (#3295), and a --details --verbose option which includes the function description (#597).
read has a byte budget now — read will read up to 10 MiB by default, leaving the target variable empty and exiting with status 122 if the line is too long. You can set a different limit with the FISH_READ_BYTE_LIMIT variable. 10 MiB is a whole personality, ngl.
read goes quiet, and takes a plain prompt 🤫 — read supports a new --silent option to hide the characters typed (#838), for when reading sensitive data from the terminal. read also now accepts simple strings for the prompt (rather than scripts) with the new -P and --prompt-str options (#802).
colon paths are understood — export and setenv now understand colon-separated PATH, CDPATH and MANPATH variables. the way that colon keeps the paths together?? lowkey genius.
setenv is not just set -gx anymore — setenv is no longer a simple alias for set -gx and will complain, just like the csh version, if given more than one value (#4103).
bind --list-modes — bind supports a new --list-modes option (#3872).
bg checks the vibes first — bg will check all of its arguments before backgrounding any jobs; any invalid arguments will cause a failure, but non-existent (eg recently exited) jobs are ignored (#3909).
funced notices when you changed literally nothing 🙈 — funced warns if the function being edited has not been modified (#3961). called out, honestly.
printf and the big integers — printf correctly outputs "long long" integers (#3352).
status current-function — status supports a new current-function subcommand to print the current function name (#1743). main character energy fr.
string got three new toys 🎀 — string supports a new repeat subcommand (#3864). string match supports a new --entire option to emit the entire line matched by a pattern (#3957). string replace supports a new --filter option to only emit lines which underwent a replacement (#3348).
test -k — test supports the -k option to test for sticky bits (#733). sticky bits, sticky situation 🍓
umask speaks symbolic — umask understands symbolic modes (#738).
empty path components become . — empty components in the CDPATH, MANPATH and PATH variables are now converted to . (#2106, #3914).
the ncurses scrollback situation 😭 — new versions of ncurses (6.0 and up) wipe terminal scrollback buffers with certain commands; the C-l binding tries to avoid this (#2855). protect the scrollback at all costs.
root's USER gets set — some systems' su implementations do not set the USER environment variable; it is now reset for root users (#3916).
bracketed paste, but make it safe 🫶 — under terminals which support it, bracketed paste is enabled, escaping problematic characters for security and convenience (#3871). Inside single quotes ('), single quotes and backslashes in pasted text are escaped (#967). The fish_clipboard_paste function (bound to C-v by default) is still the recommended pasting method where possible as it includes this functionality and more. paste responsibly bestie 💅
pipelines stop getting yelled at early — processes in pipelines are no longer signalled as soon as one command in the pipeline has completed (#1926). This behaviour matches other shells more closely. we're matching, we're mingling 🦋
any Python is fine, Python 3 is preferred 🐍 — all functions requiring Python work with whichever version of Python is installed (#3970). Python 3 is preferred, but Python 2.6 remains the minimum version required.
the cancel character gets a colour ✨ — the color of the cancellation character can be controlled by the fish_color_cancel variable (#3963).
Added completions for:
caddy (#4008)
castnow (#3744)
climate (#3760)
flatpak
gradle (#3859)
gsettings (#4001)
helm (#3829)
i3-msg (#3787)

…and bestie the list just keeps going, no cap:

ipset ✨ — issue #3924, https://github.com/fish-shell/fish-shell/issues/3924
jq — issue #3804, https://github.com/fish-shell/fish-shell/issues/3804
light — issue #3752, https://github.com/fish-shell/fish-shell/issues/3752
minikube — issue #3778, https://github.com/fish-shell/fish-shell/issues/3778
mocha — issue #3828, https://github.com/fish-shell/fish-shell/issues/3828
mkdosfs — issue #4017, https://github.com/fish-shell/fish-shell/issues/4017
pv 🦋 — issue #3773, https://github.com/fish-shell/fish-shell/issues/3773
setsid — issue #3791, https://github.com/fish-shell/fish-shell/issues/3791
terraform — issue #3960, https://github.com/fish-shell/fish-shell/issues/3960
usermod — issue #3775, https://github.com/fish-shell/fish-shell/issues/3775
xinput 🎀 — no issue number, it just showed up and ate, periodt
yarn — issue #3816, https://github.com/fish-shell/fish-shell/issues/3816

And the glow-ups to completions that already existed? Literally a whole roster, so let me lay it out instead of cramming it into one unreadable paragraph:

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 — no issue number attached, it's just there being iconic
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 — again, no issue number, she's mysterious 💅
man — #3762, https://github.com/fish-shell/fish-shell/issues/3762
mount — #3764 and #3841, https://github.com/fish-shell/fish-shell/issues/3764 and 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
udisks — #3764, https://github.com/fish-shell/fish-shell/issues/3764

🐟 fish 2.5.0 (released February 3, 2017)

Okay so between 2.5b1 and 2.5.0 there are no major changes, bestie — it's the same girl, just officially out of beta. But if you're upgrading from version 2.4.0 or before, please also read the release notes for 2.5b1 (they're included right below, don't worry 💖).

Notable fixes and improvements

The Home, End, Insert, Delete, Page Up and Page Down keys actually work in Vi-style key bindings now — issue #3731, https://github.com/fish-shell/fish-shell/issues/3731. The way that used to just not do anything… we don't talk about it 😭

🌈 fish 2.5b1 (released January 14, 2017)

Platform Changes

Starting with version 2.5, fish needs a more up-to-date version of C++ — specifically C++11 (from 2011, yes, ancient history). This affects some older platforms, so listen up:

Linux 🐧

If you're building from source, GCC's g++ 4.8 or later, or LLVM's clang 3.3 or later, are known to work. Older platforms may need a newer compiler installed — no cap, it's just the vibes of old toolchains.

Unfortunately, because of the complexity of the toolchain, binary packages are no longer published by the fish-shell developers for these 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 a newer version of fish on these systems will require building from source. Sorry bestie 💀

OS X SnowLeopard ❄️

Starting with version 2.5, fish requires a C++11 standard library on OS X 10.6 ("SnowLeopard"). If that library isn't installed, you'll see this error:

dyld: Library not loaded: /usr/lib/libc++.1.dylib

MacPorts is the easiest way to grab 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 — we will look 👀)

This is only necessary on 10.6. OS X 10.7 and later include the required library by default, so you can chill 🌸

Other significant changes

Trying to exit while there are running processes in the background now produces a warning, and then signals them to terminate if you attempt to exit a second time. 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 you can use the shiny new choice subcommand to pick an argument from a list — #3619, https://github.com/fish-shell/fish-shell/issues/3619 ✨
A brand new key bindings preset, fish_hybrid_key_bindings, including all the Emacs-style and Vi-style bindings, which behaves like fish_vi_key_bindings in fish 2.3.0 — #3556, https://github.com/fish-shell/fish-shell/issues/3556
function now returns an error when called with invalid options, instead of 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, so yeah, we fixed our own mess 🙈
fish no longer prints a warning when it identifies a running instance of an old version (2.1.0 and earlier). Just so you know: 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 operations on invalid integers — #3346, https://github.com/fish-shell/fish-shell/issues/3346, #3581, https://github.com/fish-shell/fish-shell/issues/3581
complete no longer recognises the --authoritative and --unauthoritative options, and they are marked as obsolete 💀
status accepts subcommands now, and should be used like status is-interactive. 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 "begin-selection") no longer selects a character 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_default_mode_prompt, which makes it way easier to include the mode prompt in your 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 identifies 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), giving you a simple way of checking whether a command exists in scripts. So handy ngl 🍓
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/issues/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 command is entered — #3616, https://github.com/fish-shell/fish-shell/issues/3616 💀
Exiting fish now signals all background processes to terminate, not just stopped jobs — #3497, https://github.com/fish-shell/fish-shell/issues/3497
A new prompt_hostname function which prints a hostname suitable for use in prompts — #3482, https://github.com/fish-shell/fish-shell/issues/3482 🎀
The __fish_man_page function (bound to Alt+h by default) now tries to recognize subcommands — e.g. git add will now open the "git-add" man page — #3678, https://github.com/fish-shell/fish-shell/issues/3678. Main character energy fr fr 👑
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/issues/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/issues/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 and #3522, https://github.com/fish-shell/fish-shell/issues/3521 and https://github.com/fish-shell/fish-shell/issues/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)

Okay so between 2.4b1 and 2.4.0 there are no major changes. That's it. That's the tea. 🍵

Notable fixes and improvements

The docs are now generated properly, and with the correct version identifier. Slay. ✨
Automatic cursor changes are now only enabled on the subset of XTerm versions that we know support them — which fixes that cursed situation where older versions printed garbage to the terminal before and after every single prompt (#3499 — https://github.com/fish-shell/fish-shell/issues/3499). No more random noise, bestie. 💅
The title set in Apple Terminal.app got improved. 🍎
Added completions for defaults, and improved the ones for diskutil (#3478 — https://github.com/fish-shell/fish-shell/issues/3478).

🦋 fish 2.4b1 (released October 18, 2016)

Significant changes

Clipboard integration got a whole revamp with explicit bindings. The killring commands no longer copy from, or paste to, the X11 clipboard — use the new copy (Ctrl+x) and paste (Ctrl+v) bindings instead. And the clipboard now works on OS X as well as systems using X11 (like 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). And heads up: you can no longer specify multiple actions via flags — so like, history --delete --save something? Not a thing anymore. 🙈
New history options dropped, including --max=n to limit the number of history entries, --show-time 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 lowkey also affects history delete) (#3236 — https://github.com/fish-shell/fish-shell/issues/3236).
history delete now correctly handles multiline commands (#31 — https://github.com/fish-shell/fish-shell/issues/31). The way that used to break… 😭
Vi-style bindings no longer include all of the default emacs-style bindings; 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 configuration files get checked for a default. And 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 — like 5^ — is no longer treated as a redirection (#1873 — https://github.com/fish-shell/fish-shell/issues/1873). She's not redirected, she's just living her life. 💀
The $version special variable can be overwritten, so you can use it for other purposes if you need to.

Notable fixes and improvements

The fish_realpath builtin has been renamed to realpath and made compatible with GNU realpath when run without arguments (#3400 — https://github.com/fish-shell/fish-shell/issues/3400). It's used only for systems that don't have 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, particularly 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/issues/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). No cap, the surprise was not the fun kind. 🫶
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). She really said "let me help you" 💖
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. And the --dump option has been renamed to --dump-parse-tree (#3191 — https://github.com/fish-shell/fish-shell/issues/3191). Renamed! Don't come for me, come for the changelog.
The display of bindings in the Web-based configuration has been greatly improved (#3325 — https://github.com/fish-shell/fish-shell/issues/3325), and so 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). Goodbye spicy fan noise. 💀
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/issues/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 on slow filesystems (#3083 — https://github.com/fish-shell/fish-shell/issues/3083). Snappy prompt = main character energy. ✨
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 correctly (#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/issues/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/issues/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/issues/3383), cygport (#3392 — https://github.com/fish-shell/fish-shell/issues/3392), git (#3274 — https://github.com/fish-shell/fish-shell/issues/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)

So this one is a functionality and bugfix release. Heads up though: it does not contain all the changes to fish since the last release — it fixes a number of issues directly affecting users at present, and includes a small number of new features. Short and sweet, periodt. 💅

Significant changes

A brand 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 being updated (#2859 — https://github.com/fish-shell/fish-shell/issues/2859). Not the stray-line aesthetic we were going for, ngl. 😭
string's match mode now actually handles -rnv (match + invert + count) the right way together — no more cursed combo behaviour, we fixed it (<https://github.com/fish-shell/fish-shell/issues/3098>). 🎀
TTY special-character handling got some love (<https://github.com/fish-shell/fish-shell/issues/3064>), so did locale handling (<https://github.com/fish-shell/fish-shell/issues/3124>), and terminal environment variable handling too (<https://github.com/fish-shell/fish-shell/issues/3060>). ✨
We did work towards handling the terminal modes for external commands launched from initialisation files (<https://github.com/fish-shell/fish-shell/issues/2980>) — towards, bestie, it's a journey.
The upgrade path from fish 2.2.0 and before got easier: we now warn users to restart fish if the string builtin isn't available (<https://github.com/fish-shell/fish-shell/issues/3057>). polite little heads-up, love that for us 💅
type -a now syntax-colourises function source output. pretty AND useful 🦋
Added completions for alsamixer, godoc, gofmt, goimports, gorename, lscpu, mkdir, modinfo, netctl-auto, poweroff, termite, udisksctl and xz (<https://github.com/fish-shell/fish-shell/issues/3123>). so many new friends 🫶
Improved completions for apt (<https://github.com/fish-shell/fish-shell/issues/3097>), aura (<https://github.com/fish-shell/fish-shell/issues/3102>), git (<https://github.com/fish-shell/fish-shell/issues/3114>), npm (<https://github.com/fish-shell/fish-shell/issues/3158>), string and suspend (<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. literally none. iconic behaviour, honestly 💀

✨ Other notable fixes and improvements ✨

abbr now allows non-letter keys (<https://github.com/fish-shell/fish-shell/issues/2996>). yes bestie, go wild 🎀
We define a few extra colours on first start (<https://github.com/fish-shell/fish-shell/issues/2987>). more pretty, always correct.
Multiple documentation updates. (that's this, hi 👋)
Added completions for rmmod (<https://github.com/fish-shell/fish-shell/issues/3007>).
Improved completions for git (<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 terminal modes and fail to behave as expected. A fix is planned but requires further testing (<https://github.com/fish-shell/fish-shell/issues/2619>). so like… known, tracked, we're on it 😭

🌸 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 don't ship an appropriate command (<https://github.com/fish-shell/fish-shell/issues/2932>). slay, portable king 👑
Alt+# toggles the current command line between commented and uncommented states, making it easy to save a command in history without executing it. main character keyboard shortcut fr fr 🔥
The fish_vi_mode function is now deprecated in favour of fish_vi_key_bindings. > heads up bestie: deprecated means use fish_vi_key_bindings instead, okay? 💅

✨ Other notable fixes and improvements ✨

Fix the build on Cygwin (<https://github.com/fish-shell/fish-shell/issues/2952>) and RedHat Enterprise Linux/CentOS 5 (<https://github.com/fish-shell/fish-shell/issues/2955>). builds build again 🧚
Avoid confusing the terminal line driver with non-printing characters in fish_title (<https://github.com/fish-shell/fish-shell/issues/2453>).
Improved completions for busctl, git (<https://github.com/fish-shell/fish-shell/issues/2585>, <https://github.com/fish-shell/fish-shell/issues/2879>, <https://github.com/fish-shell/fish-shell/issues/2984>), and netctl.

🦋 fish 2.3b1 (released April 19, 2016) 🦋

💜 Significant Changes 💜

A new string builtin to handle… strings! This builtin will measure, split, search and replace text strings, including using regular expressions. It can also be used to turn lists into plain strings using join. string can be used in place of sed, grep, tr, cut, and awk in many situations. (<https://github.com/fish-shell/fish-shell/issues/2296>) — not a replacement for your whole personality but honestly close 🔥
Allow using escape as the Meta modifier key, by waiting after seeing an escape character wait up to 300ms for an additional character. This is consistent with readline (e.g. bash) and can be configured via the fish_escape_delay_ms variable. This allows using escape as the Meta modifier. (<https://github.com/fish-shell/fish-shell/issues/1356>) — 300ms, that's the number, don't forget it 💀
Add new directories for vendor functions and configuration snippets (<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. (limitations = go read the docs, bestie 🫶)

😭 Backward-incompatible changes 😭

read this part carefully, these WILL change how your old stuff behaves.

Unmatched globs will now cause an error, except when used with for, set or count (<https://github.com/fish-shell/fish-shell/issues/2719>). yes, an actual error, not a silent nothing 🙈
and and or will now bind to the closest if or while, allowing compound conditions without begin and end (<https://github.com/fish-shell/fish-shell/issues/1428>).
set -ql now searches up to function scope for variables (<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 (<https://github.com/fish-shell/fish-shell/issues/2643>).
source no longer puts the file name in $argv if no arguments are given (<https://github.com/fish-shell/fish-shell/issues/139>). keep that literal, $argv, yes 💅
History files are stored under the XDG_DATA_HOME hierarchy (by default, in ~/.local/share), and existing history will be moved on first use (<https://github.com/fish-shell/fish-shell/issues/744>). your history is moving house, don't panic 🎀

✨ Other notable fixes and improvements ✨

fish no longer silences errors in config.fish (<https://github.com/fish-shell/fish-shell/issues/2702>). errors are loud now, sorry not sorry 😭
Directory autosuggestions will now descend as far as possible if there is only one child directory (<https://github.com/fish-shell/fish-shell/issues/2531>). it just keeps going, obsessed 🌸
Add support for bright colors (<https://github.com/fish-shell/fish-shell/issues/1464>). bright, as in the actual bright colours, yes 🔥
Allow Ctrl+J (\cj) to be bound separately from Ctrl+M (\cm) (<https://github.com/fish-shell/fish-shell/issues/217>).
psub now has a “-s”/“-suffix” option to name the temporary file with that suffix. cute + functional 🎀
Enable 24-bit colors on select terminals (<https://github.com/fish-shell/fish-shell/issues/2495>). select terminals, iykyk 🌈
Support for SVN status in the prompt (<https://github.com/fish-shell/fish-shell/issues/2582>).
Mercurial and SVN support have been added to the Classic + Git (now Classic + VCS) prompt (via the new __fish_vcs_prompt function) (<https://github.com/fish-shell/fish-shell/issues/2592>). it got a rebrand, love that 👑
export now handles variables with a “=” in the value (<https://github.com/fish-shell/fish-shell/issues/2403>).
New completions for:
- alsactl
- Archlinux's asp, makepkg
- Atom's apm (<https://github.com/fish-shell/fish-shell/issues/2390>)
- entr - the “Event Notify Test Runner” (<https://github.com/fish-shell/fish-shell/issues/2265>)
- Fedora's dnf (<https://github.com/fish-shell/fish-shell/issues/2638>)
- OSX diskutil (<https://github.com/fish-shell/fish-shell/issues/2738>)
- pkgng (<https://github.com/fish-shell/fish-shell/issues/2395>)
- pulseaudio's pacmd and pactl
- rust's rustc and cargo (<https://github.com/fish-shell/fish-shell/issues/2409>)
- sysctl (<https://github.com/fish-shell/fish-shell/issues/2214>)
- systemd's machinectl (<https://github.com/fish-shell/fish-shell/issues/2158>), busctl (<https://github.com/fish-shell/fish-shell/issues/2144>), systemd-nspawn, systemd-analyze, localectl, timedatectl
- and more
fish no longer has a function called sgrep, freeing it for user customization (<https://github.com/fish-shell/fish-shell/issues/2245>). it's yours now 🫶
A rewrite of the completions for cd, fixing a few bugs (<https://github.com/fish-shell/fish-shell/issues/2299>, <https://github.com/fish-shell/fish-shell/issues/2300>, <https://github.com/fish-shell/fish-shell/issues/562>).
Linux VTs now run in a simplified mode to avoid issues (<https://github.com/fish-shell/fish-shell/issues/2311>).
The vi-bindings now inherit from the emacs bindings. yes, inherit 💅
fish will also execute fish_user_key_bindings when in vi-mode.
funced will now also check $VISUAL (<https://github.com/fish-shell/fish-shell/issues/2268>). $VISUAL has entered the chat 🌸
A new suspend function (<https://github.com/fish-shell/fish-shell/issues/2269>).
Subcommand completion now works better with split /usr (<https://github.com/fish-shell/fish-shell/issues/2141>).
The command-not-found-handler can now be overridden by defining a function called __fish_command_not_found_handler in config.fish (<https://github.com/fish-shell/fish-shell/issues/2332>).
A few fixes to the Sorin theme. (the Sorin girlies are eating good 🎀)
PWD shortening in the prompt can now be configured via the fish_prompt_pwd_dir_length variable, set to the length per path component (<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 (<https://github.com/fish-shell/fish-shell/issues/2799>). slay, one less thing to break ✨

⭐ fish 2.2.0 (released July 12, 2015) ⭐

💖 Significant changes 💖

Abbreviations: the new abbr command allows for interactively-expanded abbreviations, allowing quick access to frequently-used commands (<https://github.com/fish-shell/fish-shell/issues/731>). type short, get long, it's giving efficiency 💅
Vi mode: run fish_vi_mode to switch fish into the key bindings and prompt familiar to users of the Vi editor (<https://github.com/fish-shell/fish-shell/issues/65>).
New inline and interactive pager, which will be familiar to users of zsh (<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. Notably, old fish sessions will not be able to communicate universal variable changes with new fish sessions. For best results, restart all running instances of fish.

fr fr, restart all your fish instances. old sessions and new sessions can't talk anymore 😭

New documentation design (#1662 <https://github.com/fish-shell/fish-shell/issues/1662>) — and heads up, building it now needs a Doxygen version 1.8.7 or newer. 💅
fish now defines a default directory for other packages to provide completions. By default this is /usr/share/fish/vendor-completions.d; on systems with pkgconfig installed this path is discoverable with pkg-config --variable completionsdir fish. 🎀
A new parser removes many bugs; all existing syntax should keep working. no cap, ur old scripts are safe ✨
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>). she's dramatic but she'll still run 💀
The . command is deprecated and the source command is preferred (#310 <https://github.com/fish-shell/fish-shell/issues/310>). use source bestie, the dot is giving legacy 🫶
bind supports "bind modes", which allows bindings to be set for a particular 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 shells' 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 (recursively) 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>). recursive inheritance?? iconic ✨
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 sessions 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>). quiet luxury type behavior 💅
Pressing f1 now shows the manual page for the current command (#1063 <https://github.com/fish-shell/fish-shell/issues/1063>). literally help on demand 🫶
fish_title functions have access to the arguments of the currently running 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 Fedora (#1280 <https://github.com/fish-shell/fish-shell/issues/1280>).
Alt+. searches backwards in the token history, mapping to the same behavior as inserting the last argument of the previous command, like other shells (#89 <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/issues/1211>), apt (#2018 <https://github.com/fish-shell/fish-shell/issues/2018>), aura (#1292 <https://github.com/fish-shell/fish-shell/issues/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>). the completion glow-up is real 🌸
Improved completions for brew (#1090 <https://github.com/fish-shell/fish-shell/issues/1090> & #1810 <https://github.com/fish-shell/fish-shell/issues/1810>), bundler (#1779 <https://github.com/fish-shell/fish-shell/issues/1779>), cd (#1135 <https://github.com/fish-shell/fish-shell/issues/1135>), emerge (#1840 <https://github.com/fish-shell/fish-shell/issues/1840>), git (#1680 <https://github.com/fish-shell/fish-shell/issues/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>). ate and left no crumbs 💅

🍓 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, "Verify Disk" in Disk Utility will report "Invalid number of hard links." We don't have any reports of data loss or other adverse consequences. fish 2.1.2 avoids triggering the bug, but does not repair an already affected filesystem. To repair the filesystem, you can boot into Recovery Mode and use Repair Disk from Disk Utility. Linux and versions of OS X prior to Yosemite are believed to be unaffected.

ok so listen — this one does NOT fix ur disk if it's already hit. it just stops poking the bear. 😭 read the paragraph above, don't skip it bestie.

There are no other changes in this release.

🦋 fish 2.1.1 (released September 26, 2014)

IMPORTANT, fr fr: if you are upgrading, stop all running instances of fishd as soon as possible after installing this release; it will be restarted automatically. On most systems, there will be no further action 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 variables work as intended. 💀

Distributors are highly encouraged to call killall fishd, pkill fishd or similar in installation scripts, or to warn their users to do so. 👑

🔒 Security fixes

The fish_config web interface now uses an authentication token to protect requests and only responds to requests from the local machine with this token, preventing a remote code execution attack. (closing CVE-2014-2914). #1438 <https://github.com/fish-shell/fish-shell/issues/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/issues/1437>
fishd uses a secure path for its socket, preventing a local privilege escalation attack (closing CVE-2014-2905). #1436 <https://github.com/fish-shell/fish-shell/issues/1436>
fishd now ignores SIGPIPE, which fixes crashes when you're using tools like GNU Parallel — and honestly those crashes got way more common as a side effect of all the other fishd changes. #1084 & #1690 — https://github.com/fish-shell/fish-shell/issues/1084, 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

okay so this is the good stuff 🫶 When you tab-complete a file, fish goes in stages: first prefix matches (foo matches foobar), then substring matches (ooba matches foobar), and lastly subsequence matches (fbr matches foobar). So like, in a directory with files foo1.txt, foo2.txt, foo3.txt…, you can literally type just the numeric part and hit tab and it fills in the rest. obsessed.

Real talk though: this feature is implemented for files and executables. It is not yet implemented for options (like --foobar), and not yet implemented across path components (like /u/l/b to match /usr/local/bin). someday bestie 💀

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

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 backgrounded. If no job is in the background, it will fail to expand. In particular, fg % can be used to put the most recent background job in the foreground. iconic behaviour fr fr 👑

🔥 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 appended, 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). so you're gonna wait the full 10 seconds bestie, no shortcuts 😭

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 messages. #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 eval'd 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 $status on failure; it is untouched on success. This allows for the following pattern:

if set python_path (which python)
   ...
end

Because set does not modify $status on success, the if branch effectively tests whether which succeeded, and if so, whether the set also succeeded. chef's kiss honestly 👑

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 "slices") #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/issues/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
Ctrl+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 rxvt's 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 installed separately #633 — https://github.com/fish-shell/fish-shell/issues/633
__fish_filter_mime no longer spews #628 — https://github.com/fish-shell/fish-shell/issues/628
The -no-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 it's 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 directory, 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 "appropriate" the closing quote #552 — https://github.com/fish-shell/fish-shell/issues/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 Ctrl+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 user's 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 get their own muted color — lowkey a whole vibe upgrade, tracked in #279 (https://github.com/fish-shell/fish-shell/issues/279)
Wildcards that start with a . (like ls .*) no longer match . and .. — no more surprise directory gremlins, #270 (https://github.com/fish-shell/fish-shell/issues/270)
Recursive wildcards now handle symlink loops — the infinite hallway glitch is fixed, #268 (https://github.com/fish-shell/fish-shell/issues/268)
You can now delete history items from the fish_config web interface — decluttering era, #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 the 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 character 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 — literally the glow-up we deserved
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 — "sometimes" is doing a lot of heavy lifting here but slay, #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 function — #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 "accept autosuggestion" 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 "internalized scripts" feature is disabled for now.
Disabled delayed suspend. This is a strange job-control feature of BSD systems, including OS X. Disabling it frees up Control+Y for other purposes; in particular, for yank, which now works on OS X.
fish_indent is fixed. In particular, the funced and funcsave 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 "555 yellow".

✨ New Features

A history builtin, and associated interactive function that enables deleting history items. Example usage:
- Print all history items beginning with echo: history --prefix echo
- Print all history items containing foo: history --contains foo
- Interactively delete some items containing foo: history --delete --contains foo
Credit to @siteshwar for implementation. Thanks @siteshwar! 🫶

🌈 fishfish Beta r1

📜 Scripting

No changes! All existing fish scripts, config files, completions, etc. from trunk should continue to work. (a miracle, honestly)

🌟 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; there's 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 (set_color cyan) or by specifying RGB hex values (set_color FF3333); fish will pick the closest supported color. Some xterms do not advertise term256 support either in the $TERM or terminfo max_colors field, but nevertheless support it. For that reason, fish will default into using it on any xterm (but it can be disabled with an environment variable).
Web-based configuration page. There is a new function fish_config. This spins up a simple Python web server and opens a browser window to it. From this web page, you can set your shell colors and view your functions, variables, and history; all changes apply immediately to all running shells. Eventually all configuration ought to be supported via this mechanism (but in addition to, not instead of, command line mechanisms).
Man page completions. There is a new function fish_update_completions. This function reads all the man1 files from your manpath, removes the roff formatting, parses them to find the commands and options, and outputs fish completions into ~/.config/fish/completions. It won't 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. We've 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 don't know what halloc is, well, now you have two reasons to be happy. 💀
All the crufty C data structures are entirely gone. array_list_t, priority_queue_t, hash_table_t, string_buffer_t have been removed and replaced by STL equivalents like std::vector, std::map, and std::wstring. A lot of the string handling now uses std::wstring 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 extensible YAML-style syntax. History "merging" (multiple shells writing to the same history file) now works better. There is now a maximum history length of about 250k items (256 * 1024).
The parser has been "instanced," so you can now create more than one.
Total #LoC has shrunk slightly even with the new features. iconic behavior ngl

🔥 Performance

fish now runs syntax highlighting in a background thread, so typing commands is always responsive even on slow filesystems.
echo, test, and pwd are now builtins, which eliminates many forks.
The files in share/functions and share/completions now get 'internalized' 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 depend on these "standard" functions, so changing them is perhaps not a good idea anyways.

Here are some system call counts for launching and then exiting fish with the default configuration, on OS X. The first column is fish trunk, the next column is with our changes, and the last column is bash for comparison. This data was collected via dtrace.

open — before: 9, after: 4, bash: 5
fork — before: 28, after: 14, bash: 0
stat — before: 131, after: 85, bash: 11
lstat — before: 670, after: 0, bash: 0
read — before: 332, after: 80, bash: 4
write — before: 172, after: 149, bash: 0

The large number of forks relative to bash are due to fish's insanely expensive default prompt, which is unchanged in my version. If we switch to a prompt comparable to bash's (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.

We've got some work to do to be as lean as bash, but we're on the right track. 💪

🖥️ Terminal Compatibility

fish writes various control sequences to the terminal. Some must be implemented 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) commands, 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 terminal must ignore it.

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 document, terminfo (TI) codes are included for reference only.

✨ Required Commands ✨

okay bestie, these are the non-negotiables — the sequences your terminal has to understand or fish is gonna have a bad time 💅

\r — TI: n/a — moves the cursor back to the beginning of the line. classic.
\n — TI: cud1 — moves the cursor down one line.
\e[ Ps A — TI: cuu — moves the cursor up Ps columns, or just one column if there's no parameter.
\e[ Ps C — TI: cuf — moves the cursor to the right Ps columns, or one column if there's no parameter.
\x08 — TI: cub1 — moves the cursor one column to the left.
\e[ Ps D — TI: cub — moves the cursor to the left Ps times.
\e[H — TI: cup — sets the cursor position (no parameters means: move to row 1, column 1).
\e[K — TI: el — clears to the end of the line.
\e[J — TI: ed — clears to the end of the screen.
\e[2J — TI: clear — clears the screen. iconique.
\e[0c — TI: (none listed) — requests the Primary Device Attribute. the terminal must respond with a CSI command that starts with the ? parameter byte (so, a sequence starting with \e[?) and has c as its final byte.

🫶 real talk though: if your terminal doesn't implement this, you get a brief pause at startup followed by a warning. for the time being, both of those can be turned off by turning off the query-terminal feature flag <#featureflags>. no cap.

n/a — TI: am — soft wraps text at screen width.
n/a — TI: xenl — printing to the last column does not move the cursor to the next line. verify it yourself by running:

printf %0"$COLUMNS"d 0; sleep 3

🎀 Optional Commands 🎀

these ones are the glow-up extras — nice to have, not mandatory 💖

\t — TI: it — moves the cursor to the next tab stop (at 8 columns). this is mainly relevant if your prompt includes tabs 👀
\e[m — TI: sgr0 — turns off bold/dim/italic/underline/strikethrough/reverse attribute modes and selects default colors. the big reset button, honestly.
\e[1m — TI: bold — enters bold mode.
\e[2m — TI: dim — enters dim mode.
\e[3m — TI: sitm — enters italic mode. fancy ✨
\e[4m — TI: smul — enters underline mode.
\e[4:2m — TI: Su — enters double underline mode.
\e[4:3m — TI: Su — enters curly underline mode.
\e[4:4m — TI: Su — enters dotted underline mode.
\e[4:5m — TI: Su — enters dashed underline mode.
\e[7m — TI: rev — enters reverse video mode (swaps foreground and background colors). iykyk 🌈
\e[9m — terminfo name smxx, and it's giving "enter strikethrough mode" ✨
\e[23m — terminfo ritm, aka exit italic mode. bye bestie italic 💅
\e[24m — terminfo rmul, exits underline mode.
\e[29m — terminfo rmxx, exits strikethrough mode. no more strike-through era 🫶
\e[38;5; Ps m — terminfo setaf, selects foreground color Ps from the 256-color-palette 🎨
\e[48;5; Ps m — terminfo setab, selects background color Ps from the 256-color-palette.
\e[58:5: Ps m (note: colons, not semicolons — literally don't get this wrong) — terminfo Su, selects underline color Ps from the 256-color-palette.
\e[ Ps m — terminfo setaf / setab, selects foreground/background color. This uses a color in the aforementioned 256-color-palette, based on the range that contains the parameter: 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 background 8-15. so like, the range is the whole personality check 💀
\e[38;2; Ps ; Ps ; Ps m — no terminfo name here, it just selects foreground color from 24-bit RGB colors 🌈
\e[48;2; Ps ; Ps ; Ps m — same energy but for the background: selects background color from 24-bit RGB colors.
\e[39m — resets foreground color to the terminal's default. back to factory settings bestie 🎀
\e[49m — resets background color to the terminal's default.
\e[58:2:: Ps : Ps : Ps m (note: colons not semicolons, yes again) — terminfo Su, selects underline color from 24-bit RGB colors.
\e[59m — terminfo Su, resets underline color to the default (which follows the foreground color). iconic inheritance behavior 💜
\e[ Ps S — terminfo indn, scrolls up the content (not the viewport!) by 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 <#status-test-terminal-features> will return 0, which enables the ctrl+l binding to use the scrollback-push <#special-input-functions-scrollback-push> special input function. lowkey a whole chain of events fr fr 🔥
\e[= Ps u, \e[? Ps u — terminfo n/a, enables the kitty keyboard protocol 👑
\e[6n — terminfo n/a, requests a cursor position report. The response must be of the form \e[ Ps ; Ps R where the first parameter is the row number and the second parameter is the column number. Both start at 1. This is used for truncating multiline autosuggestions at the screen's bottom edge, by the scrollback-push <#special-input-functions-scrollback-push> special input function, and inside terminals that implement the OSC 133 click_events feature. so many jobs omg 😭
\e[ \x20 q — terminfo Se, resets cursor style to the terminal's default. This is not used as of today but may be in future, so like, it's on standby 🦋
\e[ Ps \x20 q — terminfo Ss, sets cursor style (DECSCUSR); Ps is 2, 4 or 6 for block, underscore or line shape. pick your fighter ✨
\e[ Ps q — terminfo n/a, requests terminal name and version (XTVERSION). This is only used for temporary workarounds for incompatible terminals — no cap, that's the entire job 🙈
\e[?25h — terminfo cvvis, enables cursor visibility (DECTCEM). look at her, she's back 💖
\e[?1004h — (second column: n/a) — turns focus reporting on. ✨
\e[?1004l — (second column: n/a) — turns focus reporting back off. 💅
\e[?1049h — (second column: n/a) — enables the alternate screen buffer, aka the magic "new screen, who dis" move. 🦋
\e[?1049l — (second column: n/a) — disables the alternate screen buffer and puts you back where you were. 🎀
\e[?2004h — (second column is empty on this one) — enables bracketed paste. 🫶
\e[?2004l — (second column empty too) — disables bracketed paste. 🙈

\e[?2031h — (no second-column value) — enables unsolicited color theme reporting, spec'd over at https://contour-terminal.org/vt-extensions/color-palette-update-notifications/. The way this works: when it's enabled, the terminal should send \e[?997;1n or \e[?997;2n whenever its color theme has changed. That ping is literally what prompts fish to go query for the background color. not me being obsessed with theme telemetry 💜
\e[?2031l — disables unsolicited color theme reporting. bye bestie 👋

\e]0; Pt \e\\ — (second column: ts) — sets the terminal window title (that's OSC 0). Used in fish_title. 👑
\e]1; Pt \e\\ — (second column: ts) — sets the terminal tab title (OSC 1). Used in fish_tab_title. ⭐
\e]7;file:// Pt / Pt \e\\ — (no second-column value) — reports the working directory (OSC 7). And here's the little caveat: since the terminal may be running on a different system than a (remote) shell, the hostname (the first parameter) will not be localhost. keep that in mind fr fr 💀
\e]8;; Pt \e\\ — (no second-column value) — creates a hyperlink (OSC 8), full details at https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda. This one's used in fish's man pages. iconic behavior honestly 🌈

\e]11;?\e\\ — (second column: n/a) — queries the 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, representing red, blue and green components.

What's it for? It populates fish_terminal_color_theme (see #envvar-fish_terminal_color_theme), which is then used to select a theme variant (see #fish-config-theme-files) that's optimized for the terminal's color theme. matching aesthetics?? we love to see it 💖

\e]52;c; Pt \e\\ — (no second-column value) — copy to clipboard (OSC 52). Used by fish_clipboard_copy. paste goblins stay winning 🍓

\e]133;A;click_events=1\e\\ — (no second-column value) — marks the prompt start (OSC 133), with kitty's click_events extension. That extension enables mouse clicks to move the cursor or select pager items — assuming that cursor position reporting is available. (big assumption, but slay) 🔥
\e]133;B\e\\ — (no second-column value) — marks the prompt end (OSC 133). 🎀
\e]133;C;cmdline_url= Pt \e\\ — (no second-column value) — marks the command start (OSC 133), with kitty's cmdline_url extension, whose parameter is the URL-encoded command line. 👑
\e]133;D; Ps \e\\ — (no second-column value) — marks the command end (OSC 133); here Ps is the exit status. so you always know how it went 😭
\eP+q Pt \e\\ — request a 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, like, the same as the request parameter. No switching up on us bestie 💅

fish queries the following string capabilities:

indn — the response's second parameter is ignored. We literally do not care about it.
query-os-name (for status terminal-os) — terminals running on Unix should respond with the hex encoding of $(uname -s) as second parameter. That's the whole vibe. 🐧

🖥️ DCS commands and GNU screen

Okay so DCS parsing is optional because fish temporarily switches to the alternate screen before printing any DCS commands. Nice, right? 💖

But — and here's the plot twist 😭 — GNU screen neither allows turning on the alternate screen buffer by default, nor treats DCS commands in a compatible way. So fish's initial prompt may end up garbled by a DCS payload like +q696e646e. Not cute. Not slay. Straight-up cursed.

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

Bestie, that workaround function literally erases itself after it runs once. One-and-done icon behavior. 🎀

🔤 Unicode Codepoints

By default, fish outputs the following non-ASCII characters:

× ► ¶ ⏎ • ● … μ ’ ‘ “ ”

as well as control pictures (U+2400 through U+241F), and locale-specific ones in translated messages. All the pretty glyphs, no cap ✨

🌈 Contributing To fish

This document tells you how you can contribute to fish. Pull up a chair, bestie, we're getting you in the group chat 🫶

fish is free and open source software, distributed under the terms of the GPLv2.

Contributions are welcome, and there are so 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 something — this document will tell you how. Pick your fighter 💅

📬 Mailing List

Send patches to the public mailing list: ~krobelus/fish-shell@lists.sr.ht. Archives are available at https://lists.sr.ht/~krobelus/fish-shell/. Old-school, but it works, and honestly? Iconic.

🐙 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. Boom, you're in 🎉

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 contribute 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 judgement! 💖

Once you have your changes, open a pull request on https://github.com/fish-shell/fish-shell/pulls. Go off, queen 👑

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

Two bullets, infinite wisdom. Lowkey the whole philosophy.

🧾 Commit History

We use a linear, recipe-style history (https://www.bitsnbites.eu/git-history-work-log-vs-recipe/). 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 request on the latest version of master is also welcome, especially if it resolves conflicts.

If you're using Git, consider using jj (https://www.jj-vcs.dev/) to make this easier. It's giving future-of-version-control energy ⭐

If a commit should close an issue, add a Fixes #<issue-number> line at the end of the commit description.

Rewriting history is encouraged here, which is honestly the most liberating thing about this whole repo. Clean history or nothing, periodt 💅

🧩 Contributing completions

Completion scripts are the most common contribution to fish, and they are very welcome. This is the starter quest, bestie 🌸

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

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)
If it uses a common unix tool, use POSIX-compatible invocations — ideally it would work on GNU/Linux, macOS, the BSDs and other systems
Option and argument descriptions should be kept short. The shorter the description, the more likely it is that fish can use more columns.
Function names should start with __fish, and functions should be kept in the completion file unless they're used elsewhere.
Run fish_indent on your script.
Try not to use minor convenience features right after they are available in fish — we do try to keep completion scripts backportable. If something 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. One file per command, no bundling 🎀

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. Vibe check your own docs, bestie 👀✨

🎨 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

All fish scripts, such as those in the share/functions and tests directories, should be formatted using the fish_indent command.
Function names should be in all lowercase with words separated by underscores. Private functions should begin with an underscore. The first word should be fish if the function is unique to fish.
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.

Three rules, all bangers. Number 3 is literally the "don't step on the user's toes" rule and it eats 💜

⌨️ 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/ftplugin/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 indent-tabs-mode nil) for it (via a hook or in use-packages ":init" 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)))

okay that's the snippet, bestie 💖 moving on 💅

🦀 Minimum Supported Rust Version (MSRV) Policy 🦀

We support at least the version of rustc available in Debian Stable. That's the whole policy — no cap, that's it ✨

🧪 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 don't run the tests on your machine, they will still be run via GitHub Actions — so like, the CI will catch you 🙈

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 regressions in the future (i.e., we don't reintroduce the bug). future-you will literally thank present-you, fr fr 🫶

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/ridiculousfish/littlecheck> and test noninteractive (script) behavior, except for tests/checks/tmux-* which test interactive scenarios.
tests/pexpects tests interactive scenarios using pexpect <https://pexpect.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-explanatory. It's a fish script with the expected output in # CHECK: or # CHECKERR: (for stderr) comments. If your littlecheck test has a specific dependency, 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 interactivity. 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 directory in them. iconic behavior honestly 👑

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). weird little helper guy, we love him 💜

🌸 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 debug build 🐛

To run all tests and linters, use:

cargo xtask check

slay, one command to rule them all ✨

🌍 Contributing Translations 🌍

fish can localize messages present in its Rust source code, as well as messages in the various fish scripts present in this repository. The latter include a large amount of automatically identified messages, originating for example from fish function descriptions. When translating, prioritize the messages from the Rust source code.

fish uses two different localization systems: GNU gettext <https://www.gnu.org/software/gettext/> and Fluent <https://projectfluent.org/>. The former is used for all messages from fish scripts. For messages from the Rust source code, we are in the process of replacing gettext with Fluent. At the moment, both are used side-by-side, with some messages localized with gettext and the others with Fluent. it's giving "two eras, one queen" 💅

We use custom tools for extracting messages from source files and for gettext localization at runtime. This means that we do not have a runtime dependency on the gettext library. It also means that some of gettext's features are not supported, such as message context and plurals. We expect all files to be UTF-8-encoded.

Translation sources for gettext are stored in the localization/po directory and named ll_CC.po, whereas Fluent uses the localization/fluent directory and names of the shape ll_CC.ftl, 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 for gettext and pt_BR.ftl for Fluent, indicating Brazilian Portuguese. These are the files you will interact with when adding translations 🎀

In some cases, we also use language identifiers without a county code, i.e. ll.po/ll.ftl. Which variant is chosen involves various trade-offs for fallback behavior. If you want to add a new language or language variant, feel free to ask about this. Generally, if people who understand any variant of the language are expected to understand the version you add and there are no existing translations for another variant of the language, it probably makes sense to omit the country code, otherwise to use it for all variants of the language.

🆕 Adding translations for a new language 🆕

Creating new translations for gettext requires the gettext tools. More specifically, you will need msguniq, msgmerge, and msgmerge for creating translations for a new language. To create a PO file for a new language ll_CC, run:

cargo xtask gettext new ll_CC

This will create a new PO file in localization/po/ containing all messages available for translation. If the file already exists, it will be updated 👍

For Fluent, it is sufficient to create a new, empty file with the language-appropriate name in localization/fluent.

After modifying a translation file, you can recompile fish, and it will integrate the modifications you made. This requires that the msgfmt utility is installed (comes as part of gettext). For messages localized with Fluent, recompiling fish is not necessary when you use a debug build. Then, restarting fish is sufficient for seeing updated translations. It is important that the localize-messages 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

Alternatively, you can also use the built-in status language command, e.g.:

status language set pt_BR

Use

status language list-available

to see a list of the available language identifiers. This might also be helpful for checking that your new translations are recognized as expected. Note that using environment variables enables fallback behavior, e.g. if you specify LANG=de_DE.utf8 and we do not have a de_DE catalog but a de catalog, you will see messages from the latter. With status language, only exact matches are supported, giving you more control over the fallback order. If status language is used, it overrides the environment variable configuration.

For more options regarding how to choose languages via environment variables, see the corresponding gettext documentation <https://www.gnu.org/software/gettext/manual/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 defined using the LANGUAGE variable, e.g.:

set LANGUAGE pt_BR de_DE

or using:

status language set pt_BR de

to try to translate messages to Portuguese, if that fails try German, and if that fails too you will see the default English version. a whole little fallback chain, we love a backup plan 💖

✏️ Modifying existing translations ✏️

If you want to work on translations for a language which already has translations, it is sufficient to edit the existing files. No other changes are necessary.

After recompiling fish, you should be able to see your translations in action. See the previous section for details. go off 👑

📝 Editing PO files 📝

Many tools are available for editing translation files, including command-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 English string to translate. The second line (msgstr) is where your translation 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 must 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 mismatched placeholders - otherwise fish would crash at runtime when the string is about to be used. 😭 please don't let fish crash, bestie

Be cautious about blindly updating an existing translation file. msgid strings should never be updated manually, only by running the appropriate script.

🦋 Editing FTL files 🦋

To get familiar with Fluent's FTL format, you can read Fluent's guide <https://projectfluent.org/fluent/guide/>.

The core principle is that each message has an ID. This ID is specified in the source code. At runtime, Fluent checks FTL files according to the user's language settings to try to map the ID to a localized message. All messages are localized into English because the source code only contains IDs, not proper messages. Check localization/fluent/en.ftl to see which IDs are in use and what the corresponding messages are.

Some messages receive arguments, called variables in Fluent. In Fluent, each variable has a name, which allows reordering them, so they can appear in the order which makes most sense for the language. The general format of a variable in an FTL file is { $variable_name }.

The Fluent ecosystem is not as mature as gettext, meaning there is less available tooling. Therefore, we provide some of our own tools. Running cargo xtask fluent provides an overview.

For translators, the following can be useful:

cargo xtask fluent format

to make FTL files conform to our expected format,

cargo xtask fluent show-missing

to show which message IDs do not have a translation yet, and

cargo xtask fluent check

to run checks on the FTL files, which can catch some mistakes. Each of these commands takes optional path arguments, so if you are working on a certain file like pt_BR.ftl, you might want to use

cargo xtask fluent check localization/fluent/pt_BR.ftl

from the repository root directory, or, if you are in the localization/fluent directory,

cargo xtask fluent check pt_BR.ftl

okay so if you want formatting in your editor, bestie,

cargo --quiet xtask fluent format -

might be useful, which reads FTL text from stdin and writes a formatted version to stdout, or a copy of stdin if formatting failed. Instead of invoking Cargo each time, you could also invoke the xtask binary if it exists.

A simple format-on-write setup in Vim:

function FormatFTL()
    let cursor = getpos('.')
    :%!cargo --quiet xtask fluent format -
    call setpos('.', cursor)
endfunction

augroup ftl
    autocmd!
    autocmd! BufWritePre *.ftl :call FormatFTL()
augroup END

or equivalently in Lua for NeoVim:

local augroup_ftl = vim.api.nvim_create_augroup("ftl", { clear = true })
vim.api.nvim_create_autocmd("BufWritePre", {
    group = augroup_ftl,
    pattern = "*.ftl",
    callback = function()
        local cursor = vim.fn.getpos(".")
        vim.cmd("%!cargo --quiet xtask fluent format -")
        vim.fn.setpos(".", cursor)
    end,
})

There is also a Vim plugin for syntax highlighting at https://github.com/projectfluent/fluent.vim 🦋

🛠️ Modifications to strings in source files (gettext-only) 🛠️

If a string changes in the sources, the old translations will no longer work. If you add/remove/change a translatable string in a source file, run cargo xtask gettext update to propagate this to all translation files (localization/po/*.po). This is only relevant for developers modifying the source files of fish or fish scripts. Note translations for messages which are no longer present in the sources will be deleted from the PO files. If the source string changed in a way which should not affect translations, consider updating the msgid in the PO files such that translations are preserved.

🌸 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 localize! macro for Fluent localization, e.g.:

localize!(
    "some-message-id" = "English version of the message. Must be a valid Fluent message definition. Example variables: { $var1 }, { $var2 }",
    var1 = "some string",
    var2 = 42,
);

where the first key-value pair is the message's Fluent ID and the English version of the message. The remaining key-value pairs specify Fluent variables and their values. These must match the variables used in the message definition.

For changing message IDs or associated variable names across all FTL files, the

cargo xtask fluent rename

command can be helpful. The definitions in the Rust sources are the source of truth for the English version of the messages. Our tooling automatically generates a corresponding en.po file from these definitions, but that file is fully auto-generated and manual modifications to it are not supported. The en.po file exists to allow using Fluent tooling which expects such a file, and to be able to detect changes to the definitions in the Rust sources. Note that changes to the message definitions have consequences for translations. Our tooling automatically detects such changes. In some cases, they can be resolved automatically, e.g. when a message ID no longer exists, the translations will be deleted. If no automatic resolution is possible, annotations will be added to the affected translations, indicating that they need developer attention. As long as such annotations are present, our checks will not pass. To resolve them, use cargo xtask fluent resolve-outdated, or, for languages into which you can translate, update the translation and remove the annotation manually.

Legacy gettext localization uses the wgettext! or wgettext_fmt! macros. New code should use Fluent instead.

streams.out.appendln(&wgettext_fmt!("%s: There are no jobs", argv[0]));

For explicit localization in fish scripts, all messages 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 parentheses or before the closing parentheses.

📦 Updating Dependencies 📦

To update dependencies, run build_tools/update-dependencies.sh. This currently 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 release number (e.g., 2.6.0).

🤖 AI Contributions Policy 🤖

We do not accept contributions created with generative artificial intelligence tools. Do not submit pull requests, GitHub issues or comments, artwork, where the output has been created by or edited with one of these tools.

This includes products such as GitHub Copilot, Zed AI, Cursor.dev's AI features, other coding assistants, and ChatGPT.

⚖️ License ⚖️

💖 License for fish 💖

fish includes other code licensed under the GNU General Public License, version 2, including GNU printf.

The GNU General Public License agreement follows.

GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software - to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this 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 restrictions 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 recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program 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 covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

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 recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

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 including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (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.)

Okay so those two bullets are the whole vibe check of "if you ship a modified version, bestie, you gotta do it right." ✨

These requirements apply to the modified work as a whole. If identifiable 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 collective 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. like, putting two things on the same CD does not a derivative work make, bestie 💿

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 physically 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 interchange; or,
Accompany it with the information you received as to the offer to distribute 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 Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed 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 component itself accompanies the executable. 🧚 like yeah, you don't have to ship the entire kernel, bestie, that's not the assignment

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 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 remain in full compliance. 💀 no cap, step out of bounds and your rights poof — but everyone downstream who's behaving keeps theirs

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the 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 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 practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to 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 conditions 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 exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. 💌

NO WARRANTY 🚨

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO 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, EITHER 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.

bestie it is literally "AS IS" — all caps, no take-backsies 😭 the risk is yours, the vibes are free

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 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

🐍 License for 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

okay bestie, deep breath — we are now in the ✨legal era✨ of this manpage and I need you to stay with me 😭 because these licenses are literally the reason fish exists at all and they are not optional reading. No skipping. Periodt. 💅

The first one is the Python Software Foundation's agreement — yes, the Python one, we'll get to why in a sec. Here it is, word for word, because legal text is the one place you never paraphrase 🫶

1. This LICENSE AGREEMENT is between the Python Software Foundation
   ("PSF"), and the Individual or Organization ("Licensee") accessing and
   otherwise using this software ("Python") in source or binary form and
   its associated documentation.

2. Subject to the terms and conditions of this License Agreement, PSF
   hereby grants Licensee a nonexclusive, royalty-free, world-wide license
   to reproduce, analyze, test, perform and/or display publicly, prepare
   derivative works, distribute, and otherwise use Python alone or in any
   derivative version, provided, however, that PSF's License Agreement and
   PSF's notice of copyright, i.e., "Copyright (c) 2001, 2002, 2003, 2004,
   2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016,
   2017 Python Software Foundation; All Rights Reserved" are retained in
   Python alone or in any derivative version prepared by Licensee.

3. In the event Licensee prepares a derivative work that is based on or
   incorporates Python or any part thereof, and wants to make the
   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
   EXAMPLE, 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
   MODIFYING, 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
   relationship 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.

see? not so scary. it's giving "standard permissive license but make it official" ✨

🎀 MIT License

okay THIS one is the fun one because it's a whole little squad of borrowed code and every single member gets a shoutout 💖

fish ships a copy of Alpine.js, copyright 2019-2021 Caleb Porzio and contributors, licensed under the MIT License.
It also uses FindRust.cmake, from the Corrosion project, copyright 2018 Andrew Gaspar, licensed under the MIT license.
It also includes the Dracula theme, copyright 2018 Dracula Team, and the Nord theme, copyright 2016-present Sven Greb. Both of these themes are also used under the MIT license.

And then there's this icon 👑: fish contains code derived from musl-libc (https://www.musl-libc.org), which is copyright 2006-2020 Rich Felker, et al., used to implement printf. That code is used under the terms of the MIT license.

The MIT license follows, and here it is in full:

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 Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
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 LIABILITY, 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

The GNU Library General Public License agreement follows. Buckle up, it's long, but every word matters:

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 preamble is literally the "why are we like this" section and honestly it ate 🔥

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
intended 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
restrictions 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
library, 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
recipients 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 individually 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 license, the GNU Library General Public License, applies to certain
designated 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.

⚠️ bestie this is a genuine warning from the license itself — do not assume this license is the same as the ordinary GPL. Read it in full. I'm so serious. 🙈

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 derivative of the original library, and the ordinary
General Public License treats it as such.

Because of this blurred distinction, using the ordinary General Public
License for libraries did not effectively promote software sharing,
because most developers did not use the libraries.  We concluded that
weaker conditions 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 developers 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 derived from the library, while the latter only
works together with the library.

Note that it is possible for a library to be covered by the ordinary
General Public License rather than by this special one.

^ that distinction is the whole main character of this license, iykyk 🦋

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 language.  (Hereinafter, translation is included without
limitation in the term "modification".)

and that's where we pause, bestie — section 0 is still going, so don't you dare close the tab 💅✨

Okay so, "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 definition files, plus the scripts used to control compilation and installation of the library. All of it, bestie, no vibe-based skipping 💅

Activities other than copying, distribution and modification are not covered 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 (independent 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. iykyk 🌸

1. verbatim copies, go off 👑

You may copy and distribute verbatim copies of the Library's complete 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
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. modified versions, the whole glow-up ✨

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 modifications 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. (Yes, a date. Put it in. 🗓️)
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 application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. 🙏

For example, a function in a library to compute square roots has a purpose 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 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 Library, 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.

So like, it is not the intent of this section to claim rights or contest your rights to work written entirely by you — 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. the upgrade-to-GPL option 🔥

You may opt to apply the terms of the ordinary GNU General Public License 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 refer 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 General 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. 💀 No take-backs!

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. object code & executables 📦

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 software 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. "work that uses the Library" 🦋

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 — and this is the plot twist 😭 — linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable 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 Library, 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 layouts and accessors
small macros and small inline functions (ten lines or less in length)

…then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing 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. the exception clause, main character energy 👑

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 🛠️
reverse engineering for debugging such modifications 🔍

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 displays copyright notices, you must include the copyright notice for the Library 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 machine-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 distribution. 💸
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 executable from it. However, as a special exception, the source code distributed 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 component 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 Library together in an executable that you distribute. 😭 No cap, that's just how it is.

7. combined libraries, the group project 🎀

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 ✅
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. Ok so real talk — you may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. And if you try to copy, modify, sublicense, link with, or distribute the Library any other way? That attempt is void, and it will automatically terminate your rights under this License. 💀 The one soft spot: parties who have received copies, or rights, from you under this License will not have their licenses terminated, as long as those parties remain in full compliance. 🫶

9. Fun fact bestie: you're not actually required to accept this License, since you haven't signed it. ✍️ But — and this is the big but — nothing else grants you permission to modify or distribute the Library or its derivative works. Those actions are prohibited by law if you don't accept this License. So by modifying or distributing the Library (or any work based on the Library), you're indicating your acceptance of this License to do so, plus all its terms and conditions for copying, distributing or modifying the Library or works based on it. It's giving "by entering this venue you consent to being filmed" but for software. 🙈

10. Every time you redistribute the Library (or any work based on the Library), 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. And you may not impose any further restrictions on the recipients' exercise of the rights granted herein. Not your job to police it either — you are not responsible for enforcing compliance by third parties to this License. 🕊️

11. Okay this one's chunky, stay with me. If — as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues) — conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. Nope. If you can't distribute in a way that satisfies 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 redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. Uncomfy but factual.

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

And just so we're clear: 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 practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it's up to the author/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. iykyk.

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

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 Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. Pick your fighter. 🥊

14. Wanna incorporate parts of the Library into other free programs 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 — they sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. 💖

🫣 NO WARRANTY 🫣

Bestie. Read this part twice. It's the legal equivalent of "no refunds, no vibes guaranteed." 😭

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 PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER 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 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 REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING 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 POSSIBILITY OF SUCH DAMAGES. 💀🙏

💅 Author

fish-shell developers — yes, that's the whole vibe. Iconic. 👑

🎀 Copyright

fish-shell developers — hold that, bestie. 🫶

And that's the whole page, start to finish! 🦋 This last bit came from fish-shell developers, version 4.9, dated Sep 08, 2026 — that's the source/version line and the date straight off the footer, and FISH-DOC(1) is the page name if you ever need to cite it. Go forth and man with confidence, bestie. 💖✨

📦 where this page comes from

arch rolling: fish 4.9.3-1 · GPL-2.0-only AND BSD-3-Clause AND ISC AND MIT AND PSF-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

FISH-DOC(1)

🌸 WHERE TO GO? 🌸

🎀 SETUP 🎀

🦋 Installation 🦋

🦋 Starting and Exiting 🦋

🦋 Default Shell 🦋

🦋 Uninstalling 🦋

🦋 Shebang Line 🦋

💜 CONFIGURATION 💜

🧚 Examples: 🧚

⭐ RESOURCES ⭐

🔥 OTHER HELP PAGES 🔥

🌈 Frequently asked questions 🌈

💀 What is the equivalent to this thing from bash (or other shells)?

💀 How do I set or clear an environment variable?

💀 How do I check whether a variable is defined?

💀 How do I check whether a variable is not empty?

💀 Why doesn't set -Ux (exported universal variables) seem to work?

💀 How do I run a command every login? What's fish's equivalent to .bashrc or .profile?

💀 How do I set my prompt?

Why does my prompt show a [I]?

How do I customize my syntax highlighting colors?

How do I change the greeting message?

How do I run a command from history?

Why doesn't history substitution ("!$" etc.) work?

How do I run a subcommand? The backtick doesn't work!

My command (pkg-config) gives its output as a single long string?

How do I get the exit status of a command?

My command prints "No matches for wildcard" but works in bash

Why won't SSH/SCP/rsync connect properly when fish is my login shell?

I'm getting weird graphical glitches (a staircase effect, ghost characters, cursor in the wrong position,...)?

fish does not work in a specific terminal

Uninstalling fish

✨ Interactive use ✨

Help

Autosuggestions

Tab Completion

Syntax highlighting

Syntax highlighting variables

🎨 Pager color variables

⌨️ Abbreviations

🪞 Programmable prompt

👋 Configurable greeting

🏷️ Programmable title

🎀 Command line editor

🌸 Shared bindings

💜 Emacs mode commands

🦋 Vi mode commands

🎮 Command mode 🎮

✍️ Insert mode ✍️

👀 Visual mode 👀

🎀 Custom bindings 🎀

🔑 Key sequences 🔑

💀 Copy and paste (Kill Ring) 💀

🧵 Multiline editing 🧵

🕰️ Searchable command history 🕰️

Private mode 🕵️‍♀️

Navigating directories 🧭

Directory history 📜

Directory stack 🥞

✨ The fish language ✨

Syntax overview 🧠

Terminology 📖

Quotes 🎀

Escaping Characters 🔠

🔀 Input/Output Redirection

🔗 Piping

🧩 Combining pipes and redirections

🎛️ Job control

🧚 Functions

🏷️ Defining aliases

Autoloading functions 🦋

Comments 💬

Conditions 🎀

The if statement

The switch statement 🔀

Combiners (and / or / && / ||) 🔥

Loops and blocks 🌈

Parameter expansion ✨

🌸 Wildcards ("Globbing") 🌸

💀 Why doesn't `set -Ux` (exported universal variables) seem to work?

💀 How do I run a command every login? What's fish's equivalent to `.bashrc` or `.profile`?

🌸 `_` — call fish's translations

🎀 `abbr` — manage fish abbreviations