Basics

Introduction

fish ships with autosuggestions, syntax highlighting, and tab completions for common commands. Scripts use fish's own syntax rather than POSIX sh.

Comments and printing

# my comment
echo 'Hello from Fish!'
printf '%s\n' 'Hello from Fish!'

echo adds a newline; printf takes a format string.

See: Comments

Variables

set my_variable 'Hello from Fish!'
set --erase my_variable

set stores a list even when given one value; echo $my_variable expands it.

See: Variables

Variable scope

set -l local_var 1     # current block
set -g global_var 1    # current session
set -U universal_var 1 # every session
set -x EDITOR nvim     # exported to children

-l, -g, and -U choose where a variable lives; -x exports it.

See: Variables

Inspecting variables

set --show PATH
set --query EDITOR; and echo 'editor is set'

--show prints scope and value; --query sets $status without printing.

See: set

Keys

Moving around

ShortcutDescription
Left / RightMove one character
Alt Left / Alt RightMove one word
Alt < / Alt >Start/end of commandline
^A / ^EStart/end of line

See: Shared bindings

Editing the line

ShortcutDescription
^UKill to start of line
^KKill to end of line
^WKill previous path component
Alt BackspaceKill previous word
^CCancel the line
^DDelete character; exit if empty
^LClear the screen
^Z / ^_Undo the last edit

See: Emacs mode

History and completion

ShortcutDescription
TabComplete the current token
Shift TabComplete and search the pager
Up / DownPrevious/next command
Alt Up / Alt DownPrevious/next argument
^RSearch history

See: History search

Lists and math

Slicing

set v a b c
echo $v[1]    # a
echo $v[1..2] # a b
echo $v[2..]  # b c
echo $v[-1]   # c

Indexes count from 1; negative indexes start at the end.

See: Slices

Numbers

set count (math $count + 1)
echo (math '2 ^ 10')

math prints the result; capture it with (...).

Operators

OperatorPerforms
+Addition
-Subtraction
*Multiplication
/Division
%Modulo
^Exponentiation

See: math

Strings

Matching

string match --regex --entire 'Fish' 'Hello from Fish!'
string match --quiet 'Fish*' 'Hello from Fish!'

--quiet sets $status instead of printing.

Patterns

PatternMatches
x?Zero or one x chars
x*Any count of x chars
x+One or more x chars
x{n}n times x chars
x{n,m}n to m times x chars
x{n,}n or more x chars
[xy]x or y char
[^xy]Not x or y char
\wWord character
\dDigit character
\WNot word character
\DNot digit character

See: string match

Replacing

# Replaces the first match
string replace --regex 'Fish' 'fish' 'Hello from Fish!'
# Replaces all matches
string replace --regex --all 'Fish' 'fish' 'Hello from Fish!'

Add --all to replace every match.

See: string replace

Transforming

string upper 'Hello'  # HELLO
string lower 'Hello'  # hello
string trim '  hi  '  # hi
string length 'Hello' # 5

See: string upper

Splitting and joining

string split , 'a,b,c'   # a b c
string join , a b c      # a,b,c
string collect (printf 'a\nb\n')  # joins lines

string split returns a list; string join takes one.

See: string split

Control flow

If/else

if test $my_variable -lt $another_variable
  echo 'less'
else if test $my_variable -eq $another_variable
  echo 'equal'
else
  echo 'greater'
end

See: Conditions

Tests

test -d /tmp; and echo 'directory'
test -f /nope; or echo 'missing'

and and or run the next command based on $status; && and || work too.

Numbers

OperatorMeaning
-ltLess than
-eqEqual
-gtGreater than
-leLess than or equal
-geGreater than or equal
-neNot equal

Strings

OperatorMeaning
=Equal
!=Not equal

Files

OperatorMeaning
-fFile exists
-dDirectory exists
-rExists and readable
-wExists and writable
-xExists and executable

See: Conditions

Switch

switch $my_variable
  case 'Yes'
    echo 'Affirmative'
  case '*'
    echo 'Anything else'
end

case '*' is the default branch.

See: Conditions

Loops

for i in (seq 1 3)
  echo "i=$i"
end

for file in *.txt
  echo $file
end

while true
  break
end

break and continue work inside loops.

See: Loops

Functions

function my_function --description 'My description'
  echo $argv[1]
end

functions --erase my_function

Arguments arrive in $argv.

See: Functions

Editing functions

funced my_function    # edit in $EDITOR
funcsave my_function  # write to config

funced opens the function; funcsave persists it.

See: funced

Processes

Pipes and redirection

my_command | another_command
my_command &| another_command  # pipes stdout and stderr
my_command > out.txt 2>&1
my_command < in.txt

&| pipes both streams; 2>&1 merges stderr into stdout.

See: Pipes

Command substitution

echo (math 1 + 2)
echo $(math 1 + 2)        # fish 3.4+
echo (my_command | psub)  # gives a temp file path

psub turns command output into a file for programs that need one.

See: Command substitution

Background jobs

my_command &
jobs
fg %1
bg %1

Job specs look like %1.

See: Job control

Input

read name
read -s password      # no echo
read -P 'Name: ' name # prompt

-s hides typed input; -P prints a prompt.

See: read

Paths

The path builtin

path basename /usr/local/bin/fish  # fish
path dirname /usr/local/bin/fish   # /usr/local/bin
path extension src/main.rs         # .rs
path change-extension .js src/a.ts # src/a.js
path normalize ./src/../a.txt      # a.txt

path filter and path is take -d, -f, -r, -w, -x.

See: path

Adding to PATH

fish_add_path ~/.local/bin
fish_add_path --prepend /opt/bin

It edits fish_user_paths and records it in universal variables.

See: fish_add_path

Interactive

Abbreviations

abbr --add grh 'git reset --hard HEAD'
abbr --show
abbr --erase grh

Abbreviations expand while typing, in interactive shells only.

See: Abbreviations

History

history search 'git commit'
history delete --contains 'secret'
history merge

^R opens the history pager.

See: History

Completions

complete --command mycommand --arguments 'install uninstall'
complete --command mycommand --short-option h --long-option help
complete --command mycommand --erase

complete registers options for tab completion.

Completion options

OptionDescription
--argumentsArguments to the command or option
--short-optionShort option
--long-optionLong option
--no-filesDon't suggest files
--force-filesSuggest files
--conditionOnly suggest under a condition
--descriptionDescription in the pager

See: complete

Key bindings

bind \cy 'echo hi'
bind --erase \cy

fish_key_reader prints the notation for a pressed key.

See: bind

Configuration

Config files

~/.config/fish/config.fish

set -gx EDITOR nvim
fish_add_path ~/.local/bin

Snippets in ~/.config/fish/conf.d/ run first, in name order, then config.fish. Universal variables persist in ~/.local/share/fish/fish_variables.

See: Configuration

Status checks

status is-interactive
status is-login
status fish-path

$status holds the exit code of the last command.

See: status

Also see

0 Comments for this cheatsheet. Write yours!