WHERE TO GO?

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:

> fish

> exit

Default Shell

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

The simplest method is to set your terminal emulator (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:

To change your login shell to fish:

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

> chsh -s "$(command -v fish)"

To change it back to another shell, substitute fish with bash, tcsh or zsh as appropriate in the above command.

Uninstalling

For uninstalling fish: see FAQ: Uninstalling fish <#faq-uninstalling>.

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.

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

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.

Examples:

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

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

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

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

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

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

See Fish for bash users <>

How do I set or clear an environment variable?

Use the set <> command:

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

Since fish 3.1 you can set an environment variable for one command using the key=value some command syntax, like in other shells. The two lines 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.

How do I check whether a variable is defined?

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

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

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

How do I check whether a variable is not empty?

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

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

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

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

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

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

A global variable of the same name already exists.

Environment variables such as EDITOR or TZ can be set universally using set -Ux. However, if there is an environment variable already set 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.

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.

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 normal
    echo -n ' > '
end

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

Or you can use fish_config from the commandline:

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

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

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

This also applies to fish_right_prompt <> and fish_mode_prompt <>.

Why does my prompt show a [I]?

That's the fish_mode_prompt <>. It is displayed by default when you've 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.

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

How do I customize my syntax highlighting colors?

Use the web configuration tool, fish_config <>, or alter the fish_color family of environment variables <#variables-color>.

You can also use fish_config on the commandline, like:

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

How do I change the greeting message?

Change the value of the variable fish_greeting or create a fish_greeting <> function. For example, to remove the greeting use:

set -U fish_greeting

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

set -g fish_greeting

in config.fish <#configuration>.

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.

Additional default key bindings include ctrl-p (up) and ctrl-n (down). See Searchable command history <#history-search> for more information.

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

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

As a special case, most of the time history substitution is used as sudo !!. In that case 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:

See documentation <#editor> for more details about line editing in fish.

That being said, you can use Abbreviations <#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 <#configuration> to keep it.

How do I run a subcommand? The backtick doesn't work!

fish uses parentheses for subcommands. For example:

for i in (ls)
    echo $i
end

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

My command (pkg-config) gives its output as a single long string?

Unlike other shells, fish splits command substitutions only on newlines, not spaces or tabs or the characters in $IFS.

That means if you run

count (printf '%s ' a b c)

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

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

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

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

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

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

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

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

How do I get the exit status of a command?

Use the $status variable. This replaces the $? variable used in other shells.

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

If you are only interested in success or failure, you can run the command directly as the if-condition:

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

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

somecommand
or someothercommand

See the Conditions <#syntax-conditional> and the documentation for test <> and if <> for more information.

My command prints "No matches for wildcard" but works in bash

In short: quote <#quotes> or escape <#escapes> the wildcard:

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

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

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

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

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

That means that commands like the above

scp user@ip:/dir/string-*

or

apt install postgres-*

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

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

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

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

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

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

Why won't SSH/SCP/rsync connect properly when fish is my login shell?

This problem may show up as messages like "Received message too long", "open terminal failed: not a terminal", "Bad packet length", or "Connection refused" with strange output in ssh_exchange_identification messages in the debug log.

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

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

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

if status is-interactive
  ...
end

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

I'm getting weird graphical glitches (a staircase effect, ghost characters, cursor in the wrong position,...)?

In a terminal, the application running inside it and the terminal 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:

This also means that a few things are unsupportable:

fish does not work in a specific terminal

The terminal might not meet all of fish's requirements <>. Please report this to your terminal's and to fish's issue tracker.

Uninstalling fish

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

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

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

Interactive use

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

Fish is used by giving commands in the fish language, see The Fish Language <> for information on that.

Help

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

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

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

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

Autosuggestions

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

To accept the autosuggestion (replacing the command line contents), press right (→) or ctrl-f. To accept the first suggested word, press alt-right (→) or alt-f. If the autosuggestion is not what you want, ignore it: it won't execute unless you accept it.

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

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

set -g fish_autosuggestion_enabled 0

Tab Completion

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

The pager can be navigated with the arrow keys, pageup / pagedown, tab or shift-tab. Pressing ctrl-s (the pager-toggle-search binding - / in vi mode) opens up a search menu that you can use to filter the list.

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

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

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 <#syntax-function-autoloading>. The difference is the $fish_complete_path list <#variables-lists> 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.

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:

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 in the terminal.

For example, to disable nearly all coloring:

fish_config theme choose None

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

fish_config theme show

Syntax highlighting variables

The colors used by fish for syntax highlighting can be configured by changing the values of various variables. The value of these variables can be one of the colors accepted by the set_color <> command. Options accepted by set_color like --background=, --bold, --dim, --italics, --reverse, --underline and --underline-color= are also accepted.

Example: to make errors highlighted and red, use:

set fish_color_error red --bold

The following variables are available to change the highlighting colors in fish:

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

Pager color variables

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

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

set fish_pager_color_background --background=white

To have black text on alternating white and gray backgrounds:

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

Variables affecting the pager colors:

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

Abbreviations

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

abbr -a gco git checkout

After entering gco and pressing space or enter, a gco in command position will turn into git checkout in the command line. If you want to use a literal gco sometimes, use ctrl-space [1].

Abbreviations are a lot more powerful than just replacing literal strings. For example you can make going up a number of directories easier with this:

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

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

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

[1]

Any binding that executes the expand-abbr or execute bind function <> will expand abbreviations. By default ctrl-space is bound to just inserting a space.

Programmable prompt

When it is fish's turn to ask for input (like after it started or the command ended), it will show a prompt. Often this looks something like:

you@hostname ~>

This prompt is determined by running the fish_prompt <> and fish_right_prompt <> functions.

The output of the former is displayed on the left and the latter's output on the right side of the terminal. For vi mode, the output of fish_mode_prompt <> will be prepended on the left.

If fish_transient_prompt <#envvar-fish_transient_prompt> is set to 1, fish will redraw the prompt with a --final-rendering argument before running a commandline, allowing you to change it before pushing it to the scrollback.

Fish ships with a few prompts which you can see with fish_config <>. If you run just fish_config it will open a web interface [2] where you'll be shown the prompts and can pick which one you want. fish_config prompt show will show you the prompts right in your terminal.

For example fish_config prompt choose disco will temporarily select the "disco" prompt. If you like it and decide to keep it, run fish_config prompt save.

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

[2]

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

Configurable greeting

When it is started interactively, fish tries to run the fish_greeting <> 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 <#variables-universal>:

set -U fish_greeting

or you can set it globally <#variables-scope> in config.fish <#configuration>:

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 <#syntax-function-autoloading>. You can also use funced <> and funcsave <> to edit it easily.

Programmable title

Most terminals allow setting the text displayed in the titlebar of the terminal window. Fish does this by running the fish_title <> function. It is executed before and after a command and the output is used as a titlebar message.

The status current-command <> builtin will always return the name of the job to be put into the foreground (or fish if control is returning to the shell) when the fish_title <> function is called. The first argument will 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 is fish) and the current working directory. All of this is shortened to not make the tab too wide.

Examples:

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

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

Command line editor

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

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

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

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

Shared bindings

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

Emacs mode commands

To enable emacs mode, use fish_default_key_bindings <>. This is also the default.

You can change these key bindings using the bind <> builtin.

Vi mode commands

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

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

function fish_user_key_bindings
    # Execute this once per mode that emacs bindings should be used in
    fish_default_key_bindings -M insert
    # Then execute the vi-bindings so they take precedence when there's a conflict.
    # Without --no-erase fish_vi_key_bindings will default to
    # resetting all bindings.
    # The argument specifies the initial mode (insert, "default" or visual).
    fish_vi_key_bindings --no-erase insert
end

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

When a binding switches the mode, it will repaint the mode-prompt if it exists, and the rest of the prompt only if it doesn't. So if you want a mode-indicator in your fish_prompt, you need to erase fish_mode_prompt e.g. by adding an empty file at ~/.config/fish/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. The following snippet can be used to manually configure cursors after enabling vi mode:

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

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

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

If the cursor shape does not appear to be changing after setting the above variables, it's likely your terminal emulator does not support the capabilities necessary to do this.

Command mode

Command mode is also known as normal mode.

Insert mode

Visual 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 <#configuration> 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.

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

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

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 enable it, either set $fish_private_mode to a non-empty value, or launch with fish --private (or fish -P for short).

If you launch fish with -P, it both hides old history and prevents writing history to disk. This is useful to avoid leaking personal information (e.g. for screencasts) or when dealing with sensitive information.

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

Navigating directories

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

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

Directory history

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

Several commands are provided to interact with this directory history:

Directory stack

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

The fish language

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

For interactive features see Interactive use <>.

Syntax overview

Shells like fish are used by giving them commands. A command is executed by writing the name of the command followed by any arguments. For example:

echo hello world

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

Everything in fish is done with commands. There are commands for repeating other commands, commands for assigning variables, commands for treating a group of commands as a single command, etc. All of these commands follow the same basic syntax.

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

Here is a list of some useful commands:

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.

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:

Quotes

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

rm "my file.txt"

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

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

Between single quotes, fish performs no expansions. Between double quotes, fish only performs variable expansion and command substitution in the $(command). No other kind of expansion (including brace expansion or 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.

More examples:

grep 'enabled)$' foo.txt

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

apt install "postgres-*"

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

Escaping Characters

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

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.

The special characters and their escape sequences are:

As a special case, \ immediately followed by a literal new line is a "continuation" and tells fish to ignore the line break and resume input at the start of the next line (without introducing any whitespace or terminating a token).

Input/Output Redirection

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

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

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

DESTINATION can be one of the following:

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

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

File descriptors cannot be used with a <? input redirection, only a regular < one.

For example:

# Write `foo`'s standard error (file descriptor 2)
# to a file called "output.stderr":
foo 2> output.stderr
# if $num doesn't contain a number,
# this test will be false and print an error,
# so by ignoring the error we can be sure that we're dealing
# with a number in the "if" block:
if test "$num" -gt 2 2>/dev/null
    # do things with $num as a number greater than 2
else
    # do things if $num is <= 2 or not a number
end
# Save `make`s output in a file:
make &>/log
# Redirections stack and can be used with blocks:
begin
    echo stdout
    echo stderr >&2 # <- this goes to stderr!
end >/dev/null # ignore stdout, so this prints "stderr"
# print all lines that include "foo" from myfile, or nothing if it doesn't exist.
string match '*foo*' <?myfile

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

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

Piping

Another way to redirect streams is a pipe. A pipe connects streams with each other. Usually the standard output of one command is connected with the standard input of another. This is done by separating commands with the pipe character |. For example:

cat foo.txt | head

The command cat foo.txt sends the contents of foo.txt to stdout. This output is provided as input for the head program, which prints the first 10 lines of its input.

It is possible to pipe a different output file descriptor by prepending its FD number and the output redirect symbol to the pipe. For example:

make fish 2>| less

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

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

[2]

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

Combining pipes and redirections

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

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

Consider this helper function:

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

Now let's see a few cases:

# Redirect both stderr and stdout to less
print 2>&1 | less
# or
print &| less
# Show the "out" on stderr, silence the "err"
print >&2 2>/dev/null
# Silence both
print >/dev/null 2>&1

Job control

When you start a job in fish, fish itself will pause, and give control of the terminal to the program it just started. Sometimes, you want to continue using the commandline, and have the job run in the background. To create a background job, append an & (ampersand) to your command. This will tell fish to run the job in the background. Background jobs are very useful when running programs that have a graphical user 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 back at the fish commandline, you can start other programs and do anything you want. If you then want you can go back to the suspended command by using the fg <> (foreground) command.

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

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

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

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

Functions

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

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

function ll
    ls -l $argv
end

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

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

This is a kind of function known as an alias.

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

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

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

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

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

Defining aliases

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

To easily create a function of this form, you can use the alias <> command. Unlike other shells, this just makes functions - fish has no separate concept of an "alias", we just use the word for a simple wrapping function like this. alias <> immediately creates a function. Consider using alias --save or funcsave <> to save the created function into an autoload file instead of recreating the alias each time.

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

Autoloading functions

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

When fish needs to load a function, it searches through any directories in the list variable $fish_function_path for a file with a name consisting of the name of the function plus the suffix .fish and loads the first it finds.

For example if you try to execute something called banana, fish will go through all directories in $fish_function_path looking for a file called banana.fish and load the first one it finds.

By default $fish_function_path contains the following:

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

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

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

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

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

Comments

Anything after a # until the end of the line is a comment. That means it's purely for the reader's benefit, fish ignores it.

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

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

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

Comments can also appear after a line like so:

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

Conditions

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

The if statement

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

Like other shells, but unlike typical programming languages you might know, the condition here is a command. Fish runs it, and if it returns a true exit status (that's 0), the if-block is run. For example:

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

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

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

A more complicated example with a command substitution:

if test "$(uname)" = Linux
    echo I like penguins
end

Because test can be used for many different tests, it is important to quote variables and command substitutions. If the $(uname) was not quoted, and uname printed nothing it would run test = Linux, which is an error.

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

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

The not <> keyword can be used to invert the status:

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

Other things commonly used in if-conditions:

The switch statement

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

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

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

Combiners (and / or / && / ||)

For simple checks, you can use combiners. and <> or && run the second 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.

Compare:

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

and:

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

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

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

if command -sq foo; and foo

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

Combiners execute step-by-step, so it isn't recommended to build longer chains of them because they might do something you don't want. Consider:

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

This will execute return 1 also if the test succeeded. This is because fish runs test -e /etc/my.config, sets $status to 0, then skips the echo, keeps $status at 0, and then executes the return 1 because $status is still 0.

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

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

Loops and blocks

Like most programming language, fish also has the familiar while <> and for <> loops.

while works like a repeated if:

while true
    echo Still running
    sleep 1
end

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

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

for file in *
    echo file: $file
end

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

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

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

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

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

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

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

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

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

Parameter expansion

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

Parameter expansion is limited to 524288 items. There is a limit to how many arguments the operating system allows for any command, and 524288 is far above it. This is a measure to stop the shell from hanging doing useless computation.

Wildcards ("Globbing")

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

Wildcard matches are sorted case insensitively. When sorting matches containing numbers, they are naturally sorted, so that the strings '1' '5' and '12' would be sorted like 1, 5, 12.

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

Examples:

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

Examples:

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

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

apt install "ncurses-*"

Variable expansion

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

A simple example:

echo $HOME

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

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

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

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

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

echo $nonexistentvariable
# Prints no output.

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

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

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

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

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

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

Quoting variables

Variable expansion also happens in double quoted strings. Inside double quotes ("these"), variables will always expand to exactly one argument. If they are empty or undefined, it will result in an empty string. If they have one element, they'll expand to that element. If they have more than that, the elements will be joined with spaces, unless the variable is a path variable - in that case it will use a colon (:) instead [3].

Fish variables are all lists, and they are split into elements when they are set - that means it is important to decide whether to use quotes or not with set <>:

set foo 1 2 3 # a variable with three elements
rm $foo # runs the equivalent of `rm 1 2 3` - trying to delete three files: 1, 2 and 3.
rm "$foo" # runs `rm '1 2 3'` - trying to delete one file called '1 2 3'
set foo # an empty variable
rm $foo # runs `rm` without arguments
rm "$foo" # runs the equivalent of `rm ''`
set foo "1 2 3"
rm $foo # runs the equivalent of `rm '1 2 3'` - trying to delete one file
rm "$foo" # same thing

This is unlike other shells, which do what is known as "Word Splitting", where they split the variable when it is used in an expansion. E.g. in bash:

foo="1 2 3"
rm $foo # runs the equivalent of `rm 1 2 3`
rm "$foo" # runs the equivalent of `rm '1 2 3'`

This is the cause of very common problems with filenames with spaces in bash scripts.

In fish, unquoted variables will expand to as many arguments as they have elements. That means an empty list will expand to nothing, a variable with one element will expand to that element, and a variable with multiple 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 information.

Most of the time, not quoting a variable is correct. The exception is when you need to ensure that the variable is passed as one element, even if it might be unset or have multiple elements. This happens often with test <>:

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

[3]

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

Dereferencing variables

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

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

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

This can also be used to give a variable name to a function:

function print_var
    for arg in $argv
        echo Variable $arg is $$arg
    end
end
set -g foo 1 2 3
set -g bar a b c
print_var foo bar
# prints "Variable foo is 1 2 3" and "Variable bar is a b c"

Of course the variable will have to be accessible from the function, so it needs to be global/universal or exported. It also can't clash with a 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.

Examples:

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

Sometimes you want to pass the output of a command to another command that only accepts files. If it's just one file, you can usually pass it via a pipe, like:

grep fish myanimallist1 | wc -l

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

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

This creates a temporary file, stores the output of the command in that file and prints the filename, so it is given to the outer command.

Fish has a default limit of 1 GiB on the data it will read in a command substitution. If that limit is reached the command (all of it, not just the command substitution - the outer command won't be executed at all) fails and $status is set to 122. This is so command substitutions can't cause the system to go out of memory, because typically your operating system has a much lower limit, so reading more than that would be useless and harmful. This limit can be adjusted with the fish_read_limit variable (0 meaning no limit). This limit also affects the read <> command.

[4]

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

Brace expansion

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

Examples:

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

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

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

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

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

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

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

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

The very first character of a command token is never interpreted as expanding brace, because it's the beginning of a compound statement <>:

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

Combining lists

Fish expands lists like brace expansions:

>_ set -l foo x y z
>_ echo 1$foo
# Any element of $foo is combined with the "1":
1x 1y 1z
>_ echo {good,bad}" apples"
# Any element of the {} is combined with the " apples":
good apples bad apples
# Or we can mix the two:
>_ echo {good,bad}" "$foo
good x bad x good y bad y good z bad z

Any string attached to a list will be concatenated to each element.

Two lists will be expanded in all combinations - every element of the first with every element of the second:

>_ set -l a x y z; set -l b 1 2 3
>_ echo $a$b # same as {x,y,z}{1,2,3}
x1 y1 z1 x2 y2 z2 x3 y3 z3

A result of this is that, if a list has no elements, this combines the string with no elements, which means the entire token is removed!

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

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

for file in $PATH/*

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

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

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

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

Slices

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

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

In index brackets, fish understands ranges written like a..b ('a' and 'b' being indices). They are expanded into a sequence of indices from a to b (so a a+1 a+2 ... b), going up if b is larger and going down if a is larger. Negative indices can also be used - they are taken from the end of the list, so -1 is the last element, and -2 the one before it. If an index doesn't exist the range is clamped to the next possible index.

If a list has 5 elements the indices go from 1 to 5, so a range of 2..16 will only go from element 2 to element 5.

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

A missing starting index in a range defaults to 1. This is allowed if the range is the first index expression of the sequence. Similarly, a missing ending index, defaulting to -1 is allowed for the last index in the sequence.

Multiple ranges are also possible, separated with a space.

Some examples:

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

The same works when setting or expanding variables:

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

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

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

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

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

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

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

Home directory expansion

The ~ (tilde) character at the beginning of a parameter, followed by a username, is expanded into the home directory of the specified user. A lone ~, or a ~ followed by a slash, is expanded into the home directory of the process owner:

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

Combining different expansions

All of the above expansions can be combined. If several expansions result in more than one parameter, all possible combinations are created.

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

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

Example:

If the current directory contains the files 'foo' and 'bar', the command echo a(ls){1,2,3} will output abar1 abar2 abar3 afoo1 afoo2 afoo3.

Table Of Operators

Putting it together, here is a quick reference to fish's operators, all of the special symbols it uses:

Shell variables

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

To set a variable value, use the set <> command. A variable name can not be empty and can contain only letters, digits, and underscores. It may begin and end with any of those characters.

Example:

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

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

Example:

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

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

Variable Scope

All variables in fish have a scope. For example they can be global or local to a function or block:

# This variable is global, we can use it everywhere.
set --global name Patrick
# This variable is local, it will not be visible in a function we call from here.
set --local place "at the Krusty Krab"
function local
    # This can find $name, but not $place
    echo Hello this is $name $place
    # This variable is local, it will not be available
    # outside of this function
    set --local instrument mayonnaise
    echo My favorite instrument is $instrument
    # This creates a local $name, and won't touch the global one
    set --local name Spongebob
    echo My best friend is $name
end
local
# Will print:
# Hello this is Patrick
# My favorite instrument is mayonnaise
# My best friend is Spongebob
echo $name, I am $place and my instrument is $instrument
# Will print:
# Patrick, I am at the Krusty Krab and my instrument is

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

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:

There can be many variables with the same name, but different scopes. When you use a variable, the smallest scoped variable of that name will be used. If a local variable exists, it will be used instead of the global or universal variable of the same name.

Example:

There are a few possible uses for different scopes.

Typically inside functions you should use local scope:

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

If you want to set something in config.fish, or set something in a function and have it available for the rest of the session, global scope is a good choice:

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

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

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

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

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

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

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

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

Overriding variables for a single command

If you want to override a variable for a single command, you can use "var=val" statements before the command:

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

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

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

Multiple elements can be given in a brace expansion:

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

Or with a glob:

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

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

This syntax is supported since fish 3.1.

Universal Variables

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

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

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

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

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.

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.

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

As a convention, an uppercase name is usually used for exported variables, while lowercase variables are not exported. (CMD_DURATION is an exception for historical reasons). This rule is not enforced by fish, but it is good coding practice to use casing to distinguish between exported and unexported variables.

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

The status variable

Whenever a process exits, an exit status is returned to the program that started it (usually the shell). This exit status is an integer number, which tells the calling application how the execution of the command went. In general, a zero exit status means that the command executed without problem, but a non-zero exit status means there was some form of problem.

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

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

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

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

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

For example:

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

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

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

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

For example, if you have a pipeline like:

cat file1 file2 | head -n 50

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

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

Here, the "141" signifies that cat was killed by signal number 13 (128 + 13 == 141) - a SIGPIPE. You can also use fish_kill_signal to see the signal number. This happens because it was still working, and then head closed the pipe, so cat received a signal that it didn't ignore and so it died.

Whether cat here will see a SIGPIPE depends on how long the file is and how much it writes at once, so you might see a pipestatus of "0 0", depending on the implementation. This is a general unix issue and not specific to fish. Some shells feature a "pipefail" feature that will call a pipeline failed if one of the processes in it failed, and this is a big problem with it.

Locale Variables

The "locale" of a program is its set of language and regional settings. In UNIX, these are made up of several categories. The categories used by fish are:

Builtin commands

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

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

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

Command lookup

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

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

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

In order:

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:

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

Configuration files

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

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

Configuration files are run in the following order:

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

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

If you are developing another program, you may want to add 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.

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

Here is what they mean:

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

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

or opted into globally for a user:

> set -U fish_features regex-easyesc qmark-noglob

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

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

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

set -Ua fish_features no-qmark-noglob

Event handlers

When defining a new function in fish, it is possible to make it into an event handler, i.e. a function that is automatically run when a specific event takes place. Events that can trigger a handler currently are:

Example:

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

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

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

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

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

If there are multiple handlers for an event, they will all be run, but the order might change between fish releases, so you should not rely on it.

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

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

Debugging fish scripts

Fish includes basic built-in debugging facilities that allow you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt where you can execute any fish command to inspect or change state (there are no debug commands as such). For example, you can check or change the value of any variables using printf <> and set <>. As another example, you can run status print-stack-trace <> to see how the current breakpoint was reached. To resume normal execution of the script, type exit <> or ctrl-d.

To start a debug session insert the builtin command <> breakpoint at the point in a function or script where you wish to gain control, then run the function or script. Also, the default action of the TRAP signal is to call this builtin, meaning a running script can be actively debugged by sending it the TRAP signal (kill -s TRAP <PID>). There is limited support for interactively setting or modifying breakpoints from this debug prompt: it is 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.

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.

For example:

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

This will show the time for each command itself in the first column, the time for the command and every subcommand (like any commands inside of a function or command substitutions) in the second and the command itself in the third, separated with tabs.

The time is given in microseconds.

To see the slowest commands last, sort -nk2 /path/to/logfile is useful.

For profiling fish's startup there is also --profile-startup /path/to/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

Tools

Builtins to do a task, like

Known functions

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

Helper functions

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

Helper commands

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

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

The full list

And here is the full list:

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.

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 <#envvar-LANG>, LC_MESSAGES <#envvar-LC_MESSAGES>, LC_ALL <#envvar-LC_ALL>, and LANGUAGE <#envvar-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 <#envvar-LANGUAGE> you can use a list, or use colons to separate multiple languages.

Options

_ takes no options.

Examples

Use German translations:

> set LANG de_DE.UTF-8
> _ file
Datei

Specify a precedence of languages (only works with LANGUAGE <#envvar-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.

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
abbr --list
abbr --query NAME ...

Description

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

Note:

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.

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 <#configuration> 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 <#configuration>, 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 <#configuration> by doing something like the following:

> abbr > ~/.config/fish/conf.d/myabbrs.fish

This will save all your abbreviations in "myabbrs.fish", overwriting the whole file so it doesn't leave any duplicates, or restore abbreviations you had erased. Of course any functions will have to be saved separately, see funcsave <>.

"add" subcommand

abbr [-a | --add] NAME [--position command | anywhere] [-r | --regex PATTERN]
     [-c | --command COMMAND] [--set-cursor[=MARKER]] ([-f | --function FUNCTION] | EXPANSION)

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

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

With --command COMMAND, the abbreviation will only expand when it is used as an argument to the given COMMAND. Multiple --command can be used together, and the abbreviation will expand for each. An empty COMMAND means it will expand only when there is no command. --command implies --position anywhere and disallows --position command. Even with different COMMANDS, the NAME of the abbreviation needs to be unique. Consider using --regex if you want to expand the same word differently for multiple commands.

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

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

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

Examples

abbr --add gco git checkout

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

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

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

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

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

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

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

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

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

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

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

abbr --command git co checkout

Turns "co" as an argument to "git" into "checkout". Multiple commands are possible, --command={git,hg} would expand "co" to "checkout" for both git and hg.

Other subcommands

abbr --rename [ [-c | --command COMMAND]... ] OLD_NAME NEW_NAME

Renames an abbreviation, from OLD_NAME to NEW_NAME. For command-specific abbreviations, the --command options must be provided to disambiguate which abbreviation to rename.

abbr [-s | --show]

Show all abbreviations in a manner suitable for import and export

abbr [-l | --list]

Prints the names of all abbreviation

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

Erases the abbreviation with the given name. For command-specific abbreviations, the --command options must be provided to disambiguate which abbreviation to rename.

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

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

abbr -h or --help

Displays help for the abbr command.

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.

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.

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

The following options are available:

Example

The following code will create rmi, which runs rm with additional arguments on every invocation.

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

alias sometimes requires escaping, as you can see here:

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

See more

Synopsis

PREVIOUS; and COMMAND

Description

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

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

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

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

Example

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

make; and make install; or make clean

See Also

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.

Each option specification (OPTION_SPEC) is written in the domain specific language described below. All OPTION_SPECs must appear after any argparse flags and before the -- that separates them from the arguments to be parsed.

Each option that is seen in the ARG list will result in variables named _flag_X, where X is the short flag letter and the long flag name (if they are defined). For example a --help option could cause argparse to define one variable called _flag_h and another called _flag_help.

The variables will be set with local scope (i.e., as if the script had done set -l _flag_X). If the flag is a boolean (that is, it is passed or not, it doesn't have a value) the values are the short and long flags seen. If the option is not a boolean the values will be zero or more values corresponding to the values collected when the ARG list is processed. If the flag was not seen the flag variable will not be set.

Options

The following argparse options are available. They must appear before all OPTION_SPECs:

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:

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:

These variables are passed to the function as local exported variables.

The script should write any error messages to stdout, not stderr. It should return a status of zero if the flag value is valid otherwise a non-zero status to indicate it is invalid.

Fish ships with a _validate_int function that accepts a --min and --max flag. Let's say your command accepts a -m or --max flag and the minimum 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:

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.

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

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:

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

Synopsis

bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [--preset | --user] [-s | --silent] KEYS COMMAND ...
bind [(-M | --mode) MODE] [--preset] [--user] [KEYS]
bind [-a | --all] [--preset] [--user]
bind (-f | --function-names)
bind (-K | --key-names)
bind (-L | --list-modes)
bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] [-a | --all] | KEYS ...

Description

bind manages key bindings.

If both KEYS and COMMAND are given, bind adds (or replaces) a binding in MODE. If only KEYS is given, any existing binding for those keys in the given MODE will be printed. If no KEYS argument is provided, all bindings (in the given MODE) are printed.

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:

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:

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:

Special input functions

The following special input functions are available:

Additional functions

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

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

For instance, historically the control key modifies a character by setting the top three bits to 0. This means:

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.

When in doubt, run fish_key_reader - explore what characters keyboard keys send <>. If that tells you that pressing ctrl-i sends tab, your terminal does not support these better encodings, and so fish is limited to what it sends.

Key timeout

When you've bound a sequence of multiple characters, there is always the possibility that fish has only seen a part of it, and then it needs to disambiguate between the full sequence and part of it.

For example:

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

will bind the sequence jk to insert "foo" into the commandline. When you've only pressed "j", fish doesn't know if it should insert the "j" (because of the default self-insert), or wait for the "k".

You can enable a timeout for this, by setting the fish_sequence_key_delay_ms <#envvar-fish_sequence_key_delay_ms> variable to the timeout in milliseconds. If the timeout elapses, fish will no longer wait for the sequence to be completed, and do what it can with the characters it already has.

The escape key is a special case, because it can be used standalone as a real key or as part of a longer escape sequence, like function or arrow keys. Holding alt and something else also typically sends escape, for 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 <#envvar-fish_escape_delay_ms>.

See also Key sequences <#interactive-key-sequences>.

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.

Event blocks should not be confused with code blocks, which are created with begin, if, while or for

Without options, block sets up a block that is released automatically at the end of the current function scope.

The following options are available:

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.

Synopsis

LOOP_CONSTRUCT
   [COMMANDS ...]
   break
   [COMMANDS ...]
end

Description

break halts a currently running loop (LOOP_CONSTRUCT), such as a for <> or while <> loop. It is usually added inside of a conditional block such as an if <> block.

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

Example

The following code searches all .c files for "smurf", and halts at the first occurrence.

for i in *.c
    if grep smurf $i
        echo Smurfs are present in $i
        break
    end
end

See Also

Synopsis

breakpoint

Description

breakpoint is used to halt a running script and launch an interactive debugging prompt.

For more details, see Debugging fish scripts <#debugging> in the fish manual.

There are no parameters for breakpoint.

Synopsis

builtin [OPTIONS] BUILTINNAME
builtin --query BUILTINNAME ...
builtin --names

Description

builtin forces the shell to use a builtin command named BUILTIN, rather than a function or external program.

The following options are available:

Example

builtin jobs
# executes the jobs builtin, even if a function named jobs exists

Synopsis

switch VALUE
   [case [GLOB ...]
       [COMMAND ...]]
end

Description

switch executes one of several blocks of commands, depending on whether a specified value matches one of several values. case is used together with the switch statement in order to determine which block should be executed.

Each case command is given one or more parameters. The first case command with a parameter that matches the string specified in the switch command will be evaluated. case parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames.

Note that fish does not fall through on case statements. Only the first matching case is executed.

Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter.

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

Synopsis

cd [DIRECTORY]

Description

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

cd changes the current working directory.

If DIRECTORY is given, it will become the new directory. If no parameter is given, the HOME <#envvar-HOME> environment variable will be used.

If DIRECTORY is a relative path, all the paths in the CDPATH <#envvar-CDPATH> will be tried as prefixes for it, in addition to PWD <#envvar-PWD>. It is recommended to keep . as the first element of CDPATH <#envvar-CDPATH>, or PWD <#envvar-PWD> will be tried last.

Fish will also try to change directory if given a command that looks like a directory (starting with ., / or ~, or ending with /), without explicitly requiring cd.

Fish also ships a wrapper function around the builtin cd that understands cd - as changing to the previous directory. See also prevd <>. This wrapper function maintains a history of the 25 most recently visited directories in the $dirprev and $dirnext global variables. If you make those universal variables your cd history is shared among all fish instances.

As a special case, cd . is equivalent to cd $PWD, which is useful in cases where a mountpoint has been recycled or a directory has been removed and recreated.

The --help or -h option displays help about using this command, and does not change the directory.

Examples

cd
# changes the working directory to your home directory.
cd /usr/src/fish-shell
# changes the working directory to /usr/src/fish-shell

See Also

Navigate directories using the directory history <#directory-history> or the directory stack <#directory-stack>

Synopsis

cdh [DIRECTORY]

Description

cdh with no arguments presents a list of recently visited directories <#directory-history>. You can then select one of the entries by letter or number. You can also press tab to use the completion pager to select an item from the list. If you give it a single argument it is equivalent to cd DIRECTORY.

Note that the cd command limits directory history to the 25 most recently visited directories. The history is stored in the dirprev and dirnext variables, which this command manipulates. If you make those universal variables, your cd history is shared among all fish instances.

See Also

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.

In command foo, command is a keyword.

The following options are available:

Examples

command ls executes the ls program, even if an ls function also exists.
command -s ls prints the path to the ls program.
command -q git; and command git log runs git log only if git exists.
command -sq git and command -q git and command -vq git return true (0) if a git command could be found and don't print anything.

Synopsis

commandline [OPTIONS] [CMD]

Description

commandline can be used to set or get the current contents of the command line buffer.

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

With CMD specified, the command line buffer is erased and replaced with the contents of CMD.

The following options are available:

The following options change the way commandline updates the command line buffer:

The following options change what part of the commandline is printed or updated:

The following options change the way commandline prints the current commandline buffer:

If commandline is called during a call to complete a given string using complete -C STRING, commandline will consider the specified string to be the current contents of the command line.

The following options output metadata about the commandline state:

Example

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

If the commandline contains

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

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

The echo $flounder >& is the first process, less the second and and echo $catfish the third.

echo $flounder >&2 | less is the first job, and echo $catfish the second.

$flounder is the current token.

The most common use for something like completions is

set -l tokens (commandline -xpc)

which gives the current process (what is being completed), tokenized into separate entries, up to but excluding the currently being completed token

If you are then also interested in the in-progress token, add

set -l current (commandline -ct)

Note that this makes it easy to render fish's infix matching moot - if 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

Synopsis

complete ((-c | --command) | (-p | --path)) COMMAND [OPTIONS]
complete (-C | --do-complete) [--escape] STRING

Description

complete defines, removes or lists completions for a command.

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

The following options are available:

Command-specific tab-completions in fish are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as -h, -help or --help. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU getopt library. These styles are:

Multiple commands and paths can be given in one call to define the same completions for multiple commands.

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

Invoking complete multiple times for the same command adds the new definitions on top of any existing completions defined for the command.

When -a or --arguments is specified in conjunction with long, short, or old-style options, the specified arguments are only completed as arguments for any of the specified options. If -a or --arguments is specified without any long, short, or old-style options, the specified arguments are used when completing non-option arguments to the command (except when completing an option argument that was specified with -r or --require-parameter).

Command substitutions found in ARGUMENTS should return a newline-separated list of arguments, and each argument may optionally have a tab character followed by the argument description. Description given this way override a description given with -d or --description.

Descriptions given with --description are also used to group options given with -s, -o or -l. Options with the same (non-empty) description will be listed as one candidate, and one of them will be picked. If the description is empty or no description was given this is skipped.

The -w or --wraps options causes the specified command to inherit completions from another command, "wrapping" the 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, it is possible to either erase all completions for a specific command by specifying complete -c COMMAND -e, or by specifying 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 without any arguments shows all loaded completions, complete -c foo shows all loaded completions for foo. Since completions are autoloaded <#syntax-function-autoloading>, you will have to trigger them first.

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.

Synopsis

contains [OPTIONS] KEY [VALUES ...]

Description

contains tests whether the set VALUES contains the string KEY. If so, contains exits with code 0; if not, it exits with code 1.

The following options are available:

Note that contains interprets all arguments starting with a - as an option to contains, until an -- argument is reached.

See the examples below.

Example

If animals is a list of animals, the following will test if animals contains "cat":

if contains cat $animals
   echo Your animal list is evil!
end

This code will add some directories to PATH <#envvar-PATH> if they aren't yet included:

for i in ~/bin /usr/local/bin
    if not contains $i $PATH
        set PATH $PATH $i
    end
end

While this will check if function hasargs is being ran with the -q option:

function hasargs
    if contains -- -q $argv
        echo '$argv contains a -q option'
    end
end

The -- here stops contains from treating -q to an option to itself. Instead it treats it as a normal string to check.

Synopsis

LOOP_CONSTRUCT; [COMMANDS ...;] continue; [COMMANDS ...;] end

Description

continue skips the remainder of the current iteration of the current inner loop, such as a for <> loop or a while <> loop. It is usually added inside of a conditional block such as an if <> statement or a switch <> statement.

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

Example

The following code removes all tmp files that do not contain the word smurf.

for i in *.tmp
    if grep smurf $i
        continue
    end
    # This "rm" is skipped over if "continue" is executed.
    rm $i
    # As is this "echo"
    echo $i
end

See Also

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.

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

Synopsis

dirh

Description

dirh prints the current directory history <#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.

See Also

Synopsis

dirs [-c]

Description

dirs prints the current directory stack <#directory-stack>, as created by pushd <> and modified by popd <>.

The following options are available:

dirs does not accept any arguments.

See Also

Synopsis

disown [PID ...]

Description

disown removes the specified job <#syntax-job-control> from the list of jobs. The job itself continues to exist, but fish does not keep track of it any longer. This will make fish lose all knowledge of the job, so functions defined with --on-process-exit or --on-job-exit will no longer fire.

Jobs in the list of jobs are sent a hang-up signal when fish terminates, which usually causes the job to terminate; disown allows these processes to continue regardless.

If no process is specified, the most recently-used job is removed (like bg <> and fg <>). If one or more PIDs are specified, jobs with the specified process IDs are removed from the job list. Invalid jobs are ignored and a warning is printed.

If a job is stopped, it is sent a signal to continue running, and a warning is printed. It is not possible to use the bg <> builtin to continue a job once it has been disowned.

disown returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered.

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

Example

firefox &; disown will start the Firefox web browser in the background and remove it from the job list, meaning it will not be closed when the fish process is closed.

disown (jobs -p) removes all jobs <> from the job list without terminating them.

Synopsis

echo [OPTIONS] [STRING]

Description

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

echo displays STRING of text.

The following options are available:

Unlike other shells, this echo accepts -- to signal the end of the options.

Escape Sequences

If -e is used, the following sequences are recognized:

Example

> echo 'Hello World'
Hello World
> echo -e 'Top\nBottom'
Top
Bottom
> echo -- -n
-n

See Also

Synopsis

if CONDITION; COMMANDS_TRUE ...; [else; COMMANDS_FALSE ...;] end

Description

if <> will execute the command CONDITION*. If the condition's exit status is 0, the commands COMMANDS_TRUE will execute. If it is not 0 and else is given, COMMANDS_FALSE will be executed.

Example

The following code tests whether a file foo.txt exists as a regular file.

if test -f foo.txt
    echo foo.txt exists
else
    echo foo.txt does not exist
end

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.

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.

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:

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.

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.

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

Synopsis

exec COMMAND

Description

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

exec replaces the currently running shell with a new command. On successful completion, exec never returns. exec cannot be used inside a pipeline.

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

Example

exec emacs starts up the emacs text editor, and exits fish. When emacs exits, the session will terminate.

Synopsis

exit [CODE]

Description

exit is a special builtin that causes the shell to exit. Either 255 or the CODE supplied is used, whichever is lesser. Otherwise, the exit status will be that of the last command executed.

If exit is called while sourcing a file (using the source <> builtin) the rest of the file will be skipped, but the shell itself will not exit.

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

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.

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

Synopsis

false

Description

false sets the exit status to 1.

See Also

Synopsis

fg [PID]

Description

The fg builtin brings the specified job <#syntax-job-control> to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job containing a process with the specified process ID is put in the foreground.

For compatibility with other shells, job expansion syntax is supported for fg. A PID of the format %1 will foreground job 1. Job numbers can be seen in the output of jobs <>.

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

Example

fg will put the last job in the foreground.

fg %3 will put job 3 into the foreground.

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.

The following options are available:

The fish exit status is generally the exit status of the last foreground command <#variables-status>.

Debugging

While fish provides extensive support for debugging fish scripts <#debugging>, it is also possible to debug and instrument its internals. Debugging can be enabled by passing the --debug option. For example, the following command turns on debugging for background IO thread events, in addition to the default categories, i.e. debug, error, warning, and warning-path:

> fish --debug=iothread

Available categories are listed by fish --print-debug-categories. The --debug option accepts a comma-separated list of categories, and supports glob syntax. The following command turns on debugging for complete, history, history-file, and profile-history, as well as the default categories:

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

Debug messages output to stderr by default. Note that if fish_trace <#envvar-fish_trace> is set, execution tracing also outputs to stderr by default. You can output to a file using the --debug-output option:

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

These options can also be changed via the FISH_DEBUG <#envvar-FISH_DEBUG> and FISH_DEBUG_OUTPUT <#envvar-FISH_DEBUG_OUTPUT> variables. The categories enabled via --debug are added to the ones enabled by $FISH_DEBUG, so they can be disabled by prefixing them with - (reader-*,-ast* enables reader debugging and disables ast debugging).

The file given in --debug-output takes precedence over the file in FISH_DEBUG_OUTPUT <#envvar-FISH_DEBUG_OUTPUT>.

Examples

To just start fish:

fish

To run a file with fish:

fish /path/to/script.fish

To run some commands with fish:

fish -c 'echo Hi there!'

You can also pass arguments to those commands:

> fish -c 'printf %s\n $argv' "first line" "second line"
first line
second line

To run a script, except read this other file first:

fish --init-cmd "source otherfile" script.fish

To profile <#profiling> 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

Synopsis

fish_add_path path ...
fish_add_path [(-g | --global) | (-U | --universal) | (-P | --path)] [(-m | --move)] [(-a | --append) | (-p | --prepend)] [(-v | --verbose) | (-n | --dry-run)] PATHS ...

Description

fish_add_path is a simple way to add more directories to fish's PATH <#envvar-PATH>. It does this by adding the directories either to fish_user_paths <#envvar-fish_user_paths> or directly to PATH <#envvar-PATH> (if the --path switch is given).

It is (by default) safe to use fish_add_path in config.fish, or it can be used once, interactively, and the paths will stay in future because of universal variables <#variables-universal>. This is a "do what I mean" style command - it tries to do the right thing by default, and follow your lead on what you have already set up (e.g. by using a global fish_user_paths <#envvar-fish_user_paths> if you have that already). If you need more control, consider modifying the variable yourself.

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

Directories are added in the order they are given, and they are prepended to the path unless --append is given. If $fish_user_paths is used, that means they are last in $fish_user_paths, which is itself prepended to PATH <#envvar-PATH>, so they still stay ahead of the system paths. If the --path option is used, the paths are appended/prepended to PATH <#envvar-PATH> directly, so this doesn't happen.

With --path, because PATH <#envvar-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 <#configuration>. This also applies to fish_user_paths <#envvar-fish_user_paths> if you make it global (for instance by passing --global).

If no directory is new, the variable (fish_user_paths <#envvar-fish_user_paths> or PATH <#envvar-PATH>) is not set again or otherwise modified, so variable handlers are not triggered.

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

Options

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

Synopsis

fish_breakpoint_prompt

function fish_breakpoint_prompt
    ...
end

Description

fish_breakpoint_prompt is the prompt function when asking for input in response to a breakpoint <> command.

The exit status of commands within fish_breakpoint_prompt will not modify the value of $status <#variables-status> outside of the fish_breakpoint_prompt function.

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 is a simplified version of the default debugging prompt:

function fish_breakpoint_prompt -d "Write out the debug prompt"
    set -l function (status current-function)
    set -l line (status current-line-number)
    set -l prompt "$function:$line >"
    echo -ns (set_color $fish_color_status) "BP $prompt" (set_color normal) ' '
end

Synopsis

fish_clipboard_copy
foo | fish_clipboard_copy

Description

The fish_clipboard_copy function copies text to the system clipboard.

If stdin is not a terminal (see isatty <>), it will read all input from there and copy it. If it is, it will use the current commandline, or the current selection if there is one.

It is bound to ctrl-x by default.

fish_clipboard_copy works by calling a system-specific backend. If it doesn't appear to work you may need to install yours.

Currently supported are:

See also

Synopsis

fish_clipboard_paste
fish_clipboard_paste | foo

Description

The fish_clipboard_paste function copies text from the system clipboard.

If its stdout is not a terminal (see isatty <>), it will output everything there, as-is, without any additional newlines. If it is, it will put the text in the commandline instead.

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

It is bound to ctrl-v by default.

fish_clipboard_paste works by calling a system-specific backend. If it doesn't appear to work you may need to install yours.

Currently supported are:

See also

Synopsis

function fish_command_not_found
   ...
end

Description

When fish tries to execute a command and can't find it, it invokes this function.

It can print a message to tell you about it, and it often also checks for a missing package that would include the command.

Fish ships multiple handlers for various operating systems and chooses from them when this function is loaded, or you can define your own.

It receives the full commandline as one argument per token, so $argv[1] contains the missing command.

When you leave fish_command_not_found undefined (e.g. by adding an empty function file) or explicitly call __fish_default_command_not_found_handler, fish will just print a simple error.

Example

A simple handler:

function fish_command_not_found
    echo Did not find command $argv[1]
end
> flounder
Did not find command flounder

Or the handler for OpenSUSE's command-not-found:

function fish_command_not_found
    /usr/bin/command-not-found $argv[1]
end

Or the simple default handler:

function fish_command_not_found
    __fish_default_command_not_found_handler $argv
end