fish
ships with a large number of builtin commands, shellscript functions and external commands. These are all described below.
Almost all fish commands respond to the -h
or --help
options to display their relevant help, also accessible using the help
and man
commands, like so:
echo -h echo --help # Prints help to the terminal window man echo # Displays the man page in the system pager # (normally 'less', 'more' or 'most'). help echo # Open a web browser to show the relevant documentation
abbr --add word phrase... abbr --rename word new_word abbr --show abbr --list abbr --erase word
abbr
manipulates the list of abbreviations that fish will expand.
Abbreviations are user-defined character sequences or words that are replaced with longer phrases after they are entered. For example, a frequently-run command such as 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.
Abbreviations are stored in a variable named fish_user_abbreviations
. This is automatically created as a universal variable the first time an abbreviation is created. If you want your abbreviations to be private to a particular fish session you can put the following in your *~/.config/fish/config.fish* file before you define your first abbrevation:
if status --is-interactive set -g fish_user_abbreviations abbr --add first 'echo my first abbreviation' abbr --add second 'echo my second abbreviation' # etcetera end
You can create abbreviations directly on the command line and they will be saved automatically and made visible to other fish sessions if fish_user_abbreviations
is a universal variable. If you keep the variable as universal, abbr --add
statements in config.fish will do nothing but slow down startup slightly.
The following parameters are available:
-a WORD PHRASE
or --add WORD PHRASE
Adds a new abbreviation, causing WORD to be expanded to PHRASE.-r WORD NEW_WORD
or --rename WORD NEW_WORD
Renames an abbreviation, from WORD to NEW_WORD.-s
or --show
Show all abbreviated words and their expanded phrases in a manner suitable for export and import.-l
or --list
Lists all abbreviated words.-e WORD
or --erase WORD
Erase the abbreviation WORD.Note: fish version 2.1 supported -a WORD=PHRASE
. This syntax is now deprecated but will still be converted.
abbr -a gco git checkout
Add a new abbreviation where gco
will be replaced with git checkout
.
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.
Back to command index.
alias alias NAME DEFINITION alias NAME=DEFINITION
alias
is a simple wrapper for the function
builtin, which creates a function wrapping a command. It has similar syntax to POSIX shell alias
. For other uses, it is recommended to define a function.
fish
marks functions that have been created by alias
by including the command used to create them in the function description. You can list alias
-created functions by running alias
without arguments. They must be erased using functions -e
.
NAME
is the name of the aliasDEFINITION
is the actual command to execute. The string $argv
will be appended.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 code will create rmi
, which runs rm
with additional arguments on every invocation.
alias rmi="rm -i" # This is equivalent to entering the following function: function rmi --wraps rm --description 'alias rmi=rm -i' rm -i $argv end # 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'
Back to command index.
COMMAND1; and COMMAND2
and
is used to execute a command if the current exit status (as set by the previous command) is 0.
and
statements may be used as part of the condition in an if
or while
block. See the documentation for if
and while
for examples.
and
does not change the current exit status. The exit status of the last foreground command to exit can always be accessed using the $status variable.
The following code runs the make
command to build a program. If the build succeeds, make
's exit status is 0, and the program is installed. If either step fails, the exit status is 1, and make clean
is run, which removes the files created by the build process.
make; and make install; or make clean
Back to command index.
begin; [COMMANDS...;] end
begin
is used to create a new block of code.
The block is unconditionally executed. begin; ...; end
is equivalent to if true; ...; end
.
begin
is used to group a number of commands into a block. This 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
.
begin
does not change the current exit status.
The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends.
begin set -l PIRATE Yarrr ... end echo $PIRATE # This will not output anything, since the PIRATE variable # went out of scope at the end of the block
In the following code, all output is redirected to the file out.html.
begin echo $xml_header echo $html_header if test -e $file ... end ... end > out.html
Back to command index.
bg [PID...]
bg
sends jobs to the background, resuming them if they are stopped. A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background.
The PID of the desired process is usually found by using process expansion.
When at least one of the arguments isn't a valid job specifier (i.e. PID), bg
will print an error without backgrounding anything.
When all arguments are valid job specifiers, bg will background all matching jobs that exist.
bg %1
will put the job with job ID 1 in the background.
bg 123 456 789
will background 123, 456 and 789.
If only 123 and 789 exist, it will still background them and print an error about 456.
bg 123 banana
or bg banana 123
will complain that "banana" is not a valid job specifier.
Back to command index.
bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [(-k | --key)] SEQUENCE COMMAND [COMMAND...] bind [(-M | --mode) MODE] [(-k | --key)] SEQUENCE bind (-K | --key-names) [(-a | --all)] bind (-f | --function-names) bind (-L | --list-modes) bind (-e | --erase) [(-M | --mode) MODE] (-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE...])
bind
adds a binding for the specified key sequence to the specified command.
SEQUENCE is the character sequence to bind to. These should be written as fish escape sequences. For example, because pressing the Alt key and another character sends that character prefixed with an escape character, Alt-based key bindings can be written using the \e
escape. For example, Alt-w can be written as \ew
. The control character can be written in much the same way using the \c
escape, for example 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 default key binding can be set by specifying a SEQUENCE
of the empty string (that is, ''
). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the self-insert
function (i.e. bind '' self-insert
) as the default keybinding. 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 printable.
If the -k
switch is used, the name of the 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.)
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 such a script produces output, the script needs to finish by calling commandline -f repaint
in order to tell fish that a repaint is in order.
When multiple COMMAND
s are provided, they are all run in the specified order when the key is pressed.
If no SEQUENCE
is provided, all bindings (or just the bindings in the specified MODE
) are printed. If SEQUENCE
is provided without COMMAND
, just the binding matching that sequence is printed.
Key bindings are not saved between sessions by default. Bare bind
statements in config.fish won't have any effect because it is sourced before the default keybindings are setup. To save custom keybindings, put the bind
statements into a function called fish_user_key_bindings
, which will be autoloaded.
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.
The following parameters are available:
-k
or --key
Specify a key name, such as 'left' or 'backspace' instead of a character sequence-K
or --key-names
Display a list of available key names. Specifying -a
or --all
includes keys that don't have a known mapping-f
or --function-names
Display a list of available input functions-L
or --list-modes
Display a list of defined bind modes-M MODE
or --mode MODE
Specify a bind mode that the bind is used in. Defaults to "default"-m NEW_MODE
or --sets-mode NEW_MODE
Change the current mode to NEW_MODE
after this binding is executed-e
or --erase
Erase the binding with the given sequence and mode instead of defining a new one. Multiple sequences can be specified with this flag. Specifying -a
or --all
with -M
or --mode
erases all binds in the given mode regardless of sequence. Specifying -a
or --all
without -M
or --mode
erases all binds in all modes regardless of sequence.-a
or --all
See --erase
and --key-names
The following special input functions are available:
accept-autosuggestion
, accept the current autosuggestion completelybackward-char
, moves one character to the leftbackward-bigword
, move one whitespace-delimited word to the leftbackward-delete-char
, deletes one character of input to the left of the cursorbackward-kill-bigword
, move the whitespace-delimited word to the left of the cursor to the killringbackward-kill-line
, move everything from the beginning of the line to the cursor to the killringbackward-kill-path-component
, move one path component to the left of the cursor (everything from the last "/" or whitespace exclusive) to the killringbackward-kill-word
, move the word to the left of the cursor to the killringbackward-word
, move one word to the leftbeginning-of-buffer
, moves to the beginning of the buffer, i.e. the start of the first linebeginning-of-history
, move to the beginning of the historybeginning-of-line
, move to the beginning of the linebegin-selection
, start selecting textcapitalize-word
, make the current word begin with a capital lettercomplete
, guess the remainder of the current tokencomplete-and-search
, invoke the searchable pager on completion options (for convenience, this also moves backwards in the completion pager)delete-char
, delete one character to the right of the cursordowncase-word
, make the current word lowercaseend-of-buffer
, moves to the end of the buffer, i.e. the end of the first lineend-of-history
, move to the end of the historyend-of-line
, move to the end of the lineend-selection
, end selecting textforward-bigword
, move one whitespace-delimited word to the rightforward-char
, move one character to the rightforward-word
, move one word to the righthistory-search-backward
, search the history for the previous matchhistory-search-forward
, search the history for the next matchkill-bigword
, move the next whitespace-delimited word to the killringkill-line
, move everything from the cursor to the end of the line to the killringkill-selection
, move the selected text to the killringkill-whole-line
, move the line to the killringkill-word
, move the next word to the killringsuppress-autosuggestion
, remove the current autosuggestionswap-selection-start-stop
, go to the other end of the highlighted text without changing the selectiontranspose-chars
, transpose two characters to the left of the cursortranspose-words
, transpose two words to the left of the cursorupcase-word
, make the current word uppercaseyank
, insert the latest entry of the killring into the bufferyank-pop
, rotate to the previous entry of the killringbind \cd 'exit'
Causes fish
to exit when Control-D is pressed.
bind -k ppage history-search-backward
Performs a history search when the Page Up key is pressed.
set -g fish_key_bindings fish_vi_key_bindings bind -M insert \cc kill-whole-line force-repaint
Turns on Vi key bindings and rebinds Control-C to clear the input line.
The escape key can be used standalone, for example, to switch from insertion mode to normal mode when using Vi keybindings. Escape may also be used as a "meta" key, to indicate the start of an escape sequence, such as function or arrow keys. Custom bindings can also be defined that begin with an escape character.
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 300 milliseconds (0.3 seconds) in the default key bindings and 10 milliseconds in the vi key bindings. It can be configured by setting the fish_escape_delay_ms
variable to a value between 10 and 5000 ms. It is recommended that this be a universal variable that you set once from an interactive session.
Note: fish 2.2.0 and earlier used a default of 10 milliseconds, and provided no way to configure it. That effectively made it impossible to use escape as a meta key.
Back to command index.
block [OPTIONS...]
block
prevents events triggered by fish
or the emit
command from being delivered and acted upon while the block is in place.
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:
-l
or --local
Release the block automatically at the end of the current innermost code block scope-g
or --global
Never automatically release the lock-e
or --erase
Release global block# 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
Note that events are only received from the current fish process as there is no way to send events from one fish process to another.
Back to command index.
LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end
break
halts a currently running loop, such as a for loop or a while loop. It is usually added inside of a conditional block such as an if statement or a switch statement.
There are no parameters for break
.
The following code searches all .c files for "smurf", and halts at the first occurrence.
for i in *.c if grep smurf $i echo Smurfs are present in $i break end end
Back to command index.
breakpoint
breakpoint
is used to halt a running script and launch an interactive debugging prompt.
For more details, see Debugging fish scripts in the fish
manual.
There are no parameters for breakpoint
.
Back to command index.
builtin BUILTINNAME [OPTIONS...]
builtin
forces the shell to use a builtin command, rather than a function or program.
The following parameters are available:
-n
or --names
List the names of all defined builtinsbuiltin jobs # executes the jobs builtin, even if a function named jobs exists
Back to command index.
switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
switch
performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. case
is used together with the switch
statement in order to determine which block should be executed.
Each case
command is given one or more parameters. The first case
command with a parameter that matches the string specified in the switch command will be evaluated. case
parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames.
Note that fish does not fall through on case statements. Only the first matching case is executed.
Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter.
If the variable $animal contains the name of an animal, the following code would attempt to classify it:
switch $animal case cat echo evil case wolf dog human moose dolphin whale echo mammal case duck goose albatross echo bird case shark trout stingray echo fish # 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
.
Back to command index.
cd [DIRECTORY]
cd
changes the current working directory.
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
environment variable array will be tried as prefixes for the specified path.
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.
cd # changes the working directory to your home directory. cd /usr/src/fish-shell # changes the working directory to /usr/src/fish-shell
Back to command index.
command [OPTIONS] COMMANDNAME [ARGS...]
command
forces the shell to execute the program COMMANDNAME
and ignore any functions or builtins with the same name.
The following options are available:
-s
or --search
returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the $PATH
.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 the type -q
, for testing only the exit status.
For basic compatibility with POSIX command
, the -v
flag is recognized as an alias for -s
.
command ls
causes fish to execute the ls
program, even if an ls
function exists.
command -s ls
returns the path to the ls
program.
Back to command index.
commandline [OPTIONS] [CMD]
commandline
can be used to set or get the current contents of the command line buffer.
With no parameters, commandline
returns the current value of the command line.
With CMD
specified, the command line buffer is erased and replaced with the contents of CMD
.
The following options are available:
-C
or --cursor
set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position.-f
or --function
inject readline functions into the reader. This option cannot be combined with any other option. It will cause any additional arguments to be interpreted as readline functions, and these functions will be injected into the reader, so that they will be returned to the reader before any additional actual key presses are read.The following options change the way commandline
updates the command line buffer:
-a
or --append
do not remove the current commandline, append the specified string at the end of it-i
or --insert
do not remove the current commandline, insert the specified string at the current cursor position-r
or --replace
remove the current commandline and replace it with the specified string (default)The following options change what part of the commandline is printed or updated:
-b
or --current-buffer
select the entire buffer (default)-j
or --current-job
select the current job-p
or --current-process
select the current process-t
or --current-token
select the current token.The following options change the way commandline
prints the current commandline buffer:
-c
or --cut-at-cursor
only print selection up until the current cursor position-o
or --tokenize
tokenize the selection and print one string-type token per lineIf commandline
is called during a call to complete a given string using complete -C STRING
, commandline
will consider the specified string to be the current contents of the command line.
The following options output metadata about the commandline state:
-L
or --line
print the line that the cursor is on, with the topmost line starting at 1-S
or --search-mode
evaluates to true if the commandline is performing a history search-P
or --paging-mode
evaluates to true if the commandline is showing pager contents, such as tab completionscommandline -j $history[3]
replaces the job under the cursor with the third item from the command line history.
If the commandline contains
> echo $flounder >&2 | less; and echo $catfish
(with the cursor on the "o" of "flounder")
Then the following invocations behave like this:
> 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
Back to command index.
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 ) OPTION_ARGUMENTS] [( -f | --no-files )] [( -r | --require-parameter )] [( -x | --exclusive )] [( -w | --wraps ) WRAPPED_COMMAND]... [( -n | --condition ) CONDITION] [( -d | --description ) DESCRIPTION] complete ( -C[STRING] | --do-complete[=STRING] )
For an introduction to specifying completions, see Writing your own completions in the fish manual.
COMMAND
is the name of the command for which to add a completion.SHORT_OPTION
is a one character option for the command.LONG_OPTION
is a multi character option for the command.OPTION_ARGUMENTS
is parameter containing a space-separated list of possible option-arguments, which may contain command substitutions.DESCRIPTION
is a description of what the option and/or option arguments do.-c COMMAND
or --command COMMAND
specifies that COMMAND
is the name of the command.-p COMMAND
or --path COMMAND
specifies that COMMAND
is the absolute path of the program (optionally containing wildcards).-e
or --erase
deletes the specified completion.-s SHORT_OPTION
or --short-option=SHORT_OPTION
adds a short option to the completions list.-l LONG_OPTION
or --long-option=LONG_OPTION
adds a GNU style long option to the completions list.-o LONG_OPTION
or --old-option=LONG_OPTION
adds an old style long option to the completions list (See below for details).-a OPTION_ARGUMENTS
or --arguments=OPTION_ARGUMENTS
adds the specified option arguments to the completions list.-f
or --no-files
specifies that the options specified by this completion may not be followed by a filename.-r
or --require-parameter
specifies that the options specified by this completion always must have an option argument, i.e. may not be followed by another option.-x
or --exclusive
implies both -r
and -f
.-w WRAPPED_COMMAND
or --wraps=WRAPPED_COMMAND
causes the specified command to inherit completions from the wrapped command (See below for details).-n
or --condition
specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.-CSTRING
or --do-complete=STRING
makes complete try to find all possible completions for the specified string.-C
or --do-complete
with no argument makes complete try to find all possible completions for the current command line buffer. If the shell is not in interactive mode, an error is returned.-A
and --authoritative
no longer do anything and are silently ignored.-u
and --unauthoritative
no longer do anything and are silently ignored.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 version of the getopt library. These styles are:
-a
'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '-la
', which is equivalent to '-l -a
'). Option arguments may be specified in the following parameter ('-w 32
') or by appending the option with the value ('-w32
').-Wall
'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('-ao null
').--colors
'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('--quoting-style shell
') or by appending the option with a '=
' and the value ('--quoting-style=shell
'). GNU style long options may be abbreviated so long as the abbreviation is unique ('--h
') is equivalent to '--help
' if help is the only long option beginning with an 'h').The options for specifying command name and command path may be used multiple times to define the same completions for multiple commands.
The options for specifying command switches and wrapped commands may be used multiple times to define multiple completions for the command(s) in a single 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 used as completions when attempting to complete an argument 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 any argument to the command (except when completing an option argument that was specified with -r
or --require-parameter
).
Command substitutions found in OPTION_ARGUMENTS
are not expected to return a space-separated list of arguments. Instead they must return a newline-separated list of arguments, and each argument may optionally have a tab character followed by the argument description. Any description provided in this way overrides a description given with -d
or --description
.
The -w
or --wraps
options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may 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. Note that 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 by specifying either a long, short or old style option.
The short style option -o
for the gcc
command requires that a file follows it. This can be done using writing:
complete -c gcc -s o -r
The short style option -d
for the grep
command requires that one of the strings 'read
', 'skip
' or 'recurse
' is used. This can be specified writing:
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" -d nodeps "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.
Back to command index.
contains [OPTIONS] KEY [VALUES...]
contains
tests whether the set VALUES
contains the string KEY
. If so, contains
exits with status 0; if not, it exits with status 1.
The following options are available:
-i
or --index
print the word indexNote that, like GNU tools, contains
interprets all arguments starting with a -
as options to contains, until it reaches an argument that is --
(two dashes). See the examples below.
for i in ~/bin /usr/local/bin if not contains $i $PATH set PATH $PATH $i end end
The above code tests if ~/bin
and /usr/local/bin
are in the path and adds them if not.
function hasargs if contains -- -q $argv echo '$argv contains a -q option' end end
The above code checks for -q
in the argument list, using the --
argument to demarcate options to contains
from the key to search for.
Back to command index.
LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end
continue
skips the remainder of the current iteration of the current inner loop, such as a for loop or a while loop. It is usually added inside of a conditional block such as an if statement or a switch statement.
The following code removes all tmp files that do not contain the word smurf.
for i in *.tmp if grep smurf $i continue end rm $i end
Back to command index.
count $VARIABLE
count
prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains.
count
does not accept any options, including -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.
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'.
Back to command index.
dirh
dirh
prints the current directory history. The current position in the history is highlighted using the color defined in the fish_color_history_current
environment variable.
dirh
does not accept any parameters.
Note that the cd
command limits directory history to the 25 most recently visited directories. The history is stored in the $dirprev
and $dirnext
variables.
Back to command index.
dirs dirs -c
dirs
prints the current directory stack, as created by the pushd
command.
With "-c", it clears the directory stack instead.
dirs
does not accept any parameters.
Back to command index.
disown [ PID ... ]
disown
removes the specified job from the list of jobs. The job itself continues to exist, but fish does not keep track of it any longer.
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 PID
s 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.
The PID of the desired process is usually found by using process expansion, which can specify jobs or search by process name.
disown
returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered.
firefox &; disown
will start the Firefox web browser in the background and remove it from the job list, meaning it will not be closed when the fish process is closed.
disown (jobs -p)
removes all jobs from the job list without terminating them.
Back to command index.
echo [OPTIONS] [STRING]
echo
displays a string of text.
The following options are available:
-n
, Do not output a newline-s
, Do not separate arguments with spaces-E
, Disable interpretation of backslash escapes (default)-e
, Enable interpretation of backslash escapesIf -e
is used, the following sequences are recognized:
\
backslash\a
alert (BEL)\b
backspace\c
produce no further output\e
escape\f
form feed\n
new line\r
carriage return\t
horizontal tab\v
vertical tab\0NNN
byte with octal value NNN (1 to 3 digits)\xHH
byte with hexadecimal value HH (1 to 2 digits)echo 'Hello World'
Print hello world to stdout
echo -e 'Top\nBottom'
Print Top and Bottom on separate lines, using an escape sequence
Back to command index.
if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
if
will execute the command CONDITION
. If the condition's exit status is 0, the commands COMMANDS_TRUE
will execute. If it is not 0 and else
is given, COMMANDS_FALSE
will be executed.
The following code tests whether a file foo.txt
exists as a regular file.
if test -f foo.txt echo foo.txt exists else echo foo.txt does not exist end
Back to command index.
emit EVENT_NAME [ARGUMENTS...]
emit
emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments.
The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type.
function event_test --on-event test_event echo event test: $argv end emit test_event something \subsection notes Notes Note that events are only sent to the current fish process as there is no way to send events from one fish process to another.
Back to command index.
begin; [COMMANDS...] end if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end while CONDITION; COMMANDS...; end for VARNAME in [VALUES...]; COMMANDS...; end switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
end
ends a block of commands.
For more information, read the documentation for the block constructs, such as if
, for
and while
.
The end
command does not change the current exit status.
Back to command index.
eval [COMMANDS...]
eval
evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator.
The following code will call the ls command. Note that fish
does not support the use of shell variables as direct commands; eval
can be used to work around this.
set cmd ls eval $cmd
Back to command index.
exec COMMAND [OPTIONS...]
exec
replaces the currently running shell with a new command. On successful completion, exec
never returns. exec
cannot be used inside a pipeline.
exec emacs
starts up the emacs text editor, and exits fish
. When emacs exits, the session will terminate.
Back to command index.
exit [STATUS]
exit
causes fish to exit. If STATUS
is supplied, it will be converted to an integer and used as the exit code. Otherwise, the exit code will be that of the last command executed.
If exit is called while sourcing a file (using the source builtin) the rest of the file will be skipped, but the shell itself will not exit.
Back to command index.
false
false
sets the exit status to 1.
Back to command index.
fg [PID]
fg
brings the specified job to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.
The PID of the desired process is usually found by using process expansion. Fish is capable of expanding far more than just the numeric PID, including referencing itself and finding PIDs by name.
fg %1
will put the job with job ID 1 in the foreground.
Back to command index.
fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]]
fish
is a command-line shell written mainly with interactive use in mind. The full manual is available in HTML by using the help command from inside fish.
The following options are available:
-c
or --command=COMMANDS
evaluate the specified commands instead of reading from the commandline-d
or --debug-level=DEBUG_LEVEL
specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.-i
or --interactive
specify that fish is to run in interactive mode-l
or --login
specify that fish is to run as a login shell-n
or --no-execute
do not execute any commands, only perform syntax checking-p
or --profile=PROFILE_FILE
when fish exits, output timing information on all executed commands to the specified file-v
or --version
display version and exit-D
or --debug-stack-frames=DEBUG_LEVEL
specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.The fish exit status is generally the exit status of the last foreground command. If fish is exiting because of a parse error, the exit status is 127.
Back to command index.
fish_config
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.
fish_config
starts a local web server and then opens a web browser window; when you have finished, close the browser window and then press the Enter key to terminate the configuration session.
fish_config
optionally accepts name of the initial configuration tab. For e.g. fish_config history
will start configuration interface with history tab.
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.
fish_config
opens a new web browser window and allows you to configure certain fish settings.
Back to command index.
fish_indent [OPTIONS]
fish_indent
is used to indent a piece of fish code. fish_indent
reads commands from standard input and outputs them to standard output or a specified file.
The following options are available:
-w
or --write
indents a specified file and immediately writes to that file.-i
or --no-indent
do not indent commands; only reformat to one job per line.-v
or --version
displays the current fish version and then exits.--ansi
colorizes the output using ANSI escape sequences, appropriate for the current $TERM, using the colors defined in the environment (such as $fish_color_command
).--html
outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as fish_color_command
.-d
or --debug-level=DEBUG_LEVEL
enables debug output and specifies a verbosity level (like fish -d
). Defaults to 0.-D
or --debug-stack-frames=DEBUG_LEVEL
specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.--dump-parse-tree
dumps information about the parsed statements to stderr. This is likely to be of interest only to people working on the fish source code.Back to command index.
fish_key_reader [OPTIONS]
fish_key_reader
is used to study input received from the terminal and can help with key binds. The program is interactive and works on standard input. Individual characters themselves and their hexadecimal values are displayed.
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:
-c
or --continuous
begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.-d
or --debug-level=DEBUG_LEVEL
enables debug output and specifies a verbosity level (like fish -d
). Defaults to 0.-D
or --debug-stack-frames=DEBUG_LEVEL
specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.-h
or --help
prints usage information.The delay in milliseconds since the previous character was received is included in the diagnostic information written to stderr. This information may be useful to determine the optimal fish_escape_delay_ms
setting or learn the amount of lag introduced by tools like ssh
, mosh
or tmux
.
fish_key_reader
intentionally disables handling of many signals. To terminate fish_key_reader
in --continuous
mode do:
Ctrl-C
twice, orCtrl-D
twice, orexit
, orquit
Back to command index.
fish_mode_prompt will output the mode indicator for use in vi-mode.
The output of fish_mode_prompt
will be displayed in the mode indicator position to the left of the regular prompt.
Multiple lines are not supported in fish_mode_prompt
.
Back to command index.
function fish_prompt ... end
By defining the fish_prompt
function, the user can choose a custom prompt. The fish_prompt
function is executed when the prompt is to be shown, and the output is used as a prompt.
The exit status of commands within fish_prompt
will not modify the value of $status outside of the fish_prompt
function.
fish
ships with a number of example prompts that can be chosen with the fish_config
command.
A simple prompt:
function fish_prompt -d "Write out the prompt" printf '%s@%s%s%s%s> ' (whoami) (hostname | cut -d . -f 1) \ (set_color $fish_color_cwd) (prompt_pwd) (set_color normal) end
Back to command index.
function fish_right_prompt ... end
fish_right_prompt
is similar to fish_prompt
, except that it appears on the right side of the terminal window.
Multiple lines are not supported in fish_right_prompt
.
A simple right prompt:
function fish_right_prompt -d "Write out the right prompt" date '+%m/%d/%y' end
Back to command index.
fish_update_completions
parses manual pages installed on the system, and attempts to create completion files in the fish
configuration directory.
This does not overwrite custom completions.
There are no parameters for fish_update_completions
.
Back to command index.
fish_vi_mode
This function is deprecated. Please call fish_vi_key_bindings directly
fish_vi_mode
enters a vi-like command editing mode. To always start in vi mode, add fish_vi_mode
to your config.fish
file.
Back to command index.
for VARNAME in [VALUES...]; COMMANDS...; end
for
is a loop construct. It will perform the commands specified by COMMANDS
multiple times. On each iteration, the local variable specified by VARNAME
is assigned a new value from VALUES
. If VALUES
is empty, COMMANDS
will not be executed at all.
for i in foo bar baz; echo $i; end # would output: foo bar baz
Back to command index.
funced [OPTIONS] NAME
funced
provides an interface to edit the definition of the function NAME
.
If the $VISUAL
environment variable is set, it will be used as the program to edit the function. If $VISUAL
is unset but $EDITOR
is set, that will be used. Otherwise, a built-in editor will be used. Note that to enter a 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
-e command
or --editor command
Open the function body inside the text editor given by the command (for example, -e vi
). The special command fish
will use the built-in editor (same as specifying -i
).-i
or --interactive
Force opening the function body in the built-in editor even if $VISUAL
or $EDITOR
is defined.Back to command index.
funcsave FUNCTION_NAME
funcsave
saves the current definition of a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use.
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 shell initialization file instead of using funcsave
.
Back to command index.
function NAME [OPTIONS]; BODY; end
function
creates a new function NAME
with the body BODY
.
A function is a list of commands that will be executed when the name of the function is given as a command.
The following options are available:
-a NAMES
or --argument-names NAMES
assigns the value of successive command-line arguments to the names given in NAMES.-d DESCRIPTION
or --description=DESCRIPTION
is a description of what the function does, suitable as a completion description.-w WRAPPED_COMMAND
or --wraps=WRAPPED_COMMAND
causes the function to inherit completions from the given wrapped command. See the documentation for complete
for more information.-e
or --on-event EVENT_NAME
tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.-v
or --on-variable VARIABLE_NAME
tells fish to run this function when the variable VARIABLE_NAME changes value.-j PGID
or --on-job-exit PGID
tells fish to run this function when the job with group ID PGID exits. Instead of PGID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.-p PID
or --on-process-exit PID
tells fish to run this function when the fish child process with process ID PID exits.-s
or --on-signal SIGSPEC
tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP).-S
or --no-scope-shadowing
allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function.-V
or --inherit-variable NAME
snapshots the value of the variable NAME
and defines a local variable with that same name and value when the function is defined. This is similar to a closure in other languages like Python but a bit different. Note the word "snapshot" in the first sentence. If you change the value of the variable after defining the function, even if you do so in the same scope (typically another function) the new value will not be used by the function you just created using this option. See the function notify
example below for how this might be used.If the user enters any additional arguments after the function, they are inserted into the environment variable array $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:
fish_prompt
, which is emitted whenever a new fish prompt is about to be displayed.fish_command_not_found
, which is emitted whenever a command lookup failed.fish_preexec
, which is emitted right before executing an interactive command. The commandline is passed as the first parameter.
Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.
fish_postexec
, which is emitted right after executing an interactive command. The commandline is passed as the first parameter.
Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.
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.
Note that events are only received from the current fish process as there is no way to send events from one fish process to another.
Back to command index.
functions [ -a | --all ] [ -n | --names ] functions [ -D | --details ] [ -v ] FUNCTION functions -c OLDNAME NEWNAME functions -d DESCRIPTION FUNCTION functions [ -e | -q ] FUNCTIONS...
functions
prints or erases functions.
The following options are available:
-a
or --all
lists all functions, even those whose name starts with an underscore.-c OLDNAME NEWNAME
or --copy OLDNAME NEWNAME
creates a new function named NEWNAME, using the definition of the OLDNAME function.-d DESCRIPTION
or --description=DESCRIPTION
changes the description of this function.-e
or --erase
causes the specified functions to be erased.-D
or --details
reports the path name where each function is defined or could be autoloaded, stdin
if the function was defined interactively or on the command line or by reading stdin, and n/a
if the function isn't available. If the --verbose
option is also specified then five lines are written:autoloaded
, not-autoloaded
or n/a
,scope-shadowing
if the function shadows the vars in the calling function (the normal case if it wasn't defined with --no-scope-shadowing
), else no-scope-shadowing
, or n/a
if the function isn't defined,n/a
if the function isn't defined.You should not assume that only five lines will be written since we may add additional information to the output in the future.
-n
or --names
lists the names of all defined functions.-q
or --query
tests if the specified functions exist.-v
or --verbose
will make some output more verbose.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 not included in the output.
If any non-option parameters are given, the definition of the specified functions are printed.
Automatically loaded functions cannot be removed using functions -e
. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions.
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.
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`
Back to command index.
help [SECTION]
help
displays the fish help documentation.
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 an array, 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.
help fg
shows the documentation for the fg
builtin.
Back to command index.
history search [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] [ --max=n ] [ --null ] [ "search string"... ] history delete [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] "search string"... history merge history save history clear history ( -h | --help )
history
is used to search, delete, and otherwise manipulate the history of interactive commands.
The following operations (sub-commands) are available:
search
returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to explicitly say history search
if you wish to search for one of the subcommands. The --contains
search option will be used if you don't specify a different search option. Entries are ordered newest to oldest. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin simply writes the results to stdout.delete
deletes history items. Without the --prefix
or --contains
options, the exact match of the specified text will be deleted. If you don't specify --exact
a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID separated by a space to delete multiple entries. Just press [enter] to not delete anything. Note that the interactive delete behavior is a feature of the history function. The history builtin only supports --exact --case-sensitive
deletion.merge
immediately incorporates history changes from other sessions. Ordinarily fish
ignores history changes from sessions started after the current one. This command applies those changes immediately.save
immediately writes all changes to the history file. The shell automatically saves the history file; this option is provided for internal use and should not normally need to be used by the user.clear
clears the history file. A prompt is displayed before the history is erased asking you to confirm you really want to clear all history unless builtin history
is used.The following options are available:
These flags can appear before or immediately after one of the sub-commands listed above.
-C
or --case-sensitive
does a case-sensitive search. The default is case-insensitive. Note that prior to fish 2.4.0 the default was case-sensitive.-c
or --contains
searches or deletes items in the history that contain the specified text string. This is the default for the --search
flag. This is not currently supported by the --delete
flag.-e
or --exact
searches or deletes items in the history that exactly match the specified text string. This is the default for the --delete
flag. Note that the match is case-insensitive by default. If you really want an exact match, including letter case, you must use the -C
or --case-sensitive
flag.-p
or --prefix
searches or deletes items in the history that begin with the specified text string. This is not currently supported by the --delete
flag.-t
or --show-time
prepends each history entry with the date and time the entry was recorded . By default it uses the strftime format # cn
. You can specify another format; e.g., `–show-time='Y-m-d H:M:S 'or
–show-time='aIp'. The short option,
-tdoesn't accept a stftime format string; it only uses the default format. Any strftime format is allowed, including
sto get the raw UNIX seconds since the epoch. Note that
–with-time` is also allowed but is deprecated and will be removed at a future date.-z
or --null
causes history entries written by the search operations to be terminated by a NUL character rather than a newline. This allows the output to be processed by read -z
to correctly handle multiline history entries.-<number>
-n <number>
or --max=<number>
limits the matched history items to the first "n" matching entries. This is only valid for history search
.-h
or --help
display help for this command.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 seperated by a space.
If you specify both --prefix
and --contains
the last flag seen is used.
Note that for backwards compatibility each subcommand can also be specified as a long option. For example, rather than history search
you can type history --search
. Those long options are deprecated and will be removed in a future release.
Back to command index.
if CONDITION; COMMANDS_TRUE...; [else if CONDITION2; COMMANDS_TRUE2...;] [else; COMMANDS_FALSE...;] end
if
will execute the command CONDITION
. If the condition's exit status is 0, the commands COMMANDS_TRUE
will execute. If the exit status is not 0 and else
is given, COMMANDS_FALSE
will be executed.
You can use and
or or
in the condition. See the second example below.
The exit status of the last foreground command to exit can always be accessed using the $status variable.
The following code will print foo.txt exists
if the file foo.txt exists and is a regular file, otherwise it will print bar.txt exists
if the file bar.txt exists and is a regular file, otherwise it will print foo.txt and bar.txt do not exist
.
if test -f foo.txt echo foo.txt exists else if test -f bar.txt echo bar.txt exists else echo foo.txt and bar.txt do not exist end
The following code will print "foo.txt exists and is readable" if foo.txt is a regular file and readable
if test -f foo.txt and test -r foo.txt echo "foo.txt exists and is readable" end
Back to command index.
isatty [FILE DESCRIPTOR]
isatty
tests if a file descriptor is a tty.
FILE DESCRIPTOR
may be either the number of a file descriptor, or one of the strings stdin
, stdout
, or stderr
.
If the specified file descriptor is a tty, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error.
From an interactive shell, the commands below exit with a return value of zero:
isatty isatty stdout isatty 2 echo | isatty 1
And these will exit non-zero:
echo | isatty isatty 9 isatty stdout > file isatty 2 2> file
Back to command index.
jobs [OPTIONS] [PID]
jobs
prints a list of the currently running jobs and their status.
jobs accepts the following switches:
-c
or --command
prints the command name for each process in jobs.-g
or --group
only prints the group ID of each job.-l
or --last
prints only the last job to be started.-p
or --pid
prints the process ID for each process in all jobs.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%.
jobs
outputs a summary of the current jobs.
Back to command index.
math [-sN] EXPRESSION
math
is used to perform mathematical calculations. It is a very thin wrapper for the bc program, which makes it possible to specify an expression from the command line without using non-standard extensions or a pipeline.
For a description of the syntax supported by math, see the manual for the bc program. Keep in mind that parameter expansion takes place on any expressions before they 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 have to be escaped.
The following options are available:
-sN
Sets the scale of the result. N
must be an integer and defaults to zero. This simply sets bc's scale
variable to the provided value. Note that you cannot put a space between -s
and N
.If invalid options or no expression is provided the return status
is two. If the expression is invalid the return status
is three. If bc returns a result of 0
(literally, not 0.0
or similar variants) the return status
is one otherwise it's zero.
math 1+1
outputs 2.
math $status-128
outputs the numerical exit status of the last command minus 128.
math 10 / 6
outputs 1
.
math -s0 10.0 / 6.0
outputs 1
.
math -s3 10 / 6
outputs 1.666
.
Note that the modulo operator (x % y
) is not well defined for floating point arithmetic. The bc
command produces a nonsensical result rather than emit an error and fail in that case. It doesn't matter if the arguments are integers; e.g., 10 % 4
. You'll still get an incorrect result. Do not use the -sN
flag with N greater than zero if you want sensible answers when using the modulo operator.
Back to command index.
nextd [ -l | --list ] [POS]
nextd
moves forwards POS
positions in the history of visited directories; if the end of the history has been hit, a warning is printed.
If the -l
or --list
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.
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
Back to command index.
not COMMAND [OPTIONS...]
not
negates the exit status of another command. If the exit status is zero, not
returns 1. Otherwise, not
returns 0.
The following code reports an error and exits if no file named spoon can be found.
if not test -f spoon echo There is no spoon exit 1 end
Back to command index.
open FILES...
open
opens a file in its default application, using the appropriate tool for the operating system. On GNU/Linux, this requires the common but optional xdg-open
utility, from the xdg-utils
package.
Note that this function will not be used if a command by this name exists (which is the case on macOS or Haiku).
open *.txt
opens all the text files in the current directory using your system's default text editor.
Back to command index.
COMMAND1; or COMMAND2
or
is used to execute a command if the current exit status (as set by the previous command) is not 0.
or
statements may be used as part of the condition in an and
or while
block. See the documentation for if
and while
for examples.
or
does not change the current exit status. The exit status of the last foreground command to exit can always be accessed using the $status variable.
The following code runs the make
command to build a program. If the build succeeds, the program is installed. If either step fails, make clean
is run, which removes the files created by the build process.
make; and make install; or make clean
Back to command index.
popd
popd
removes the top directory from the directory stack and changes the working directory to the new top directory. Use pushd
to add directories to the stack.
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
Back to command index.
prevd [ -l | --list ] [POS]
prevd
moves backwards POS
positions in the history of visited directories; if the beginning of the history has been hit, a warning is printed.
If the -l
or --list
flag is specified, the current history is also 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.
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
Back to command index.
printf format [argument...]
printf formats the string FORMAT with ARGUMENT, and displays the result.
The string FORMAT should contain format specifiers, each of which are replaced with successive arguments according to the specifier. Specifiers are detailed below, and are taken from the C library function printf(3)
.
Unlike echo
, printf
does not append a new line unless it is specified as part of the string.
Valid format specifiers are:
%d
: Argument will be used as decimal integer (signed or unsigned)%i
: Argument will be used as a signed integer%o
: An octal unsigned integer%u
: An unsigned decimal integer%x
or %X
: An unsigned hexadecimal integer%f
, %g
or %G
: A floating-point number%e
or %E
: A floating-point number in scientific (XXXeYY) notation%s
: A string%b
: As a string, interpreting backslash escapes, except that octal escapes are of the form \0 or \0ooo.%%
signifies a literal "%".
Note that conversion may fail, e.g. "102.234" will not losslessly convert to an integer, causing printf to print an error.
printf also knows a number of backslash escapes:
\"
double quote\\
backslash\a
alert (bell)\b
backspace\c
produce no further output\e
escape\f
form feed\n
new line\r
carriage return\t
horizontal tab\v
vertical tab\ooo
octal number (ooo is 1 to 3 digits)\xhh
hexadecimal number (hhh is 1 to 2 digits)\uhhhh
16-bit Unicode character (hhhh is 4 digits)\Uhhhhhhhh
32-bit Unicode character (hhhhhhhh is 8 digits)The format
argument is re-used as many times as necessary to convert all of the given arguments. If a format specifier is not appropriate for the given argument, an error is printed. For example, `printf 'd' "102.234"` produces an error, as "102.234" cannot be formatted as an integer.
This file 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
.
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.
Back to command index.
prompt_pwd
prompt_pwd is a function to print the current working directory in a way suitable for prompts. It will replace the home directory with "~" and shorten every path component but the last to a default of one character.
To change the number of characters per path component, set $fish_prompt_pwd_dir_length to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely.
> 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
Back to command index.
COMMAND1 ( COMMAND2 | psub [-f] [-s SUFFIX])
Posix shells feature a syntax that is a mix between command substitution and piping, called process substitution. It is used to send the output of a command into the calling command, much like command substitution, but with the difference that the output is not sent through commandline arguments but through a named pipe, with the filename of the named pipe sent as an argument to the calling program. psub
combined with a regular command substitution provides the same functionality.
If the -f
or --file
switch is given to psub
, psub
will use a regular file instead of a named pipe to communicate with the calling process. This will cause psub
to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream.
If the -s
or ---suffix
switch is given, psub
will append SUFFIX to the filename.
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 -s .c) # highlights `main.c` after preprocessing as a C source.
Back to command index.
pushd [DIRECTORY]
The pushd
function adds DIRECTORY
to the top of the directory stack and makes it the current working directory. popd
will pop it off and return to the original directory.
Without arguments, it exchanges the top two directories in the stack.
pushd +NUMBER
rotates the stack counter-clockwise i.e. from bottom to top
pushd -NUMBER
rotates clockwise i.e. top to bottom.
See also dirs
and dirs -c
.
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 pushd /tmp/ # Working directory is now /tmp # Directory stack contains /tmp /usr/src /usr/src/fish-shell pushd +1 # Working directory is now /usr/src # Directory stack contains /usr/src /usr/src/fish-shell /tmp popd # Working directory is now /usr/src/fish-shell # Directory stack contains /usr/src/fish-shell /tmp
Back to command index.
pwd
pwd
outputs (prints) the current working directory.
Note that fish
always resolves symbolic links in the current directory path.
Back to command index.
random random SEED random START END random START STEP END random choice [ITEMS...]
RANDOM
generates a pseudo-random integer from a uniform distribution. The range (inclusive) is dependent on the arguments passed. No arguments indicate a range of [0; 32767]. 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 of [START; END]. Three arguments indicate a range of [START; 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.
The following code will count down from a random even number between 10 and 20 to 1:
for i in (seq (random 10 2 20) -1 1) echo $i end
And this will open a random picture from any of the subdirectories:
open (random choice **jpg)
Back to command index.
read [OPTIONS] [VARIABLES...]
read
reads from standard input and stores the result in one or more shell variables. By default it reads one line terminated by a newline but options are available to read up to a null character and to limit each "line" to a maximum number of characters.
The following options are available:
-c CMD
or --command=CMD
sets the initial string in the interactive mode command buffer to CMD
.-g
or --global
makes the variables global.-i
or --silent
makes the characters typed obfuscated. This is useful for reading things like passwords or other sensitive information. Note that in bash the short flag is -s
. We can't use that due to the existing use as an alias for --shell
.-l
or --local
makes the variables local.-m NAME
or --mode-name=NAME
specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available.-n NCHARS
or --nchars=NCHARS
causes read
to return after reading NCHARS characters rather than waiting for a complete line of input (either newline or null terminated).-p PROMPT_CMD
or --prompt=PROMPT_CMD
uses the output of the shell command PROMPT_CMD
as the prompt for the interactive mode. The default prompt command is set_color green; echo read; set_color normal; echo "> "
.-P PROMPT_STR
or --prompt-str=PROMPT_STR
uses the string as the prompt for the interactive mode. It is equivalent to echo PROMPT_STR
and is provided solely to avoid the need to frame the prompt as a command. All special characters in the string are automatically escaped before being passed to the echo
command.-R RIGHT_PROMPT_CMD
or --right-prompt=RIGHT_PROMPT_CMD
uses the output of the shell command RIGHT_PROMPT_CMD
as the right prompt for the interactive mode. There is no default right prompt command.-s
or --shell
enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.-u
or --unexport
prevents the variables from being exported to child processes (default behaviour).-U
or --universal
causes the specified shell variable to be made universal.-x
or --export
exports the variables to child processes.-a
or --array
stores the result as an array in a single variable.-z
or --null
reads up to NUL instead of newline. Disables interactive mode.read
reads a single line of input from stdin, breaks it into tokens based on the IFS
shell variable, 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. As a special case, if IFS
is set to the empty string, each character of the input is considered a separate token.
If -a
or --array
is provided, only one variable name is allowed and the tokens are stored as an array 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 separator, it sets $status
to 1. If not, it sets it to 0.
Fish has a default limit of 10 MiB on the number of characters each read
will consume. If you attempt to read more than that $status
is set to 122 and the variable will be empty. You can modify that limit by setting the FISH_READ_BYTE_LIMIT
variable at any time including in the environment before fish starts running. This is a safety mechanism to keep the shell from consuming an unreasonable amount of memory if the input is malformed.
The following code stores the value 'hello' in the shell variable $foo
.
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
Back to command index.
realpath path
This is implemented as a function and a builtin. The function will attempt to use an external realpath command if one can be found. Otherwise it falls back to the builtin. The builtin does not support any options. It's meant to be used only by scripts which need to be portable. The builtin implementation behaves like GNU realpath when invoked without any options (which is the most common use case). In general scripts should not invoke the builtin directly. They should just use realpath
.
If the path is invalid no translated path will be written to stdout and an error will be reported.
Back to command index.
function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end
return
halts a currently running function. The exit status is set to STATUS
if it is given.
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.
The following code is an implementation of the false command as a fish function
function false return 1 end
Back to command index.
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
manipulates shell variables.
If set is called with no arguments, the names and values of all shell variables are printed in sorted order. If some of the scope or export flags have been given, only the variables matching the specified scope are printed.
With both variable names and values provided, set
assigns the variable VARIABLE_NAME
the values VALUES...
.
The following options control variable scope:
-l
or --local
forces the specified shell variable to be given a scope that is local to the current block, even if a variable with the given name exists and is non-local-g
or --global
causes the specified shell variable to be given a global scope. Non-global variables disappear when the block they belong to ends-U
or --universal
causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current users fish instances on the current computer, and will be preserved across restarts of the shell.-x
or --export
causes the specified shell variable to be exported to child processes (making it an "environment variable")-u
or --unexport
causes the specified shell variable to NOT be exported to child processesThe following options are available:
-e
or --erase
causes the specified shell variable to be erased-q
or --query
test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined.-n
or --names
List only the names of all defined variables, not their value. The names are guaranteed to be sorted.-L
or --long
do not abbreviate long values when printing set variablesIf a variable is set to more than one value, the variable will be an array with the specified elements. If a variable is set to zero elements, it will become an array with zero elements.
If the variable name is one or more array elements, such as PATH[1 3 7]
, only those array elements specified will be changed. When array indices are specified to set
, multiple arguments may be used to specify additional indexes, e.g. set PATH[1] PATH[4] /bin /sbin
. If you specify a negative index when expanding or assigning to an array variable, the index will be calculated from the end of the array. For example, the index -1 means the last index of an array.
The scoping rules when creating or updating a variable are:
-l
or --local
flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. If no function is executing, the variable will be global.The exporting rules when creating or updating a variable are identical to the scoping rules for variables:
In query mode, the scope to be examined can be specified.
In erase mode, if variable indices are specified, only the specified slices of the array variable will be erased.
set
requires all options to come before any other arguments. For example, set flags -l
will have the effect of setting the value of the variable flags
to '-l', not making the variable local.
In assignment mode, set
does not modify the exit status. This allows simultaneous capture of the output and exit status of a subcommand, e.g. if set output (command)
. In query mode, the exit status is the number of variables that were not found. In erase mode, set
exits with a zero exit status in case of success, with a non-zero exit status if the commandline was invalid, if the variable was write-protected or if the variable did not exist.
set -xg # Prints all global, exported variables. set foo hi # Sets the value of the variable $foo to be 'hi'. set -e smurf # Removes the variable $smurf set PATH[4] ~/bin # Changes the fourth element of the $PATH array to ~/bin if set python_path (type -p python) echo "Python is at $python_path" end # Outputs the path to Python if `type -p` returns true.
Back to command index.
set_color [OPTIONS] VALUE
set_color
is used to control the color and styling of text in the terminal. VALUE
corresponds to a reserved color name such as red or a RGB color value given as 3 or 6 hexadecimal digits. The br-, as in 'bright', forms are full-brightness variants of the 8 standard-brightness colors on many terminals. brblack has higher brightness than black - towards gray. A special keyword normal resets text formatting to terminal defaults.
Valid colors include:
An RGB value with three or six hex digits, such as A0FF33 or f2f can be used. fish
will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., set_color 2BC
is the same as set_color 22BBCC
. Hexadecimal RGB values can be in lower or uppercase. Depending on the capabilities of your terminal (and the level of support set_color
has for it) the actual color may be approximated by a nearby matching reserved color name or set_color
may not have an effect on color. A second color may be given as a desired fallback color. e.g. set_color 124212
brblue will instruct set_color to use brblue if a terminal is not capable of the exact shade of grey desired. This is very useful when an 8 or 16 color terminal might otherwise not use a color.
The following options are available:
-b
, --background
COLOR sets the background color.-c
, --print-colors
prints a list of the 16 named colors.-o
, --bold
sets bold mode.-d
, --dim
sets dim mode.-i
, --italics
sets italics mode.-r
, --reverse
sets reverse mode.-u
, --underline
sets underlined mode.Using the normal keyword will reset foreground, background, and all formatting back to default.
--bold
escape sequence to switch to a brighter color set rather than increasing the weight of text.set_color
works by printing sequences of characters to stdout. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit code of isatty stdout
before using set_color
can be useful to decide not to colorize output in a script.set_color red; echo "Roses are red" set_color blue; echo "Violets are blue" set_color 62A; echo "Eggplants are dark purple" set_color normal; echo "Normal is nice" ## Resets the background too
Fish uses a heuristic to decide if a terminal supports the 256-color palette as opposed to the more limited 16 color palette of older terminals. Support can be forced on by setting fish_term256
to 1. If $TERM
contains "256color" (e.g., xterm-256color), 256-color support is enabled. If $TERM
contains xterm, 256 color support is enabled (except for MacOS: $TERM_PROGRAM
and $TERM_PROGRAM_VERSION
are used to detect Terminal.app from MacOS 10.6; support is disabled here it because it is known that it reports xterm
and only supports 16 colors.
If terminfo reports 256 color support for a terminal, support will always be enabled. To debug color palette problems, tput colors
may be useful to see the number of colors in terminfo for a terminal. Fish launched as fish -d2
will include diagnostic messages that indicate the color support mode in use.
Many terminals support 24-bit (i.e., true-color) color escape sequences. This includes modern xterm, Gnome Terminal, Konsole, and iTerm2. Fish attempts to detect such terminals through various means in config.fish
You can explicitly force that support via set fish_term24bit 1
.
The set_color
command uses the terminfo database to look up how to change terminal colors on whatever terminal is in use. Some systems have old and incomplete terminfo databases, and may lack color information for terminals that support it. Fish will assume that all terminals can use the ANSI X3.64 escape sequences if the terminfo definition indicates a color below 16 is not supported.
Support for italics, dim, reverse, and other modes is not guaranteed in all terminal emulators. Fish attempts to determine if the terminal supports these modes even if the terminfo database may not be up-to-date.
Back to command index.
source FILENAME [ARGUMENTS...]
source
evaluates the commands of the specified file in the current shell. This is different from starting a new process to perform the commands (i.e. fish < FILENAME
) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the $argv
variable. The $argv
variable will not include the name of the sourced file.
If no file is specified, or if the file name '-
' is used, stdin will be read.
The return status of source
is the return status of the last job to execute. If something goes wrong while opening or reading the file, source
exits with a non-zero status.
.
(a single period) is an alias for the source
command. The use of .
is deprecated in favour of source
, and .
will be removed in a future version of fish.
source ~/.config/fish/config.fish # Causes fish to re-read its initialization file.
In fish versions prior to 2.3.0 the $argv
variable would have a single element (the name of the sourced file) if no arguments are present. Otherwise it would contain arguments without the name of the sourced file. That behavior was very confusing and unlike other shells such as bash and zsh.
Back to command index.
status status is-login status is-interactive status is-block status is-command-substitution status is-no-job-control status is-full-job-control status is-interactive-job-control status current-filename status current-function status current-line-number status print-stack-trace status job-control CONTROL-TYPE
With no arguments, status
displays a summary of the current login and job control status of the shell.
The following operations (sub-commands) are available:
is-command-sub
returns 0 if fish is currently executing a command substitution. Also -c
or --is-command-substitution
.is-block
returns 0 if fish is currently executing a block of code. Also -b
or --is-block
.is-interactive
returns 0 if fish is interactive - that is, connected to a keyboard. Also -i
or --is-interactive
.is-login
returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH. Also -l
or --is-login
.is-full-job-control
returns 0 if full job control is enabled. Also --is-full-job-control
(no short flag).is-interactive-job-control
returns 0 if interactive job control is enabled. Also, --is-interactive-job-control
(no short flag).is-no-job-control
returns 0 if no job control is enabled. Also --is-no-job-control
(no short flag).current-filename
prints the filename of the currently running script. Also -f
or --current-filename
.current-function
prints the name of the currently called function if able, when missing displays "Not a function". Also -u
or --current-function
.current-line-number
prints the line number of the currently running script. Also -n
or --current-line-number
.job-control CONTROL-TYPE
sets the job control type, which can be none
, full
, or interactive
. Also -j CONTROL-TYPE
or --job-control=CONTROL-TYPE
.print-stack-trace
prints a stack trace of all function calls on the call stack. Also -t
or --print-stack-trace
.For backwards compatibility each subcommand can also be specified as a long or short option. For example, rather than status is-login
you can type status --is-login
. The flag forms are deprecated and may be removed in a future release (but not before fish 3.0).
You can only specify one subcommand per invocation even if you use the flag form of the subcommand.
Back to command index.
string length [(-q | --quiet)] [STRING...] string sub [(-s | --start) START] [(-l | --length) LENGTH] [(-q | --quiet)] [STRING...] string split [(-m | --max) MAX] [(-r | --right)] [(-q | --quiet)] SEP [STRING...] string join [(-q | --quiet)] SEP [STRING...] string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)] [(-q | --quiet)] [STRING...] string escape [(-n | --no-quoted)] [STRING...] string match [(-a | --all)] [((-e | --entire)] [(-i | --ignore-case)] [(-r | --regex)] [(-n | --index)] [(-q | --quiet)] [(-v | --invert)] PATTERN [STRING...] string replace [(-a | --all)] [(-f | --filter)] [(-i | --ignore-case)] [(-r | --regex)] [(-q | --quiet)] PATTERN REPLACEMENT [STRING...] string repeat [(-n | --count)] [(-m | --max)] [(-N | --no-newline)] [(-q | --quiet)] [STRING...]
string
performs operations on strings.
STRING arguments are taken from the command line unless standard input is connected to a pipe or a file, in which case they are read from standard input, one STRING per line. It is an error to supply STRING arguments on the command line and on standard input.
Arguments beginning with -
are normally interpreted as switches; --
causes the following arguments not to be treated as switches even if they begin with -
. Switches and required arguments are recognized only on the command line.
Most subcommands accept a -q
or --quiet
switch, which suppresses the usual output but exits with the documented status.
The following subcommands are available.
string length
reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise.
string sub
prints a substring of each string argument. The start of the substring can be specified with -s
or --start
followed by a 1-based index value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be specified with -l
or --length
. If the length is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise.
string split
splits each STRING on the separator SEP, which can be an empty string. If -m
or --max
is specified, at most MAX splits are done on each STRING. If -r
or --right
is given, splitting is performed right-to-left. This is useful in combination with -m
or --max
. Exit status: 0 if at least one split was performed, or 1 otherwise.
string join
joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise.
string trim
removes leading and trailing whitespace from each STRING. If -l
or --left
is given, only leading whitespace is removed. If -r
or --right
is given, only trailing whitespace is trimmed. The -c
or --chars
switch causes the characters in CHARS to be removed instead of whitespace. Exit status: 0 if at least one character was trimmed, or 1 otherwise.
string escape
escapes each STRING such that it can be passed back to eval
to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If -n
or --no-quoted
is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.
string match
tests each STRING against PATTERN and prints matching substrings. Only the first match for each STRING is reported unless -a
or --all
is given, in which case all matches are reported.The default behavior is equivalent to grep -o
.
If you specify the -e
or --entire
then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to grep
without the -o
flag). You can, obviously, achieve the same result by prepending and appending *
or .*
depending on whether or not you have specified the --regex
flag. The --entire
flag is simply a way to avoid having to complicate the pattern in that fashion and make the intent of the string match
clearer.
Matching can be made case-insensitive with --ignore-case
or -i
.
If --index
or -n
is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire STRING argument. A glob pattern is only considered a valid match if it matches the entire STRING.
If --regex
or -r
is given, PATTERN is interpreted as a Perl-compatible regular expression, which does not have to match the entire STRING. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group.
If --invert
or -v
is used the selected lines will be only those which do not match the given glob pattern or regular expression.
Exit status: 0 if at least one match was found, or 1 otherwise.
string replace
is similar to string match
but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched.
If -r
or --regex
is given, PATTERN is interpreted as a Perl-compatible regular expression, and REPLACEMENT can contain C-style escape sequences like \t
as well as references to capturing groups by number or name as $n
or ${n}
.
If you specify the -f
or --filter
flag then each input string is printed only if a replacement was done. This is useful where you would otherwise use this idiom: a_cmd | string match pattern | string replace pattern new_pattern
. You can instead just write a_cmd | string replace --filter pattern new_pattern
.
Exit status: 0 if at least one replacement was performed, or 1 otherwise.
string repeat
repeats the STRING -n
or --count
times. The -m
or --max
option will limit the number of outputed char (excluding the newline). This option can be used by itself or in conjuction with --count
. If both --count
and --max
are present, max char will be outputed unless the final repeated string size is less than max, in that case, the string will repeat until count has been reached. Both --count
and --max
will accept a number greater than or equal to zero, in the case of zero, nothing will be outputed. If -N
or --no-newline
is given, the output won't contain a newline character at the end. Exit status: 0 if yielded string is not empty, 1 otherwise.
Both the match
and replace
subcommand support regular expressions when used with the -r
or --regex
option. The dialect is that of PCRE2.
In general, special characters are special by default, so a+
matches one or more "a"s, while a\+
matches an "a" and then a "+". (a+)
matches one or more "a"s in a capturing group ((?:XXXX)
denotes a non-capturing group). For the replacement parameter of replace
, $n
refers to the n-th group of the match. In the match parameter, \n
(e.g. \1
) refers back to groups.
> string length 'hello, world' 12 > set str foo > string length -q $str; echo $status 0 # Equivalent to test -n $str
> string sub --length 2 abcde ab > string sub -s 2 -l 2 abcde bc > string sub --start=-2 abcde de
> string split . example.com example com > string split -r -m1 / /usr/local/bin/fish /usr/local/bin fish > string split '' abc a b c
> seq 3 | string join ... 1...2...3
> string trim ' abc ' abc > string trim --right --chars=yz xyzzy zany x zan
> echo \x07 | string escape \cg
> string match '?' a a > string match 'a*b' axxb axxb > string match -i 'a??B' Axxb Axxb > echo 'ok?' | string match '*\?' >_ ok?
> string match -r 'cat|dog|fish' 'nice dog' dog > string match -r -v "c.*[12]" {cat,dog}(seq 1 4) dog1 dog2 cat3 dog3 cat4 dog4 > string match -r '(\d\d?):(\d\d):(\d\d)' 2:34:56 2:34:56 2 34 56 > string match -r '^(\w{2,4})\g1$' papa mud murmur papa pa murmur mur > string match -r -a -n at ratatat 2 2 4 2 6 2 > string match -r -i '0x[0-9a-f]{1,8}' 'int magic = 0xBadC0de;' 0xBadC0de
> string replace is was 'blue is my favorite' blue was my favorite > string replace 3rd last 1st 2nd 3rd 1st 2nd last > string replace -a ' ' _ 'spaces to underscores' spaces_to_underscores
> string replace -r -a '[^\d.]+' ' ' '0 one two 3.14 four 5x' 0 3.14 5 > string replace -r '(\w+)\s+(\w+)' '$2 $1 $$' 'left right' right left $ > string replace -r '\s*newline\s*' '\n' 'put a newline here' put a here
> string repeat -n 2 'foo ' foo foo > echo foo | string repeat -n 2 foofoo > string repeat -n 2 -m 5 'foo' foofo > string repeat -m 5 'foo' foofo
Back to command index.
suspend [--force]
suspend
suspends execution of the current shell by sending it a SIGTSTP signal, returning to the controlling process. It can be resumed later by sending it a SIGCONT. In order to prevent suspending a shell that doesn't have a controlling process, it will not suspend the shell if it is a login shell. This requirement is bypassed if the --force
option is given or the shell is not interactive.
Back to command index.
switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
switch
performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. case
is used together with the switch
statement in order to determine which block should be executed.
Each case
command is given one or more parameters. The first case
command with a parameter that matches the string specified in the switch command will be evaluated. case
parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames.
Note that fish does not fall through on case statements. Only the first matching case is executed.
Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter.
If the variable $animal contains the name of an animal, the following code would attempt to classify it:
switch $animal case cat echo evil case wolf dog human moose dolphin whale echo mammal case duck goose albatross echo bird case shark trout stingray echo fish case '*' echo I have no idea what a $animal is end
If the above code was run with $animal
set to whale
, the output would be mammal
.
Back to command index.
test [EXPRESSION] [ [EXPRESSION] ]
Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments.
The first form (test
) is preferred. For compatibility with other shells, the second form is available: a matching pair of square brackets ([ [EXPRESSION ] ]
).
This test is mostly POSIX-compatible.
-b FILE
returns true if FILE
is a block device.-c FILE
returns true if FILE
is a character device.-d FILE
returns true if FILE
is a directory.-e FILE
returns true if FILE
exists.-f FILE
returns true if FILE
is a regular file.-g FILE
returns true if FILE
has the set-group-ID bit set.-G FILE
returns true if FILE
exists and has the same group ID as the current user.-k FILE
returns true if FILE
has the sticky bit set. If the OS does not support the concept it returns false. See https://en.wikipedia.org/wiki/Sticky_bit.-L FILE
returns true if FILE
is a symbolic link.-O FILE
returns true if FILE
exists and is owned by the current user.-p FILE
returns true if FILE
is a named pipe.-r FILE
returns true if FILE
is marked as readable.-s FILE
returns true if the size of FILE
is greater than zero.-S FILE
returns true if FILE
is a socket.-t FD
returns true if the file descriptor FD
is a terminal (TTY).-u FILE
returns true if FILE
has the set-user-ID bit set.-w FILE
returns true if FILE
is marked as writable; note that this does not check if the filesystem is read-only.-x FILE
returns true if FILE
is marked as executable.STRING1 = STRING2
returns true if the strings STRING1
and STRING2
are identical.STRING1 != STRING2
returns true if the strings STRING1
and STRING2
are not identical.-n STRING
returns true if the length of STRING
is non-zero.-z STRING
returns true if the length of STRING
is zero.NUM1 -eq NUM2
returns true if NUM1
and NUM2
are numerically equal.NUM1 -ne NUM2
returns true if NUM1
and NUM2
are not numerically equal.NUM1 -gt NUM2
returns true if NUM1
is greater than NUM2
.NUM1 -ge NUM2
returns true if NUM1
is greater than or equal to NUM2
.NUM1 -lt NUM2
returns true if NUM1
is less than NUM2
.NUM1 -le NUM2
returns true if NUM1
is less than or equal to NUM2
.Note that only integers are supported. For more complex mathematical operations, including fractions, the env
program may be useful. Consult the documentation for your operating system.
COND1 -a COND2
returns true if both COND1
and COND2
are true.COND1 -o COND2
returns true if either COND1
or COND2
are true.Expressions can be inverted using the !
operator:
! EXPRESSION
returns true if EXPRESSION
is false, and false if EXPRESSION
is true.Expressions can be grouped using parentheses.
( EXPRESSION )
returns the value of EXPRESSION
.
Note that parentheses will usually require escaping with \(
to avoid being interpreted as a command substitution.
If the /tmp
directory exists, copy the /etc/motd
file to it:
if test -d /tmp cp /etc/motd /tmp/motd end
If the variable MANPATH
is defined and not empty, print the contents. (If MANPATH
is not defined, then it will expand to zero arguments, unless quoted.)
if test -n "$MANPATH" echo $MANPATH end
Parentheses and the -o
and -a
operators can be combined to produce more complicated expressions. In this example, success is printed if there is a /foo
or /bar
file as well as a /baz
or /bat
file.
if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \) echo Success. end.
Numerical comparisons will simply fail if one of the operands is not a number:
if test 42 -eq "The answer to life, the universe and everything" echo So long and thanks for all the fish ## will not be executed end
A common comparison is with $status:
if test $status -eq 0 echo "Previous command succeeded" end
test
implements a subset of the IEEE Std 1003.1-2008 (POSIX.1) standard. The following exceptions apply:
<
and >
operators for comparing strings are not implemented.Because this test is a shell builtin and not a standalone utility, using the -c flag on a special file descriptors like standard input and output may not return the same result when invoked from within a pipe as one would expect when invoking the test
utility in another shell.
In cases such as this, one can use command
test
to explicitly use the system's standalone test
rather than this builtin
test
.
Back to command index.
trap [OPTIONS] [[ARG] REASON ... ]
trap
is a wrapper around the fish event delivery framework. It exists for backwards compatibility with POSIX shells. For other uses, it is recommended to define an event handler.
The following parameters are available:
ARG
is the command to be executed on signal delivery.REASON
is the name of the event to trap. For example, a signal like INT
or SIGINT
, or the special symbol EXIT
.-l
or --list-signals
prints a list of signal names.-p
or --print
prints all defined signal handlers.If ARG
and REASON
are both specified, ARG
is the command to be executed when the event specified by REASON
occurs (e.g., the signal is delivered).
If ARG
is absent (and there is a single REASON) or -, each specified signal is reset to its original disposition (the value it had upon entrance to the shell). If ARG
is the null string the signal specified by each REASON
is ignored by the shell and by the commands it invokes.
If ARG
is not present and -p
has been supplied, then the trap commands associated with each REASON
are displayed. If no arguments are supplied or if only -p
is given, trap
prints the list of commands associated with each signal.
Signal names are case insensitive and the SIG
prefix is optional.
The return status is 1 if any REASON
is invalid; otherwise trap returns 0.
trap "status --print-stack-trace" SIGUSR1 # Prints a stack trace each time the SIGUSR1 signal is sent to the shell.
Back to command index.
true
true
sets the exit status to 0.
Back to command index.
type [OPTIONS] NAME [NAME ...]
With no options, type
indicates how each NAME
would be interpreted if used as a command name.
The following options are available:
-a
or --all
prints all of possible definitions of the specified names.-f
or --no-functions
suppresses function and builtin lookup.-t
or --type
prints function
, builtin
, or file
if NAME
is a shell function, builtin, or disk file, respectively.-p
or --path
returns the name of the disk file that would be executed, or nothing if type -t name
would not return file
.-P
or --force-path
returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the $PATH
.-q
or --quiet
suppresses all output; this is useful when testing the exit status.> type fg fg is a builtin
Back to command index.
ulimit [OPTIONS] [LIMIT]
ulimit
builtin sets or outputs the resource usage limits of the shell and any processes spawned by it. If a new limit value is omitted, the current value of the limit of the resource is printed; otherwise, the specified limit is set to the new value.
Use one of the following switches to specify which resource limit to set or report:
-c
or --core-size
: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled.-d
or --data-size
: the maximum size of a process' data segment.-f
or --file-size
: the maximum size of files created by the shell.-l
or --lock-size
: the maximum size that may be locked into memory.-m
or --resident-set-size
: the maximum resident set size.-n
or --file-descriptor-count
: the maximum number of open file descriptors (most systems do not allow this value to be set).-s
or --stack-size
: the maximum stack size.-t
or --cpu-time
: the maximum amount of CPU time in seconds.-u
or --process-count
: the maximum number of processes available to a single user.-v
or --virtual-memory-size
The maximum amount of virtual memory available to the shell.Note that not all these limits are available in all operating systems.
The value of limit can be a number in the unit specified for the resource or one of the special values hard
, soft
, or unlimited
, which stand for the current hard limit, the current soft limit, and no limit, respectively.
If limit is given, it is the new value of the specified resource. If no option is given, then -f
is assumed. Values are in kilobytes, except for -t
, which is in seconds and -n
and -u
, which are unscaled values. The return status is 0 unless an invalid option or argument is supplied, or an error occurs while setting a new limit.
ulimit
also accepts the following switches that determine what type of limit to set:
-H
or --hard
sets hard resource limit-S
or --soft
sets soft resource limitA hard limit can only be decreased. Once it is set it cannot be increased; a soft limit may be increased up to the value of the hard limit. If neither -H nor -S is specified, both the soft and hard limits are updated when assigning a new limit value, and the soft limit is used when reporting the current value.
The following additional options are also understood by ulimit
:
-a
or --all
prints all current limitsThe fish
implementation of ulimit
should behave identically to the implementation in bash, except for these differences:
ulimit
supports GNU-style long options for all switchesulimit
does not support the -p
option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish.ulimit
does not support getting or setting multiple limits in one command, except reporting all values using the -a switchulimit -Hs 64
sets the hard stack size limit to 64 kB.
Back to command index.
umask [OPTIONS] [MASK]
umask
displays and manipulates the "umask", or file creation mode mask, which is used to restrict the default access to files.
The umask may be expressed either as an octal number, which represents the rights that will be removed by default, or symbolically, which represents the only rights that will be granted by default.
Access rights are explained in the manual page for the chmod
(1) program.
With no parameters, the current file creation mode mask is printed as an octal number.
-h
or --help
prints this message.-S
or --symbolic
prints the umask in symbolic form instead of octal form.-p
or --as-command
outputs the umask in a form that may be reused as inputIf a numeric mask is specified as a parameter, the current shell's umask will be set to that value, and the rights specified by that mask will be removed from new files and directories by default.
If a symbolic mask is specified, the desired permission bits, and not the inverse, should be specified. A symbolic mask is a comma separated list of rights. Each right consists of three parts:
u
, g
, o
or a
, where u
specifies the user who owns the file, g
specifies the group owner of the file, o
specific other users rights and a
specifies all three should be changed.=
, +
or -
, where =
specifies that the rights should be set to the new value, +
specifies that the specified right should be added to those previously specified and -
specifies that the specified rights should be removed from those previously specified.r
, w
and x
, representing read, write and execute rights.If the first and second parts are skipped, they are assumed to be a
and =
, respectively. As an example, r,u+w
means all users should have read access and the file owner should also have write access.
Note that symbolic masks currently do not work as intended.
umask 177
or umask u=rw
sets the file creation mask to read and write for the owner and no permissions at all for any other users.
Back to command index.
vared VARIABLE_NAME
vared
is used to interactively edit the value of an environment variable. Array variables as a whole can not be edited using vared
, but individual array elements can.
vared PATH[3]
edits the third element of the PATH array
Back to command index.
while CONDITION; COMMANDS...; end
while
repeatedly executes CONDITION
, and if the exit status is 0, then executes COMMANDS
.
If the exit status of CONDITION
is non-zero on the first iteration, COMMANDS
will not be executed at all.
You can use and
or or
for complex conditions. Even more complex control can be achieved with while true
containing a break.
while test -f foo.txt; or test -f bar.txt ; echo file exists; sleep 10; end # outputs 'file exists' at 10 second intervals as long as the file foo.txt or bar.txt exists.
Back to command index.