Skip to content

README.md

Latest commit

 

History

History
336 lines (233 loc) · 11.8 KB

README.md

File metadata and controls

336 lines (233 loc) · 11.8 KB

Fish Shell Configuration Documentation

🇷🇺 Русская версия

This document describes the configuration of the Fish shell environment.

Table of Contents

XDG Base Directories

The configuration follows the XDG Base Directory Specification for organizing configuration files:

  • XDG_CONFIG_HOME: $HOME/.config
  • XDG_DATA_HOME: $HOME/.local/share
  • XDG_STATE_HOME: $HOME/.local/state
  • XDG_CACHE_HOME: $HOME/.cache

These directories are automatically created if they don't exist.

Path Configuration

The configuration automatically adds all subdirectories for functions and completions:

  • For functions: all subfolders inside $__fish_config_dir/functions/ are added to fish_function_path.
  • For completions: all subfolders inside $__fish_config_dir/completions/ are added to fish_complete_path.

The implementation and configuration of this logic is located in conf.d/recursive_paths.fish.

Theme and Appearance

The shell uses Catppuccin theme with automatic dark/light mode detection based on macOS system settings:

Dynamic Theme Switching

The configuration supports dynamic theme switching for all components, including:

  • fzf - interactive file search
  • bat - syntax highlighting
  • eza (ls) - file listing color scheme
  • Fish shell - shell theme

Available Commands

# Reload all themes (fish, fzf, bat, eza)
theme_reload  # or shortcut: tr

# Reload only fzf theme
fzf_theme_reload  # or shortcut: ftr

Automatic Theme Switching

Fish 4.3+ supports automatic theme change detection through the built-in fish_terminal_color_theme variable. When you change the theme in macOS, modern terminals (Ghostty, iTerm2, WezTerm) automatically notify Fish of the change.

Automatic theme reloading is enabled by default through the reload_theme function, which subscribes to fish_terminal_color_theme changes:

# Automatically triggered when terminal theme changes
function reload_theme --on-variable fish_terminal_color_theme
    # Theme switching logic
end

How it works:

  1. You change the theme in macOS settings (light ↔ dark)
  2. Terminal sends Fish an OSC sequence about the theme change
  3. Fish updates the fish_terminal_color_theme variable
  4. The reload_theme function automatically triggers
  5. All themes (fzf, bat, eza, fish) update instantly across all open sessions

Note: If your terminal doesn't support OSC notifications, use the theme_reload command manually after changing the theme.

Cache Management

Cache files are managed in $XDG_CACHE_HOME/fish:

  • Expired cache files (older than 1200 minutes) are automatically removed
  • Cache initialization for various tools (Homebrew, FZF, Zoxide, mise, etc.)
  • Cached configurations for better performance

Plugin Management

Plugins are installed automatically using chezmoi based on the .chezmoiexternals/fish.toml file. This file contains all plugins, their sources, and update settings.

Used Plugins and Extensions

See .chezmoiexternals/fish.toml for the full list and configuration.

Shell Integration

Oh My Posh

  • Custom prompt configuration from $XDG_CONFIG_HOME/oh-my-posh/config.json
  • Automatic theme switching based on system appearance
  • Version-based caching for performance

FZF Integration

  • Custom color schemes for dark/light modes using Catppuccin themes
  • Default commands and preview settings with fd
  • Integration with bat for file preview
  • Custom key bindings for navigation and file editing
  • Integration with diff-so-fancy for diff highlighting

Screenshots

Here is how FZF looks with the current Catppuccin theme settings:

Light theme Dark theme
FZF Light FZF Dark

Zoxide

  • Directory jumping functionality
  • Automatic initialization with caching

Chezmoi

  • Template management integration
  • Automatic completion generation

Development Tools

Version Managers

  • ASDF: Configuration for multiple language versions
    • Automatic shims setup
    • Completion generation
    • Config file location: $HOME/.config/asdf/asdfrc
  • MISE: Modern development environment management
    • Automatic activation
    • Completion generation
    • Install path: /opt/homebrew/bin/mise

Homebrew

  • Automatic shell environment setup with caching
  • Fish completions integration
  • Analytics disabled by default (HOMEBREW_NO_ANALYTICS=1)

WebOS TV SDK

  • SDK home: $HOME/stv-tools/webos-sdk
  • CLI tools path: $LG_WEBOS_TV_SDK_HOME/bin
  • Tizen Studio integration

File Management

EZA (Modern ls)

  • Custom color schemes using Vivid with Catppuccin themes
  • Various aliases for different listing options:
    • l: Basic listing with git ignore
    • ll: Detailed listing with headers
    • llm: Modified time sorting
    • la: All files with details
    • lt: Tree view

Bat

  • Used as a replacement for cat
  • Theme matching system appearance
  • Syntax highlighting for various file types

Key Bindings

  • Vi mode enabled with custom bindings
  • Clipboard integration for copy/paste operations
  • Visual mode support
  • Custom bindings:
    • Ctrl+L / Ctrl+Д: Clear screen and reinitialize
    • Ctrl+E / Ctrl+У: Open Neovim
    • y in visual mode: Copy to clipboard
    • yy in normal mode: Copy line to clipboard
    • p: Paste from clipboard

Environment Variables

Node & NPM

The configuration sets XDG-compliant environment variables for Node.js and npm:

  • NODE_REPL_HISTORY: Stores Node.js REPL history in $XDG_STATE_HOME/node_repl_history.
  • NPM_CONFIG_INIT_MODULE: Path to npm init script at $XDG_CONFIG_HOME/npm/config/npm-init.js.
  • NPM_CONFIG_CACHE: Stores npm cache in $XDG_CACHE_HOME/npm.
  • NPM_CONFIG_USERCONFIG: User npm config at $XDG_CONFIG_HOME/npm/npmrc.

This keeps Node.js and npm files organized and portable, following XDG standards.

Editor Settings

  • EDITOR: Neovim
  • VISUAL: Same as EDITOR
  • GIT_EDITOR: Same as EDITOR

Development

  • GOPATH: $HOME/Library/go
  • LG_WEBOS_TV_SDK_HOME: WebOS TV SDK location
  • BAT_THEME: Matches system theme
  • SHELL: Fish shell path

Path Additions

  • $HOME/bin, $HOME/.bin, $HOME/.local/bin
  • $HOME/.cargo/bin (Rust)
  • $GOPATH/bin (Go)
  • $WEBOS_CLI_TV (WebOS tools)
  • node_modules/.bin (Node.js)
  • Coreutils GNU binaries

Abbreviations and Aliases

General

  • e: Open Neovim
  • y: Open Yazi file manager
  • ca: Apply Chezmoi changes
  • ee: Neovim config picker
  • eu: Update Neovim plugins
  • f: Fish performance test
  • q: Exit shell

Git

  • gb: List branches
  • gba: List all branches
  • gbsup: Set upstream branch
  • gc!: Amend commit
  • gcn!: Amend commit without editing
  • gf: Fetch
  • gfa: Fetch all and prune
  • gl: Pull
  • gp: Push
  • gpsup: Push and set upstream
  • gp!: Force push with lease
  • gco: Checkout
  • gcod: Checkout develop
  • gcom: Checkout main

Git Flow

  • gfb, gff, gfr, gfh, gfs: Git flow commands
  • gfbs, gffs, gfrs, gfhs, gfss: Start flow branches
  • gfbt, gfft, gfrt, gfht, gfst: Track flow branches

Development

  • nr: npm run
  • cat: bat (with syntax highlighting)
  • Various ls alternatives using eza

Custom Functions

The configuration includes several custom functions organized in the functions directory:

Neovim Related Functions

  • nvim_config_pick: Interactive function to select and switch between different Neovim configurations
    • Uses fd and FZF for configuration selection
    • Supports multiple Neovim configurations via NVIM_APPNAME
  • nvim_update: Updates Neovim and its plugins
  • nvim_disable_builtin_colorschemes: Disables built-in color schemes in Neovim

Git Related Functions

Located in functions/core/git/:

  • git.branch_current: Helper function to get the current Git branch name
  • git.branch_prune: Git branch deletion utility for managing merged branches (including squashed commits)

Yabai Related Functions

Located in functions/core/yabai/:

  • yabai.rearrange: Rearranges windows when new ones are created (triggered by Yabai signal)
  • yabai.restart: Restarts Yabai service cleanly
  • yabai.sudoers: Manages sudoers configuration for Yabai scripting addition

System Management Functions

Located in functions/core/:

  • restart_vm: Utility for restarting window manager services (Yabai, skhd, SketchyBar, etc.)
  • clear_and_reinit: Clears screen and reinitializes fish

Command Wrappers

Located in functions/wrappers/:

  • lazygit: Wrapper for the lazygit terminal UI for Git
  • btm: Wrapper for the bottom (btm) system monitor
  • grep: Enhanced grep wrapper

These functions enhance the shell's functionality and provide convenient shortcuts for common tasks. They are automatically loaded when the shell starts.

Secrets Management

The configuration integrates with KeePassXC for secure secret management:

  • OPENAI_API_KEY: OpenAI API key
  • GITLAB_TOKEN: GitLab access token
  • GITHUB_TOKEN: GitHub access token

Secrets are automatically loaded from KeePassXC using Chezmoi template functions.

Additional Features

  • Automatic man page path configuration
  • VS Code shell integration
  • Custom Git pathspec configuration (_GIT_PATHSPEC)
  • Automatic completion generation for various tools
  • Performance optimization through caching
  • Integration with macOS system appearance changes