Fish Shell Configuration - Gentleman.Dots

Fish (Friendly Interactive Shell) is designed to be immediately usable and feature-rich out of the box. It provides intelligent autosuggestions, excellent tab completions, and beautiful syntax highlighting without complex configuration.

Overview

The Gentleman.Dots Fish configuration includes:

Gentleman color scheme applied to syntax highlighting
Fisher plugin manager for extensibility
Vi mode for vim-like editing
Starship, Zoxide, Atuin, and FZF integrations
Carapace for enhanced completions
Project jumping with custom pj function
Automatic tmux session startup
NVM for Node.js version management

Installation

Install Fish Shell

brew install fish

Install Dependencies

# Core tools
brew install starship zoxide atuin fzf carapace bat

# GNU ls for colors (macOS)
brew install coreutils

Deploy Configuration

# Backup existing config
mv ~/.config/fish ~/.config/fish.backup 2>/dev/null

# Copy Fish configuration
cp -r GentlemanFish/fish ~/.config/

# Copy Starship config
cp starship.toml ~/.config/starship.toml

Install Fisher & Plugins

Fish will auto-install Fisher on first interactive launch.

# Start Fish
fish

# Fisher installs automatically
# Install additional plugins if desired
fisher install jorgebucaran/nvm.fish

Set as Default Shell

# Add to /etc/shells if needed
echo $(which fish) | sudo tee -a /etc/shells

# Set as default
chsh -s $(which fish)

Configuration Structure

~/.config/fish/
├── config.fish              # Main configuration
├── fish_plugins             # Fisher plugin list
├── functions/               # Custom functions
│   ├── fisher.fish         # Fisher plugin manager
│   ├── pj.fish             # Project jumper
│   ├── nvm.fish            # Node version manager
│   └── tmux.fish           # Tmux utilities
├── completions/            # Auto-completions
│   ├── bun.fish
│   ├── nvm.fish
│   └── pj.fish
└── conf.d/                 # Auto-loaded configs
    └── nvm.fish

Configuration Breakdown

Main Config (config.fish)

Auto-Install Fisher

Fisher plugin manager installs automatically:

config.fish:3-8

if not functions -q fisher
    curl -sL https://git.io/fisher | source
    fisher install jorgebucaran/fisher
end

Path Configuration

Comprehensive PATH setup for various tools:

config.fish:19

set -x PATH $HOME/.local/bin $HOME/.opencode/bin $HOME/.volta/bin \
    $HOME/.bun/bin $HOME/.nix-profile/bin \
    /nix/var/nix/profiles/default/bin \
    /usr/local/bin $HOME/.cargo/bin $PATH

Automatic Tmux Startup

Sessions start inside tmux automatically:

config.fish:22-24

if not set -q TMUX
    tmux
end

To disable auto-tmux, comment out or remove the tmux block in config.fish.

Tool Integrations

Modern CLI tools initialized on startup:

config.fish:30-33

starship init fish | source
zoxide init fish | source
atuin init fish | source
fzf --fish | source

Carapace Completions

Advanced completion setup with initialization check:

config.fish:36-48

set -Ux CARAPACE_BRIDGES 'zsh,fish,bash,inshellisense'

if not test -f ~/.config/fish/completions/.initialized
    mkdir -p ~/.config/fish/completions
    carapace --list | awk '{print $1}' | xargs -I{} touch ~/.config/fish/completions/{}.fish
    touch ~/.config/fish/completions/.initialized
end

carapace _carapace | source

Gentleman Color Scheme

Custom syntax highlighting colors:

config.fish:71-102

# Color definitions
set -l foreground F3F6F9
set -l red CB7C94
set -l green B7CC85
set -l yellow FFE066
set -l cyan 7AA89F
set -l purple A3B5D6
set -l pink FF8DD7

# Apply to Fish
set -g fish_color_command $cyan
set -g fish_color_keyword $pink
set -g fish_color_quote $yellow
set -g fish_color_param $purple
set -g fish_color_operator $green
set -g fish_color_escape $pink

Vi Mode

Vim-like command line editing:

config.fish:54-55

# Enable vi mode
fish_vi_key_bindings

Aliases

Useful shortcuts for common operations:

config.fish:61-69

# Colorized ls
alias ls='gls --color=auto'  # Linux
alias ls='ls --color=auto'   # macOS

# FZF utilities
alias fzfbat='fzf --preview="bat --theme=gruvbox-dark --color=always {}"'
alias fzfnvim='nvim (fzf --preview="bat --theme=gruvbox-dark --color=always {}")'

Project Jumper (pj.fish)

Quickly navigate between project directories:

functions/pj.fish:1-41

function pj --description "Jump to a project"
    # Usage: pj PROJECT_NAME
    # Or: pj open PROJECT_NAME (opens in $EDITOR)
    
    set -l target (find $PROJECT_PATHS -maxdepth 1 -name $argv[1] | head -n 1)
    
    if test -n "$target"
        cd $target
    else
        echo "No such project: $argv[1]"
        return 1
    end
end

Setup:

# Add project directories to config.fish
set -Ux PROJECT_PATHS ~/work ~/projects ~/code

# Usage
pj my-project          # Jump to project
pj open my-project     # Open in $EDITOR

Fisher Plugin Manager

Fisher provides a minimalist plugin system:

fisher install jethrokuan/z
fisher install PatrickF1/fzf.fish

Key Features

Autosuggestions

Fish shows suggestions based on command history:

Type a command, see gray suggestion
Press → or Ctrl+F to accept
Press Alt+→ to accept one word
Suggestions learn from your history

Fish remembers your most-used commands and prioritizes them in suggestions. The more you use Fish, the smarter it gets!

Syntax Highlighting

Real-time feedback as you type:

Valid commands: Cyan
Invalid commands: Red
Strings: Yellow
Parameters: Purple
Operators: Green

Tab Completions

Intelligent completions for:

Commands and subcommands
File paths
Git branches and remotes
Command options (with descriptions!)
Custom completions from Carapace

Web Configuration

Fish includes a web-based configuration UI:

# Launch web config
fish_config

# Opens in browser with:
# - Color scheme editor
# - Function viewer
# - Variable inspector
# - Prompt configurator

Functions

Creating Custom Functions

Fish functions are simple and clean:

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

Saving Functions

# Define and save in one command
funcs --save mkcd

# Edit function
funced mkcd

# Save after editing
funcsave mkcd

Functions are saved to ~/.config/fish/functions/.

Useful Function Examples

function backup --argument filename
    cp $filename $filename.bak
end

Customization

Changing Colors

Modify the color scheme in config.fish:

# Your custom colors
set -l my_blue "0087af"
set -l my_green "00af87"

set -g fish_color_command $my_blue
set -g fish_color_param $my_green

Or use the web interface:

fish_config colors

Disabling Vi Mode

Revert to Emacs-style keybindings:

# In config.fish, replace:
fish_vi_key_bindings

# With:
fish_default_key_bindings

Custom Keybindings

Define in fish_user_key_bindings function:

function fish_user_key_bindings
    # Ctrl+F for fzf file search
    bind \cf 'fzf-file-widget'
    
    # Ctrl+G for git status
    bind \cg 'git status; commandline -f repaint'
end

Integration with Tools

Starship Prompt

Configured via shared ~/.config/starship.toml:

# Starship auto-loads with Gentleman palette
starship init fish | source

Zoxide Integration

# Smart directory jumping
z dotfiles        # Jump to ~/dotfiles
z doc             # Jump to most frecent match
zi                # Interactive selection with fzf

Atuin History

Enhanced shell history:

# Search (Ctrl+R)
atuin search docker

# Statistics
atuin stats

# Sync across machines
atuin sync

FZF Integration

Fuzzy finder with custom commands:

# Preview and open file
fzfnvim

# Preview with bat
fzfbat

# FZF built-in bindings
Ctrl+T    # File search
Ctrl+R    # History search (Atuin)
Alt+C     # Directory search

Tips & Tricks

Abbreviations expand automatically:

abbr -a gs git status
abbr -a gp git push
abbr -a gc git commit

Type gs and press Space - it expands to git status!

Universal variables persist across sessions:

set -Ux EDITOR nvim
set -Ux PROJECT_PATHS ~/work ~/code

Command substitution uses parentheses:

set files (ls *.txt)
cd (git rev-parse --show-toplevel)

Fish is not POSIX-compatible. Bash scripts need adaptation:

# Bash
export PATH="/usr/local/bin:$PATH"

# Fish
set -x PATH /usr/local/bin $PATH

Troubleshooting

Fisher Not Installing

# Manually install Fisher
curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | \
    source && fisher install jorgebucaran/fisher

Completions Not Working

# Rebuild completions
rm -rf ~/.config/fish/completions/*
fish_update_completions

# Reinitialize Carapace
carapace --list | awk '{print $1}' | xargs -I{} touch ~/.config/fish/completions/{}.fish

Starship Not Loading

# Check installation
which starship

# Test initialization
starship init fish | source

# Verify config exists
ls -la ~/.config/starship.toml

PATH Issues

# View current PATH
echo $PATH | tr ' ' '\n'

# Add directory temporarily
set -x PATH /my/path $PATH

# Add permanently
set -Ux fish_user_paths /my/path $fish_user_paths

Learning Resources

Fish Tutorial

Official interactive tutorial

Fish Documentation

Comprehensive reference guide

Awesome Fish

Curated plugins and resources

Fisher Plugins

Browse available Fisher plugins

Popular Fisher Plugins

# FZF integration
fisher install PatrickF1/fzf.fish

# Git utilities
fisher install laughedelic/pisces

Next Steps

Configure Starship prompt for customization
Set up Tmux session management
Explore Neovim integration
Learn about Zoxide directory jumping

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

​Overview

​Installation

​Configuration Structure

​Configuration Breakdown

​Main Config (config.fish)

​Auto-Install Fisher

​Path Configuration

​Automatic Tmux Startup

​Tool Integrations

​Carapace Completions

​Gentleman Color Scheme

​Vi Mode

​Aliases

​Project Jumper (pj.fish)

​Fisher Plugin Manager

​Key Features

​Autosuggestions

​Syntax Highlighting

​Tab Completions

​Web Configuration

​Functions

​Creating Custom Functions

​Saving Functions

​Useful Function Examples

​Customization

​Changing Colors

​Disabling Vi Mode

​Custom Keybindings

​Integration with Tools

​Starship Prompt

​Zoxide Integration

​Atuin History

​FZF Integration

​Tips & Tricks

​Troubleshooting

​Fisher Not Installing

​Completions Not Working

​Starship Not Loading

​PATH Issues

​Learning Resources

Fish Tutorial

Fish Documentation

Awesome Fish

Fisher Plugins

​Popular Fisher Plugins

​Next Steps

Build docs developers (and LLMs) love

Overview

Installation

Configuration Structure

Configuration Breakdown

Main Config (config.fish)

Auto-Install Fisher

Path Configuration

Automatic Tmux Startup

Tool Integrations

Carapace Completions

Gentleman Color Scheme

Vi Mode

Aliases

Project Jumper (pj.fish)

Fisher Plugin Manager

Key Features

Autosuggestions

Syntax Highlighting

Tab Completions

Web Configuration

Functions

Creating Custom Functions

Saving Functions

Useful Function Examples

Customization

Changing Colors

Disabling Vi Mode

Custom Keybindings

Integration with Tools

Starship Prompt

Zoxide Integration

Atuin History

FZF Integration

Tips & Tricks

Troubleshooting

Fisher Not Installing

Completions Not Working

Starship Not Loading

PATH Issues

Learning Resources

Popular Fisher Plugins

Next Steps