Introduction¶
This is the documentation for fish, the friendly interactive shell.
A shell is a program that helps you operate your computer by starting other programs. fish offers a command-line interface focused on usability and interactive use.
Unlike other shells, fish does not follow the POSIX standard, but still uses roughly the same model.
Some of the special features of fish are:
Extensive UI: Syntax highlighting, autosuggestions, tab completion and selection lists that can be navigated and filtered.
No configuration needed: fish is designed to be ready to use immediately, without requiring extensive configuration.
Easy scripting: New functions can be added on the fly. The syntax is easy to learn and use.
This page gives an overview of fish's features, syntax, and interface. If this is your first time using fish, see the tutorial.
If you are already familiar with other shells like bash and want to see the scripting differences, see Fish For Bash Users.
Installation and Start¶
This section describes how to install, uninstall, start, and exit the fish shell. It also explains how to make fish the default shell.
Installation¶
Up-to-date instructions for installing the latest version of fish are on the fish homepage.
To install the development version of fish, see the instructions on the project's GitHub page.
Starting and Exiting¶
Once fish has been installed, open a terminal. If fish is not the default shell:
Type
fishto start a fish shell:> fish
Type
exitto exit a fish shell:> exit
Executing Bash¶
If fish is your default shell and you want to copy commands from the internet that are written in bash (the default shell on most systems), you can proceed in one of the following two ways:
Use the
bashcommand with the-cswitch to read from a string:> bash -c 'some bash command'
Use
bashwithout a switch to open a bash shell you can use andexitafterward:> bash $ some bash command $ exit > _
Default Shell¶
To make fish your default shell:
Add the line
/usr/local/bin/fishto/etc/shells.Change your default shell with
chsh -s /usr/local/bin/fish.
For detailed instructions see Switching to fish.
Uninstalling¶
For uninstalling fish: see FAQ: Uninstalling fish.
Shebang Line¶
Because shell scripts are written in many different languages, they need to carry information about which interpreter should be used to execute them. For this, they are expected to have a first line, the shebang line, which names the interpreter executable.
A script written in bash would need a first line like this:
#!/bin/bash
When the shell tells the kernel to execute the file, it will use the 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!).
Syntax Overview¶
Shells like fish are used by giving them commands. Every fish command follows the same basic syntax. A command is executed by writing the name of the command followed by any arguments. For example:
echo hello world
This calls the echo command. echo writes its arguments to the screen. In the example above, 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:
cd: Change the current directory
ls: List files and directoriesman: Display a manual pagemv: Move (rename) filescp: Copy filesopen: Open files with the default application associated with each filetype
less: Display the contents of files
Commands and arguments are separated by the space character ' '. Every command ends with either a newline (by pressing the return key) or a semicolon ;. Multiple commands can be written on the same line by separating them with semicolons.
A switch is a very common special type of argument. Switches almost always start with one or more hyphens - and alter the way a command operates. For example, the ls command usually lists the names of all files and directories in the current working directory. By using the -l switch, the behavior of ls is changed to not only display the filename, but also the size, permissions, owner, and modification time of each file.
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¶
Here we define some of the terms used on this page and throughout the rest of the fish documentation:
Argument: A parameter given to a command.
Builtin: A command that is implemented by the shell. Builtins are so closely tied to the operation of the shell that it is impossible to implement them as external commands.
Command: A program that the shell can run, or more specifically an external program that the shell runs in another process.
Function: A block of commands that can be called as if they were a single command. By using functions, it is possible to string together multiple simple commands into one more advanced command.
Job: A running pipeline or command.
Pipeline: A set of commands strung together so that the output of one command is the input of the next command.
Redirection: An operation that changes one of the input or output streams associated with a job.
Switch or Option: A special kind of argument that alters the behavior of a command. A switch almost always begins with one or two hyphens.
Quotes¶
Sometimes features like parameter expansion and character escapes get in the way. When that happens, you can use quotes, either single (') or double ("). Between single quotes, fish performs no expansions. Between double quotes, fish only performs variable expansion. No other kind of expansion (including brace expansion or parameter expansion) is performed, and escape sequences (for example, \n) are ignored. Within quotes, whitespace is not used to separate arguments, allowing quoted arguments to contain spaces.
The only meaningful escape sequences in single quotes are \', which escapes a single quote and \\, which escapes the backslash symbol. The only meaningful escapes in double quotes are \", which escapes a double quote, \$, which escapes a dollar character, \ followed by a newline, which deletes the backslash and the newline, and \\, which escapes the backslash symbol.
Single quotes have no special meaning within double quotes and vice versa.
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 cannot be written directly on the command line. For these characters, so-called escape sequences are provided. These are:
\arepresents the alert character.\erepresents the escape character.\frepresents the form feed character.\nrepresents a newline character.\rrepresents the carriage return character.\trepresents the tab character.\vrepresents the vertical tab character.\xHH, whereHHis a hexadecimal number, represents the ASCII character with the specified value. For example,\x9is the tab character.\XHH, whereHHis a hexadecimal number, represents a byte of data with the specified value. If you are using a multibyte encoding, this can be used to enter invalid strings. Only use this if you know what you are doing.\ooo, whereooois an octal number, represents the ASCII character with the specified value. For example,\011is the tab character.\uXXXX, whereXXXXis a hexadecimal number, represents the 16-bit Unicode character with the specified value. For example,\u9is the tab character.\UXXXXXXXX, whereXXXXXXXXis a hexadecimal number, represents the 32-bit Unicode character with the specified value. For example,\U9is the tab character.\cX, whereXis a letter of the alphabet, represents the control sequence generated by pressing the control key and the specified letter. For example,\ciis the tab character
Some characters have special meaning to the shell. For example, an apostrophe ' disables expansion (see Quotes). To tell the shell to treat these characters literally, escape them with a backslash. For 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:
\(backslash space) escapes the space character. This keeps the shell from splitting arguments on the escaped space.\$escapes the dollar character.\\escapes the backslash character.\*escapes the star character.\?escapes the question mark character (this is not necessary if theqmark-noglobfeature flag is enabled).\~escapes the tilde character.\#escapes the hash character.\(escapes the left parenthesis character.\)escapes the right parenthesis character.\{escapes the left curly bracket character.\}escapes the right curly bracket character.\[escapes the left bracket character.\]escapes the right bracket character.\<escapes the less than character.\>escapes the more than character.\^escapes the circumflex character.\&escapes the ampersand character.\|escapes the vertical bar character.\;escapes the semicolon character.\"escapes the quote character.\'escapes the apostrophe character.
Input/Output Redirection¶
Most programs use three input/output (I/O) streams:
Standard input (stdin) for reading. Defaults to reading from the keyboard.
Standard output (stdout) for writing output. Defaults to writing to the screen.
Standard error (stderr) for writing errors and warnings. Defaults to writing to the screen.
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.
To read standard input from a file, use
<SOURCE_FILE.To write standard output to a file, use
>DESTINATION.To write standard error to a file, use
2>DESTINATION. 1To append standard output to a file, use
>>DESTINATION_FILE.To append standard error to a file, use
2>>DESTINATION_FILE.To not overwrite ("clobber") an existing file, use
>?DESTINATIONor2>?DESTINATION. This is known as the "noclobber" redirection.
DESTINATION can be one of the following:
A filename. The output will be written to the specified file. Often
>/dev/nullto silence output by writing it to the special "sinkhole" file.An ampersand (
&) followed by the number of another file descriptor like&2for standard error. The output will be written to the destination descriptor.An ampersand followed by a minus sign (
&-). The file descriptor will be closed.
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.
To redirect the input of descriptor N, use
N<DESTINATION.To redirect the output of descriptor N, use
N>DESTINATION.To append the output of descriptor N to a file, use
N>>DESTINATION_FILE.
For example, echo hello 2> output.stderr writes the standard error (file descriptor 2) to output.stderr.
- 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¶
Another way to redirect streams is a pipe. A pipe connects streams with each other. Usually the standard output of one command is connected with the standard input of another. This is done by separating commands with the pipe character |. For example:
cat foo.txt | head
The command cat foo.txt sends the contents of foo.txt to stdout. This output is provided as input for the head program, which prints the first 10 lines of its input.
It is possible to pipe a different output file descriptor by prepending its FD number and the output redirect symbol to the pipe. For example:
make fish 2>| less
will attempt to build fish, and any errors will be shown using the less pager. 2
As a convenience, the pipe &| redirects both stdout and stderr to the same process. Note that this is different from bash, which uses |&.
- 2
A "pager" here is a program that takes output and "paginates" it.
lessdoesn't just do pages, it allows arbitrary scrolling (even back!).
Job control¶
When you start a job in fish, fish itself will pause, and give control of the terminal to the program just started. Sometimes, you want to continue using the commandline, and have the job run in the background. To create a background job, append an & (ampersand) to your command. This will tell fish to run the job in the background. Background jobs are very useful when running programs that have a graphical user interface.
Example:
emacs &
will start the emacs text editor in the background. fg can be used to bring it into the foreground again when needed.
Most programs allow you to suspend the program's execution and return control to fish by pressing 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.
Note that 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¶
Functions are programs written in the fish syntax. They group together various commands and their arguments using a single name.
For example, here's a simple function to list directories:
function ll
ls -l $argv
end
The first line tells fish to define a function by the name of ll, so it can be used by simply writing ll on the commandline. The second line tells fish that the command ls -l $argv should be called when ll is 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¶
One of the most common uses for functions is to slightly alter the behavior of an already existing command. For example, one might want to redefine the ls command to display colors. The switch for turning on colors on GNU systems is --color=auto. An alias, or wrapper, around ls might look like this:
function ls
command ls --color=auto $argv
end
There are a few important things that need to be noted about aliases:
Always take care to add the $argv variable to the list of parameters to the wrapped command. This makes sure that if the user specifies any additional parameters to the function, they are passed on to the underlying command.
If the alias has the same name as the aliased command, you need to prefix the call to the program with
commandto tell fish that the function should not call itself, but rather a command with the same name. If you forget to do so, the function would call itself until the end of time. Usually fish is smart enough to figure this out and will refrain from doing so (which is hopefully in your interest).Autoloading isn't applicable to aliases. Since, by definition, the function is created at the time the alias command is executed. You cannot autoload 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¶
Functions can be defined on the commandline or in a configuration file, but they can also be automatically loaded. This has some advantages:
An autoloaded function becomes available automatically to all running shells.
If the function definition is changed, all running shells will automatically reload the altered version, after a while.
Startup time and memory usage is improved, etc.
When fish needs to load a function, it searches through any directories in the list variable $fish_function_path for a file with a name consisting of the name of the function plus the suffix .fish and loads the first it finds.
By default $fish_function_path contains the following:
A directory for end-users to keep their own functions, usually
~/.config/fish/functions(controlled by theXDG_CONFIG_HOMEenvironment variable).A directory for systems administrators to install functions for all users on the system, usually
/etc/fish/functions(really$__fish_sysconfdir/functions).Directories for other software to put their own functions. These are in the directories in the
XDG_DATA_DIRSenvironment variable, in a subdirectory calledfish/vendor_functions.d. The default is usually/usr/share/fish/vendor_functions.dand/usr/local/share/fish/vendor_functions.d.The functions shipped with fish, usually installed in
/usr/share/fish/functions(really$__fish_data_dir/functions).
If you are unsure, your functions probably belong in ~/.config/fish/functions.
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 you are developing another program and want to install fish functions for it, install them to the "vendor" functions directory. As this path varies from system to system, you can use pkgconfig to discover it with the output of pkg-config --variable functionsdir fish. Your installation system should support a custom path to override the pkgconfig path, as other distributors may need to alter it easily.
Comments¶
Anything after a # until the end of the line is a comment. That means it's purely for the reader's benefit, fish ignores it.
This is useful to explain what and why you are doing something:
function ls
# The function is called ls,
# so we have to explicitly call `command ls` to avoid calling ourselves.
command ls --color=auto $argv
end
There are no multiline comments. If you want to make a comment span multiple lines, simply start each line with a #.
Comments can also appear after a line like so:
set -gx EDITOR emacs # I don't like vim.
Conditions¶
Fish has some builtins that let you execute commands only if a specific criterion is met: if, switch, and and or, and also the familiar &&/|| syntax.
The 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¶
Like most programming language, fish also has the familiar while and for loops.
while works like a repeated if:
while true
echo Still running
sleep 1
end
will print "Still running" once a second. You can abort it with ctrl-c.
for loops work like in other shells, which is more like python's for-loops than e.g. C's:
for file in *
echo file: $file
end
will print each file in the current directory. The part after the in is just a list of arguments, so you can use any expansions there:
set moreanimals bird fox
for animal in {cat,}fish dog $moreanimals
echo I like the $animal
end
If you need a list of numbers, you can use the seq command to create one:
for i in (seq 1 5)
echo $i
end
break is available to break out of a loop, and continue to jump to the next iteration.
Input and output redirections (including pipes) can also be applied to loops:
while read -l line
echo line: $line
end < file
In addition there's a begin block that just groups commands together so you can redirect to a block or use a new variable scope without any repetition:
begin
set -l foo bar # this variable will only be available in this block!
end
Parameter expansion¶
When fish is given a commandline, it expands the parameters before sending them to the command. There are multiple different kinds of expansions:
Wildcards, to create filenames from patterns
Variable expansion, to use the value of a variable
Command substitution, to use the output of another command
Brace expansion, to write lists with common pre- or suffixes in a shorter way
Tilde expansion, to turn the
~at the beginning of paths into the path to the home directory
Parameter expansion is limited to 524288 items. There is a limit to how many arguments the operating system allows for any command, and 524288 is far above it. This is a measure to stop the shell from hanging doing useless computation.
Wildcards ("Globbing")¶
When a parameter includes an unquoted * star (or "asterisk") or a ? question mark, fish uses it as a wildcard to match files.
*matches any number of characters (including zero) in a file name, not including/.**matches any number of characters (including zero), and also descends into subdirectories. If**is a segment by itself, that segment may match zero times, for compatibility with other shells.?can match any single character except/. This is deprecated and can be disabled via theqmark-noglobfeature flag, so?will just be an ordinary character.
Other shells, such as zsh, have a much richer glob syntax, like **(.) to only match regular files. Fish does not. Instead of reinventing the whell, 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:
a*matches any files beginning with an 'a' in the current directory.???matches any file in the current directory whose name is exactly three characters long.**matches any files and directories in the current directory and all of its subdirectories.~/.*matches all hidden files (also known as "dotfiles") and directories in your home directory.
For most commands, if any wildcard fails to expand, the command is not executed, $status is set to nonzero, and a warning is printed. This behavior is like what bash does with shopt -s failglob. There are 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
findoutput on newlines. If you want to avoid that, use find's-print0option and string split0.
Variable expansion¶
One of the most important expansions in fish is the "variable expansion". This is the replacing of a dollar sign ($) followed by a variable name with the _value_ of that variable. For more on shell variables, read the Shell variables section.
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.
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:
echo The plural of $WORD is "$WORD"s
# Prints "The plural of cat is cats" when $WORD is set to cat.
echo The plural of $WORD is {$WORD}s
# ditto
Note that 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¶
The output of a command (or an entire pipeline) can be used as the arguments to another command.
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
$IFSto 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¶
Curly braces can be used to write comma-separated lists. They will be expanded with each element becoming a new parameter, with the surrounding string attached. This is useful to save on typing, and to separate a variable name from surrounding text.
Examples:
> echo input.{c,h,txt}
input.c input.h input.txt
# Move all files with the suffix '.c' or '.h' to the subdirectory src.
> mv *.{c,h} src/
# Make a copy of `file` at `file.bak`.
> cp file{,.bak}
> set -l dogs hot cool cute "good "
> echo {$dogs}dog
hotdog cooldog cutedog good dog
If there is no "," or variable expansion between the curly braces, they will not be expanded:
# This {} isn't special
> echo foo-{}
foo-{}
# This passes "HEAD@{2}" to git
> git reset --hard HEAD@{2}
> echo {{a,b}}
{a} {b} # because the inner brace pair is expanded, but the outer isn't.
If after expansion there is nothing between the braces, the argument will be removed (see the 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
Combining lists (Cartesian Product)¶
When lists are expanded with other parts attached, they are expanded with these parts still attached. Even if two lists are attached to each other, they are expanded in all combinations. This is referred to as the cartesian product (like in mathematics), and works basically like brace expansion.
Examples:
# Brace expansion is the most familiar:
# All elements in the brace combine with the parts outside of the braces
>_ echo {good,bad}" apples"
good apples bad apples
# The same thing happens with variable expansion.
>_ set -l a x y z
>_ set -l b 1 2 3
# $a is {x,y,z}, $b is {1,2,3},
# so this is `echo {x,y,z}{1,2,3}`
>_ echo $a$b
x1 y1 z1 x2 y2 z2 x3 y3 z3
# Same thing if something is between the lists
>_ echo $a"-"$b
x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3
# Or a brace expansion and a variable
>_ echo {x,y,z}$b
x1 y1 z1 x2 y2 z2 x3 y3 z3
# A combined brace-variable expansion
>_ echo {$b}word
1word 2word 3word
# Special case: If $c has no elements, this expands to nothing
>_ echo {$c}word
# Output is an empty line
Sometimes this may be unwanted, especially that tokens can disappear after expansion. In those cases, you should double-quote variables - echo "$c"word.
This also happens after command substitution. To avoid tokens 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¶
Sometimes it's necessary to access only some of the elements of a list, or some of the lines a command substitution outputs. Both are possible in fish by writing a set of indices in brackets, like:
$var[2]
# or
$var[1..3]
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 the second element to one that doesn't exist, 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¶
The ~ (tilde) character at the beginning of a parameter, followed by a username, is expanded into the home directory of the specified user. A lone ~, or a ~ followed by a slash, is expanded into the home directory of the process owner:
ls ~/Music # lists my music directory
echo ~root # prints root's home directory, probably "/root"
Combining different expansions¶
All of the above expansions can be combined. If several expansions result in more than one parameter, all possible combinations are created.
When combining multiple parameter expansions, expansions are performed in the following order:
Command substitutions
Variable expansions
Bracket expansion
Wildcard expansion
Expansions are performed from right to left, nested bracket expansions 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¶
Variables are a way to save data and pass it around. They can be used just by the shell, or they can be "exported", so that a copy of the variable is available to any external command the shell starts. An exported variable is referred to as an "environment variable".
To set a variable value, use the set command. A variable name can not be empty and can contain only letters, digits, and underscores. It may begin and end with any of those characters.
Example:
To set the variable smurf_color to the value blue, use the command set smurf_color blue.
After a variable has been set, you can use the value of a variable in the shell through variable expansion.
Example:
set smurf_color blue
echo Smurfs are usually $smurf_color
set pants_color red
echo Papa smurf, who is $smurf_color, wears $pants_color pants
So you set a variable with set, and use it with a $ and the name.
Variable scope¶
There are three kinds of variables in fish: universal, global and local variables.
Universal variables are shared between all fish sessions a user is running on one computer.
Global variables are specific to the current fish session, and will never be erased unless explicitly requested by using
set -e.Local variables are specific to the current fish session, and associated with a specific block of commands, and automatically erased when a specific block goes out of scope. A block of commands is a series of commands that begins with one of the commands
for,while,if,function,beginorswitch, and ends with the commandend.
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:
When a scope is explicitly given, it will be used. If a variable of the same name exists in a different scope, that variable will not be changed.
When no scope is given, but a variable of that name exists, the variable of the smallest scope will be modified. The scope will not be changed.
As a special case, when no scope is given and no variable has been defined the variable will belong to the scope of the currently executing function. Note that this is different from the
--localflag, which would make the variable local to the current block.
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 (also :ref:`exported <variables-export>`):
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
The following code will not output anything:
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¶
If you want to override a variable for a single command, you can use "var=val" statements before the command:
# Call git status on another directory
# (can also be done via `git -C somerepo status`)
GIT_DIR=somerepo git status
Note that, 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¶
Universal variables are variables that are shared between all the user's fish sessions on the computer. Fish stores many of its configuration options as universal variables. This means that in order to change fish settings, all you have to do is change the variable value once, and it will be automatically updated for all sessions, and preserved across computer reboots and login/logout.
To see universal variables in action, start two fish sessions side by side, and issue the following command in one of them set fish_color_cwd blue. Since fish_color_cwd is a universal variable, the color of the current working directory listing in the prompt will instantly change to blue on both terminals.
Universal variables are stored in the file .config/fish/fish_variables. Do not edit this file directly, as your edits may be overwritten. Edit the variables through fish scripts or by using fish interactively instead.
Do not append to universal variables in config.fish, because these variables will then get longer with each new shell instance. Instead, simply set them once at the command line.
Variable scope for functions¶
When calling a function, all current local variables temporarily disappear. This shadowing of the local scope is needed since the variable namespace would become cluttered, making it very easy to accidentally overwrite variables from another function.
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¶
Variables in fish can be "exported", so they will be inherited by any commands started by fish. In particular, this is necessary for variables used to configure external commands like $LESS or $GOPATH, but also for variables that contain general system settings like $PATH or $LANGUAGE. If an external command needs to know a variable, it needs to be exported.
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:
If a variable is explicitly set to either be exported or not exported, that setting will be honored.
If a variable is not explicitly set to be exported or not exported, but has been previously defined, the previous exporting rule for the variable is kept.
Otherwise, by default, the variable will not be exported.
If a variable has local scope and is exported, any function called receives a copy of it, so any changes it makes to the variable disappear once the function returns.
Global variables are accessible to functions whether they are exported or not.
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¶
Fish can store a list (or an "array" if you wish) of multiple strings inside of a variable:
> set mylist first second third
> printf '%s\n' $mylist # prints each element on its own line
first
second
third
To access one element of a list, use the index of the element inside of square brackets, like this:
echo $PATH[3]
Note that 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¶
An important list is $argv, which contains the arguments to a function or script. For example:
function myfunction
echo $argv[1]
echo $argv[3]
end
This function takes whatever arguments it gets and prints the first and third:
> myfunction first second third
first
third
> myfunction apple cucumber banana
apple
banana
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 are a special kind of variable used to support colon-delimited path lists including PATH, CDPATH, MANPATH, PYTHONPATH, etc. All variables that end in "PATH" (case-sensitive) become 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¶
You can change the settings of fish by changing the values of certain variables.
PATH, a list of directories in which to search for commandsCDPATH, a list of directories in which the cd builtin looks for a new directory.The locale variables
LANG,LC_ALL,LC_COLLATE,LC_CTYPE,LC_MESSAGES,LC_MONETARY,LC_NUMERICandLC_TIMEset the language option for the shell and subprograms. See the section Locale variables for more information.A number of variable starting with the prefixes
fish_colorandfish_pager_color. See Variables for changing highlighting colors for more information.fish_ambiguous_widthcontrols the computed width of ambiguous-width characters. This should be set to 1 if your terminal renders these characters as single-width (typical), or 2 if double-width.fish_emoji_widthcontrols whether fish assumes emoji render as 2 cells or 1 cell wide. This is necessary because the correct value changed from 1 to 2 in Unicode 9, and some terminals may not be aware. Set this if you see graphical glitching related to emoji (or other "special" characters). It should usually be auto-detected.FISH_DEBUGandFISH_DEBUG_OUTPUTcontrol what debug output fish generates and where it puts it, analogous to the--debugand--debug-outputoptions. These have to be set on startup, via e.g.FISH_DEBUG='reader*' FISH_DEBUG_OUTPUT=/tmp/fishlog fish.fish_escape_delay_mssets how long fish waits for another key after seeing an escape, to distinguish pressing the escape key from the start of an escape sequence. The default is 30ms. Increasing it increases the latency but allows pressing escape instead of alt for alt+character bindings. For more information, see the chapter in the bind documentation.fish_greeting, the greeting message printed on startup. This is printed by a function of the same name that can be overridden for more complicated changes (see funcedfish_handle_reflow, determines whether fish should try to repaint the commandline when the terminal resizes. In terminals that reflow text this should be disabled. Set it to 1 to enable, anything else to disable.fish_history, the current history session name. If set, all subsequent commands within an interactive fish session will be logged to a separate file identified by the value of the variable. If unset, or set todefault, the default session name "fish" is used. If set to an empty string, history is not saved to disk (but is still available within the interactive session).fish_trace, if set and not empty, will cause fish to print commands before they execute, similar toset -xin bash. The trace is printed to the path given by the --debug-output option to fish (stderr by default).fish_user_paths, a list of directories that are prepended toPATH. This can be a universal variable.umask, the current file creation mask. The preferred way to change the umask variable is through the umask function. An attempt to set umask to an invalid value will always fail.BROWSER, your preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
Fish also provides additional information through the values of certain environment variables. Most of these variables are read-only and their value can't be changed with set.
_, the name of the currently running command (though this is deprecated, and the use ofstatus current-commandis preferred).argv, a list of arguments to the shell or function.argvis only defined when inside a function call, or if fish was invoked with a list of arguments, likefish myscript.fish foo bar. This variable can be changed.CMD_DURATION, the runtime of the last command in milliseconds.COLUMNSandLINES, the current size of the terminal in height and width. These values are only used by fish if the operating system does not report the size of the terminal. Both variables must be set in that case otherwise a default of 80x24 will be used. They are updated when the window size changes.fish_kill_signal, the signal that terminated the last foreground job, or 0 if the job exited normally.fish_pid, the process ID (PID) of the shell.history, a list containing the last commands that were entered.HOME, the user's home directory. This variable can be changed.hostname, the machine's hostname.IFS, the internal field separator that is used for word splitting with the read builtin. Setting this to the empty string will also disable line splitting in command substitution. This variable can be changed.last_pid, the process ID (PID) of the last background process.PWD, the current working directory.pipestatus, a list of exit statuses of all processes that made up the last executed pipe.SHLVL, the level of nesting of shells.status, the exit status of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number.status_generation, the "generation" count of$status. This will be incremented only when the previous command produced an explicit status. (For example, background jobs will not increment this).USER, the current username. This variable can be changed.version, the version of the currently running fish (also available asFISH_VERSIONfor backward compatibility).
As a convention, an uppercase name is usually used for exported variables, while lowercase variables are not exported. (CMD_DURATION is an exception for historical reasons). This rule is not enforced by fish, but it is good coding practice to use casing to distinguish between exported and unexported variables.
Fish also uses some variables internally, their name usually starting with __fish. These are internal and should not typically be modified directly.
The status variable¶
Whenever a process exits, an exit status is returned to the program that started it (usually the shell). This exit status is an integer number, which tells the calling application how the execution of the command went. In general, a zero exit status means that the command executed without problem, but a non-zero exit status means there was some form of problem.
Fish stores the exit status of the last process in the last job to exit in the status variable.
If fish encounters a problem while executing a command, the status variable may also be set to a specific value:
0 is generally the exit status of fish commands if they successfully performed the requested operation.
1 is generally the exit status of fish commands if they failed to perform the requested operation.
121 is generally the exit status of fish commands if they were supplied with invalid arguments.
123 means that the command was not executed because the command name contained invalid characters.
124 means that the command was not executed because none of the wildcards in the command produced any matches.
125 means that while an executable with the specified name was located, the operating system could not actually execute the command.
126 means that while a file with the specified name was located, it was not executable.
127 means that no function, builtin or command with the given name could be located.
If a process exits through a signal, the exit status will be 128 plus the number of the signal.
Syntax highlighting variables¶
The colors used by fish for syntax highlighting can be configured by changing the values of a various variables. The value of these variables can be one of the colors accepted by the set_color command. The --bold or -b switches accepted by set_color are also accepted.
Example: to make errors highlighted and red, use:
set fish_color_error red --bold
The following variables are available to change the highlighting colors in fish:
Variable |
Meaning |
|---|---|
|
default color |
|
commands like echo |
|
keywords like if - this falls back on command color if unset |
|
quoted text like "abc" |
|
IO redirections like >/dev/null |
|
process separators like ';' and '&' |
|
syntax errors |
|
ordinary command parameters |
|
comments like '# important' |
|
selected text in vi visual mode |
|
parameter expansion operators like '*' and '~' |
|
character escapes like 'n' and 'x70' |
|
autosuggestions (the proposed rest of a command) |
|
the current working directory in the default prompt |
|
the username in the default prompt |
|
the hostname in the default prompt |
|
the hostname in the default prompt for remote sessions (like ssh) |
|
the '^C' indicator on a canceled command |
|
history search matches and selected pager items (background only) |
Pager color variables¶
fish will sometimes present a list of choices in a table, called the pager.
Example: to set the background of each pager row, use:
set fish_pager_color_background --background=white
To have black text on alternating white and gray backgrounds:
set fish_pager_color_prefix black
set fish_pager_color_completion black
set fish_pager_color_description black
set fish_pager_color_background --background=white
set fish_pager_color_secondary_background --background=brwhite
Variables affecting the pager colors:
Variable |
Meaning |
|---|---|
|
the progress bar at the bottom left corner |
|
the background color of a line |
|
the prefix string, i.e. the string that is to be completed |
|
the completion itself, i.e. the proposed rest of the string |
|
the completion description |
|
background of the selected completion |
|
prefix of the selected completion |
|
suffix of the selected completion |
|
description of the selected completion |
|
background of every second unselected completion |
|
prefix of every second unselected completion |
|
suffix of every second unselected completion |
|
description of every second unselected completion |
Locale variables¶
The "locale" of a program is its set of language and regional settings. In UNIX, there are a few separate variables to control separate things - LC_CTYPE defines the text encoding while LC_TIME defines the time format.
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.
Builtin commands¶
Fish includes a number of commands in the shell directly. We call these "builtins". These include:
Builtins that manipulate the shell state - cd changes directory, set sets variables
Builtins for dealing with data, like string for strings and math for numbers, count for counting lines or arguments
status for asking about the shell's status
test for checking conditions
argparse for parsing function arguments
source to read a script in the current shell (so changes to variables stay) and eval to execute a string as script
random to get random numbers or pick a random element from a list
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¶
The names given to variables and functions (so called "identifiers") have to follow certain rules:
A variable name cannot be empty. It can contain only letters, digits, and underscores. It may begin and end with any of those characters.
A function name cannot be empty. It may not begin with a hyphen ("-") and may not contain a slash ("/"). All other characters, including a space, are valid.
A bind mode name (e.g.,
bind -m abc ...) must be a valid variable name.
Other things have other restrictions. For instance what is allowed for file names depends on your system, but at the very least they cannot contain a "/" (because that is the path separator) or NULL byte (because that is how UNIX ends strings).
Interactive use¶
Fish prides itself on being really nice to use interactively. That's down to a few features we'll explain in the next few sections.
Help¶
Fish has an extensive help system. Use the help command to obtain help on a specific subject or command. For instance, writing help syntax displays the syntax section of this documentation.
Fish also has man pages for its commands, and translates the help pages to man pages. For example, man set will show the documentation for set as a man page.
Help on a specific builtin can also be obtained with the -h parameter. For instance, to obtain help on the fg builtin, either type fg -h or help fg.
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¶
fish suggests commands as you type, based on command history, completions, and valid file paths. As you type commands, you will see a suggestion offered after the cursor, in a muted gray color (which can be changed with the fish_color_autosuggestion variable).
To accept the autosuggestion (replacing the command line contents), press → 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¶
Tab completion is a time saving feature of any modern shell. When you type Tab, fish tries to guess the rest of the word under the cursor. If it finds just one possibility, it inserts it. If it finds more, it inserts the longest unambiguous part and then opens a menu (the "pager") that you can navigate to find what you're looking for.
The pager can be navigated with the arrow keys, 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:
Commands (builtins, functions and regular programs).
Shell variable names.
Usernames for tilde expansion.
Filenames, even on strings with wildcards such as
*and**.
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:
The programs
manandwhatisshow all installed manual pages as completions.The
makeprogram uses all targets in the Makefile in the current directory as completions.The
mountcommand uses all mount points specified in fstab as completions.The
sshcommand uses all hosts that are stored in the known_hosts file as completions. (See the ssh documentation for more information)The
sucommand shows the users on the systemThe
apt-get,rpmandyumcommands show installed or installable packages
You can also write your own completions or install some you got from someone else. For that, see Writing your own completions.
Syntax highlighting¶
Fish interprets the command line as it is typed and uses syntax highlighting to provide feedback. The most important feedback is the detection of potential errors. By default, errors are marked red.
Detected errors include:
Non existing commands.
Reading from or appending to a non existing file.
Incorrect use of output redirects
Mismatched parenthesis
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.
Abbreviations¶
To avoid needless typing, a frequently-run command like git checkout can be abbreviated to gco using the abbr command.
abbr -a gco git checkout
After entering gco and pressing Space or Enter, 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¶
When using most virtual terminals, it is possible to set the message displayed in the titlebar of the terminal window. This can be done automatically in fish by defining the fish_title function. The fish_title function is executed before and after a new command is executed or put into the foreground and the output is used as a titlebar message. The status current-command builtin will always return the name of the job to be put into the foreground (or fish if control is returning to the shell) when the fish_prompt <cmd-fish_prompt> function is called. The first argument to fish_title will contain the most recently executed foreground command as a string, starting with fish 2.2.
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¶
When fish waits for input, it will display a prompt by evaluating the fish_prompt and fish_right_prompt functions. The output of the former is displayed on the left and the latter's output on the right side of the terminal. The output of fish_mode_prompt will be prepended on the left, though the default function only does this when in vi-mode.
Configurable greeting¶
If a function named fish_greeting exists, it will be run when entering interactive mode. Otherwise, if an environment variable named fish_greeting exists, it will be printed.
Private mode¶
If $fish_private_mode is set to a non-empty value, commands will not be written to the history file on disk.
You can also launch with fish --private (or fish -P for short). This both hides old history and prevents writing history to disk. This is useful to avoid leaking personal information (e.g. for screencasts) or when dealing with sensitive information.
You can query the variable fish_private_mode (if set -q 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¶
The fish editor features copy and paste, a searchable history and many editor functions that can be bound to special keyboard shortcuts.
Similar to bash, fish has Emacs and Vi editing modes. The default editing mode is Emacs. You can switch to Vi mode with 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 $fish_key_bindings 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
Emacs mode commands¶
Home or Control+A moves the cursor to the beginning of the line.
End or Control+E moves to the end of line. If the cursor is already at the end of the line, and an autosuggestion is available, End or Control+E accepts the autosuggestion.
Control+B, Control+F move the cursor one character left or right or accept the autosuggestion just like the ← (Left) and → (Right) shared bindings (which are available as well).
Control+N, Control+P move the cursor up/down or through history, like the up and down arrow shared bindings.
Delete or Backspace removes one character forwards or backwards respectively.
Control+K moves contents from the cursor to the end of line to the killring.
Alt+C capitalizes the current word.
Alt+U makes the current word uppercase.
Control+T transposes the last two characters.
Alt+T transposes the last two words.
Control+Z, Control+_ (Control+/ on some terminals) undo the most recent edit of the line.
Alt+/ reverts the most recent undo.
You can change these key bindings using the bind builtin.
Vi mode commands¶
Vi mode allows for the use of Vi-like commands at the prompt. Initially, insert mode is active. Escape enters command mode. The commands available in command, insert and visual mode are described below. Vi mode shares some bindings with Emacs mode.
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¶
Command mode is also known as normal mode.
H moves the cursor left.
L moves the cursor right.
I enters insert mode at the current cursor position.
V enters visual mode at the current cursor position.
A enters insert mode after the current cursor position.
Shift+A enters insert mode at the end of the line.
0 (zero) moves the cursor to beginning of line (remaining in command mode).
D+D deletes the current line and moves it to the killring.
Shift+D deletes text after the current cursor position and moves it to the killring.
P pastes text from the killring.
U search history backwards.
[ and ] search the command history for the previous/next token containing the token under the cursor before the search was started. See the history section for more information on history searching.
Backspace moves the cursor left.
Insert mode¶
Escape enters command mode.
Backspace removes one character to the left.
Visual mode¶
← (Left) and → (Right) extend the selection backward/forward by one character.
B and W extend the selection backward/forward by one word.
D and X move the selection to the killring and enter command mode.
Escape and Control+C enter command mode.
Custom bindings¶
In addition to the standard bindings listed here, you can also define your own with bind:
# Just clear the commandline on control-c
bind \cc 'commandline -r ""'
Put bind statements into config.fish or a function called fish_user_key_bindings.
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)¶
Fish uses an Emacs-style kill ring for copy and paste functionality. For example, use Control+K (kill-line) to cut from the current cursor position to the end of the line. The string that is cut (a.k.a. killed in emacs-ese) is inserted into a list of kills, called the kill ring. To paste the latest value from the kill ring (emacs calls this "yanking") use Control+Y (the yank input function). After pasting, use Alt+Y (yank-pop) to rotate to the previous kill.
Copy and paste from outside are also supported, both via the Control+X / Control+V bindings (the fish_clipboard_copy and fish_clipboard_paste functions 7) 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.
- 7
These rely on external tools. Currently xsel, xclip, wl-copy/wl-paste and pbcopy/pbpaste are supported.
Multiline editing¶
The fish commandline editor can be used to work on commands that are several lines long. There are three ways to make a command span more than a single line:
Pressing the Enter key while a block of commands is unclosed, such as when one or more block commands such as
for,beginorifdo not have a corresponding end command.Pressing Alt+Enter instead of pressing the Enter key.
By inserting a backslash (
\) character before pressing the Enter key, escaping the newline.
The fish commandline editor works exactly the same in single line mode and in multiline mode. To move between lines use the left and right arrow keys and other such keyboard shortcuts.
Searchable command history¶
After a command has been executed, it is remembered in the history list. Any duplicate history items are automatically removed. By pressing the up and down keys, you can search forwards and backwards in the history. If the current command line is not empty when starting a history search, only the commands containing the string entered into the command line are shown.
By pressing Alt+↑ 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, and they can be aborted by pressing the escape key.
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'.
Initialization files¶
On startup, Fish evaluates a number of configuration files, which can be used to control the behavior of the shell. The location of these is controlled by a number of environment variables, and their default or usual location is given below.
Configuration files are evaluated in the following order:
Configuration shipped with fish, which should not be edited, in
$__fish_data_dir/config.fish(usually/usr/share/fish/config.fish).Configuration snippets in files ending in
.fish, in the directories:$__fish_config_dir/conf.d(by default,~/.config/fish/conf.d/)$__fish_sysconf_dir/conf.d(by default,/etc/fish/conf.d/)Directories for third-party software vendors to ship their own configuration snippets for their software. Fish searches the directories in the
XDG_DATA_DIRSenvironment variable for afish/vendor_conf.ddirectory; if this variable is not defined, the default is usually to search/usr/share/fish/vendor_conf.dand/usr/local/share/fish/vendor_conf.d
If there are multiple files with the same name in these directories, only the first will be executed. They are executed in order of their filename, sorted (like globs) in a natural order (i.e. "01" sorts before "2").
System-wide configuration files, where administrators can include initialization that should be run for all users on the system - similar to
/etc/profilefor POSIX-style shells - in$__fish_sysconf_dir(usually/etc/fish/config.fish).User initialization, usually in
~/.config/fish/config.fish(controlled by theXDG_CONFIG_HOMEenvironment variable, and accessible as$__fish_config_dir).
These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above.
This wide search may be confusing. If you are unsure where to put your own customisations, use ~/.config/fish/config.fish.
Note that ~/.config/fish/config.fish is sourced after the snippets. This is so users can copy snippets and override some of their behavior.
These files are all executed on the startup of every shell. If you want to run a command only on starting an interactive shell, use the exit status of the command status --is-interactive to determine if the shell is interactive. If you want to run a command only when using a login shell, use status --is-login instead. This will speed up the starting of non-interactive or non-login shells.
If you are developing another program, you may wish to install configuration which is run for all users of the fish shell on a system. This is discouraged; if not carefully written, they may have side-effects or slow the startup of the shell. Additionally, users of other shells will not benefit from the Fish-specific configuration. However, if they are absolutely required, you may install them to the "vendor" configuration directory. As this path may vary from system to system, the pkgconfig framework should be used to discover this path with the output of pkg-config --variable confdir fish.
Examples:
If you want to add the directory ~/linux/bin to your PATH variable when using a login shell, add the following to your ~/.config/fish/config.fish file:
if status --is-login
set -gx PATH $PATH ~/linux/bin
end
If you want to run a set of commands when fish exits, use an event handler that is triggered by the exit of the shell:
function on_exit --on-event fish_exit
echo fish is now exiting
end
Future feature flags¶
Feature flags are how fish stages changes that might break scripts. Breaking changes are introduced as opt-in, in a few releases they become opt-out, and eventually the old behavior is removed.
You can see the current list of features via status features:
> status features
stderr-nocaret on 3.0 ^ no longer redirects stderr
qmark-noglob 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¶
When defining a new function in fish, it is possible to make it into an event handler, i.e. a function that is automatically run when a specific event takes place. Events that can trigger a handler currently are:
When a signal is delivered
When a job exits
When the value of a variable is updated
When the prompt is about to be shown
Example:
To specify a signal handler for the WINCH signal, write:
function my_signal_handler --on-signal WINCH
echo Got WINCH signal!
end
Please note that event handlers only become active when a function is loaded, which means you might need to otherwise source or execute a function instead of relying on autoloading. One approach is to put it into your initialization file.
For more information on how to define new event handlers, see the documentation for the function command.
Debugging fish scripts¶
Fish includes a built in debugging facility. The debugger allows you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt. At this prompt you can execute any fish command (there are no debug commands as such). For example, you can check or change the value of any variables using printf and set. As another example, you can run status print-stack-trace to see how this breakpoint was reached. To resume normal execution of the script, simply type exit or Control+D.
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.
Further help and development¶
If you have a question not answered by this documentation, there are several avenues for help:
The GitHub page
The official Gitter channel
The official mailing list at fish-users@lists.sourceforge.net
The IRC channel, #fish on
irc.oftc.net
If you have an improvement for fish, you can submit it via the GitHub page.