fish: Commands

`fish` shell | Documentation | Tutorial | Design | Commands | FAQ | License
Commands

# Command reference

`fish` ships with a large number of builtin commands, shellscript functions and external commands. These are all described below.

Almost all fish commands respond to the `-h` or `--help` options to display their relevant help, also accessible using the `help` and `man` commands, like so:

    echo -h
    echo --help
    # Prints help to the terminal window

    man echo
    # Displays the man page in the system pager
    # (normally 'less', 'more' or 'most').

    help echo
    # Open a web browser to show the relevant documentation

# abbr - manage fish abbreviations

## Synopsis

    abbr -a word="phrase"
    abbr -s
    abbr -l
    abbr -e word

## Description

`abbr` manipulates the list of abbreviations that fish will expand.

Abbreviations are user-defined character sequences or words that are replaced with longer phrases after they are entered. For example, a frequently-run command such as `git checkout` can be abbreviated to `gco`. After entering `gco` and pressing Space or Enter, the full text `git checkout` will appear in the command line.

Abbreviations are stored, by default, in a universal variable.

The following parameters are available:

- `-a WORD PHRASE` or `--add WORD PHRASE` Adds a new abbreviation, where WORD will be expanded to PHRASE.
- `-s` or `--show` Show all abbreviated words and their expanded phrases in a manner suitable for export and import.
- `-l` or `--list` Lists all abbreviated words.
- `-e WORD` or `--erase WORD` Erase the abbreviation WORD.

## Examples

    abbr -a gco git checkout

Add a new abbreviation where `gco` will be replaced with `git checkout`.

    abbr -e gco

Erase the `gco` abbreviation.

    ssh another_host abbr -s | source

Import the abbreviations defined on another_host over SSH.

Back to index.

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

- `NAME` is the name of the alias
- `DEFINITION` is the actual command to execute. The string `$argv` will be appended.

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

    echo $PIRATE
    # This will not output anything, since the PIRATE variable
    # went out of scope at the end of the block

In the following code, all output is redirected to the file out.html.

    begin
        echo $xml_header
        echo $html_header
        if test -e $file
            ...
        end
        ...
    end > out.html

Back to 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 [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE]
         [(-k | --key)] SEQUENCE COMMAND [COMMAND...]
    bind [(-M | --mode) MODE] [(-k | --key)] SEQUENCE
    bind (-K | --key-names) [(-a | --all)]
    bind (-f | --function-names)
    bind (-e | --erase) [(-M | --mode) MODE]
         (-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE...])

## 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 terminals, not `fish`.

The default key binding can be set by specifying a `SEQUENCE` of the empty string (that is, `''` ). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the `self-insert` function (i.e. `bind '' self-insert`) as the default keybinding. This will insert any keystrokes not specifically bound to into the editor. Non- printable characters are ignored by the editor, so this will not result in control sequences being printable.

If the `-k` switch is used, the name of the key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key_' prefix. (See `terminfo(5)` for more information, or use `bind --key-names` for a list of all available named keys.)

`COMMAND` can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use `bind --function-names` for a complete list of these input functions.

When `COMMAND` is a shellscript command, it is a good practice to put the actual code into a function and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well.

If such a script produces output, the script needs to finish by calling `commandline -f repaint` in order to tell fish that a repaint is in order.

When multiple `COMMAND`s are provided, they are all run in the specified order when the key is pressed.

If no `SEQUENCE` is provided, all bindings (or just the bindings in the specified `MODE`) are printed. If `SEQUENCE` is provided without `COMMAND`, just the binding matching that sequence is printed.

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

Key bindings may use "modes", which mimics Vi's modal input behavior. The default mode is "default", and every bind applies to a single mode. The mode can be viewed/changed with the `$fish_bind_mode` variable.

The following parameters are available:

- `-k` or `--key` Specify a key name, such as 'left' or 'backspace' instead of a character sequence
- `-K` or `--key-names` Display a list of available key names. Specifying `-a` or `--all` includes keys that don't have a known mapping
- `-f` or `--function-names` Display a list of available input functions
- `-M MODE` or `--mode MODE` Specify a bind mode that the bind is used in. Defaults to "default"
- `-m NEW_MODE` or `--sets-mode NEW_MODE` Change the current mode to `NEW_MODE` after this binding is executed
- `-e` or `--erase` Erase the binding with the given sequence and mode instead of defining a new one. Multiple sequences can be specified with this flag. Specifying `-a` or `--all` with `-M` or `--mode` erases all binds in the given mode regardless of sequence. Specifying `-a` or `--all` without `-M` or `--mode` erases all binds in all modes regardless of sequence.
- `-a` or `--all` See `--erase` and `--key-names`

The following special input functions are available:

- `backward-char`, moves one character to the left
- `backward-delete-char`, deletes one character of input to the left of the cursor
- `backward-kill-line`, move everything from the beginning of the line to the cursor to the killring
- `backward-kill-word`, move the word to the left of the cursor to the killring
- `backward-word`, move one word to the left
- `beginning-of-history`, move to the beginning of the history
- `beginning-of-line`, move to the beginning of the line
- `capitalize-word`, make the current word begin with a capital letter
- `complete`, guess the remainder of the current token
- `delete-char`, delete one character to the right of the cursor
- `delete-line`, delete the entire line
- `downcase-word`, make the current word lowercase
- `dump-functions`, print a list of all key-bindings
- `end-of-history`, move to the end of the history
- `end-of-line`, move to the end of the line
- `explain`, print a description of possible problems with the current command
- `forward-char`, move one character to the right
- `forward-word`, move one word to the right
- `history-search-backward`, search the history for the previous match
- `history-search-forward`, search the history for the next match
- `kill-line`, move everything from the cursor to the end of the line to the killring
- `kill-whole-line`, move the line to the killring
- `kill-word`, move the next word to the killring
- `upcase-word`, make the current word uppercase
- `yank`, insert the latest entry of the killring into the buffer
- `yank-pop`, rotate to the previous entry of the killring

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

    set -g fish_key_bindings fish_vi_key_bindings
    bind -M insert \cc kill-whole-line force-repaint

Turns on Vi key bindings and rebinds Control-C to clear the input line.

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:

- `-l` or `--local` Release the block automatically at the end of the current innermost code block scope
- `-g` or `--global` Never automatically release the lock
- `-e` or `--erase` Release global block

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

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

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

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

- `-n` or `--names` List the names of all defined builtins

## 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 `~`, or ending with `/`).

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

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

- `-C` or `--cursor` set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position.
- `-f` or `--function` inject readline functions into the reader. This option cannot be combined with any other option. It will cause any additional arguments to be interpreted as readline functions, and these functions will be injected into the reader, so that they will be returned to the reader before any additional actual key presses are read.

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

- `-a` or `--append` do not remove the current commandline, append the specified string at the end of it
- `-i` or `--insert` do not remove the current commandline, insert the specified string at the current cursor position
- `-r` or `--replace` remove the current commandline and replace it with the specified string (default)

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

- `-b` or `--current-buffer` select the entire buffer (default)
- `-j` or `--current-job` select the current job
- `-p` or `--current-process` select the current process
- `-t` or `--current-token` select the current token.

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

- `-c` or `--cut-at-cursor` only print selection up until the current cursor position
- `-o` or `--tokenize` tokenize the selection and print one string-type token per line

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.

The following options output metadata about the commandline state:

- `-L` or `--line` print the line that the cursor is on, with the topmost line starting at 1
- `-S` or `--search-mode` evaluates to true if the commandline is performing a history search
- `-P` or `--paging-mode` evaluates to true if the commandline is showing pager contents, such as tab completions

## Example

`commandline -j $history[3]` replaces the job under the cursor with the third item from the command line history.

Back to index.

# command - run a program

## Synopsis

    command [OPTIONS] COMMANDNAME [ARGS...]

## Description

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

The following options are available:

- `-s` or `--search` returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the `$PATH`.

With the `-s` option, `command` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found.

For basic compatibility with POSIX `command`, the `-v` flag is recognized as an alias for `-s`.

## Examples

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

`command -s ls` returns the path to the `ls` program.

Back to 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]
            [( -w | --wraps ) WRAPPED_COMMAND]
            [( -d | --description ) DESCRIPTION]

## Description

For an introduction to specifying completions, see Writing your own completions in the fish manual.

- `COMMAND` is the name of the command for which to add a completion.
- `SHORT_OPTION` is a one character option for the command.
- `LONG_OPTION` is a multi character option for the command.
- `OPTION_ARGUMENTS` is parameter containing a space-separated list of possible option-arguments, which may contain subshells.
- `DESCRIPTION` is a description of what the option and/or option arguments do.
- `-C STRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string.
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command.
- `-e` or `--erase` implies that the specified completion should be deleted.
- `-f` or `--no-files` specifies that the option specified by this completion may not be followed by a filename.
- `-n` or `--condition` specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.
- `-o` or `--old-option` implies that the command uses old long style options with only one dash.
- `-p` or `--path` implies that the string `COMMAND` is the full path of the command.
- `-r` or `--require-parameter` specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option.
- `-u` or `--unauthoritative` implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors.
- `-A` or `--authoritative` implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors.
- `-x` or `--exclusive` implies both `-r` and `-f`.

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:

- Short options, like '`-a`'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '`-la`', which is equivalent to '`-l -a`'). Option arguments may be specified in the following parameter ('`-w 32`') or by appending the option with the value ('`-w32`').
- Old style long options, like '`-Wall`'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('`-ao null`').
- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h').

The options for specifying command name, 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.

The `-w` or `--wraps` options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the `-e` or `--erase` options.

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" -d nodeps "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.

To implement an alias, use the `-w` or `--wraps` option:

    complete -c hub -w git

Now hub inherits all of the completions from git. Note this can also be specified in a function declaration.

Back to 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:

- `-i` or `--index` print the word index

Note that, like GNU tools, `contains` interprets all arguments starting with a `-` as options to contains, until it reaches an argument that is `--` (two dashes). See the examples below.

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

    function hasargs
        if contains -- -q $argv
            echo '$argv contains a -q option'
        end
    end

The above code checks for `-q` in the argument list, using the `--` argument to demarcate options to `contains` from the key to search for.

Back to 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` or `--help`.

`count` exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed.

## 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 [OPTIONS] [STRING]

## Description

`echo` displays a string of text.

The following options are available:

- `-n`, Do not output a newline
- `-s`, Do not separate arguments with spaces
- `-E`, Disable interpretation of backslash escapes (default)
- `-e`, Enable interpretation of backslash escapes

## Escape Sequences

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

- `\` backslash
- `\a` alert (BEL)
- `\b` backspace
- `\c` produce no further output
- `\e` escape
- `\f` form feed
- `\n` new line
- `\r` carriage return
- `\t` horizontal tab
- `\v` vertical tab
- `\0NNN` byte with octal value NNN (1 to 3 digits)
- `\xHH` byte with hexadecimal value HH (1 to 2 digits)

## 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 following code will call the ls command. Note that `fish` does not support the use of shell variables as direct commands; `eval` can be used to work around this.

    set cmd ls
    eval $cmd

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

Back to index.

# false - return an unsuccessful result

## Synopsis

    false

## Description

`false` sets the exit status to 1.

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

`fish_config` optionally accepts name of the initial configuration tab. For e.g. `fish_config history` will start configuration interface with history tab.

If the `BROWSER` environment variable is set, it will be used as the name of the web browser to open instead of the system default.

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

- `-i` or `--no-indent` do not indent commands; only reformat to one job per line
- `-v` or `--version` displays the current fish version and then exits
- `--ansi` colorizes the output using ANSI escape sequences, appropriate for the current $TERM, using the colors defined in the environment (such as `$fish_color_command`).
- `--html` outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as `fish_color_command`

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 - the friendly interactive shell

## Synopsis

    fish [OPTIONS] [-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:

- `-c` or `--command=COMMANDS` evaluate the specified commands instead of reading from the commandline
- `-d` or `--debug-level=DEBUG_LEVEL` specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.
- `-i` or `--interactive` specify that fish is to run in interactive mode
- `-l` or `--login` specify that fish is to run as a login shell
- `-n` or `--no-execute` do not execute any commands, only perform syntax checking
- `-p` or `--profile=PROFILE_FILE` when fish exits, output timing information on all executed commands to the specified file
- `-v` or `--version` display version and exit

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

408-600-6421

# fish_vi_mode - Enable vi mode

## Synopsis

    fish_vi_mode

## Description

`fish_vi_mode` enters a vi-like command editing mode. To always start in vi mode, add `fish_vi_mode` to your `config.fish` file.

Back to 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 local variable specified by `VARNAME` is assigned a new value from `VALUES`. If `VALUES` is empty, `COMMANDS` will not be executed at all.

## Example

    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

- `-e command` or `--editor command` Open the function body inside the text editor given by the command (for example, "vi"). The command 'fish' will use the built-in editor.
- `-i` or `--interactive` Open function body in the built-in editor.

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.

# functions - print or erase functions

## Synopsis

    functions [ -a | --all ] [ -n | --names ]
    functions -c OLDNAME NEWNAME
    functions -d DESCRIPTION FUNCTION
    functions [ -e | -q ] FUNCTIONS...

## Description

`functions` prints or erases functions.

The following options are available:

- `-a` or `--all` lists all functions, even those whose name start with an underscore.
- `-c OLDNAME NEWNAME` or `--copy OLDNAME NEWNAME` creates a new function named NEWNAME, using the definition of the OLDNAME function.
- `-d DESCRIPTION` or `--description=DESCRIPTION` changes the description of this function.
- `-e` or `--erase` causes the specified functions to be erased.
- `-n` or `--names` lists the names of all defined functions.
- `-q` or `--query` tests if the specified functions exist.

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.

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

- `-a NAMES` or `--argument-names NAMES` assigns the value of successive command-line arguments to the names given in NAMES.
- `-d DESCRIPTION` or `--description=DESCRIPTION` is a description of what the function does, suitable as a completion description.
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the function to inherit completions from the given wrapped command. See the documentation for `complete` for more information.
- `-e` or `--on-event EVENT_NAME` tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
- `-v` or `--on-variable VARIABLE_NAME` tells fish to run this function when the variable VARIABLE_NAME changes value.
- `-j PGID` or `--on-job-exit PGID` tells fish to run this function when the job with group ID PGID exits. Instead of PGID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
- `-p PID` or `--on-process-exit PID` tells fish to run this function when the fish child process with process ID PID exits.
- `-s` or `--on-signal SIGSPEC` tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP).
- `-S` or `--no-scope-shadowing` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function.
- `-V` or `--inherit-variable NAME` snapshots the value of the variable `NAME` and defines a local variable with that same name and value when the function is executed.

If the user enters any additional arguments after the function, they are inserted into the environment variable array `$argv`. If the `--argument-names` option is provided, the arguments are also assigned to names specified in that option.

By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the emit builtin. Fish generates the following named events:

- `fish_prompt`, which is emitted whenever a new fish prompt is about to be displayed.
- `fish_command_not_found`, which is emitted whenever a command lookup failed.

- `fish_preexec`, which is emitted right before executing an interactive command. The commandline is passed as the first parameter.

  Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.

- `fish_postexec`, which is emitted right after executing an interactive command. The commandline is passed as the first parameter.

  Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.

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

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

    function notify
        set -l job (jobs -l -g)
        or begin; echo "There are no jobs" >&; return 1; end

        function _notify_job_$job --on-job-exit $job --inherit-variable job
            echo -n \a ## beep
            functions -e _notify_job_$job
        end
    end

This will beep when the most recent job completes.

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 ( --merge | --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:

- `--merge` immediately incorporates history changes from other sessions. Ordinarily `fish` ignores history changes from sessions started after the current one. This command applies those changes immediately.
- `--save` saves all changes in the history file. The shell automatically saves the history file; this option is provided for internal use.
- `--clear` clears the history file. A prompt is displayed before the history is erased.
- `--search` returns history items in keeping with the `--prefix` or `--contains` options.
- `--delete` deletes history items.
- `--prefix` searches or deletes items in the history that begin with the specified text string.
- `--contains` searches or deletes items in the history that contain the specified text string.

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

The following code will print `foo.txt exists` if the file foo.txt exists and is a regular file, otherwise it will print `bar.txt exists` if the file bar.txt exists and is a regular file, otherwise it will print `foo.txt and bar.txt do not exist`.

    if test -f foo.txt
        echo foo.txt exists
    else if test -f bar.txt
        echo bar.txt exists
    else
        echo foo.txt and bar.txt do not exist
    end

Back to index.

# isatty - test if a 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`, or `stderr`.

If the specified file descriptor is a tty, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error.

## Examples

From an interactive shell, the commands below exit with a return value of zero:

    isatty
    isatty stdout
    isatty 2
    echo | isatty 1

And these will exit non-zero:

    echo | isatty
    isatty 9
    isatty stdout > file
    isatty 2 2> file

Back to 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:

- `-c` or `--command` prints the command name for each process in jobs.
- `-g` or `--group` only prints the group ID of each job.
- `-l` or `--last` prints only the last job to be started.
- `-p` or `--pid` prints the process ID for each process in all jobs.

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

## 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 shell 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:

- `-t`, `--input-file-data` determines the files' type both by their filename and by their contents (default behaviour).
- `-f`, `--input-filename` determines the files' type by their filename.
- `-i`, `--input-mime` specifies that the arguments are not files, but MIME types.
- `-m`, `--output-mime` outputs the MIME type of each file (default behaviour).
- `-f`, `--output-description` outputs the description of each MIME type.
- `-a`, `--output-action` outputs the default action of each MIME type.
- `-l`, `--launch` launches the default action for the specified files.
- `-v`, `--version` displays the version number and exits.

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

The following options are available:

- `-c CMD` or `--command=CMD` sets the initial string in the interactive mode command buffer to `CMD`.
- `-g` or `--global` makes the variables global.
- `-l` or `--local` makes the variables local.
- `-m NAME` or `--mode-name=NAME` specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available.
- `-n NCHARS` or `--nchars=NCHARS` causes `read` to return after reading NCHARS characters rather than waiting for a complete line of input.
- `-p PROMPT_CMD` or `--prompt=PROMPT_CMD` uses the output of the shell command `PROMPT_CMD` as the prompt for the interactive mode. The default prompt command is `set_color green; echo read; set_color normal; echo "> "`.
- `-R RIGHT_PROMPT_CMD` or `--right-prompt=RIGHT_PROMPT_CMD` uses the output of the shell command `RIGHT_PROMPT_CMD` as the right prompt for the interactive mode. There is no default right prompt command.
- `-s` or `--shell` enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.
- `-u` or `--unexport` prevents the variables from being exported to child processes (default behaviour).
- `-U` or `--universal` causes the specified shell variable to be made universal.
- `-x` or `--export` exports the variables to child processes.
- `-a` or `--array` stores the result as an array.
- `-z` or `--null` reads up to NUL instead of newline. Disables interactive mode.

`read` reads a single line of input from stdin, breaks it into tokens based on the `IFS` shell variable, and then assigns one token to each variable specified in `VARIABLES`. If there are more tokens than variables, the complete remainder is assigned to the last variable. As a special case, if `IFS` is set to the empty string, each character of the input is considered a separate token.

If `-a` or `--array` is provided, only one variable name is allowed and the tokens are stored as an array in this variable.

See the documentation for `set` for more details on the scoping rules for variables.

## Example

The following code stores the value 'hello' in the shell 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_color - set the terminal color

## Synopsis

    set_color [OPTIONS] [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:

- `-b`, `--background` `COLOR` sets the background color.
- `-c`, `--print-colors` prints a list of all valid color names.
- `-o`, `--bold` sets bold or extra bright mode.
- `-u`, `--underline` sets underlined mode.

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.

# set - display and change shell 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 shell variables.

If set is called with no arguments, the names and values of all shell 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:

- `-l` or `--local` forces the specified shell variable to be given a scope that is local to the current block, even if a variable with the given name exists and is non-local
- `-g` or `--global` causes the specified shell variable to be given a global scope. Non-global variables disappear when the block they belong to ends
- `-U` or `--universal` causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current users fish instances on the current computer, and will be preserved across restarts of the shell.
- `-x` or `--export` causes the specified shell variable to be exported to child processes (making it an "environment variable")
- `-u` or `--unexport` causes the specified shell variable to NOT be exported to child processes

The following options are available:

- `-e` or `--erase` causes the specified shell variable to be erased
- `-q` or `--query` test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined.
- `-n` or `--names` List only the names of all defined variables, not their value
- `-L` or `--long` do not abbreviate long values when printing set variables

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.

`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
    # Prints all global, exported variables.

    set foo hi
    # Sets the value of the variable $foo to be 'hi'.

    set -e smurf
    # Removes the variable $smurf

    set PATH[4] ~/bin
    # Changes the fourth element of the $PATH array to ~/bin

    if set python_path (which python)
        echo "Python is at $python_path"
    end
    # Outputs the path to Python if `which` returns true.

Back to index.

# source - evaluate contents of file.

## Synopsis

    source 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 shell variables will 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 `source` is the return status of the last job to execute. If something goes wrong while opening or reading the file, `source` exits with a non-zero status.

`.` (a single period) is an alias for the `source` command. The use of `.` is deprecated in favour of `source`, and `.` will be removed in a future version of fish.

## Example

    source ~/.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:

- `-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 - that is, connected to a keyboard.
- `-l` or `--is-login` returns 0 if fish is a login shell - that is, 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` sets the job control type, which can be `none`, `full`, or `interactive`.
- `-t` or `--print-stack-trace` prints a stack trace of all function calls on the call stack.

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]
    [ [EXPRESSION] ]

## Description

Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments.

The first form (`test`) is preferred. For compatibility with other shells, the second form is available: a matching pair of square brackets (`[ [EXPRESSION ] ]`).

The following operators are available to examine files and directories:

- `-b FILE` returns true if `FILE` is a block device.
- `-c FILE` returns true if `FILE` is a character device.
- `-d FILE` returns true if `FILE` is a directory.
- `-e FILE` returns true if `FILE` exists.
- `-f FILE` returns true if `FILE` is a regular file.
- `-g FILE` returns true if `FILE` has the set-group-ID bit set.
- `-G FILE` returns true if `FILE` exists and has the same group ID as the current user.
- `-L FILE` returns true if `FILE` is a symbolic link.
- `-O FILE` returns true if `FILE` exists and is owned by the current user.
- `-p FILE` returns true if `FILE` is a named pipe.
- `-r FILE` returns true if `FILE` is marked as readable.
- `-s FILE` returns true if the size of `FILE` is greater than zero.
- `-S FILE` returns true if `FILE` is a socket.
- `-t FD` returns true if the file descriptor `FD` is a terminal (TTY).
- `-u FILE` returns true if `FILE` has the set-user-ID bit set.
- `-w FILE` returns true if `FILE` is marked as writable; note that this does not check if the filesystem is read-only.
- `-x FILE` returns true if `FILE` is marked as executable.

The following operators are available to compare and examine text strings:

- `STRING1 = STRING2` returns true if the strings `STRING1` and `STRING2` are identical.
- `STRING1 != STRING2` returns true if the strings `STRING1` and `STRING2` are not identical.
- `-n STRING` returns true if the length of `STRING` is non-zero.
- `-z STRING` returns true if the length of `STRING` is zero.

The following operators are available to compare and examine numbers:

- `NUM1 -eq NUM2` returns true if `NUM1` and `NUM2` are numerically equal.
- `NUM1 -ne NUM2` returns true if `NUM1` and `NUM2` are not numerically equal.
- `NUM1 -gt NUM2` returns true if `NUM1` is greater than `NUM2`.
- `NUM1 -ge NUM2` returns true if `NUM1` is greater than or equal to `NUM2`.
- `NUM1 -lt NUM2` returns true if `NUM1` is less than `NUM2`.
- `NUM1 -le NUM2` returns true if `NUM1` is less than or equal to `NUM2`.

Note that only integers are supported. For more complex mathematical operations, including fractions, the `env` program may be useful. Consult the documentation for your operating system.

Expressions can be combined using the following operators:

- `COND1 -a COND2` returns true if both `COND1` and `COND2` are true.
- `COND1 -o COND2` returns true if either `COND1` or `COND2` are true.

Expressions can be inverted using the `!` operator:

- `! EXPRESSION` returns true if `EXPRESSION` is false, and false if `EXPRESSION` is true.

Expressions can be grouped using parentheses.

- `( EXPRESSION )` returns the value of `EXPRESSION`.

  Note that parentheses will usually require escaping with `\(` to avoid being interpreted as a command substitution.

## Examples

If the `/tmp` directory exists, copy the `/etc/motd` file to it:

    if test -d /tmp
        cp /etc/motd /tmp/motd
    end

If the variable `MANPATH` is defined and not empty, print the contents. (If `MANPATH` is not defined, then it will expand to zero arguments, unless quoted.)

    if test -n "$MANPATH"
        echo $MANPATH
    end

Parentheses and the `-o` and `-a` operators can be combined to produce more complicated expressions. In this example, success is printed if there is a `/foo` or `/bar` file as well as a `/baz` or `/bat` file.

    if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \)
        echo Success.
    end.

## Standards

`test` implements a subset of the IEEE Std 1003.1-2008 (POSIX.1) standard. The following exceptions apply:

- The `<` and `>` operators for comparing strings are not implemented.

- Because this test is a shell builtin and not a standalone utility, using the -c flag on a special file descriptors like standard input and output may not return the same result when invoked from within a pipe as one would expect when invoking the `test` utility in another shell.

  In cases such as this, one can use `command` `test` to explicitly use the system's standalone `test` rather than this `builtin` `test`.

Back to 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:

- `ARG` is the command to be executed on signal delivery.
- `SIGSPEC` is the name of the signal to trap.
- `-l` or `--list-signals` prints a list of signal names.
- `-p` or `--print` prints 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.

## Example

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

Back to index.

# true - return a successful result

## Synopsis

    true

## Description

`true` sets the exit status to 0.

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:

- `-a` or `--all` prints all of possible definitions of the specified names.
- `-f` or `--no-functions` suppresses function and builtin lookup.
- `-t` or `--type` prints `function`, `builtin`, or `file` if `NAME` is a shell function, builtin, or disk file, respectively.
- `-p` or `--path` returns the name of the disk file that would be executed, or nothing if `type -t name` would not return `file`.
- `-P` or `--force-path` returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the `$PATH`.
- `-q` or `--quiet` suppresses all output; this is useful when testing the exit status.

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

- `-c` or `--core-size`: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled.
- `-d` or `--data-size`: the maximum size of a process' data segment.
- `-f` or `--file-size`: the maximum size of files created by the shell.
- `-l` or `--lock-size`: the maximum size that may be locked into memory.
- `-m` or `--resident-set-size`: the maximum resident set size.
- `-n` or `--file-descriptor-count`: the maximum number of open file descriptors (most systems do not allow this value to be set).
- `-s` or `--stack-size`: the maximum stack size.
- `-t` or `--cpu-time`: the maximum amount of CPU time in seconds.
- `-u` or `--process-count`: the maximum number of processes available to a single user.
- `-v` or `--virtual-memory-size` The maximum amount of virtual memory available to the shell.

Note that not all these limits are available in all operating systems.

The value of limit can be a number in the unit specified for the resource or one of the special values `hard`, `soft`, or `unlimited`, which stand for the current hard limit, the current soft limit, and no limit, respectively.

If limit is given, it is the new value of the specified resource. If no option is given, then `-f` is assumed. Values are in kilobytes, except for `-t`, which is in seconds and `-n` and `-u`, which are unscaled values. The return status is 0 unless an invalid option or argument is supplied, or an error occurs while setting a new limit.

`ulimit` also accepts the following switches that determine what type of limit to set:

- `-H` or `--hard` sets hard resource limit
- `-S` or `--soft` sets soft resource limit

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

- `-a` or `--all` prints all current limits

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

- `-h` or `--help` prints this message.
- `-S` or `--symbolic` prints the umask in symbolic form instead of octal form.
- `-p` or `--as-command` outputs the umask in a form that may be reused as input

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:

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

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.