The fish Shell

Come for the colors and autosuggestions, stay for the sane scripting!

Table of Contents

• Overview
• License
• Goals
• History
• Sections
• Using Fish
• Installing
• Default Shell
• Uninstalling
• Starting
• Help
• Autosuggestions
• Tab Completions
• Changing Working Directory
• Commands
• and & or Commands
• Command History
• Command Substitution
• Wildcards
• Pipes and Redirection
• Brace Expansion
• Customizing Fish
• Aliases
• Abbreviations
• Configuration
• Configuration via Web UI
• Colors Tab
• Prompt Tab
• Functions Tab
• Variables Tab
• History Tab
• Bindings Tab
• Abbreviations Tab
• Configuration Server
• Configuration via config.fish
• Custom Greeting
• PATH environment variable
• Tools for Fish
• Scripting in Fish
• echo Command
• Variables
• Advanced Use of Variables
• Special Variables
• Eval
• Strings
• Regular Expressions
• Numbers
• Math
• Lists (aka Arrays)
• Hashmaps
• Colors
• printf Command
• status Command
• Files
• Tests
• Functions
• Comparison to JavaScript
• Function Autoloading
• Auto-running Functions
• Types of Commands
• if Command
• switch Command
• Loop Commands
• Custom Prompt
• Debugging Functions
• Custom Tab Completions
• Extras
• Absolute Path
• Dates
• Opening Files
• Reading from stdin
• Processes
• Jobs
• Random Numbers and Options
• Example in Node, bash, and fish
• Summary
• Acknowledgments

Overview

• colorful prompts
• auto-suggestions while typing
• auto-completion of commands, their switches (aka options), file paths, variable names, git branches, and more
• easy access to web-based help
• error messages that explain the problem and suggest a solution
• ability to customize colors and the prompt using a web UI
• highly consistent and simple scripting language where everything is done with commands, not special syntax to be memorized
• commands never create subshells, so changes they make (such as setting variables) are visible in the invoking shell
• variables can be set so they are shared with all current and future shells (see "universal variables")

License

You may copy, distribute and modify the software as long as you track changes/dates in source files. Any modifications to or software including (via compiler) GPL-licensed code must also be made available under the GPL along with build and install instructions.

Goals

• Everything that can be done in other shell languages should be possible to do in fish, though fish may rely on external commands in doing so.
• Fish should be user friendly, but not at the expense of expressiveness. Most trade-offs between power and ease of use can be avoided with careful design.
• Whenever possible without breaking the above goals, fish should follow the POSIX syntax.
  (This may lead some to avoid using fish for sysadmin and install types of scripts because there is often a desire for those to be highly portable without requiring installation of new software such as fish. However, for scripts targeted at typical users or scripts that only you will use, implementing them in a shell that is not 100% POSIX compliant is much less of a concern.)
• The shell language should have a small set of orthogonal features.
• Everything should be tab-completable, and every tab completion should have a description.
• Every syntax error and error in a builtin command should result in an error message describing what went wrong and a relevant help page. Whenever possible, errors should be flagged in red by the syntax highlighter.
• The language should be uniform so that once the user understands the command/argument syntax, they will know the whole language and be able to use tab-completion to discover new features.

History

Sections

Using Fish

Installing

Default Shell

Uninstalling

• rm -rf /usr/local/etc/fish /usr/local/share/fish ~/.config/fish
• rm /usr/local/share/man/man1/fish*.1
• rm -f /usr/local/bin/fish
• rm -f /usr/local/bin/fish_indent
• Edit the file /etc/shells and remove the path to fish.

Starting

Help

• Github repo at https://github.com/fish-shell/
• Wikipedia page at https://en.wikipedia.org/wiki/Friendly_interactive_shell
• official mailing list at fish-users@lists.sourceforge.net
• Stack Overflow at https://stackoverflow.com/questions/tagged/fish
• IRC channel #fish on irc.oftc.net

Autosuggestions

Tab Completions

Examples

Changing Working Directory

Commands

and & or Commands

command1
and command2

🐠 date && ls
fish: Unsupported use of '&&'. In fish, please use 'COMMAND; and COMMAND'.
date && ls
      ^

Command History

Command Substitution

set dateFormat '+%A %B %d, %G' # ex. Tuesday, November 1, 2017
set announcement 'Today is '(date $dateFormat)'.'

Wildcards

Pipes and Redirection

Brace Expansion

set cells {a,b,c}{1,2} # a1 b1 c1 a2 b2 c2

Customizing Fish

Aliases

Abbreviations

Configuration

1. executing commands in a shell
2. using the web configuration UI
3. adding commands in a configuration file

Configuration via Web UI

Colors Tab

Prompt Tab

Functions Tab

Variables Tab

History Tab

Bindings Tab

Abbreviations Tab

Configuration Server

Configuration via config.fish

Custom Greeting

PATH environment variable

if set -l index (contains -i some-path $fish_user_paths)
  set -e fish_user_paths[$index]
end

Tools for Fish

• awesome-fish -
  "A curated list of awesome tools, prompts, and other cool nuggets for the amazing fish-shell."
  https://github.com/JorgeBucaran/awesome-fish
• Fisher - "A package manager for the fish shell"
  https://github.com/jorgebucaran/fisher
• Fundle - "a minimalist package manager for fish inspired by Vundle"
  https://github.com/danhper/fundle
• Oh My Fish - "provides core infrastructure to allow you to install packages which extend or modify the look of your shell"
  https://github.com/oh-my-fish/oh-my-fish

Scripting in Fish

• Decide where to create the implementation file.
• Make sure that directory is listed in the PATH environment variable.
• Create the file and write the code.
• Add a "shebang" comment as the first line.
• Use the chmod command to make the file executable.

• Enter funced name. This opens an editor for entering or modifying the script. If the script is new, the editor is populated with a starting point for the function definition.
• Write or modify the code, save the changes, and exit the editor. If the function was previously defined in a file, this will not update the file!
• Enter funcsave name. This saves the script to a file with the same name as the function in the ~/.config/fish/functions directory. When commands are executed, fish automatically looks for their implementation here. If this step is skipped, the function can still be used as a command, but it won't be available in other existing or future sessions.

echo Command

Variables

Eval

set extension 'js'
set command 'ls *.'$extension
eval $command # lists all JavaScript files in the current directory

Advanced Use of Variables

set foo 1
set bar foo
echo $$bar # 1

set pocket wallet
set pant pocket
echo $$pant # wallet

set foreground blue
set background green
set side fore
set name $side'ground'
echo $$name # blue

set colors red green blue
set listName colors

Special Variables

• CMD_DURATION - duration of the last command in milliseconds
• COLUMNS - number of columns in the current terminal
• FISH_VERSION and version - version of the fish shell being used
  (can be output by entering fish -v)
• HOME - user's home directory
• LINES - number of lines (or rows) in the current terminal
• PWD - current (or present) working directory
• USER - current username
• _ - name of the currently executing command
• status - status of the last command

Strings

set middle 'some middle'
set result 'some prefix'$middle'some suffix'

set result some prefix"$middle"some suffix
set result some prefix{$middle}some suffix

• is empty: if test -z "$var"
• is not empty: if test -n "$var"
• is equal to another: if test "$var1" = "$var2"
• is not equal to another: if test "$var1" != "$var2"

if expr $v1 '<=' $v2
  # code goes here
end

set csv 'red,green,blue'
set colors (string split , $csv) # red green blue

• --left (-l) only trims from left
• --right (-r) only trim from right
• --chars (-c) specifies the characters to be trimmed instead of whitespace

set myText '00019'
set result (string trim --left --chars 0 $myText) # 19

set first Richard
set middle Mark
set last Volkmann
set initialList (string sub -l 1 $first $middle $last) # R M V
set initials (string join '' $initialList) # RMV

Regular Expressions

set name 'Mark Volkmann'
string match --quiet --regex 'Vo' $name
echo $status # 0 for found

set text 'This is foolish work for a boolean.'
set matches (string match -ar '.oo' $text) # foo boo
set matches (string match -anr '.oo' $text) # 9 3 28 3
set text 'A foal isn\'t boolean.'
# The next regular expression uses a capture group.
set matches (string match -ar '.(o.).' $text) # foal oa bool oo

set text 'This is foolish work for a fool.'
set newText (string replace --all 'foo' 'bar' $text) # not using a regex
# this is barlish work for a barl
set newText (string replace -ar '.oo' 'bar' $text) # regex matching more than foo
# this is barlish work for a barl

Numbers

• equal: if test $n1 -eq $n2
• not equal: if test $n1 -ne $n2
• less than: if test $n1 -lt $n2
• less than or equal: if test $n1 -le $n2
• greater than: if test $n1 -gt $n2
• greater than or equal: if test $n1 -ge $n2

Math

set width 2
set height 3
set area (math "$width * $height") # 6

set pi (echo "a(1) * 4" | bc -l) # 3.14159265
set degrees 45
set radians (math -s8 "$degrees * $pi / 180") # .78539816
set result (echo "s($radians)" | bc --mathlib) # .70710678

Lists (aka Arrays)

if contains item $listName
  # code goes here
end

if set --local index (contains --index item $listName)
  set --erase listName[$index]
end

for item in $listName
  # use $item here
end

set columns a b c
set rows 1 2
set cells $columns$rows # a1 b1 c1 a2 b2 c2
count $cells # 6

set dashedCells $columns'-'$rows # a-1 b-1 c-1 a-2 b-2 c-2

set labels 'Column '$columns # Column a Column b Column c
count $labels # 3

Hashmaps

set colors red green blue
set items_red fire
set items_green grass
set items_blue water
for color in $colors
  eval echo '$'items_$color # fire, grass, water
end

Colors

echo Roses are (set_color red)red(set_color normal), \
  violets are (set_color blue)blue(set_color normal).

• --background (-b) specifies a background instead of a foreground color
• --print-colors (-c) prints the list of supported color names
• --bold (-o) sets bold mode
• --dim (-d) sets dim mode
  Some terminals, including iTerm2 on macOS, don't support this by default.
• --italics (-i) sets italics mode
  Some terminals, including iTerm2 on macOS, don't support this by default.
• --reverse (-r) sets reverse mode where foreground and background colors are swapped
• --underline (-u) sets underline mode

printf Command

• %d or %i for signed decimal (integer)
• %f for float
• %s for string
• %% for literal %

• \a for bell
• \n for newline
• \t for tab

set format 'My name is %s and I am '(set_color red)%i(set_color normal)' years old.'
printf $format Paige 6

# This is another approach that produces the same result.
set format 'My name is %s and I am %s%i%s years old.'
printf $format Paige (set_color red) 6 (set_color normal)

status Command

• status current-filename - outputs the file path of the current file
  If the function was defined interactively and has not been explicitly saved to a file, this will output the path to the temporary file where its definition has been saved.
• status current-function - outputs the name of the current function
• status current-line-number - outputs the line number within the file where this appears. This command has issues. See https://github.com/fish-shell/fish-shell/issues/4161.
• status print-stack-trace - prints a stack trace which is useful when debugging issues in nested function calls

Files

cat filePath | while read line
  # do something with $line
end

while read line
  # do something with $line
end < filePath 

• exists: if test -e $file
• is a file: if test -f $file
• is a directory: if test -d $file
• is a symbolic link: if test -L $file
• is readable: if test -r $file
• is writable: if test -w $file
• is executable: if test -x $file
• is non-empty (has size): if test -s $file
• and more (see the test command for details)

Tests

if test $color = 'yellow'; and test $size = 'large'
  # code here
end

if test $color = 'yellow'
  and test $size = 'large'
  # code here
end

if test \( $color = 'yellow' \) -a \( $size = 'large' \)
  # code here
end

Functions

function name
  # code goes here
end

function orderShirt -a size color
  # Use $size and $color here.
  # $argv is also set to a list of the arguments.
  echo I see you want to order a $size shirt that is $color.
end

set -q argName[1]; or set argName defaultValue

function orderShirt -a size color
  set -q size[1]; or set size 'large'
  set -q color[1]; or set color 'white'
  echo I see you want to order a $size shirt that is $color.
end

function fndesc -a fnName -d 'displays description of a function'
  set lines (functions --details --verbose $fnName)
  echo $lines[5]
end

• path to the definition
• whether it was autoloaded (outputs "autoloaded" or "n/a")
• line number within the file where definition begins or 0 if not autoloaded
• whether "scope shadowing" was disabled
  This is disabled by default. See the --no-scope-shadowing switch of the function command for details.
• the function description specified with the --description (-d) switch or "n/a" if no description was provided

set_color $fish_color_error
echo someErrorMsg 1>&2 # writes to stdout
set_color normal
return someNonZeroStatus

sed -i .bak 's/    /  /g' fn-name.fish

Comparison to JavaScript

function product(n1, n2) {
  return n1 * n2;
}
const result = product(2, 3); // 6

function product -a n1 n2
  math "$n1 * $n2"
end
set result (product 2 3) # 6

Function Autoloading

funced foo; and funcsave foo; and source ~/.config/fish/functions/foo.fish

Auto-running Functions

Auto-running on Events

function takeShelter --on-event tornado
  echo Tornado warning! Take shelter!
end

• fish_prompt
  This is emitted whenever a new fish prompt is about to be displayed.
• fish_command_not_found
  This is emitted whenever a command lookup fails. It is a bit like method_missing in the Ruby programming language.
• fish_preexec and fish_postexec
  These are emitted before and after each interactive command is executed, even if the command is invalid. The entire command line is passed as the first argument.

Auto-running on Variable Changes

function announcePath --on-variable PATH
  echo PATH is now $PATH
end
set -U PATH /foo $PATH

Auto-running on Process Exits

function announceProcessExit --on-process-exit 12345
  echo an important process exited
end

# %self expands to the current process id.
function announceMyExit --on-process-exit %self
  echo 'got process exit' > process.log
end

Auto-running on Signals

function handleHupSignal --on-signal hup
  echo got hup
end

kill -hup %self # got hup

Types of Commands

alias greet 'echo Hello, $USER'
functions greet

# Defined in - @ line 0
function greet --description 'alias greet echo Hello, $USER'
  echo Hello, $USER $argv;
end

if Command

if command
  commands
else if command
  commands
else
  commands
end

switch Command

switch expression # ex. $color
  case value1 value2
    statements
  case value3
    statements
  case '*' # like default in other languages
    statements
end

function product -d 'outputs the product of any # of arguments'
  set result 1
  for arg in $argv
    switch $arg
      case '-h' '--help'
        echo 'This function returns the product of its arguments.'
        return
      case '*'
        # If $arg starts with a dash ...
        # -- is needed in case $arg starts with a dash.
        if string match -qr '^-' -- $arg
          echo "Unsupported switch $arg"
          return
        end
        set result (math "$result * $arg")
    end
  end
  echo $result
end

Loop Commands

while command
  # commands go here
end

for var in list
  # use $var here
end

for n in (seq 5)
  echo $n
end

for path in b*.fish
  echo $path
end

Custom Prompt

# This function is run every time fish displays a new prompt.
function fish_prompt
  set vimModeLen 2 # appears at beginning of prompt (described later)
  set remaining (math "$COLUMNS - $vimModeLen")

  # Display present working directory.
  set_color --bold brblue # pwd color
  set pwdLen (string length $PWD)
  if test $pwdLen -le $remaining
    echo -n $PWD # -n suppresses newline at end
    set remaining (math "$remaining - $pwdLen")
  else
    echo -n (prompt_pwd) # abbreviated working directory
    set remaining 0 # so nothing else is output on this line
  end

  # Get the current Git branch.
  # This will be an empty string if not in a Git repo.
  set branch (git rev-parse --abbrev-ref HEAD ^/dev/null)

  # If in a Git repo ...
  if test -n "$branch"
    set branchLen (string length $branch)
    # If branch name will fit on current line ...
    if test $branchLen -le $remaining
      echo -n ' ' # space between PWD and branch name
    else
      echo # newline
      # Indent past Vim mode on previous line.
      echo -n (string repeat -n$vimModeLen ' ')
      set remaining $COLUMNS # resets to full width
    end

    # If branch name will fit on current line ...
    if test $branchLen -le $remaining
      # Display current Git branch.
      set_color --bold yellow # git branch color
      echo -n $branch
    end
    # If branch name doesn't fit, it is not output.
  end

  # Always display "fish" prompt on new line.
  set_color normal
  # This uses printf instead of echo to output a leading newline.
  printf '\\n🐠  ' # uses Unicode for tropical fish emoji 🐠
end

function fish_mode_prompt
  if test "$fish_key_bindings" = 'fish_vi_key_bindings'
    switch $fish_bind_mode
      case default
        set_color red
        echo N
      case insert
        set_color green
        echo I
      case replace_one # There is no replace_all.
        set_color green
        echo R
      case visual
        set_color magenta
        echo V
    end
    echo ' '
  end
end

Debugging Functions

Custom Tab Completions

complete -c commandName -s shortSwitchName -l longSwitchName -a 'argument words'

• --command (-c) - specifies the command to which the completion applies
• --short-option (-s) - specifies the short name of the switch to which the completion applies
• --long-option (-l) - specifies the long name of the switch to which the completion applies
• --arguments (-a) - specifies the completion values to be used as a single, space-separated string
• --no-files (-f) - disallows file path completion for this switch
• --require-parameter (-r) - specifies that a value must follow the switch

cecho -c red fire -c green grass -c normal cloud -c blue sky

function cecho -d 'echoes given text in colors'
  for arg in $argv
    switch $arg
      case '-c' '--color'
        set expectColor 'yes'
      case '*'
        if test -n "$expectColor"
          set_color $arg
          set expectColor # no value
        else
          echo -n $arg' ' # includes space between words
        end
    end
  end
  echo # for newline
end

# Configure completions for the color switch.
set colors 'black blue cyan green magenta red white yellow'
complete --command cecho -f -r -s c -l color -a "$colors"

Extras

Absolute Path

Dates

Opening Files

Reading From stdin

• --prompt-str text (-P)
  This sets the prompt text which defaults to "read> ". For example, to prompt the user for their favorite color, use read --prompt-str 'Favorite color: ' color. This sets the variable color to what the user enters.
• --prompt command (-p)
  This sets the prompt text to the output of the specified command. It is useful for dynamic prompts. For example, to ask the user if they were born in the current month, use
  read --prompt "echo Were you born in (date '+%B')'? '" bornThisMonth
• --command text (-c)
  This sets the initial text as if the user had entered it. The user can modify this. For example, to prompt for a meeting date and default to the current date in a format like "09/30/2017", read --command (date '+%m/%d/%G') meetingDate
• --silent (-i)
  This masks the input. For example, this is appropriate for entering passwords.
• --array (-a)
  This sets the variable to a list of the words entered instead of a single string value. For example, read --array favColors sets the variable favColors to the list of colors the user enters. If "red green blue" is entered, favColors will be set to that list and count $colors will output 3.

while read line
  if test -z $line; break; end
  echo you entered $line
end

Processes

Jobs

Random Numbers and Options

set colors red orange yellow green blue purple
set color (random choice $colors)

Example in Node, bash, and fish

const chalk = require('chalk');
const fs = require('fs');
const path = require('path');

const colorMap = {
  'css': 'green',
  'html': 'blue',
  'js': 'red',
  'scss': 'green'
};

// Use colors specified in command-line arguments.
args = process.argv;
args.shift(); // path to node executable
args.shift(); // path to this file
for (const arg of args) {
  const [extension, color] = arg.split('=');
  if (!color) throw new Error(`invalid argument "${arg}"`);
  colorMap[extension] = color;
}

fs.readdir('.', (err, files) => {
  if (err) throw new Error(err);
  for (const file of files) {
    const extension = path.extname(file).substring(1);
    const color = colorMap[extension];
    if (color) {
      console.log(chalk.keyword(color)(file));
    } else {
      console.log(file);
    }
  }
});

#!/bin/bash

# Color ANSI escape sequences
black='\033[0;30m'
red='\033[0;31m'
green='\033[0;32m'
orange='\033[0;33m'
blue='\033[0;34m'
purple='\033[0;35m' # magenta
cyan='\033[0;36m'
yellow='\033[1;33m'
white='\033[1;37m'
normal='\033[0m'

# Default colors
cssColor=$green
defaultColor=$white
htmlColor=$blue
jsColor=$red
scssColor=$green

usage() {
  echo invalid argument $0
  exit 1
}

# Use colors specified in switches.
for arg in "$@"
do
  extension=${arg%%=*}
  [[ -z $extension ]] && usage
  color=${arg##*=}
  [[ -z $color ]] && usage
  varName="${extension}Color"
  eval $varName=\${!color}
done

for file in *
do
  extension=${file##*.}
  if [[ $extension == $file ]]
  then # no extension found
    color=$defaultColor
  else
    colorVar=${extension}Color
    color=${!colorVar}
    if [[ -z $color ]]
    then
      color=$defaultColor
    fi
  fi
  echo -e "$color$file"
done

function lscolor
  # Default colors
  set cssColor green
  set defaultColor normal
  set htmlColor blue
  set jsColor red
  set scssColor green

  # Use colors specified in switches.
  for arg in $argv
    set pieces (string split = $arg)
    if test (count $pieces) -lt 2
      echo 'invalid argument "'$arg'"'
      return 1
    end
    set extension $pieces[1]
    set color $pieces[2]
    set varName $extension'Color'
    set $varName $color
  end

  for file in (ls -d *)
    set pieces (string split . $file)
    if test (count $pieces) -ge 2
      set extension $pieces[-1] # last piece
      set varName $extension'Color'
      set color $$varName
      if test -z "$color"; set color $defaultColor; end
    else
      set color $defaultColor
    end
    set_color $color
    echo $file
  end
end

Summary

Acknowledgments