Fish Shell Cheat Sheet

1. Mental model

#!/usr/bin/env fish

2. Basic command syntax

3. Variables

set name Alex
set count 42
set empty ""
set words alpha beta gamma

set -l tmp value       # local to current block/function
set -g theme dark      # global to current fish process
set -U theme dark      # universal, persisted across sessions
set -x EDITOR nvim     # exported environment variable
set -gx PATH /opt/bin $PATH

set -e name            # erase variable
set -q name            # test whether variable exists
echo $name
set --show name        # detailed variable info

Lists and indexing

set fruits apple banana cherry

echo $fruits          # apple banana cherry
echo $fruits[1]       # apple, fish uses 1-based indexes
echo $fruits[2..3]    # banana cherry
echo $fruits[-1]      # cherry

set fruits[2] pear    # replace item 2
set -a fruits mango   # append
set -p fruits lime    # prepend

Strings

set greeting "hello world"
echo $greeting        # one argument because it is one variable element
string length $greeting
string replace hello hi $greeting
string split / $PATH

4. Expansion, quoting, and substitution

Command substitution

set here (pwd)
echo "Current directory: $here"

# Multiple lines become separate arguments by default
for file in (find . -name '*.go')
    echo $file
end

Variable expansion

set dir /tmp
echo $dir/file.txt        # /tmp/file.txt

set name world
echo hello_$name          # hello_world
echo "hello $name"        # hello world

Braces and globs

echo file.{txt,md}        # brace expansion
ls *.fish                 # globbing
ls **.fish                # recursive glob, fish-specific

5. Conditionals and tests

if / else

if test -f config.toml
    echo "config exists"
else if test -d config.toml
    echo "config.toml is a directory"
else
    echo "missing"
end

test shortcuts

Combining commands

command -q git; and echo "git found"
test -f README.md; or echo "no README"

if command -q rg; and test -d .git
    echo "ripgrep in a git repo"
end

fish supports and, or, and not instead of relying mainly on &&, ||, and !. Modern fish versions also accept && and ||, but the native words are idiomatic.

6. Loops

for file in *.txt
    echo $file
end

for n in (seq 1 5)
    echo $n
end

while test (count *.log) -gt 0
    echo "logs exist"
    break
end

cat urls.txt | while read -l url
    echo "fetching $url"
end

break and continue

for file in *
    test -d $file; and continue
    echo $file
end

7. Functions and aliases

Define a function

function mkcd
    mkdir -p $argv[1]
    cd $argv[1]
end

Arguments

function greet
    echo "Hello, $argv[1]"
    echo "All args: $argv"
end

Function arguments live in $argv. fish does not use $1, $2, $@, or $#.

Named arguments with argparse

function deploy
    argparse 'e/env=' 'dry-run' -- $argv
    or return

    set -q _flag_env; or set _flag_env staging

    if set -q _flag_dry_run
        echo "Dry-run deploy to $_flag_env"
    else
        echo "Deploying to $_flag_env"
    end
end

Aliases

alias ll='ls -lh'
alias gs='git status'

# Persist an alias by turning it into a function
funcsave ll

Save functions

functions                # list functions
functions mkcd          # show function body
funcsave mkcd           # save to ~/.config/fish/functions/mkcd.fish
funced mkcd             # edit function interactively

8. Pipes, redirects, and jobs

Exit status

false
echo $status            # 1

true | false
echo $pipestatus        # statuses of pipeline commands

9. Common and useful fish commands

help                    # open fish help
help set                # help for command
man fish                # manual
fish --version
fish_config             # web UI for config/theme/functions

set                     # list variables
set --show PATH
set -q VAR              # exists?
set -e VAR              # erase
set -Ux NAME value      # universal exported var

fish_add_path ~/.local/bin
fish_add_path /opt/homebrew/bin
contains /opt/bin $PATH; or fish_add_path /opt/bin

functions
functions name
funced name
funcsave name
functions -e name       # erase function

complete -c mycmd       # show completions
complete -c mycmd -e    # erase completions
fish_update_completions # generate from man pages

history
history search git
history delete --exact "bad command"

fish_config prompt      # choose prompt interactively
funced fish_prompt
funcsave fish_prompt

abbr -a gco git checkout
abbr -a gst git status
abbr -a k kubectl
abbr --show
abbr -e gst

10. Configuration files and startup

Typical config.fish

# ~/.config/fish/config.fish

# Only run interactive config in interactive shells
if status is-interactive
    fish_add_path ~/.local/bin
    fish_add_path /opt/homebrew/bin

    set -gx EDITOR nvim
    set -gx VISUAL nvim

    abbr -a gst git status
    abbr -a gco git checkout
    abbr -a k kubectl
end

Login shell

# Check path to fish
command -v fish

# Add fish to allowed shells if needed
# Example path may vary:
echo /opt/homebrew/bin/fish | sudo tee -a /etc/shells

# Change login shell
chsh -s /opt/homebrew/bin/fish

11. Completions

fish completions are first-class and often more readable than bash completion scripts.

Simple completion

complete -c mytool -s h -l help -d "Show help"
complete -c mytool -s v -l verbose -d "Verbose output"
complete -c mytool -l env -a "dev staging prod" -d "Environment"

Completion from command output

complete -c killbyname -a "(ps -axo comm | sort -u)" -d "Process name"

Completion files

~/.config/fish/completions/mytool.fish

12. Scripting patterns

Script skeleton

#!/usr/bin/env fish

set -l script_dir (dirname (status filename))

function usage
    echo "usage: myscript <name>"
end

if test (count $argv) -lt 1
    usage
    exit 1
end

set -l name $argv[1]
echo "Hello, $name from $script_dir"

Status helpers

status is-interactive   # true if interactive shell
status is-login         # true if login shell
status filename         # current script/function file
status dirname          # directory of current script/function file

Error handling

mkdir -p build
or begin
    echo "failed to create build" >&2
    exit 1
end

command -q git
or begin
    echo "git is required" >&2
    exit 1
end

Temporary environment for one command

# bash/zsh:
# FOO=bar command

# fish:
env FOO=bar command

# or:
begin
    set -lx FOO bar
    command
end

13. Main differences from bash/zsh

14. Everyday recipes

fish_add_path ~/.local/bin

set -Ux EDITOR nvim
set -Ux VISUAL nvim

if command -q rg
    rg TODO
else
    grep -R TODO .
end

function cproj
    cd ~/src/my-project
end
funcsave cproj

for file in (find . -name '*.json')
    jq . $file >/dev/null
    or echo "invalid: $file"
end

read -l -P "Deploy to prod? [y/N] " answer
if test "$answer" = y
    echo "deploying"
end

if test (count $argv) -eq 0
    echo "no args"
end

set branch (git branch --show-current)
echo "branch: $branch"

15. Migration tips for bash/zsh users

1. Do not paste your entire .bashrc or .zshrc into config.fish. Port it deliberately.
2. Start with PATH, editor, and abbreviations. Most of the value comes quickly.
3. Use fish_add_path instead of manually rebuilding PATH.
4. Prefer abbr for command shortcuts. It expands visibly, so your history contains the real command.
5. Use functions for logic. They are cleaner than aliases for anything with arguments.
6. Keep existing scripts as-is. Run bash scripts with bash, zsh scripts with zsh, and fish scripts with fish.
7. Remember the big five syntax swaps: set for assignment, (cmd) for substitution, $status for exit status, $argv for function args, and end for closing blocks.

16. Mini reference

set x value
set -l x value
set -g x value
set -U x value
set -x x value
set -gx x value
set -e x
set -q x

if test ...
    ...
else if test ...
    ...
else
    ...
end

for x in ...
    ...
end

while test ...
    ...
end

switch $x
    case a
        ...
    case '*'
        ...
end

function name
    echo $argv
end

funcsave name
funced name
functions name

help
fish_config
fish_add_path
abbr
complete
history
status
string
math
argparse