fish home | Main documentation page | Design document | Commands | FAQ | License

Commands, functions and builtins bundled with fish

Fish ships with a large number of builtin commands, shellscript functions and external commands.

These are all described below.


alias - create a function

Synopsis

alias NAME DEFINITION
alias NAME=DEFINITION

Description

Alias is a shellscript wrapper around the function builtin. It exists for backwards compatibility with Posix shells. For other uses, it is recommended to define a function.

Alias does not keep track of which functions have been defined using alias, nor does it allow erasing of aliases.

Back to index.


and - conditionally execute a command

Synopsis

COMMAND1; and COMMAND2

Description

The and builtin is used to execute a command if the current exit status (as set by the last previous command) is 0.

The and command 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.

Example

The following code runs the make command to build a program, if the build succeeds, the program is installed. If either step fails, make clean is run, which removes the files created by the build process

make; and make install; or make clean

Back to index.


begin - start a new block of code

Synopsis

begin; [COMMANDS...;] end

Description

The begin builtin is used to create a new block of code. The block is unconditionally executed. begin; ...; end is equivalent to if true; ...; end. The begin command is used to group any number of commands into a block. The reason for doing so is usually either to introduce a new variable scope, to redirect the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like and.

The begin command does not change the current exit status.

Example

The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends.

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

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


bg - send to background

Synopsis

bg [PID...]

Description

Sends the specified jobs to the background. 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 group ids are put in the background.

The PID of the desired process is usually found by using process expansion.

Example

bg %0 will put the job with job id 0 in the background.

Back to index.


bind - handle fish key bindings

Synopsis

bind [OPTIONS] SEQUENCE COMMAND

Description

The bind builtin causes fish to add a key binding from the specified sequence.

SEQUENCE is the character sequence to bind to. Usually, one would use fish escape sequences to express them. 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. Control character can be written in much the same way using the \c escape, for example Control-x can be written as \cx. Note that Alt-based key bindings are case sensitive and Control base key bindings are not. This is not a design choice in fish, it is simply how terminals work.

If SEQUENCE is the empty string, i.e. an empty set of quotes, this is interpreted as the default keybinding. 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 keybining. 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 e.g. 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 man 5 terminfo 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.

Example

bind \cd 'exit' causes fish to exit on Control-d

bind -k ppage history-search-backward Causes fish to perform a history search when the page up key is pressed

Back to index.


block - temporarily block delivery of events

Synopsis

block [OPTIONS...]

Description

Example

block -g
#Do something that should not be interrupted
block -e

Back to index.


break - stop the innermost currently evaluated loop

Synopsis

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

Description

The break builtin is used to halt 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.

Example

The following code searches all .c files for smurfs, 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 index.


breakpoint - Launch debug mode

Synopsis

breakpoint

Description

The breakpoint builtin is used to halt a running script and launch an interactive debug prompt.

Back to index.


builtin - run a builtin command

Synopsis

builtin BUILTINNAME [OPTIONS...]

Description

Prefixing a command with the word 'builtin' forces fish to ignore any functions with the same name.

Example

builtin jobs

causes fish to execute the jobs builtin, even if a function named jobs exists.

Back to index.


case - conditionally execute a block of commands

Synopsis

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

Description

The switch statement is used to perform one of several blocks of commands depending on whether a specified value equals one of several wildcarded values. The case statement is used together with the switch statement in order to determine which block should be performed.

Each case command is given one or more parameter. 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. Though the syntax may look a bit like C switch statements, it behaves more like the case statements of traditional shells.

Also note that command substitutions in a case statement will be evaluated even if it's body is not taken. This may seem counterintuitive at first, but it is unavoidable, since it would be impossible to know if a case command will evaluate to true before all forms of parameter expansion have been performed for the case command.

Example

If the variable $animal contains the name of an animal, the following code would attempt to classify it:

switch $animal
    case cat
        echo evil
    case wolf dog human moose dolphin whale
        echo mammal
    case duck goose albatross
        echo bird
    case shark trout stingray
        echo fish
    case '*'
        echo I have no idea what a $animal is
end

If the above code was run with $animal set to whale, the output would be mammal.

Back to index.


cd - change directory

Synopsis

cd [DIRECTORY]

Description Changes the current

directory. If DIRECTORY is supplied it will become the new directory. If DIRECTORY is a relative path, the paths found in the CDPATH environment variable array will be tried as prefixes for the specified path. If CDPATH is not set, it is assumed to be '.'. If DIRECTORY is not specified, $HOME will be the new directory.

Back to index.


command - run a program

Synopsis

command COMMANDNAME [OPTIONS...]

Description

prefixing a command with the word 'command' forces fish to ignore any functions or builtins with the same name.

Example

command ls

causes fish to execute the ls program, even if there exists a 'ls' function.

Back to index.


commandline - set or get the current commandline buffer

Synopsis

commandline [OPTIONS] [CMD]

Description

The following switches change what the commandline builtin does

The following switches change the way commandline updates the commandline buffer

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

The following switch changes the way commandline prints the current commandline buffer

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

Example

commandline -j $history[3]

replaces the job under the cursor with the third item from the commandline history.

Back to index.


complete - edit command specific tab-completions.

Synopsis

complete (-c|--command|-p|--path) COMMAND [(-s|--short-option) SHORT_OPTION] [(-l|--long-option|-o|--old-option) LONG_OPTION [(-a||--arguments) OPTION_ARGUMENTS] [(-d|--description) DESCRIPTION]

Description

For an introduction to how to specify completions, see the section Writing your own completions of the fish manual.

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

The options for specifying command name, command path, or command switches may all be used multiple times to specify multiple commands which have the same completion or multiple switches accepted by a command.

When erasing completions, it is possible to either erase all completions for a specific command by specifying complete -e -c COMMAND, or by specifying a specific completion option to delete by specifying either a long, short or old style option.

Example

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" -l nodeps -d "Don't check dependencies"

where __fish_contains_opt is a function that checks the commandline buffer for the presence of a specified set of options.

Back to index.


contains - test if a word is present in a list

Synopsis

contains [OPTIONS] KEY [VALUES...]

Description

Test if the set VALUES contains the string KEY. Return status is 0 if yes, 1 otherwise

Example

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 if they are not, they are added.

Back to index.


continue - skip the rest of the current lap of the innermost currently evaluated loop

Synopsis

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

Description

The continue builtin is used to skip the current lap of the innermost 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.

Example

The following code removes all tmp files without smurfs.

for i in *.tmp
    if grep smurf $i
        continue
    end
    rm $i
end

Back to index.


count - count the number of elements of an array

Synopsis

count $VARIABLE

Description

The count builtin 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, but this is not the only potential usage for the count command.

The count command does not accept any options, not even '-h'. This way the user does not have to worry about an array containing elements such as dashes. fish performs a special check when invoking the count command, and if the user uses a help option, this help page is displayed, but if a help option is contained inside of a variable or is the result of expansion, it will simply be counted like any other argument.

Count exits with a non-zero exit status if no arguments where passed to it, with zero otherwise.

Example

count $PATH

returns the number of directories in the users PATH variable.

count *.txt

returns the number of files in the current working directory ending with the suffix '.txt'.

Back to index.


dirh - print directory history

Synopsis

dirh

Description

dirh prints the current directory history. The current position in the history is highlighted using $fish_color_history_current.

Back to index.


dirs - print directory stack

Synopsis

dirs

Description

dirs prints the current directory stack.

Back to index.


else - execute command if a condition is not met

Synopsis

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

Description

if will execute the command CONDITION. If the condition's exit status is 0, the commands COMMANDS_TRUE will execute. If it is not 0 and else is given, COMMANDS_FALSE will be executed. Hint: use begin; ...; end for complex conditions.

Example

The command if test -f foo.txt; echo foo.txt exists; else; echo foo.txt does not exist; end will print foo.txt exists if the file foo.txt exists and is a regular file, otherwise it will print foo.txt does not exist.

Back to index.


emit - Emit a generic event

Synopsis

emit EVENT_NAME

Description

The emit builtin fires a generic fish event. Such events can be caught by special functions called event handlers.

Example

The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type.

function event_test --on-event test_event
    echo event test!!!
end
emit test_event

Back to index.


end - end a block of commands.

Synopsis

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

Description

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


eval - evaluate the specified commands

Synopsis

eval [COMMANDS...]

Description

The eval function causes fish to evaluate 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.

Example

set cmd ls
eval $cmd

will call the ls command.

Back to index.


exec - execute command in current process

Synopsis

exec COMMAND [OPTIONS...]

Description

The exec builtin is used to replace the currently running shells process image with a new command. On successful completion, exec never returns. exec can not be used inside a pipeline.

Example

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

Back to index.


exit - exit the shell.

Synopsis

exit [STATUS]

Description

The exit builtin 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 . builtin) the rest of the file will be skipped, but the shell itself will not exit.

Back to index.


fg - send job to foreground

Synopsis

fg [PID]

Description

Sends the specified job to the foreground. 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.

Example

fg %0 will put the job with job id 0 in the foreground.

Back to index.


fish - the friendly interactive shell

Synopsis

fish [-h] [-v] [-c command] [FILE [ARGUMENTS...]]

Description

A commandline shell written mainly with interactive use in mind. The full manual is available in html by using the help command from inside fish.

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


fish_config - Start up the web-based configuration interface

Description

This command starts up the web-based configuration interface, which allows you to edit your colors and view your functions, variables, and history.

Back to index.


fish_indent - indenter and prettifier

Synopsis

fish_indent [options]

Description

fish_indent is used to indent or otherwise prettify a piece of fish code. fish_indent reads commands from standard input and outputs them to standard output.

fish_indent understands the following options:

Back to index.


fish_pager - internal command used by fish

Description

This command is used internally by fish to display a list of completions. It should not be used by other commands, as it's interface is liable to change in the future.

Back to index.


fish_prompt - define the apperance of the command line prompt

Synopsis

function fish_prompt
    ...
end

Description

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.

Example

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


fish_update_completions - Update man-page completions

Description

This command parses your installed man pages and writes completion files to the fish config directory. This does not overwrite custom completions.

Back to index.


fishd - universal variable daemon

Synopsis

fishd [(-h|--help|-v|--version)]

Description

The fishd daemon is used to load, save and distribute universal variable information. fish automatically connects to fishd via a socket on startup. If no instance of fishd is running, fish spawns a new fishd instance. fishd will create a socket in /tmp, and wait for incoming connections from universal variable clients, such as fish, When no clients are connected, fishd will automatically shut down.

Files

~/.config/fish/fishd.HOSTNAME permanent storage location for universal variable data. The data is stored as a set of set and set_export commands such as would be parsed by fishd. The file must always be stored in ASCII format. If an instance of fishd is running (which is generally the case), manual modifications to ~/.fishd.HOSTNAME will be lost. Do NOT edit this file manually!

/tmp/fishd.socket.USERNAME the socket which fishd uses to communicate with all clients.

/tmp/fishd.log.USERNAME the fishd log file

Back to index.


for - perform a set of commands multiple times.

Synopsis

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

Description

for is a loop construct. It will perform the commands specified by COMMANDS multiple times. Each time the environment variable specified by VARNAME is assigned a new value from VALUES. If VALUES is empty, COMMANDS will not be executed at all.

Example

The command

for i in foo bar baz; echo $i; end

would output:

foo
bar
baz

Back to index.


funced - edit a function interactively

Synopsis

funced NAME

Description

Use the funced command to interactively edit the definition of a function. If there is no function with the name specified, a skeleton function is inserted, if a function exist, the definion will be shown on the command line.

Back to index.


funcsave - save the definition of a function to the users autoload directory

Synopsis

funcsave FUNCTION_NAME

Description

funcsave is used to save the current definition of a function to a file which will be autoloaded 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.

Back to index.


function - create a function

Synopsis

function [OPTIONS] NAME; BODY; end

Description

This builtin command is used to create a new function. A function is a list of commands that will be executed when the name of the function is entered. The function

function hi
	echo hello
end

will write hello whenever the user enters hi.

If the user enters any additional arguments after the function, they are inserted into the environment variable array argv.

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 <a href='emit>emit builtin. Fish generates the following named events:

Example

function ll
	ls -l $argv
end

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

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

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

Back to index.


functions - print or erase functions

Synopsis

functions [-e] FUNCTIONS...

Description

This builtin command is used to print or erase functions.

The default behavior of functions when called with no arguments, is to print the names and definitions of all defined functions. If any non-switch parameters are given, only the definition of the specified functions are printed.

Automatically loaded functions can not be removed using functions -e. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions.

Function copies, created with -c, will not have any event/signal/on-exit notifications that the original may have had.

The exit status of the functions builtin is the number functions specified in the argument list that do not exist.

Back to index.


help - display fish documentation

Synopsis

help [SECTION]

Description

The help command is used to display a section of the fish help documentation.

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

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

Example

help fg shows the documentation for the fg builtin.

Back to index.


history - Show and manipulate user's command history

Synopsis

history (--save | --clear)
history (--search | --delete ) (--prefix "prefix string" | --search "search string")

Description

history is used to list, search and delete user's command history.

Example

history --save
Save all changes in history file.
history --clear
Delete all history items.
history --search --contains "foo"
Searches commands containing "foo" string.
history --search --prefix "foo"
Searches for commands with prefix "foo".
history --delete --contains "foo"
Interactively delete commands containing string "foo".
history --delete --prefix "foo"
Interactively delete commands with prefix "foo".
history --delete "foo"
Delete command "foo" from history.

Back to index.

if - conditionally execute a command

Synopsis

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

Description

if will execute the command CONDITION.  If the condition's
exit status is 0, the commands COMMANDS_TRUE will execute.  If the
exit status is not 0 and else is given, COMMANDS_FALSE will
be executed.
In order to use the exit status of multiple commands as the condition
of an if block, use begin; ...; end and
the short circuit commands and and or.
The exit status of the last foreground command to exit can always be
accessed using the $status
variable.

Example

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

will print foo.txt exists if the file foo.txt exists and is a regular file, otherwise it will print foo.txt does not exist.

Back to index.

isatty - test if the specified file descriptor is a tty

Synopsis

 isatty [FILE DESCRIPTOR]
where FILE DESCRIPTOR may be either the number of a file descriptor, or one
of the strings stdin, stdout and stderr.
If the specified file descriptor is a tty, the exit status of the
command is zero, otherwise, it is non-zero.
Back to index.

jobs - print currently running jobs

jobs-synopsis

jobs [OPTIONS] [PID]

Description

The jobs builtin causes fish to print a list of the currently
running jobs and their status.
jobs accepts the following switches:
  • -c or --command print the command name for each process in jobs
  • -g or --group only print the group id of each job
  • -h or --help display a help message and exit
  • -l or --last only the last job to be started is printed
  • -p or --pid print 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%.
Back to index.

math - Perform mathematics calculations

Synopsis

 math EXPRESSION

Description

math is used to perform mathematical calculations. It is only a very
thin wrapper for the bc program, that makes it possible to specify an
expression from the command line without using non-standard extensions
or a pipeline. Simply use a command like math 1+1.
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 environment variables or the
output of command substitutions, but it also means that parenthesis
have to be escaped.
Back to index.

mimedb - lookup file information via the mime database

Synopsis

mimedb [OPTIONS] FILES...

Description

  • FILES is a list of files to analyse
  • -t, --input-file-data the specified files type should be determined both by their filename and by their contents (Default)
  • -f, --input-filename the specified files type should be determined by their filename
  • -i, --input-mime the arguments are not files but mimetypes
  • -m, --output-mime the output will be the mimetype of each file (Default)
  • -f, --output-description the output will be the description of each mimetype
  • -a, --output-action the output will be the default action of each mimetype
  • -l, --launch launch the default action for the specified file(s)
  • -h, --help display a help message and exit
  • -v, --version display version number and exit
The mimedb command is used to query the mimetype database and the
.desktop files installed on the system in order to find information on
a file. The information that mimedb can retrieve includes the mimetype
for a file, a description of the type and what its default action
is. mimedb can also be used to launch the default action for this
file.
Back to index.

nextd - move forward through directory history

Synopsis

nextd [-l | --list] [pos]

Description

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
history is also displayed.
Back to index.

not - negate the exit status of a job

Synopsis

not COMMAND [OPTIONS...]

Description

The not builtin is used to negate the exit status of another command.

Example

The following code reports an error and exits if no file named spoon can be found.

if not test -f spoon
	echo There is no spoon
	exit 1
end
Back to index.

open - open file in its default application

Synopsis

 open FILES...

Description

The open command is used to open a file in its default application. open is implemented using the xdg-open command if it exists, or else the mimedb command.

Example

open *.txt opens all the text files in the current directory using your system's default text editor.
Back to index.

or - conditionally execute a command

Synopsis

 COMMAND1; or COMMAND2

Description

The or builtin is used to execute a command if the current exit
status (as set by the last previous command) is not 0.
The or command 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.

Example

The following code runs the make command to build a program, if the
build succeeds, the program is installed. If either step fails,
make clean is run, which removes the files created by the
build process
make; and make install; or make clean
Back to index.

popd - move through directory stack

Synopsis

popd

Description

popd removes the top directory from the directory stack and
cd's to the new top directory.
Back to index.

prevd - move backward through directory history

Synopsis

prevd [-l | --list] [pos]

Description

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.
Back to index.

psub - perform process substitution

Synopsis

 COMMAND1 (COMMAND2|psub [-f]) 

Description

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. The psub shellscript function, which when 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.

Example

diff (sort a.txt|psub) (sort b.txt|psub) shows the difference
between the sorted versions of files a.txt and b.txt.
Back to index.

pushd - push directory to directory stack

Synopsis

pushd [DIRECTORY]

Description

The pushd function adds DIRECTORY to the top of the directory stack
and makes it the current directory. Use popd to pop it off and and
return to the original directory.
Back to index.

random - generate random number

Synopsis

 random [SEED]

Description

The random command is used to generate a random number in the
interval 0<=N<32767. If an argument is given, it is used to seed the
random number generator. This can be useful for debugging purposes,
where it can be desirable to get the same random number sequence
multiple times. If the random number generator is called without first
seeding it, the current time will be used as the seed.

Example

The following code will count down from a random number to 1:
for i in (seq (random) -1 1)
	echo $i
	sleep
end
Back to index.

read - read line of input into variables

Synopsis

read [OPTIONS] [VARIABLES...]

Description

The read builtin causes fish to read one line from standard
input and store the result in one or more environment variables.
  • -c CMD or --command=CMD specifies that the initial string in the interactive mode command buffer should be CMD.
  • -e or --export specifies that the variables will be exported to subshells.
  • -g or --global specifies that the variables will be made global.
  • -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.
  • -p PROMPT_CMD or --prompt=PROMPT_CMD specifies that the output of the shell command PROMPT_CMD should be used as the prompt for the interactive mode prompt. The default prompt command is set_color green; echo read; set_color normal; echo "> ".
  • -s or --shell Use syntax highlighting, tab completions and command termination suitable for entering shellscript code
  • -u or --unexport causes the specified environment not to be exported to child processes
  • -U or --universal causes the specified environment variable to be made universal. 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 environment variable to be exported to child processes
Read starts by reading a single line of input from stdin, the line is
then tokenized using the IFS environment variable. Each variable
specified in VARIABLES is then assigned one tokenized string
element. If there are more tokens than variables, the complete
remainder is assigned to the last variable.

Example

echo hello|read foo
Will cause the variable $foo to be assigned the value hello.
Back to index.

return - stop the innermost currently evaluated function

Synopsis

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

Description

The return builtin is used to halt a currently running function. 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.
  • STATUS is the return status of the function. If unspecified, the status is unchanged.

Example

The following code is an implementation of the false command as a fish function
function false
	return 1
end
Back to index.

set - handle environment variables.

Synopsis

set [SCOPE_OPTIONS]
set [OPTIONS] VARIABLE_NAME VALUES...
set [OPTIONS] VARIABLE_NAME[INDICES]... VALUES...
set (-q | --query) [SCOPE_OPTIONS] VARIABLE_NAMES...
set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME
set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]...
The set builtin causes fish to assign the variable VARIABLE_NAME the values VALUES....

Description

  • -e or --erase causes the specified environment variable to be erased
  • -l or --local forces the specified environment 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 environment variable to be given a global scope. Non-global variables disappear when the block they belong to ends
  • -U or --universal causes the specified environment 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.
  • -n or --names List only the names of all defined variables, not their value
  • -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.
  • -u or --unexport causes the specified environment not to be exported to child processes
  • -x or --export causes the specified environment variable to be exported to child processes
If set is called with no arguments, the names and values of all
environment variables are printed. If some of the scope or export
flags have been given, only the variables matching the specified scope
are printed.
If 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:
  1. If a variable is explicitly set to either universal, global or local, that setting will be honored. If a variable of the same name exists in a different scope, that variable will not be changed.
  2. If a variable is not explicitly set to be either universal, global or local, but has been previously defined, the previous variable scope is used.
  3. If a variable is not explicitly set to be either universal, global or local and has never before been defined, the variable will be local to the currently executing functions. 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:
  1. If a variable is explicitly set to either be exported or not exported, that setting will be honored.
  2. If a variable is not explicitly set to be exported or not exported, but has been previously defined, the previous exporting rule for the variable is kept.
  3. If a variable is not explicitly set to be either exported or unexported and has never before been defined, the variable will not be exported.
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. When erasing an entire
variable (i.e. no slicing), the scope of the variable to be erased can
be specified. That way, a global variable can be erased even if a
local variable with the same name exists. Scope can not be specified
when erasing a slice of an array. The innermost scope is always used.
The set command requires all switch arguments to come before any
non-switch 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 exits with an exit status of zero it the
variable assignments where sucessfully performed, with a non-zero exit
status otherwise. In query mode, the exit status is the number of
variables that where 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.

Example

set -xg will print 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 
Back to index.

set_color - set the terminal color

Synopsis

 set_color [-v --version] [-h --help] [-b --background COLOR] [COLOR]

Description

Change the foreground and/or background color of the terminal.
COLOR is one of black, red, green, brown, yellow, blue, magenta,
purple, cyan, white and normal.
If your terminal supports term256 (modern xterms and OS X Lion),
you can specify an RGB value with three or six hex digits, such
as A0FF33 or f2f. fish will choose the closest supported color.
  • -b, --background Set the background color
  • -c, --print-colors Prints a list of all valid color names
  • -h, --help Display help message and exit
  • -o, --bold Set bold or extra bright mode
  • -u, --underline Set underlined mode
  • -v, --version Display version and exit
Calling set_color normal will set the terminal color to
whatever is the default color of the terminal.
Some terminals use the --bold escape sequence to switch to a brighter
color set. On such terminals, set_color white will result
in a grey font color, while set_color --bold white will
result in a white font color.
Not all terminal emulators support all these features. This is not a
bug in set_color but a missing feature in the terminal emulator.
set_color 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. Download and install the latest version of
ncurses and recompile fish against it in order to fix this issue.
Back to index.

. - evaluate contents of file.

Synopsis

. FILENAME [ARGUMENTS...]

Description

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
environment variables, etc., will remain. If additional arguments are
specified after the file name, they will be inserted into the $argv
variable.
If no file is specified, or if the file name '-' is used, stdin will
be read.
The return status of . is the return status of the last job to
execute. If something goes wrong while opening or reading the file,
. exits with a non-zero status.

Example

. ~/.fish
causes fish to reread its initialization file.
Back to index.

status - query fish runtime information

Synopsis

 status [OPTION]

Description

  • -c or --is-command-substitution returns 0 if fish is currently executing a command substitution
  • -b or --is-block returns 0 if fish is currently executing a block of code
  • -i or --is-interactive returns 0 if fish is interactive, i.e.connected to a keyboard
  • -l or --is-login returns 0 if fish is a login shell, i.e. if fish should perform login tasks such as setting up the PATH.
  • --is-full-job-control returns 0 if full job control is enabled
  • --is-interactive-job-control returns 0 if interactive job control is enabled
  • --is-no-job-control returns 0 if no job control is enabled
  • -f or --current-filename prints the filename of the currently running script
  • -n or --current-line-number prints the line number of the currently running script
  • -j CONTROLTYPE or --job-control=CONTROLTYPE set the job control type. Can be one of: none, full, interactive
  • -t or --print-stack-trace prints a stack trace of all function calls on the call stack
  • -h or --help display a help message and exit
Back to index.

switch - conditionally execute a block of commands

Synopsis

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

Description

The switch statement is used to perform one of several blocks of
commands depending on whether a specified value equals one of several
wildcarded values. The case statement is used together with the switch statement in order to determine which block should be
performed.
Each case command is given one or more parameter. 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. Though the
syntax may look a bit like C switch statements, it behaves more like
the case statements of traditional shells.
Also note that command substitutions in a case statement will be
evaluated even if it's body is not taken. This may seem
counterintuitive at first, but it is unavoidable, since it would be
impossible to know if a case command will evaluate to true before all
forms of parameter expansion have been performed for the case command.

Example

If the variable $animal contains the name of an animal, the following
code would attempt to classify it:
switch $animal
    case cat
        echo evil
    case wolf dog human moose dolphin whale
        echo mammal
    case duck goose albatross
        echo bird
    case shark trout stingray
        echo fish
    case '*'
        echo I have no idea what a $animal is
end
If the above code was run with $animal set to whale, the output
would be mammal.
Back to index.

trap - perform an action when the shell receives a signal

Synopsis

trap [OPTIONS] [[ARG] SIGSPEC ... ]

Description

Trap is a shellscript wrapper around the fish event delivery
framework. It exists for backwards compatibility with Posix
shells. For other uses, it is recommended to define a event handler.
  • ARG is the command to be executed on signal delivery
  • SIGSPEC is the name of the signal to trap
  • -h or --help Display help and exit
  • -l or --list-signals print a list of signal names
  • -p or --print print all defined signal handlers
If ARG and SIGSPEC are both specified, ARG is the command to be
executed when the signal specified by SIGSPEC is delivered.
If ARG is absent (and there is a single SIGSPEC) 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 SIGSPEC 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 SIGSPEC 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 SIGSPEC is invalid; otherwise trap
returns 0.
Back to index.

type - indicate how a name would be interpreted if used as a command name

Synopsis

 type [OPTIONS] name [name ...]

Description

With no options, indicate how each name would be interpreted if used as a command name.
  • -h or --help print this message
  • -a or --all print all of possible definitions of the specified names
  • -f or --no-functions suppresses function and builtin lookup
  • -t or --type print a string which is one of alias, keyword, function, builtin, or file if name is an alias, shell reserved word, function, builtin, or disk file, respectively
  • -p or --path either return the name of the disk file that would be executed if name were specified as a command name, or nothing if 'type -t name' would not return 'file'
  • -P or --force-path either return the name of the disk file that would be executed if name were specified as a command name, or nothing no file with the specified name could be found in the PATH
type returns a zero exit status if the specified command was found,
otherwise the exit status is one.

Example

type fg outputs the string 'fg is a shell builtin'.
Back to index.

ulimit - set or get the shells resource usage limits

Synopsis

ulimit [OPTIONS] [LIMIT]

Description

The ulimit builtin is used to set 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.
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's 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. If supported by OS.
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 Set hard resource limit
  • -S or --soft Set soft resource limit
A hard limit can only be decreased, once it is set it can not 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 Print all current limits
  • -h or --help Display help and exit
The fish implementation of ulimit should behave identically to the
implementation in bash, except for these differences:
  • Fish ulimit supports GNU-style long options for all switches
  • Fish ulimit does not support the -p option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because 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.
  • Fish ulimit does not support getting or setting multiple limits in one command, except reporting all values using the -a switch

Example

ulimit -Hs 64
would set the hard stack size limit to 64 kB:
Back to index.

umask - set or get the file-creation mask

Synopsis

umask [OPTIONS] [MASK]

Description

With no argument, the current file-creation mask is printed, if an
argument is specified, it is the new file creation mask. The mask may
be specified as an octal number, in which case it is interpreted as
the rights that should be masked away, i.e. it is the inverse of the
file permissions any new files will have.
If a symbolic mask is specified, the actual file permission bits, and
not the inverse, should be specified. A symbolic mask is a comma
separated list of rights. Each right consists of three parts:
  • The first part specifies to whom this set of right applies, and can be one of u, g, o or a, where u specifies the user who owns the file, g specifies the group owner of the file, o specific other users rights and a specifies all three should be changed.
  • The second part of a right specifies the mode, and can be one of =, + or -, where = specifies that the rights should be set to the new value, + specifies that the specified right should be added to those previously specified and - specifies that the specified rights should be removed from those previously specified.
  • The third part of a right specifies what rights should be changed and can be any combination of r, w and x, representing read, write and execute rights.
If the first and second parts are skipped, they are assumed to be a and =, respectively. As an example, r,u+w means all
users should have read access and the file owner should also have
write access.
  • -h or --help print this message
  • -S or --symbolic prints the file-creation mask in symbolic form instead of octal form. Use man chmod for more information.
  • -p or --as-command prints any output in a form that may be reused as input
The umask implementation in fish should behave identically to the one
in bash.

Example

umask 177 or umask u=rw sets the file
creation mask to read and write for the owner and no permissions at
all for any other users.
Back to index.

vared - interactively edit the value of an environment variable

Synopsis

 vared VARIABLE_NAME

Description

vared is used to interactively edit the value of an environment
variable. Array variables as a whole can not be edited using vared,
but individual array elements can.

Example

vared PATH[3] edits the third element of the PATH array
Back to index.

while - perform a command multiple times

Synopsis

while CONDITION; COMMANDS...; end

Description

The while builtin causes fish to continually execute CONDITION and
execute COMMANDS as long as CONDITION returned with status 0. If CONDITION is
false on the first time, COMMANDS will not be executed at all. Hints: use
begin; ...; end for complex conditions; more
complex control can be achieved with while true containing a
break.

Example

while test -f foo.txt; echo file exists; sleep 10; end
causes fish to print the line 'file exists' at 10 second intervals as long as
the file foo.txt exists.
Back to index.

Generated on 20 Mar 2013 for fish by  doxygen 1.6.1