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 simple wrapper for the function builtin. It exists for backwards compatibility with Posix shells. For other uses, it is recommended to define a function.

fish does not keep track of which functions have been defined using alias. They must be erased using functions -e.

You cannot create an alias to a function with the same name.

Example

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

alias rmi "rm -i"

This is equivalent to entering the following function:

function rmi
    rm -i $argv
end

Back to index.

and - conditionally execute a command

Synopsis

COMMAND1; and COMMAND2

Description

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

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.

Example

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

make; and make install; or make clean

Back to index.

begin - start a new block of code

Synopsis

begin; [COMMANDS...;] end

Description

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.

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 jobs to background

Synopsis

bg [PID...]

Description

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.

Example

bg %1 will put the job with job ID 1 in the background.

Back to index.

bind - handle fish key bindings

Synopsis

bind [OPTIONS] SEQUENCE COMMAND

Description

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

Key bindings are not saved between sessions by default. To save custom keybindings, edit the fish_user_key_bindings function and insert the appropirate bind statements.

The following parameters are available:

Examples

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

Back to index.

block - temporarily block delivery of events

Synopsis

block [OPTIONS...]

Description

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:

Example

# Create a function that listens for events
function --on-event foo foo; echo 'foo fired'; end
# Block the delivery of events
block -g
emit foo
# No output will be produced
block -e
# 'foo fired' will now be printed

Back to index.

break - stop the current inner loop

Synopsis

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

Description

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.

Example

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

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

Back to index.

breakpoint - Launch debug mode

Synopsis

breakpoint

Description

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

builtin - run a builtin command

Synopsis

builtin BUILTINNAME [OPTIONS...]

Description

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

The following parameters are available:

Example

builtin jobs executes 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

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.

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

cd - change directory

Synopsis

cd [DIRECTORY]

Description

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

Examples

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

command - run a program

Synopsis

command COMMANDNAME [OPTIONS...]

Description

command forces the shell to execute the program COMMANDNAME and ignore any functions or builtins with the same name.

Example

command ls causes fish to execute the ls program, even if an 'ls' function exists.

Back to index.

commandline - set or get the current command line buffer

Synopsis

commandline [OPTIONS] [CMD]

Description

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

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

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

The following options are available:

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

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

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

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

Example

commandline -j $history[3] replaces the job under the cursor with the third item from the command line 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 specifying completions, see Writing your own completions in the fish manual.

Command specific tab-completions in fish are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as '-h', '-help' or '--help'. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU 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

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:

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 adds them if not.

Back to index.

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

Synopsis

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

Description

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

Example

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

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

Back to index.

count - count the number of elements of an array

Synopsis

count $VARIABLE

Description

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

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.

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 the color defined in the fish_color_history_current environment variable.

dirh does not accept any parameters.

Back to index.

dirs - print directory stack

Synopsis

dirs

Description

dirs prints the current directory stack, as created by the pushd command.

dirs does not accept any parameters.

Back to index.

echo - display a line of text

Synopsis

echo [STRING]

Description

echo displays a string of text.

The following options are available:

Escape Sequences

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

Example

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

Example

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

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

Back to index.

emit - Emit a generic event

Synopsis

emit EVENT_NAME [ARGUMENTS...]

Description

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.

Example

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

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

emit test_event something

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

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.

Example

The folloing code will call the ls command. Note that fish does not support the use of environment variables as direct commands; eval can be used to work around this.

set cmd ls
eval $cmd

Back to index.

exec - execute command in current process

Synopsis

exec COMMAND [OPTIONS...]

Description

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

Example

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

Back to index.

exit - exit the shell

Synopsis

exit [STATUS]

Description

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

Back to index.

fg - bring job to foreground

Synopsis

fg [PID]

Description

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.

Example

fg %1 will put the job with job ID 1 in the foreground.

Back to index.

fish - the friendly interactive shell

Synopsis

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

Description

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:

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 the web-based configuration interface

Description

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.

There are no parameters for fish_config.

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.

Example

fish_config opens a new web browser window and allows you to configure certain fish settings.

Back to index.

fish_indent - indenter and prettifier

Synopsis

fish_indent [options]

Description

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

The following options are available:

Back to index.

fish_pager - internal command used by fish

Description

fish_pager is used internally by fish. It should not be used by other commands, as its interface is liable to change in the future.

Back to index.

fish_prompt - define the appearance 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.

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

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

Example

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_right_prompt - define the appearance of the right-side command line prompt

Synopsis

function fish_right_prompt
    ...
end

Description

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.

Example

A simple right prompt:

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

Back to index.

fish_update_completions - Update completions using manual pages

Description

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

fishd is started and stopped automatically.

The following options are available if starting fishd manually:

Files

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 YAML format. If an instance of fishd is running (which is generally the case), manual modifications to ~/.fishd.MACHINE_ID will be lost. Do NOT edit this file manually!

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. On each iteration, 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 [OPTIONS] NAME

Description

funced provides an interface to edit the definition of the function NAME.

If the $EDITOR environment variable is set, it will be used as the program to edit the function. Otherwise, a built-in editor will be used.

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

Back to index.

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

Synopsis

funcsave FUNCTION_NAME

Description

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.

Back to index.

function - create a function

Synopsis

function [OPTIONS] NAME; BODY; end

Description

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:

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

Example

function ll
	ls -l $argv
end

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

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

			case '*'
				cd $argv[(count $argv)]
				return
		end
	end
end

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 [-n]
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [-eq] FUNCTIONS...

Description

functions prints or erases functions.

The following options are available:

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.

Examples

functions -n displays a list of currently-defined functions.

functions -c foo bar copies the foo function to a new function called bar.

functions -e bar erases the function bar.

Back to index.

help - display fish documentation

Synopsis

help [SECTION]

Description

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.

Note 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 command history

Synopsis

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

Description

history is used to list, search and delete the history of commands used.

The following options are available:

If --search is specified without --contains or --prefix, --contains will be assumed.

If --delete is specified without --contains or --prefix, only a history item which exactly matches the parameter will be erased. No prompt will be given. If --delete is specified with either of these parameters, an interactive prompt will be displayed before any items are deleted.

Example

history --clear deletes all history items

history --search --contains "foo" outputs a list of all previous commands containing the string "foo".

history --delete --prefix "foo" interactively deletes the record of previous commands which start with "foo".

Back to index.

if - conditionally execute a command

Synopsis

if CONDITION; COMMANDS_TRUE...; [else if CONDITION2; COMMANDS_TRUE2...;] [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 if test -f bar.txt
	echo bar.txt exists
else
	echo foo.txt and bar.txt do not exist
end
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.

Back to index.

isatty - test if the specified file descriptor is a tty

Synopsis

isatty [FILE DESCRIPTOR]

Description

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

Synopsis

jobs [OPTIONS] [PID]

Description

jobs prints a list of the currently running jobs and their status.

jobs accepts the following switches:

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

Example

jobs outputs a summary of the current jobs.

Back to index.

math - Perform mathematics calculations

Synopsis

math EXPRESSION

Description

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 environment variables or the output of command substitutions, but it also means that parenthesis have to be escaped.

Examples

math 1+1 outputs 2.

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

Back to index.

mimedb - lookup file information via the mime database

Synopsis

mimedb [OPTIONS] FILES...

Description

mimedb queries the MIME type database and the .desktop files installed on the system in order to find information on the files listed in FILES. The information that mimedb can retrieve includes the MIME type for a file, a description of the type, and the default action that can be performed on the file. mimedb can also be used to launch the default action for this file.

The following options are available:

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 directory history is also displayed.

Example

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

Back to index.

not - negate the exit status of a job

Synopsis

not COMMAND [OPTIONS...]

Description

not negates the exit status of another command. If the exit status is zero, not returns 1. Otherwise, not returns 0.

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

open opens a file in its default application, 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

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

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.

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 changes the working directory to the new top directory. Use pushd to add directories to the stack.

Example

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

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.

Example

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

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

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 working directory. popd will pop it off and return to the original directory.

Example

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

Back to index.

pwd - output the current working directory

Synopsis

pwd

Description

pwd outputs (prints) the current working directory.

Note that fish always resolves symbolic links in the current directory path.

Back to index.

random - generate random number

Synopsis

random [SEED]

Description

random outputs a random number from 0 to 32766, inclusive.

If a SEED value is provided, it is used to seed the random number generator, and no output will be produced. 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

read reads one line from standard input and stores the result in one or more environment variables.

The following options are available:

read reads a single line of input from stdin, breaks it into tokens based on the IFS environment 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.

Example

The following code stores the value 'hello' in the environment variable $foo.

echo hello|read foo

Back to index.

return - stop the current inner function

Synopsis

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

Description

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.

Example

The following code is an implementation of the false command as a fish function

function false
	return 1
end

Back to index.

set - display and change 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]...

Description

set manipulates environment variables.

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.

With both variable names and values provided, set assigns the variable VARIABLE_NAME the values VALUES....

The following options control variable scope:

The following options are available:

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 function. Note that this is different from using the -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:

  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.

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 exits with a non-zero exit status if variable assignments could not be successfully performed. If the variable assignments were performed, the exit status is unchanged. 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.

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 

if set python_path (which python)
    echo "Python is at $python_path"
end

The above outputs the path to Python if which returns true.

Back to index.

set_color - set the terminal color

Synopsis

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

Description

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

The following options are available:

Calling set_color normal will set the terminal color to 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.

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.

Examples

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

Back to index.

. - evaluate contents of file.

Synopsis

. FILENAME [ARGUMENTS...]

Description

. (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 environment variables affect the current shell. 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

. ~/.config/fish/config.fish causes fish to re-read its initialization file.

Back to index.

status - query fish runtime information

Synopsis

status [OPTION]

Description

With no arguments, status displays a summary of the current login and job control status of the shell.

The following options are available:

Back to index.

switch - conditionally execute a block of commands

Synopsis

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

Description

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.

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.

test - perform tests on files and text

Synopsis

test [EXPRESSION]

Description

Tests the expression given and sets the exit status to 0 if true, and 1 if false.

The following options are available:

Example

if test -d "/"
    echo "Fish is cool"
end

Because "/" is a directory, the expression will evaluate to true, and "Fish is cool" will be output.

Back to index.

trap - perform an action when the shell receives a signal

Synopsis

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

Description

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:

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.

Example

trap "status --print-stack-trace" SIGUSR1 prints a stack trace each time the SIGUSR1 signal is sent to the shell.

Back to index.

type - indicate how a command would be interpreted

Synopsis

type [OPTIONS] NAME [NAME ...]

Description

With no options, type indicates how each NAME would be interpreted if used as a command name.

The following options are available:

type sets the exit status to 0 if the specified command was found, and 1 if it could not be found.

Example

type fg outputs the string 'fg is a shell builtin'.

Back to index.

ulimit - set or get resource usage limits

Synopsis

ulimit [OPTIONS] [LIMIT]

Description

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:

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:

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

The fish implementation of ulimit should behave identically to the implementation in bash, except for these differences:

Example

ulimit -Hs 64 sets the hard stack size limit to 64 kB.

Back to index.

umask - set or get the file creation mode mask

Synopsis

umask [OPTIONS] [MASK]

Description

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.

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

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.

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

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.

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 outputs 'file exists' at 10 second intervals as long as the file foo.txt exists.

Back to index.

Generated on Fri May 17 00:42:58 2013 for fish by  doxygen 1.5.9