fish home | Main documentation page | Design document | External commands | Builtin commands | FAQ | License

Builtin commands

. - Evaluate contents of file.

Synopsis

. FILENAME

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.

Example

. ~/.fish

causes fish to reread its initialization file.

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 zero

Example

The following code runs the make command to build a program, and if it succeeds, it runs make install, which installs the program.
make; and make install

begin - Start a new block of code

Synopsis

begin; [COMMAND;...] end

Description

The begin builtin is used to create a new block of code. The block is unconditionally executed. Begin is equivalent to if true. The begin command is used to group any number of commands into a block. The reason for this is usually either to introduce a new variable scope or to redirect the input to output of this set of commands as a group.

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 -x PIRATE Yarrr
	...
end
# This will not output anything, since PIRATE went out of scope at the end of
# the block and was killed
echo $PIRATE

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

Example

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

bind - Handle key bindings.

Synopsis

bind [OPTIONS] [BINDINGS...]

The bind builtin causes fish to add the readline style bindings specified by BINDINGS to the list of key bindings. For more information on specifying keyboard bindings, use man readline to access the readline documentation.

Description

Example

bind -M vi changes to the vi input mode

bind '"\M-j": jobs' Binds the jobs command to the Alt-j keyboard shortcut

block - Temporarily block delivery of events

Synopsis

block [OPTIONS...]

Description

Example

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

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;

builtin - run a builtin command

Synopsis

builtin BUILTINNAME [OPTIONS...]

Description

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

Example

builtin jobs

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

case - conditionally execute a block of commands

Synopsis

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

Description

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

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.

command - run a program

Synopsis

command COMMANDNAME [OPTIONS...]

Description

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

Example

command ls

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

commandline - Set or get the current commandline buffer

Synopsis

commandline [OPTIONS] [CMD]

Description

The following switches change the way commandline updates the commandline

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

The following switch changes the way commandline prints the current commandline

Other switches

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.

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.

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;

else - execute command if a condition is not met.

Synopsis

if CONDITION; COMMAND_TRUE [else; COMMAND_FALSE] end;

Description

if will execute the command CONDITION. If the commands exit status is zero, the command COMMAND_TRUE will execute. If it is not zero and COMMAND_FALSE is specified, COMMAND_FALSE will be executed.

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.

end - end a block of commands.

Synopsis

for VARNAME in [VALUES...]; COMMANDS; end
if CONDITION; COMMAND_TRUE [else; COMMAND_FALSE] end
while CONDITION; 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.

eval - eval the specified commands

Synopsis

eval [COMMANDS...]

Description

The eval builtin 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.

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.

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

If exit is called while sourcing a file (using the . builtin) the rest of the file will be skipped, but the shell will not exit.

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

Example

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

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.

Example

The command

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

would output:

foo
bar
baz

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.

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.

functions - print or erase functions

Synopsis

functions [-e] FUNCTIONS...

Description

This builtin command is used to print or erase functions.

If functions is called with no arguments, the names and definition of all functions are printed, otherwise, the specified function definitions will be printed.

if - Conditionally execute a command

Synopsis

if CONDITION; COMMAND_TRUE [else; COMMAND_FALSE] end;

Description

if will execute the command CONDITION. If the commands exit status is zero, the command COMMAND_TRUE will execute. If it is not zero and COMMAND_FALSE is specified, COMMAND_FALSE will be executed.

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.

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:

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

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

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

Example

The following code runs the make command to build a program, or if it fails, it runs make clean, which removes the files created by the build process
make; or make clean

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

return - Stop the innermost currently evaluated function

Synopsis

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

Description The \c 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.

Example

The following code is an implementation of the false program as a fish builtin

function false
	return 1
end

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.

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.

set - Handle environment variables.

Synopsis

set [OPTIONS] [VARIABLE_NAME [VALUES...]]

or

set [OPTIONS] [VARIABLE_NAME[INDICES]... [VALUES...]]

The set builtin causes fish to assign the variable VARIABLE_NAME the values VALUES....

Description

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 the -e or --erase option is specified, the variable specified by the following arguments will be erased

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.

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.

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

status - Display fish runtime information

Synopsis

status [OPTION]

Description

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 stamantes of traditional shells.

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.

ulimit - Set or get the shells resource usage limits

Synopsis

ulimit [OPTIONS] [LIMIT]

Description

The ulimit builtin provides control over the resources available to the shell and to processes started by it. The -H and -S options specify that the hard or soft limit is set for the given resource. A hard limit cannot be increased once it is set; 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 set. 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 omitted, the current value of the soft limit of the resource is printed, unless the -H option is given. When more than one resource is specified, the limit name and unit are printed before the value. Other options are interpreted as follows:

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.

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

Example

ulimit -Hs 64

would set the hard stack size limit to 64 kB:

while - perform a command multiple times

Synopsis

while CONDITION; COMMANDS; end

Synopsis

The while builtin causes fish to continually execute the command COMMANDS while the command CONDITION returns with status 0.

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.


Generated on Fri Jun 2 04:08:18 2006 for fish by  doxygen 1.3.9.1