Fish Shell

https://fishshell.com/docs/current
Admin
Fish Shell is a friendly interactive command-line shell focused on usability and interactive use,...
Tokens:265,289
Snippets:2,955
Trust Score:9.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### and command example with make

Source: https://fishshell.com/docs/current/cmds/and.html

Runs `make` to build a program. If the build succeeds (exit status 0), `make install` runs; if either step fails (exit status 1), `make clean` runs to remove build files.

```fish
make; and make install; or make clean
```

--------------------------------

### path basename examples

Source: https://fishshell.com/docs/current/cmds/path.html

Examples of `path basename` with various inputs. The last example expands a glob and prints all files in `/usr/bin/`; the output shown is only a selection.

```fish
>_ path basename ./foo.mp4
foo.mp4

>_ path basename ../banana
banana

>_ path basename /usr/bin/
bin

>_ path basename /usr/bin/*
# This prints all files in /usr/bin/
# A selection:
cp
fish
grep
rm
```

--------------------------------

### cd Examples

Source: https://fishshell.com/docs/current/cmds/cd.html

Three examples: cd to home, cd to a specific directory, and cd -P to resolve symlinks before changing.

```fish
cd
# changes the working directory to your home directory.

cd /usr/src/fish-shell
# changes the working directory to /usr/src/fish-shell

cd -P /tmp/link
# resolves /tmp/link to its target before recording the directory
```

--------------------------------

### Example prompt output

Source: https://fishshell.com/docs/current/tutorial.html

Example output of the multi-line fish_prompt defined above, showing the date and current directory.

```text
02/06/13
/home/tutorial > _
```

--------------------------------

### prompt_login example output

Source: https://fishshell.com/docs/current/cmds/prompt_login.html

Example output of running prompt_login, showing the user and host in the format user@host.

```fish
>_ prompt_login
root@bananablaster

```

--------------------------------

### time examples for command and loop

Source: https://fishshell.com/docs/current/cmds/time.html

Examples of timing a simple command and a for loop. Exact results will vary on your system.

```fish
>_ time sleep 1s

________________________________________________________
Executed in    1,01 secs   fish           external
   usr time    2,32 millis    0,00 micros    2,32 millis
   sys time    0,88 millis  877,00 micros    0,00 millis
```

```fish
>_ time for i in 1 2 3; sleep 1s; end

________________________________________________________
Executed in    3,01 secs   fish           external
   usr time    9,16 millis    2,94 millis    6,23 millis
   sys time    0,23 millis    0,00 millis    0,23 millis
```

--------------------------------

### path normalize examples

Source: https://fishshell.com/docs/current/cmds/path.html

Examples of 'path normalize' showing how it squashes duplicate slashes, collapses '..' components, removes leading './' (except when path starts with '-'), and does not resolve symlinks or make paths absolute.

```fish
>_ path normalize /usr/bin//../../etc/fish
# The "//" is squashed and the ".." components neutralize the components before
/etc/fish
```

```fish
>_ path normalize /bin//bash
# The "//" is squashed, but /bin isn't resolved even if your system links it to /usr/bin.
/bin/bash
```

```fish
>_ path normalize ./my/subdirs/../sub2
my/sub2
```

```fish
>_ path normalize -- -/foo
./-/foo
```

--------------------------------

### prompt_hostname Example Output

Source: https://fishshell.com/docs/current/cmds/prompt_hostname.html

Example output of prompt_hostname when the full hostname is foo.bar.com. It prints only the first component, 'foo'.

```fish
# The machine's full hostname is foo.bar.com
>_ prompt_hostname
foo
```

--------------------------------

### Start fish

Source: https://fishshell.com/docs/current/cmds/fish.html

Starts fish interactively.

```fish
fish
```

--------------------------------

### path dirname examples

Source: https://fishshell.com/docs/current/cmds/path.html

Examples of `path dirname` with relative and absolute paths.

```fish
>_ path dirname ./foo.mp4
.

>_ path dirname ../banana
..

>_ path dirname /usr/bin/
/usr
```

--------------------------------

### string repeat examples

Source: https://fishshell.com/docs/current/cmds/string-repeat.html

Examples of using `string repeat` with different options and input methods, showing the output for each command.

```fish
>_ string repeat -n 2 'foo '
foo foo

>_ echo foo | string repeat -n 2
foofoo

>_ string repeat -n 2 -m 5 'foo'
foofo

>_ string repeat -m 5 'foo'
foofo

>_ string repeat 2 'foo'
foofoo

>_ string repeat 2 -n 3
222
```

--------------------------------

### nextd example with prevd

Source: https://fishshell.com/docs/current/cmds/nextd.html

Example showing how nextd moves forward in the directory history after using prevd. The comments indicate the working directory after each command.

```fish
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
COPY
```

--------------------------------

### Start fish and see the default prompt

Source: https://fishshell.com/docs/current/tutorial.html

Start fish from your current shell. The output shows the default prompt with username, hostname, and working directory.

```fish
> fish
Welcome to fish, the friendly interactive shell
Type help for instructions on how to use fish
you@hostname ~>
COPY
```

--------------------------------

### Example invocations of myfunction

Source: https://fishshell.com/docs/current/language.html

Shows two example invocations of the myfunction function, each printing the first and third arguments. The output is shown after each command.

```fish
> myfunction first second third
first
third

> myfunction apple cucumber banana
apple
banana
```

--------------------------------

### Simple fish_title example

Source: https://fishshell.com/docs/current/cmds/fish_tab_title.html

A simple title example that shows the current directory and the most recently executed foreground command. Uses fish_prompt_pwd_dir_length=1 to shorten the path.

```fish
function fish_title
    set -q argv[1]; or set argv fish
    # Looks like ~/d/fish: git log
    # or /e/apt: fish
    echo (fish_prompt_pwd_dir_length=1 prompt_pwd): $argv;
end
```

--------------------------------

### string sub examples

Source: https://fishshell.com/docs/current/cmds/string-sub.html

Examples of extracting substrings with string sub. Each command shows the output on the following line. The examples cover --length, -s/-l, --start, --end, and combinations of start/end with positive and negative indices.

```fish
>_ string sub --length 2 abcde
ab

>_ string sub -s 2 -l 2 abcde
bc

>_ string sub --start=-2 abcde
de

>_ string sub --end=3 abcde
abc

>_ string sub -e -1 abcde
abcd

>_ string sub -s 2 -e -1 abcde
bcd

>_ string sub -s -3 -e -2 abcde
c
```

--------------------------------

### Quote a glob pattern for apt install: apt install "postgres-*"

Source: https://fishshell.com/docs/current/language.html

Use double quotes to prevent fish from expanding the wildcard, so apt installs all packages with a name starting with 'postgres-' instead of looking for files in the current directory.

```fish
apt install "postgres-*"
```

--------------------------------

### Re-read fish config file with source

Source: https://fishshell.com/docs/current/cmds/source.html

Example from the documentation: sources the fish initialization file to re-read it. The comment explains the purpose.

```fish
source ~/.config/fish/config.fish
# Causes fish to re-read its initialization file.

```

--------------------------------

### Get exit status with $status in fish

Source: https://fishshell.com/docs/current/faq.html

Check the exit status with `$status` (replaces `$?`). This example tests if the status equals 7 and prints a message when it does.

```fish
somecommand
if test $status -eq 7
    echo "That's my lucky number!"
end
```

--------------------------------

### Show all completions for git

Source: https://fishshell.com/docs/current/cmds/complete.html

This example shows all completions for `git`.

```fish
complete -c git
```

--------------------------------

### Example config.fish with PATH and function

Source: https://fishshell.com/docs/current/tutorial.html

Shows the contents of the fish configuration file, which is executed at startup. It sets the PATH variable and defines a function named ll that lists files with details.

```fish
> cat ~/.config/fish/config.fish

set -x PATH $PATH /sbin/

function ll
    ls -lh $argv
end
COPY
```

--------------------------------

### Range expansion with omitted limits

Source: https://fishshell.com/docs/current/relnotes.html

Examples of range limits in index range expansions. Omitting the start or end defaults to 1 and -1 respectively, printing the full list.

```fish
echo $var[1..]
echo $var[..-1]
echo $var[..]
```

--------------------------------

### Refuse vault, mysql, and ls commands

Source: https://fishshell.com/docs/current/cmds/fish_should_add_to_history.html

A simple example that refuses to store immediate 'vault', 'mysql', or 'ls' calls. Commands starting with a space would be stored because this function takes over all history duties.

```fish
function fish_should_add_to_history
    for cmd in vault mysql ls
         string match -qr "^$cmd" -- $argv; and return 1
    end
    return 0
end

```

--------------------------------

### Simple fish_prompt example

Source: https://fishshell.com/docs/current/cmds/fish_prompt.html

A simple example prompt that displays USER@HOST and the current directory in color. It uses $USER and $hostname, which are set by fish, and prompt_pwd to show the path.

```fish
function fish_prompt -d "Write out the prompt"
    # This shows up as USER@HOST /home/user/ >, with the directory colored
    # $USER and $hostname are set by fish, so you can just use them
    # instead of using `whoami` and `hostname`
    printf '%s@%s %s%s%s > ' $USER $hostname \
        (set_color $fish_color_cwd) (prompt_pwd) (set_color --reset)
end

```

--------------------------------

### Autosuggestion example: /bin/hostname

Source: https://fishshell.com/docs/current/tutorial.html

Shows a command that fish might suggest based on history or path.

```fish
> /bin/hostname
```

--------------------------------

### Unquoted wildcard in apt install (bash behavior)

Source: https://fishshell.com/docs/current/faq.html

Another example of a command that relies on bash's behavior of passing the literal wildcard when no match is found. It may fail if a matching file appears.

```bash
apt install postgres-*
```

--------------------------------

### command examples

Source: https://fishshell.com/docs/current/cmds/command.html

Examples of using `command` to execute a program, search for its path, and conditionally run a command if it exists. `command -sq git` and `command -vq git` return true (0) if git is found and print nothing.

```fish
command ls
```

```fish
command -s ls
```

```fish
command -q git; and command git log
```

```fish
command -sq git
```

```fish
command -q git
```

```fish
command -vq git
```

--------------------------------

### status terminal

Source: https://fishshell.com/docs/current/cmds/status.html

Prints the name and version of the terminal fish is running inside (for example as reported via XTVERSION). This is not available during early startup but only starting from when the first interactive prompt is shown, possibly via builtin read, so before the first fish_prompt or fish_read event.

```APIDOC
## status terminal

### Description
Prints the name and version of the terminal fish is running inside (for example as reported via XTVERSION). This is not available during early startup but only starting from when the first interactive prompt is shown, possibly via builtin read, so before the first fish_prompt or fish_read event.

### Method
status

### Endpoint
status terminal

### Response
#### Success Response
- Prints the terminal name and version to stdout.

```

--------------------------------

### Profile fish startup and sort results

Source: https://fishshell.com/docs/current/cmds/fish.html

Profiles fish startup, writing timing to /tmp/start.prof, then sorts the profile by the second column to find the most time-consuming parts.

```fish
fish --profile-startup /tmp/start.prof -ic exit
sort -nk2 /tmp/start.prof
```

--------------------------------

### path extension examples

Source: https://fishshell.com/docs/current/cmds/path.html

Examples of `path extension` with various paths. The final example reconstructs the original path by combining `path change-extension ''` and `path extension`.

```fish
>_ path extension ./foo.mp4
.mp4

>_ path extension ../banana
# an empty line, status 1

>_ path extension ~/.config
# an empty line, status 1

>_ path extension ~/.config.d
.d

>_ path extension ~/.config.
.

>_ set -l path (path change-extension '' ./foo.mp4)
>_ set -l extension (path extension ./foo.mp4)
> echo $path$extension
# reconstructs the original path again.
./foo.mp4
```

--------------------------------

### string collect examples

Source: https://fishshell.com/docs/current/cmds/string-collect.html

Examples showing string collect behavior: default trimming, --no-trim-newlines, and --allow-empty. The first example is a comparison with command substitution.

```fish
>_ echo "zero $(echo one\ntwo\nthree) four"
zero one
two
three four

>_ echo "(echo one\ntwo\nthree | string collect)"
"one
two
three"

>_ echo "(echo one\ntwo\nthree | string collect -N)"
"one
two
three
"

>_ echo foo(true | string collect --allow-empty)bar
foobar
```

--------------------------------

### psub examples: diff with sorted files and source-highlight with cpp

Source: https://fishshell.com/docs/current/cmds/psub.html

Two example commands that use psub. The first compares the sorted contents of a.txt and b.txt with diff. The second preprocesses main.c with cpp and highlights the result as C source using source-highlight, using -f to request a regular file and -s .c to append the .c suffix.

```fish
diff (sort a.txt | psub) (sort b.txt | psub)
# shows the difference between the sorted versions of files ``a.txt`` and ``b.txt``.

source-highlight -f esc (cpp main.c | psub -f -s .c)
# highlights ``main.c`` after preprocessing as a C source.
```

--------------------------------

### Start fish shell

Source: https://fishshell.com/docs/current/index.html

Starts a fish shell session when fish is not the default shell.

```shell
> fish
COPY
```

--------------------------------

### Wide prompt example

Source: https://fishshell.com/docs/current/relnotes.html

Example of a prompt that is wider than the terminal. It will be truncated instead of replaced with '> '.

```fish
~/dev/build/fish-shell-git/src/fish-shell/build (makepkg)>
```

--------------------------------

### Example .theme file format

Source: https://fishshell.com/docs/current/cmds/fish_config.html

Example .theme file format with light, dark, and unknown variants. Comments provide name and background color to the web config tool. Lines are like 'set variable value' without expansions; quotes are allowed but not necessary.

```fish
# name: 'My Theme'

[light]
# preferred_background: ffffff
fish_color_normal 000000
fish_color_autosuggestion 7f7f7f
fish_color_command 0000ee

[dark]
# preferred_background: 000000
fish_color_normal ffffff
fish_color_autosuggestion 7f7f7f
fish_color_command 5c5cff

[unknown]
fish_color_normal --reset
fish_color_autosuggestion brblack
fish_color_cancel -r
fish_color_command --reset
```

--------------------------------

### Get current token with commandline -ct

Source: https://fishshell.com/docs/current/cmds/commandline.html

Gets the in-progress token (the current token being completed).

```fish
set -l current (commandline -ct)

```

--------------------------------

### Custom fish_mode_prompt example

Source: https://fishshell.com/docs/current/cmds/fish_mode_prompt.html

Example of a custom fish_mode_prompt that displays colored mode indicators for each vi mode.

```fish
function fish_mode_prompt
  switch $fish_bind_mode
    case default
      set_color --bold red
      echo 'N'
    case insert
      set_color --bold green
      echo 'I'
    case replace_one
      set_color --bold green
      echo 'R'
    case replace
      set_color --bold bryellow
      echo 'R'
    case visual
      set_color --bold brmagenta
      echo 'V'
    case operator f F t T
      set_color --bold cyan
      echo 'N'
    case '*'
      set_color --bold red
      echo '?'
  end
  set_color --reset
end

```

--------------------------------

### Example: pushd and popd usage

Source: https://fishshell.com/docs/current/cmds/popd.html

Shows a sequence of pushd and popd commands with comments indicating the resulting working directory and directory stack contents. Demonstrates how popd removes the top directory and changes to the new top.

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

--------------------------------

### Build fish as a self-installing binary

Source: https://fishshell.com/docs/current/relnotes.html

Builds fish as a self-installing binary. The first interactive run extracts data files to ~/.local/share/fish/install/; use fish --install=PATH to specify a different location. This build system is experimental; cmake remains the recommended approach.

```shell
cargo install --path . # in a clone of the fish repository
# or `cargo build --release` and copy target/release/fish{,_indent,_key_reader} wherever you want

```

--------------------------------

### Truncated prompt example

Source: https://fishshell.com/docs/current/relnotes.html

The truncated version of the wide prompt example. The prompt is truncated to fit the terminal width.

```fish
…h-shell/build (makepkg)>
```

--------------------------------

### Use fish_config to preview and choose prompts

Source: https://fishshell.com/docs/current/faq.html

Commands to display all prompts, load a specific prompt, and save the change permanently.

```fish
> fish_config prompt show
# displays all the prompts fish ships with
> fish_config prompt choose disco
# loads the disco prompt in the current shell
> fish_config prompt save
# makes the change permanent
```

--------------------------------

### Command substitution examples with basename, convert, set, and string split0

Source: https://fishshell.com/docs/current/language.html

Examples of command substitution: basename in echo, a for loop with convert, reading a file into a variable without splitting, and splitting on NUL bytes with string split0.

```fish
# Outputs 'image.png'.
echo (basename image.jpg .jpg).png

# Convert all JPEG files in the current directory to the
# PNG format using the 'convert' program.
for i in *.jpg; convert $i (basename $i .jpg).png; end

# Set the ``data`` variable to the contents of 'data.txt'
# without splitting it into a list.
set data "$(cat data.txt)"

# Set ``$data`` to the contents of data, splitting on NUL-bytes.
set data (cat data | string split0)
```

--------------------------------

### begin command synopsis

Source: https://fishshell.com/docs/current/cmds/begin.html

Shows the two syntaxes for the `begin` command: `begin; [COMMANDS ...]; end` and `{ [COMMANDS ...] }`. The block is unconditionally executed and is equivalent to `if true; ...; end`.

```fish
begin; [COMMANDS ...]; end
{ [COMMANDS ...] }
```

--------------------------------

### Example transient prompt output

Source: https://fishshell.com/docs/current/prompt.html

Example screen output after running two commands in the same directory with the transient prompt enabled. Shows the simplified prompt for the previous command and the full prompt with status for the current one.

```text
Oneknowing>false
~/M/L/Oneknowing[1]>_
```
Tokens:
Raw