Installation

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

Starting and Exiting

> fish

> exit

Executing Bash

> bash -c 'some bash command'

> bash
$ some bash command
$ exit
> _

Default Shell

For detailed instructions see Switching to fish.

Uninstalling

Shebang Line

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

This line is only needed 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!).

Frequently asked questions

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

How do I set or clear an environment variable?

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

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

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

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

How do I check whether a variable is defined?

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

Keep in mind that a defined variabled 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?

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?

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

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

To avoid this problem, consider changing the setting which fish inherits. If this is not possible, add a statement to your configuration file (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?

[1]

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

How do I set my prompt?

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.

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

If you haven't activated vi mode on purpose, you might have installed a third-party theme 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?

How do I change the greeting message?

set -U fish_greeting

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

set -g fish_greeting

in config.fish.

I'm seeing weird output before each prompt when using screen. What's wrong?

Run the following command in fish:

function fish_title; end; funcsave fish_title

Problem solved!

The long answer:

Fish is trying to set the titlebar message of your terminal. While screen itself supports this feature, your terminal does not. Unfortunately, when the underlying terminal doesn't support setting the titlebar, screen simply passes through the escape codes and text to the underlying terminal instead of ignoring them. It is impossible to detect and resolve this problem from inside fish since fish has no way of knowing what the underlying terminal type is. For now, the only way to fix this is to unset the titlebar message, as suggested above.

Note that fish has a default titlebar message, which will be used if the fish_title function is undefined. So simply unsetting the fish_title function will not work.

How do I run a command from history?

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

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

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

See documentation for more details about line editing in fish.

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

for i in (ls)
    echo $i
end

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

That means if you run

echo x(printf '%s ' a b c)x

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

echo x(printf '%s\n' a b c)x

it will print xax xbx xcx.

In the overwhelming majority of cases, splitting on spaces is unwanted, so this is an improvement.

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?

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

If you are just interested in success or failure, you can run the 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 documentation for test and if for more information.

My command prints No matches for wildcard but works in bash

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

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

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

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

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.

I accidentally entered a directory path and fish changed directory. What happened?

How can I use - as a shortcut for cd -?

abbr -a -- - 'cd -'

The open command doesn't work.

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

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

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

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

if status is-interactive
  ...
end

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

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

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:

How do I make fish my default shell?

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

If you installed a prepackaged version of fish, the package manager should have already done this for you.

In order to change your default shell, type:

chsh -s /usr/local/bin/fish

You may need to adjust the above path to e.g. /usr/bin/fish. Use the command which fish if you are unsure of where fish is installed.

Unfortunately, there is no way to make the changes take effect at once. You will need to log out and back in again.

Uninstalling fish

If you installed it with a package manager, just 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

Where can I find extra tools for fish?

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

Interactive use

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

Help

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.

This 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

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

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

Tab Completion

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

Fish provides some general purpose completions:

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

Syntax highlighting

Detected errors include:

When the cursor is over a parenthesis or a quote, fish also highlights its matching quote or parenthesis.

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

Syntax highlighting variables

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, fish usually tries $fish_color_normal, except for $fish_color_keyword, where it tries $fish_color_command first.

Pager color variables

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, the normal variables are used, except for $fish_pager_color_selected_background, where the background of $fish_color_search_match is tried first.

Abbreviations

abbr -a gco git checkout

After entering gco and pressing Space or Enter, the full text git checkout will appear in the command line.

This is an alternative to aliases, and has the advantage that you see the actual command before using it, and the actual command will be stored in history.

Programmable title

Examples: The default fish title is:

function fish_title
    echo (status current-command) ' '
    pwd
end

To show the last command in the title:

function fish_title
    echo $argv[1]
end

Programmable prompt

Configurable greeting

Private mode

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

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

Command line editor

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

Emacs mode commands

You can change these key bindings using the bind builtin.

Vi mode commands

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 cursor to an underscore
set fish_cursor_replace_one underscore
# 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.

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

Command mode

Insert mode

Visual mode

Custom bindings

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

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

The key sequence (the \cc) here depends on your setup, in particular the terminal. To find out what the terminal sends use fish_key_reader:

> fish_key_reader # pressing control-c
Press a key:
            hex:    3  char: \cC
Press [ctrl-C] again to exit
bind \cC 'do something'
> fish_key_reader # pressing the right-arrow
Press a key:
            hex:   1B  char: \c[  (or \e)
(  0.077 ms)  hex:   5B  char: [
(  0.037 ms)  hex:   43  char: C
bind \e\[C 'do something'

Note that some key combinations are indistinguishable or unbindable. For instance control-i is the same as the tab key. This is a terminal limitation that fish can't do anything about.

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

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

set -g fish_escape_delay_ms 100

Copy and paste (Kill Ring)

Copy and paste from outside are also supported, both via the Control+X / Control+V bindings (the fish_clipboard_copy and fish_clipboard_paste functions [1]) 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 simply by closing the quote after. Kill ring entries are stored in fish_killring variable.

[1]

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

Multiline editing

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

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

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

Prefixing the commandline with a space will prevent the entire line from being stored in the history.

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+↑ to search for previously typed words containing 'm'.

Navigating directories

Directory history

Several commands are provided to interact with this directory history:

Directory stack

The fish language

For interactive features see Interactive use.

Syntax overview

echo hello world

This calls the echo command. echo 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.

To learn more about the echo command, read its manual page by typing man echo. man is a command for displaying a manual page on a given topic. It takes the name of the manual page to display as an argument. There are manual pages for almost every command. There are also manual pages for many other things, such as system libraries and important files.

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.

Terminology

Quotes

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.

Example:

rm "cumbersome filename.txt"

removes the file cumbersome filename.txt, while

rm cumbersome filename.txt

removes two files, cumbersome and filename.txt.

Another example:

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

Escaping Characters

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:

Input/Output Redirection

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.

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

For example, echo hello 2> output.stderr writes the standard error (file descriptor 2) to output.stderr.

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 will be removed in the future. See feature flags.

Piping

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

Job control

Example:

emacs &

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

Most programs allow you to suspend the program's execution and return control to fish by pressing Control+Z (also referred to as ^Z). Once back at the fish commandline, you can start other programs and do 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.

Functions

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

function ll
    ls -l $argv
end

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

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

This is a kind of function known as a wrapper or "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

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

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

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

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

Autoloading functions

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

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

By default $fish_function_path contains the following:

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

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

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

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

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

Comments

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

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

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

Comments can also appear after a line like so:

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

Conditions

The switch command is used to execute one of possibly many blocks of commands depending on the value of a string. See the documentation for switch for more information.

The other conditionals use the exit status of a command to decide if a command or a block of commands should be executed.

Unlike programming languages you might know, if doesn't take a condition, it takes a command. If that command returned a successful exit status (that's 0), the if branch is taken, otherwise the else branch.

Some examples:

# Just see if the file contains the string "fish" anywhere.
# This executes the `grep` command, which searches for a string,
# and if it finds it returns a status of 0.
# The `-q` switch stops it from printing any matches.
if grep -q fish myanimals
    echo "You have fish!"
else
    echo "You don't have fish!"
end
# $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

For more, see the documentation for the builtins or the Conditionals section of the tutorial.

Loops and blocks

while works like a repeated if:

while true
    echo Still running
    sleep 1
end

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

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

for file in *
    echo file: $file
end

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

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

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

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

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

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

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

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

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

Parameter expansion

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

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

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

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

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

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

Examples:

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

Examples:

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

[3]

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

Variable expansion

In the simplest case, this is just something like:

echo $HOME

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

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

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

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

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

echo $nonexistentvariable
# Prints no output.

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

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

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

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

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

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

Outside of double quotes, variables will expand to as many arguments as they have elements. That means an empty list will expand to nothing, a variable with one element will expand to that element, and a variable with multiple elements will expand to each of those elements separately.

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

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

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

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

When using this feature together with list brackets, the brackets will be used from the inside out. $$foo[5] will use the fifth element of $foo as a variable name, instead of giving the fifth element of all the variables $foo refers to. That would instead be expressed as $$foo[1][5] (take the first element of $foo, use it as a variable name, then give the fifth element of that).

[4]

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

Command substitution

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

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

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

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

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

Examples:

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

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

grep fish myanimallist1 | wc -l

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

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

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

[5]

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

[6]

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

Brace expansion

Examples:

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

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

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

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

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

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

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

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

Combining lists (Cartesian Product)

Examples:

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

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

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

E.g.

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

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

for file in $PATH/*

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

Index range expansion

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

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

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

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

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

Multiple ranges are also possible, separated with a space.

Some examples:

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

The same works when setting or expanding variables:

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

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

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

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

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

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

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

Home directory expansion

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

Combining different expansions

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

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

Example:

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

Shell variables

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

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

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

Example:

There are a few possible uses for different scopes.

Typically inside funcions you should use local scope:

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

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

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

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

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

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

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

Overriding variables for a single command

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

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

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

Multiple elements can be given in a brace expansion:

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

Or with a glob:

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

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

This syntax is supported since fish 3.1.

More on universal variables

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

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

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

Variable scope for functions

For example:

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

Exporting variables

This also applies to fish - when it starts up, it receives environment variables from its parent (usually the terminal). These typically include system configuration like $PATH and locale variables.

Variables can be explicitly set to be exported with the -x or --export switch, or not exported with the -u or --unexport switch. The exporting rules when setting a variable are identical to the scoping rules for variables:

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

For example:

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

Note: Exporting is not a scope, but an additional state. It typically makes sense to make exported variables global as well, but local-exported variables can be useful if you need something more specific than Overrides. They are copied to functions so the function can't alter them outside, and still available to commands.

Lists

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

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

echo $PATH[3]

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

If you don't use any brackets, all the elements of the list will be passed to the command as separate items. This means you can iterate over a list with for:

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

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

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

set smurf blue small

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

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

If you specify a negative index when expanding or assigning to a list variable, the index will be taken from the end of the list. For example, the index -1 is the last element of the list:

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

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

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

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

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

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

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

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

A nice thing about lists is that they are passed to commands one element as one argument, so once you've set your list, you can just pass it:

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

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

Argument Handling

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

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

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

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

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

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

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

> mybetterfunction first -s second third
second

PATH variables

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

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

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

Special variables

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

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

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

The status variable

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

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

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

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

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

For example:

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

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

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

Locale variables

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

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

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

Builtin commands

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.

Shell variable and function names

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

Future feature flags

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

> status features
stderr-nocaret  on     3.0      ^ no longer redirects stderr
qmark-noglob    off    3.0      ? no longer globs
regex-easyesc   off    3.1      string replace -r needs fewer \\'s

There are two breaking changes in fish 3.0: caret ^ no longer redirects stderr, and question mark ? is no longer a glob.

There is one breaking change in fish 3.1: string replace -r does a superfluous round of escaping for the replacement, so escaping backslashes would look like string replace -ra '([ab])' '\\\\\\\$1' a. This flag removes that if turned on, so '\\\\$1' is enough.

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

> fish --features qmark-noglob,stderr-nocaret

or opted into globally for a user:

> set -U fish_features stderr-nocaret 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".

Prefixing a feature with no- turns it off instead.

Event handlers

Example:

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

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

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

To start a debug session simply run the builtin command breakpoint at the point in a function or script where you wish to gain control. Also, the default action of the TRAP signal is to call this builtin. So a running script can be debugged by sending it the TRAP signal with the kill command. Once in the debugger, it is easy to insert new breakpoints by using the funced function to edit the definition of a function.

Commands

_ - call fish's translations

Synopsis

_ STRING...

Description

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

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

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

Options

Examples

> _ File
Datei

abbr - manage fish abbreviations

Synopsis

abbr --add [SCOPE] WORD EXPANSION
abbr --erase WORD...
abbr --rename [SCOPE] OLD_WORD NEW_WORD
abbr --show
abbr --list
abbr --query WORD...

Description

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.

Options

In addition, when adding or renaming abbreviations:

See the "Internals" section for more on them.

Examples

abbr -a -g gco git checkout

Add a new abbreviation where gco will be replaced with git checkout global to the current shell. This abbreviation will not be automatically visible to other shells unless the same command is run in those shells (such as when executing the commands in config.fish).

abbr -a -U l less

Add a new abbreviation where l will be replaced with less universal so all shells. Note that you omit the -U since it is the default.

abbr -r gco gch

Renames an existing abbreviation from gco to gch.

abbr -e gco

Erase the gco abbreviation.

ssh another_host abbr -s | source

Import the abbreviations defined on another_host over SSH.

Internals

Defining an abbreviation with global scope is slightly faster than universal scope (which is the default). But in general you'll only want to use the global scope when defining abbreviations in a startup script like ~/.config/fish/config.fish like this:

if status --is-interactive
    abbr --add --global first 'echo my first abbreviation'
    abbr --add --global second 'echo my second abbreviation'
    abbr --add --global gco git checkout
    # etcetera
end

You can create abbreviations interactively and they will be visible to other fish sessions if you use the -U or --universal flag or don't explicitly specify the scope and the abbreviation isn't already defined with global scope. If you want it to be visible only to the current shell use the -g or --global flag.

alias - create a function

Synopsis

alias
alias [OPTIONS] NAME DEFINITION
alias [OPTIONS] NAME=DEFINITION

Description

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

alias rmi="rm -i"
# This is equivalent to entering the following function:
function rmi --wraps rm --description 'alias rmi=rm -i'
    rm -i $argv
end
# This needs to have the spaces escaped or "Chrome.app..."
# will be seen as an argument to "/Applications/Google":
alias chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome banana'

See more

and - conditionally execute a command

Synopsis

COMMAND1; and COMMAND2

Description

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

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

Example

make; and make install; or make clean

See Also

argparse - parse options passed to a fish script or function

Synopsis

argparse [OPTIONS] OPTION_SPEC... -- [ARG...]

Description

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

Usage

A simple example:

argparse --name=my_function '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 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.

The -- argument is required. You do not have to include any arguments after the -- but you must include the --. For example, this is acceptable:

set -l argv
argparse 'h/help' 'n/name' -- $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 --ignore-unknown) from the command arguments, so it is required.

Option Specifications

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

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

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

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 just call _validate_int without those flags is to simply check that the value is a valid integer with no limits on the min or max value allowed.

Example OPTION_SPECs

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.

If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr.

begin - start a new block of code

Synopsis

begin; [COMMANDS...;] end

Description

A block allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like and.

The block is unconditionally executed. begin; ...; end is equivalent to if true; ...; end.

begin does not change the current exit status itself. After the block has completed, $status will be set to the status returned by the most recent command.

Example

begin
    set -l PIRATE Yarrr
    ...
end
echo $PIRATE
# This will not output anything, since the PIRATE variable
# went out of scope at the end of the block

In the following code, all output is redirected to the file out.html.

begin
    echo $xml_header
    echo $html_header
    if test -e $file
        ...
    end
    ...
end > out.html

bg - send jobs to background

Synopsis

bg [PID...]

Description

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.

For compatibility with other shells, job expansion syntax is supported for bg. A PID of the format %1 will be interpreted as the PID of job 1. 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.

Example

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

bg %1 will background job 1.

bind - handle fish key bindings

Synopsis

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

Description

It can add bindings if given a SEQUENCE of characters to bind to. These should be written as fish escape sequences. The most important of these are \c for the control key, and \e for escape, and because of historical reasons also the Alt key (sometimes also called "Meta").

For example, Alt+W can be written as \ew, and Control+X (^X) can be written as \cx. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not fish.

The generic key binding that matches if no other binding does can be set by specifying a SEQUENCE of the empty string (that is, '' ). For most key bindings, it makes sense to bind this to the self-insert function (i.e. bind '' self-insert). This will insert any keystrokes not specifically bound to into the editor. Non-printable characters are ignored by the editor, so this will not result in control sequences being inserted.

If the -k switch is used, the name of a key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key_' prefix. (See terminfo(5) for more information, or use bind --key-names for a list of all available named keys). Normally this will print an error if the current $TERM entry doesn't have a given key, unless the -s switch is given.

To find out what sequence a key combination sends, 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 for a complete list of these input functions.

When COMMAND is a shellscript command, it is a good practice to put the actual code into a function and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well.

If a script produces output, it should finish by calling commandline -f repaint to tell fish that a repaint is in order.

Note that special input functions cannot be combined with ordinary shell script commands. The commands must be entirely a sequence of special input functions (from bind -f) or all shell script commands (i.e., valid fish script).

If no SEQUENCE is provided, all bindings (or just the bindings in the given MODE) are printed. If SEQUENCE is provided but no COMMAND, just the binding matching that sequence is printed.

To save custom keybindings, put the bind statements into config.fish. Alternatively, fish also automatically executes a function called fish_user_key_bindings if it exists.

Key bindings may use "modes", which mimics Vi's modal input behavior. The default mode is "default", and every bind applies to a single mode. The mode can be viewed/changed with the $fish_bind_mode variable.

Options

Special input functions

Additional functions

Examples

bind \cd 'exit'

Perform a history search when Page Up is pressed:

bind -k ppage history-search-backward

Turn on Vi key bindings and rebind Control+C to clear the input line:

set -g fish_key_bindings fish_vi_key_bindings
bind -M insert \cc kill-whole-line repaint

Launch git diff and repaint the commandline afterwards when Control+G is pressed:

bind \cg 'git diff; commandline -f repaint'

Terminal Limitations

For instance, 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) often sends \e\[C. These can differ from terminal to terminal, and the mapping is typically available in terminfo(5). Sometimes however a terminal identifies as e.g. xterm-256color for compatibility, but then implements xterm's sequences incorrectly.

Special Case: The Escape Character

Holding alt and something else also typically sends escape, for example holding alt+a will send an escape character and then an "a".

fish waits for a period after receiving the escape character, to determine whether it is standalone or part of an escape sequence. While waiting, additional key presses make the escape key behave as a meta key. If no other key presses come in, it is handled as a standalone escape. The waiting period is set to 30 milliseconds (0.03 seconds). It can be configured by setting the fish_escape_delay_ms variable to a value between 10 and 5000 ms. This can be a universal variable that you set once from an interactive session.

block - temporarily block delivery of events

Synopsis

block [OPTIONS...]

Description

In functions, block can be useful while performing work that should not be interrupted by the shell.

The block can be removed. Any events which triggered while the block was in place will then be delivered.

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

The following parameters 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

break - stop the current inner loop

Synopsis

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

Description

There are no parameters for break.

Example

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

See Also

breakpoint - launch debug mode

Synopsis

breakpoint

Description

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

There are no parameters for breakpoint.

builtin - run a builtin command

Synopsis

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

Description

The following parameters are available:

Example

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

case - conditionally execute a block of commands

Synopsis

switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end

Description

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

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

cd - change directory

Synopsis

cd [DIRECTORY]

Description

If DIRECTORY is supplied, it will become the new directory. If no parameter is given, the contents of the HOME environment variable will be used.

If DIRECTORY is a relative path, the paths found in the CDPATH list will be tried as prefixes for the specified path, in addition to $PWD.

Note that the shell will attempt to change directory without requiring cd if the name of a directory is provided (starting with ., / or ~, or ending with /).

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.

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

cdh - change to a recently visited directory

Synopsis

cdh [ directory ]

Description

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

command - run a program

Synopsis

command [OPTIONS] COMMANDNAME [ARGS...]

Description

The following options are available:

With the -s option, command treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found. Additionally passing a -q or --quiet option prevents any paths from being printed, like type -q, for testing only the exit status.

For basic compatibility with POSIX command, the -v flag is recognized as an alias for -s.

Examples

command -s ls returns the path to the ls program.

command -q git; and command git log runs git log only if git exists.

commandline - set or get the current command line buffer

Synopsis

commandline [OPTIONS] [CMD]

Description

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

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.

More examples:

>_ commandline -t
$flounder
>_ commandline -ct
$fl
>_ commandline -b # or just commandline
echo $flounder >&2 | less; and echo $catfish
>_ commandline -p
echo $flounder >&2
>_ commandline -j
echo $flounder >&2 | less

complete - edit command specific tab-completions

Synopsis

complete [( -c | --command | -p | --path )] COMMAND
        [( -c | --command | -p | --path ) COMMAND]...
        [( -e | --erase )]
        [( -s | --short-option ) SHORT_OPTION]...
        [( -l | --long-option | -o | --old-option ) LONG_OPTION]...
        [( -a | --arguments ) ARGUMENTS]
        [( -k | --keep-order )]
        [( -f | --no-files )]
        [( -F | --force-files )]
        [( -r | --require-parameter )]
        [( -x | --exclusive )]
        [( -w | --wraps ) WRAPPED_COMMAND]...
        [( -n | --condition ) CONDITION]
        [( -d | --description ) DESCRIPTION]
complete ( -C [STRING] | --do-complete[=STRING] )

Description

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

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.

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, you will have to trigger them first.

Examples

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

Show all completions for git.

contains - test if a word is present in a list

Synopsis

contains [OPTIONS] KEY [VALUES...]

Description

The following options are available:

Note that, like GNU tools and most of fish's builtins, contains interprets all arguments starting with a - as options to contains, until it reaches an argument that is -- (two dashes). See the examples below.

Example

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

This code will add some directories to $PATH if they aren't yet included:

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

While this will check if hasargs was run with the -q option:

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

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

continue - skip the remainder of the current iteration of the current inner loop

Synopsis

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

Description

Example

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

count - count the number of elements of a list

Synopsis

count $VARIABLE
COMMAND | count
count < FILE

Description

count does not accept any options, not even -h or --help.

count exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed.

Note that, like wc -l, reading from stdin counts newlines, so echo -n foo | count will print 0.

Example

count $PATH
# Returns the number of directories in the users PATH variable.
count *.txt
# Returns the number of files in the current working directory
# ending with the suffix '.txt'.
git ls-files --others --exclude-standard | count
# Returns the number of untracked files in a git repository
printf '%s\n' foo bar | count baz
# Returns 3 (2 lines from stdin plus 1 argument)
count < /etc/hosts
# Counts the number of entries in the hosts file

dirh - print directory history

Synopsis

dirh

Description

dirh 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

dirs - print directory stack

Synopsis

dirs
dirs -c

Description

With "-c", it clears the directory stack instead.

dirs does not accept any parameters.

See Also

disown - remove a process from the list of jobs

Synopsis

disown [ PID ... ]

Description

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.

Example

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

echo - display a line of text

Synopsis

echo [OPTIONS] [STRING]

Description

The following options are available:

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

Escape Sequences

Example

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

See Also

else - execute command if a condition is not met

Synopsis

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

Description

Example

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

emit - emit a generic event

Synopsis

emit EVENT_NAME [ARGUMENTS...]

Description

Example

function event_test --on-event test_event
    echo event test: $argv
end
emit test_event something

Notes

end - end a block of commands

Synopsis

begin; [COMMANDS...] end
function NAME [OPTIONS]; COMMANDS...; end
if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
while CONDITION; COMMANDS...; end
for VARNAME in [VALUES...]; COMMANDS...; end

Description

The end command does not change the current exit status. Instead, the status after it will be the status returned by the most recent command.

eval - evaluate the specified commands

Synopsis

eval [COMMANDS...]

Description

If your 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

set cmd ls \| cut -c 1-12
eval $cmd

exec - execute command in current process

Synopsis

exec COMMAND [OPTIONS...]

Description

Example

exit - exit the shell

Synopsis

exit [STATUS]

Description

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.

false - return an unsuccessful result

Synopsis

false

Description

See Also

fg - bring job to foreground

Synopsis

fg [PID]

Description

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.

Example

fg %3 will put job 3 into the foreground.

fish - the friendly interactive shell

Synopsis

fish [OPTIONS] [-c command] [FILE] [ARGUMENTS...]

Description

The following options are available:

The fish exit status is generally the exit status of the last foreground command.

Debugging

> 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 is set, execution tracing also outputs to stderr by default. You can output to a file using the --debug-output option:

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

These options can also be changed via the $FISH_DEBUG and $FISH_DEBUG_OUTPUT variables. The categories enabled via --debug are added to the ones 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.

fish_add_path - add to the path

Synopsis

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

Description

It is (by default) safe to use fish_add_path in config.fish, or it can be used once, interactively, and the paths will stay in future because of universal variables. This is a "do what I mean" style command, if you need more control, consider modifying the variable yourself.

Components are normalized by realpath. This means that trailing slashes are ignored and relative paths are made absolute (but symlinks are not resolved). If a component already exists, it is not added again and stays in the same place unless the --move switch is given.

Components are added in the order they are given, and they are prepended to the path unless --append is given (if $fish_user_paths is used, that means they are last in $fish_user_paths, which is itself prepended to $PATH, so they still stay ahead of the system paths).

If no component is new, the variable ($fish_user_paths or $PATH) is not set again or otherwise modified, so variable handlers are not triggered.

If a component 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.
> fish_add_path /opt/mycoolthing/bin
# I want my ~/.local/bin to be checked first.
> fish_add_path -m ~/.local/bin
# I prefer using a global fish_user_paths
> fish_add_path -g ~/.local/bin ~/.otherbin /usr/local/sbin
# I want to append to the entire $PATH because this directory contains fallbacks
> fish_add_path -aP /opt/fallback/bin
# I want to add the bin/ directory of my current $PWD (say /home/nemo/)
> fish_add_path -v bin/
set fish_user_paths /home/nemo/bin /usr/bin /home/nemo/.local/bin
# I have installed ruby via homebrew
> fish_add_path /usr/local/opt/ruby/bin

fish_breakpoint_prompt - define the prompt when stopped at a breakpoint

Synopsis

function fish_breakpoint_prompt
    ...
end

Description

The exit status of commands within fish_breakpoint_prompt will not modify the value of $status outside of the fish_breakpoint_prompt function.

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

Example

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

fish_command_not_found - what to do when a command wasn't found

Synopsis

function fish_command_not_found
    ...
end

Description

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

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

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

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

Or the simple default handler:

function fish_command_not_found
    __fish_default_command_not_found_handler $argv
end

Backwards compatibility

To define a handler that works in older versions of fish as well, define it the old way:

function __fish_command_not_found_handler --on-event fish_command_not_found
     echo COMMAND WAS NOT FOUND MY FRIEND $argv[1]
end

in which case fish will define a fish_command_not_found that calls it, or define a wrapper:

function fish_command_not_found
     echo "G'day mate, could not find your command: $argv"
end
function __fish_command_not_found_handler --on-event fish_command_not_found
     fish_command_not_found $argv
end

fish_config - start the web-based configuration interface

Synopsis

fish_config
fish_config browse
fish_config prompt (choose | list | save | show)

Description

Without arguments or with the browse command it starts the web-based configuration interface. The web interface allows you to view your functions, variables and history, and to make changes to your prompt and color configuration. It starts a local web server and opens a browser window. When you are finished, close the browser window and press the Enter key to terminate the configuration session.

If the BROWSER environment variable is set, it will be used as the name of the web browser to open instead of the system default.

With the prompt command fish_config can be used to view and choose a prompt from fish's sample prompts inside the terminal directly.

Available subcommands for the prompt command:

Example

fish_config prompt show demos the available sample prompts.

fish_config prompt choose disco makes the disco prompt the prompt for the current session. This can also be used in config.fish to set the prompt.

fish_config prompt save saves the current prompt to an autoloaded file.

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

fish_git_prompt - output git information for use in a prompt

Synopsis

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

Description

Git must be installed.

There are numerous customization options, which can be controlled with git options or fish variables. git options, where available, take precedence over the fish variable with the same function. git options can be set on a per-repository or global basis. git options can be set with the git config command, while fish variables can be set as usual with the set command.

A number of variables set characters and color used as indicators. Many of these have a different default if used with informative status enabled, or $__fish_git_prompt_use_informative_chars set. The usual default is given first, then the informative default (if it is different). If no default for the colors is given, they default to $__fish_git_prompt_color.

Some variables are only used in some modes, like when informative status is enabled:

Variables used with showdirtystate:

Variables used with showstashstate:

Variables used with showuntrackedfiles:

Variables used with showupstream (also implied by informative status):

Colors used with showcolorhints:

Note that all colors can also have a corresponding _done color. For example, the contents of $__fish_git_prompt_color_upstream_done is printed right _after_ the upstream.

See also fish_vcs_prompt, which will call all supported version control prompt functions, including git, Mercurial and Subversion.

Example

function fish_prompt
    # ...
    set -g __fish_git_prompt_showupstream auto
    printf '%s %s$' $PWD (fish_git_prompt)
end

fish_greeting - display a welcome message in interactive shells

Synopsis

function fish_greeting
    ...
end

Description

The default fish_greeting is a function that prints a variable of the same name ($fish_greeting), so you can also just change that if you just want to change the text.

While you could also just put echo calls into config.fish, fish_greeting takes care of only being used in interactive shells, so it won't be used e.g. with scp (which executes a shell), which prevents some errors.

Example

function fish_greeting
    echo Hello friend!
    echo The time is (set_color yellow; date +%T; set_color normal) and this machine is called $hostname
end

fish_hg_prompt - output Mercurial information for use in a prompt

Synopsis

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

Description

Mercurial (hg) must be installed.

By default, only the current branch is shown because hg status can be slow on a large repository. You can enable a more informative prompt by setting the variable $fish_prompt_hg_show_informative_status, for example:

set --universal fish_prompt_hg_show_informative_status

If you enabled the informative status, there are numerous customization options, which can be controlled with fish variables.

Some colors for status symbols:

The status symbols themselves:

Finally, $fish_prompt_hg_status_order, which can be used to change the order the status symbols appear in. It defaults to added modified copied deleted untracked unmerged.

See also fish_vcs_prompt, which will call all supported version control prompt functions, including git, Mercurial and Subversion.

Example

function fish_prompt
    ...
    set -g fish_prompt_hg_show_informative_status
    printf '%s %s$' $PWD (fish_hg_prompt)
end

fish_indent - indenter and prettifier

Synopsis

fish_indent [OPTIONS] [FILE...]

Description

The following options are available:

fish_is_root_user - check if the current user is root

Synopsis

fish_is_root_user

Description

Example

function example --description 'Just an example'
    if fish_is_root_user
        do_something_different
    end
end

fish_key_reader - explore what characters keyboard keys send

Synopsis

fish_key_reader [OPTIONS]

Description

The tool will write an example bind command matching the character sequence captured to stdout. If the character sequence matches a special key name (see bind --key-names), both bind CHARS ... and bind -k KEYNAME ... usage will be shown. Additional details about the characters received, such as the delay between chars, are written to stderr.

The following options are available:

Usage Notes

fish_key_reader intentionally disables handling of many signals. To terminate fish_key_reader in --continuous mode do:

fish_mode_prompt - define the appearance of the mode indicator

Synopsis

function fish_mode_prompt
     echo -n "$fish_bind_mode "
end

Description

The default fish_mode_prompt function will output indicators about the current Vi editor mode displayed to the left of the regular prompt. Define your own function to customize the appearance of the mode indicator. The $fish_bind_mode variable can be used to determine the current mode. It will be one of default, insert, replace_one, or visual.

You can also define an empty fish_mode_prompt function to remove the Vi mode indicators:

function fish_mode_prompt; end
funcsave fish_mode_prompt

fish_mode_prompt will be executed when the vi mode changes. If it produces any output, it is displayed and used. If it does not, the other prompt functions (fish_prompt and fish_right_prompt) will be executed as well in case they contain a mode display.

Example

function fish_mode_prompt
  switch $fish_bind_mode
    case default
      set_color --bold red
      echo 'N'
    case insert
      set_color --bold green
      echo 'I'
    case replace_one
      set_color --bold green
      echo 'R'
    case visual
      set_color --bold brmagenta
      echo 'V'
    case '*'
      set_color --bold red
      echo '?'
  end
  set_color normal
end

Outputting multiple lines is not supported in fish_mode_prompt.

fish_opt - create an option spec for the argparse command

Synopsis

fish_opt [ -h | --help ]
fish_opt ( -s X | --short=X ) [ -l LONG | --long=LONG ] [ --long-only ] [ -o | --optional-val ] [ -r | --required-val ] [ --multiple-vals ]

Description

The following argparse options are available:

Examples

set -l options (fish_opt -s h -l help)
argparse $options -- $argv

Same as above but with a second flag that requires a value:

set -l options (fish_opt -s h -l help)
set options $options (fish_opt -s m -l max --required-val)
argparse $options -- $argv

Same as above but with a third flag that can be given multiple times saving the value of each instance seen and only the long flag name (--token) can be used:

set -l options (fish_opt --short=h --long=help)
set options $options (fish_opt --short=m --long=max --required-val)
set options $options (fish_opt --short=t --long=token --multiple-vals --long-only)
argparse $options -- $argv

fish_prompt - define the appearance of the command line prompt

Synopsis

function fish_prompt
    ...
end

Description

The exit status of commands within fish_prompt will not modify the value of $status outside of the fish_prompt function.

fish ships with a number of example prompts that can be chosen with the fish_config command.

Example

function fish_prompt -d "Write out the prompt"
    # This shows up as USER@HOST /home/user/ >, with the directory colored
    # $USER and $hostname are set by fish, so you can just use them
    # instead of using `whoami` and `hostname`
    printf '%s@%s %s%s%s > ' $USER $hostname \
        (set_color $fish_color_cwd) (prompt_pwd) (set_color normal)
end

fish_right_prompt - define the appearance of the right-side command line prompt

Synopsis

function fish_right_prompt
    ...
end

Description

Multiple lines are not supported in fish_right_prompt.

Example

function fish_right_prompt -d "Write out the right prompt"
    date '+%m/%d/%y'
end

fish_status_to_signal - Convert exit codes to human-friendly signals

Synopsis

function fish_prompt
    echo -n (fish_status_to_signal $pipestatus | string join '|') (prompt_pwd) '$ '
end

Description

Example

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

fish_svn_prompt - output Subversion information for use in a prompt

Synopsis

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

Description

Subversion (svn) must be installed.

There are numerous customization options, which can be controlled with fish variables.

A number of variables control the symbol ("display") and color ("color") for the different status indicators:

See also fish_vcs_prompt, which will call all supported version control prompt functions, including git, Mercurial and Subversion.

Example

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

fish_title - define the terminal's title

Synopsis

function fish_title
    ...
end

Description

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

This requires that your terminal supports programmable titles and the feature is turned on.

Example

function fish_title
    set -q argv[1]; or set argv fish
    # Looks like ~/d/fish: git log
    # or /e/apt: fish
    echo (fish_prompt_pwd_dir_length=1 prompt_pwd): $argv;
end

fish_update_completions - update completions using manual pages

Synopsis

fish_update_completions

Description

This does not overwrite custom completions.

There are no parameters for fish_update_completions.

fish_vcs_prompt - output version control system information for use in a prompt

Synopsis

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

Description

It calls out to VCS-specific functions. The currently supported systems are:

If a VCS isn't installed, the respective function does nothing.

The svn prompt is disabled by default because it's slow on large svn repositories. To enable it, modify fish_vcs_prompt to uncomment it. See funced.

For more information, see the documentation for each of the functions above.

Example

function fish_prompt
    ...
    set -g __fish_git_prompt_showupstream auto
    printf '%s %s$' $PWD (fish_vcs_prompt)
end

for - perform a set of commands multiple times

Synopsis

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

Description

Example

for i in foo bar baz; echo $i; end
# would output:
foo
bar
baz

Notes

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

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

funced - edit a function interactively

Synopsis

funced [OPTIONS] NAME

Description

If the $VISUAL environment variable is set, it will be used as the program to edit the function. If $VISUAL is unset but $EDITOR is set, that will be used. Otherwise, a built-in editor will be used. Note that to enter a literal newline using the built-in editor you should press Alt+Enter. Pressing Enter signals that you are done editing the function. This does not apply to an external editor like emacs or vim.

If there is no function called NAME a new function will be created with the specified name

Example

Run:

>_ funced fish_prompt

This will open up your editor, allowing you to modify the function. When you're done, save and quit. Fish will reload the function, so you should see the changes right away.

When you're done, use:

>_ funcsave fish_prompt

For more, see funcsave.

funcsave - save the definition of a function to the user's autoload directory

Synopsis

funcsave FUNCTION_NAME
funcsave [(-d | --directory) where/to/save ] FUNCTION_NAME

Description

Note that because fish loads functions on-demand, saved functions will not function as event handlers until they are run or sourced otherwise. To activate an event handler for every new shell, add the function to your configuration file instead of using funcsave.

This is typically used together with funced, which will open the function in your editor and load it in the current seession afterwards.

function - create a function

Synopsis

function NAME [OPTIONS]; BODY; end

Description

A function is a list of commands that will be executed when the name of the function is given as a command.

The following options are available:

If the user enters any additional arguments after the function, they are inserted into the environment variable list $argv. If the --argument-names option is provided, the arguments are also assigned to names specified in that option.

By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the emit builtin. Fish generates the following named events:

Example

function ll
    ls -l $argv
end

will run the ls command, using the -l option, while passing on any additional files and switches to ls.

function mkdir -d "Create a directory and set CWD"
    command mkdir $argv
    if test $status = 0
        switch $argv[(count $argv)]
            case '-*'
            case '*'
                cd $argv[(count $argv)]
                return
        end
    end
end

This will run the mkdir command, and if it is successful, change the current working directory to the one just created.

function notify
    set -l job (jobs -l -g)
    or begin; echo "There are no jobs" >&2; return 1; end
    function _notify_job_$job --on-job-exit $job --inherit-variable job
        echo -n \a # beep
        functions -e _notify_job_$job
    end
end

This will beep when the most recent job completes.

Notes

See more

functions - print or erase functions

Synopsis

functions [ -a | --all ] [ -n | --names ]
functions [ -D | --details ] [ -v ] FUNCTION
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [ -e | -q ] FUNCTIONS...

Description

The following options are available:

You should not assume that only five lines will be written since we may add additional information to the output in the future.

The default behavior of functions, when called with no arguments, is to print the names of all defined functions. Unless the -a option is given, no functions starting with underscores are included in the output.

If any non-option parameters are given, the definition of the specified functions are printed.

Copying a function using -c copies only the body of the function, and does not attach any event notifications from the original function.

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

The exit status of functions is the number of functions specified in the argument list that do not exist, which can be used in concert with the -q option.

Examples

functions -n
# Displays a list of currently-defined functions
functions -c foo bar
# Copies the 'foo' function to a new function called 'bar'
functions -e bar
# Erases the function ``bar``

See more

help - display fish documentation

Synopsis

help [SECTION]

Description

If a SECTION is specified, the help for that command is shown.

If the BROWSER environment variable is set, it will be used to display the documentation. Otherwise, fish will search for a suitable browser.

If you prefer to use a different browser (other than as described above) for fish help, you can set the fish_help_browser variable. This variable may be set as a list, where the first element is the browser command and the rest are browser options.

Note that most builtin commands display their help in the terminal when given the --help option.

Example

history - show and manipulate command history

Synopsis

history [ search ] [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] [ --max=n ] [ --null ] [ -R | --reverse ] [ "search string"... ]
history delete [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] "search string"...
history merge
history save
history clear
history ( -h | --help )

Description

The following operations (sub-commands) are available:

The following options are available:

These flags can appear before or immediately after one of the sub-commands listed above.

Example

history clear
# Deletes all history items
history search --contains "foo"
# Outputs a list of all previous commands containing the string "foo".
history delete --prefix "foo"
# Interactively deletes commands which start with "foo" from the history.
# You can select more than one entry by entering their IDs separated by a space.

Customizing the name of the history file

You can set the fish_history variable to another name for the current shell session. The default value (when the variable is unset) is fish which corresponds to $XDG_DATA_HOME/fish/fish_history. If you set it to e.g. fun, the history would be written to $XDG_DATA_HOME/fish/fun_history. An empty string means history will not be stored at all. This is similar to the private session features in web browsers.

You can change fish_history at any time (by using set -x fish_history "session_name") and it will take effect right away. If you set it to "default", it will use the default session name (which is "fish").

Other shells such as bash and zsh use a variable named HISTFILE for a similar purpose. Fish uses a different name to avoid conflicts and signal that the behavior is different (session name instead of a file path). Also, if you set the var to anything other than fish or default it will inhibit importing the bash history. That's because the most common use case for this feature is to avoid leaking private or sensitive history when giving a presentation.

Notes

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

if - conditionally execute a command

Synopsis

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

Description

You can use and or or in the condition. See the second example below.

The exit status of the last foreground command to exit can always be accessed using the $status variable.

Example

if test -f foo.txt
    echo foo.txt exists
else if test -f bar.txt
    echo bar.txt exists
else
    echo foo.txt and bar.txt do not exist
end

The following code will print "foo.txt exists and is readable" if foo.txt is a regular file and readable

if test -f foo.txt
   and test -r foo.txt
   echo "foo.txt exists and is readable"
end

isatty - test if a file descriptor is a terminal

Synopsis

isatty [FILE DESCRIPTOR]

Description

FILE DESCRIPTOR may be either the number of a file descriptor, or one of the strings stdin, stdout, or stderr. If not specified, zero is assumed.

If the specified file descriptor is a terminal device, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error.

Examples

isatty
isatty stdout
isatty 2
echo | isatty 1

And these will exit non-zero:

echo | isatty
isatty 9
isatty stdout > file
isatty 2 2> file

jobs - print currently running jobs

Synopsis

jobs [OPTIONS] [ PID | %JOBID ]

Description

jobs accepts the following switches:

On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100%.

Arguments of the form PID or %JOBID restrict the output to jobs with the selected process identifiers or job numbers respectively.

If the output of jobs is redirected or if it is part of a command substitution, the column header that is usually printed is omitted, making it easier to parse.

The exit status of jobs is 0 if there are running background jobs and 1 otherwise.

Example

Job Group   State   Command
2   26012   running nc -l 55232 < /dev/random &
1   26011   running python tests/test_11.py &

math - perform mathematics calculations

Synopsis

math [-sN | --scale=N] [-bBASE | --base=BASE] [--] EXPRESSION

Description

By default, the output is a floating-point number with trailing zeroes trimmed. To get a fixed representation, the --scale option can be used, including --scale=0 for integer output.

Keep in mind that parameter expansion happens before expressions are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis (()) and the asterisk (*) glob character have to be escaped or quoted. x can also be used to denote multiplication, but it needs to be followed by whitespace to distinguish it from hexadecimal numbers.

Parentheses for functions are optional - math sin pi prints 0. However, a comma will bind to the inner function, so math pow sin 3, 5 is an error because it tries to give sin the arguments 3 and 5. When in doubt, use parentheses.

math ignores whitespace between arguments and takes its input as multiple arguments (internally joined with a space), so math 2 +2 and math "2 + 2" work the same. math 2 2 is an error.

The following options are available:

Return Values

Syntax

For numbers, . is always the radix character regardless of locale - 2.5, not 2,5. Scientific notation (10e5) and hexadecimal (0xFF) are also available.

Operators

They are all used in an infix manner - 5 + 2, not + 5 2.

Constants

Use them without a leading $ - pi - 3 should be about 0.

Functions

All of the trigonometric functions use radians (the pi-based scale, not 360°).

Examples

math $status - 128 outputs the numerical exit status of the last command minus 128.

math 10 / 6 outputs 1.666667.

math -s0 10.0 / 6.0 outputs 1.

math -s3 10 / 6 outputs 1.666.

math "sin(pi)" outputs 0.

math 5 \* 2 or math "5 * 2" or math 5 "*" 2 all output 10.

math 0xFF outputs 255, math 0 x 3 outputs 0 (because it computes 0 multiplied by 3).

math bitand 0xFE, 0x2e outputs 46.

math "bitor(9,2)" outputs 11.

math --base=hex 192 prints 0xc0.

math 'ncr(49,6)' prints 13983816 - that's the number of possible picks in 6-from-49 lotto.

Compatibility notes

You don't need to use -- before the expression, even if it begins with a minus sign which might otherwise be interpreted as an invalid option. If you do insert -- before the expression, it will cause option scanning to stop just like for every other command and it won't be part of the expression.

nextd - move forward through directory history

Synopsis

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

Description

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

Note that the cd command limits directory history to the 25 most recently visited directories. The history is stored in the $dirprev and $dirnext variables which this command manipulates.

Example

cd /usr/src
# Working directory is now /usr/src
cd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
prevd
# Working directory is now /usr/src
nextd
# Working directory is now /usr/src/fish-shell

See Also

not - negate the exit status of a job

Synopsis

not COMMAND [OPTIONS...]

Description

Example

if not test -f spoon
    echo There is no spoon
    exit 1
end

open - open file in its default application

Synopsis

open FILES...

Description

Note that this function will not be used if a command by this name exists (which is the case on macOS or Haiku).

Example

or - conditionally execute a command

Synopsis

COMMAND1; or COMMAND2

Description

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

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

Example

make; and make install; or make clean

See Also

popd - move through directory stack

Synopsis

popd

Description

Example

pushd /usr/src
# Working directory is now /usr/src
# Directory stack contains /usr/src
pushd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
# Directory stack contains /usr/src /usr/src/fish-shell
popd
# Working directory is now /usr/src
# Directory stack contains /usr/src

See Also

prevd - move backward through directory history

Synopsis

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

Description

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

Note that the cd command limits directory history to the 25 most recently visited directories. The history is stored in the $dirprev and $dirnext variables which this command manipulates.

Example

cd /usr/src
# Working directory is now /usr/src
cd /usr/src/fish-shell
# Working directory is now /usr/src/fish-shell
prevd
# Working directory is now /usr/src
nextd
# Working directory is now /usr/src/fish-shell

See Also

printf - display text according to a format string

Synopsis

printf FORMAT [ARGUMENT ...]

Description

The format argument is re-used as many times as necessary to convert all of the given arguments. So printf %s\n flounder catfish clownfish shark will print four lines.

Unlike echo, printf does not append a new line unless it is specified as part of the string.

It doesn't support any options, so there is no need for a -- separator, which makes it easier to use for arbitrary input than echo. [1]

Format Specifiers

%% signifies a literal "%".

Conversion can fail, e.g. "102.234" can't losslessly convert to an integer, causing printf to print an error. If you are okay with losing information, silence errors with 2>/dev/null.

A number between the % and the format letter specifies the width. The result will be left-padded with spaces.

Backslash Escapes

Errors and Return Status

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

This printf has been imported from the printf in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try command printf.

Example

printf '%s\t%s\n' flounder fish

Will print "flounder fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character.

printf '%s: %d' "Number of bananas in my pocket" 42

Will print "Number of bananas in my pocket: 42", without a newline.

See Also

Footnotes

[1]

(in fact while fish's echo supports --, POSIX forbids it, so other implementations can't be used if the input contains anything starting with -)

prompt_login - describe the login suitable for prompt

Synopsis

function fish_prompt
    echo -n (prompt_login) (prompt_pwd) '$ '
end

Description

Examples

>_ prompt_login
root@bananablaster

prompt_pwd - print pwd suitable for prompt

Synopsis

function fish_prompt
    echo -n (prompt_pwd) '$ '
end

Description

To change the number of characters per path component, set $fish_prompt_pwd_dir_length to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely.

Examples

>_ cd ~/
>_ echo $PWD
/home/alfa
>_ prompt_pwd
~
>_ cd /tmp/banana/sausage/with/mustard
>_ prompt_pwd
/t/b/s/w/mustard
>_ set -g fish_prompt_pwd_dir_length 3
>_ prompt_pwd
/tmp/ban/sau/wit/mustard

psub - perform process substitution

Synopsis

COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [-s SUFFIX])

Description

The following options are available:

Example

diff (sort a.txt | psub) (sort b.txt | psub)
# shows the difference between the sorted versions of files ``a.txt`` and ``b.txt``.
source-highlight -f esc (cpp main.c | psub -f -s .c)
# highlights ``main.c`` after preprocessing as a C source.

pushd - push directory to directory stack

Synopsis

pushd [DIRECTORY]

Description

Without arguments, it exchanges the top two directories in the stack.

pushd +NUMBER rotates the stack counter-clockwise i.e. from bottom to top

pushd -NUMBER rotates clockwise i.e. top to bottom.

Example

cd ~/dir1
pushd ~/dir2
pushd ~/dir3
# Working directory is now ~/dir3
# Directory stack contains ~/dir2 ~/dir1
pushd /tmp
# Working directory is now /tmp
# Directory stack contains ~/dir3 ~/dir2 ~/dir1
pushd +1
# Working directory is now ~/dir3
# Directory stack contains ~/dir2 ~/dir1 /tmp
popd
# Working directory is now ~/dir2
# Directory stack contains ~/dir1 /tmp

See Also

pwd - output the current working directory

Synopsis

pwd [(-P | --physical)] [(-L | --logical)]

Description

The following options are available:

See Also

random - generate random number

Synopsis

random
random SEED
random START END
random START STEP END
random choice [ITEMS...]

Description

If one argument is specified, the internal engine will be seeded with the argument for future invocations of random and no output will be produced.

Two arguments indicate a range from START to END (both START and END included).

Three arguments indicate a range from START to END with a spacing of STEP between possible outputs. random choice will select one random item from the succeeding arguments.

Note that seeding the engine will NOT give the same result across different systems.

You should not consider random cryptographically secure, or even statistically accurate.

Example

for i in (seq (random 10 2 20) -1 1)
    echo $i
end

And this will open a random picture from any of the subdirectories:

open (random choice **.jpg)

Or, to only get even numbers from 2 to 20:

random 2 2 20

Or odd numbers from 1 to 3:

random 1 2 3 # or 1 2 4

read - read line of input into variables

Synopsis

read [OPTIONS] [VARIABLE ...]

Description

The following options are available:

Without the --line option, read reads a single line of input from standard input, breaks it into tokens, and then assigns one token to each variable specified in VARIABLES. If there are more tokens than variables, the complete remainder is assigned to the last variable.

If no option to determine how to split like --delimiter, --line or --tokenize is given, the variable IFS is used as a list of characters to split on. Relying on the use of IFS is deprecated and this behaviour will be removed in future versions. The default value of IFS contains space, tab and newline characters. As a special case, if IFS is set to the empty string, each character of the input is considered a separate token.

With the --line option, read reads a line of input from standard input into each provided variable, stopping when each variable has been filled. The line is not tokenized.

If no variable names are provided, read enters a special case that simply provides redirection from standard input to standard output, useful for command substitution. For instance, the fish shell command below can be used to read data that should be provided via a command line argument from the console instead of hardcoding it in the command itself, allowing the command to both be reused as-is in various contexts with different input values and preventing possibly sensitive text from being included in the shell history:

mysql -uuser -p(read)

When running in this mode, read does not split the input in any way and text is redirected to standard output without any further processing or manipulation.

If -a or --array is provided, only one variable name is allowed and the tokens are stored as a list in this variable.

See the documentation for set for more details on the scoping rules for variables.

When read reaches the end-of-file (EOF) instead of the terminator, the exit status is set to 1. Otherwise, it is set to 0.

In order to protect the shell from consuming too many system resources, read will only consume a maximum of 100 MiB (104857600 bytes); if the terminator is not reached before this limit then VARIABLE is set to empty and the exit status is set to 122. This limit can be altered with the fish_read_limit variable. If set to 0 (zero), the limit is removed.

Example

echo hello|read foo
# This is a neat way to handle command output by-line:
printf '%s\n' line1 line2 line3 line4 | while read -l foo
                  echo "This is another line: $foo"
              end
# Delimiters given via "-d" are taken as one string
echo a==b==c | read -d == -l a b c
echo $a # a
echo $b # b
echo $c # c
# --tokenize honors quotes and escaping like the shell's argument passing:
echo 'a\ b' | read -t first second
echo $first # outputs "a b", $second is empty
echo 'a"foo bar"b (command echo wurst)*" "{a,b}' | read -lt -l a b c
echo $a # outputs 'afoo bar' (without the quotes)
echo $b # outputs '(command echo wurst)* {a,b}' (without the quotes)
echo $c # nothing

realpath - convert a path to an absolute path without symlinks

Synopsis

realpath PATH

Description

fish provides a realpath builtin as a fallback for systems where there is no realpath command, your OS might provide a version with more features.

If a realpath command exists, it will be preferred, so if you want to use the builtin you should use builtin realpath explicitly.

The following options are available:

return - stop the current inner function

Synopsis

function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end

Description

It is usually added inside of a conditional block such as an if statement or a switch statement to conditionally stop the executing function and return to the caller, but it can also be used to specify the exit status of a function.

Example

function false
    return 1
end

set - display and change shell variables

Synopsis

set [SCOPE_OPTIONS]
set [OPTIONS] VARIABLE_NAME VALUES...
set [OPTIONS] VARIABLE_NAME[INDICES]... VALUES...
set ( -q | --query ) [SCOPE_OPTIONS] VARIABLE_NAMES...
set ( -e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME...
set ( -e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]...
set ( -S | --show ) [VARIABLE_NAME]...

Description

If both a variable name and values are provided, set assigns the values to the variable of that name. Because all variables in fish are lists, multiple values are allowed.

If only a variable name has been given, set sets the variable to the empty list.

If set is called with no arguments, it prints the names and values of all shell variables in sorted order. Passing scope or export flags allows filtering this to only matching variables, so set --local would only show local variables.

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

With --show, set will describe the given variable names, explaining how they have been defined - in which scope with which values and options.

The following options control variable scope:

These options control additional variable options:

The following other options are available:

If a variable is set to more than one value, the variable will be a list with the specified elements. If a variable is set to zero elements, it will become a list with zero elements.

If the variable name is one or more list elements, such as PATH[1 3 7], only those list elements specified will be changed. If you specify a negative index when expanding or assigning to a list variable, the index will be calculated from the end of the list. For example, the index -1 means the last index of a list.