nazozokc Shell (fish) Guidelines
When to Use
- When writing or editing fish functions under
~/.config/fish/functions/ - When adding abbreviations (
abbr) or aliases infish_user_key_bindingsorconfig.fish - When writing fish scripts (
.fishfiles) - When debugging fish startup issues or
config.fisherrors
Basic Rules
- fish syntax only: Do not use bash syntax (
[[ ]],source,export VAR=val, etc.) - No bashisms: fish is not POSIX-compliant by design — embrace it
- Functions over aliases: Prefer
functiondefinitions overaliasfor anything non-trivial - Use
abbrfor short forms: Abbreviations expand in-line and are more discoverable than aliases
fish Syntax Cheatsheet
| Task | fish syntax | ❌ Bash (don't use) |
|---|---|---|
| Set variable | set var value |
var=value |
| Set env variable | set -x VAR value |
export VAR=value |
| Local variable | set -l var value |
local var=value |
| Condition | if test $var = "foo" |
if [ "$var" = "foo" ] |
| String compare | if string match -q "foo" $var |
if [[ $var == foo ]] |
| Command substitution | set result (cmd) |
result=$(cmd) |
| Source a file | source file.fish |
source file / . file |
| Append to PATH | fish_add_path /some/dir |
export PATH="$PATH:/some/dir" |
| Return value | return 0 |
same |
| Function args | $argv[1], $argv |
$1, $@ |
Function File Layout
# ~/.config/fish/functions/my_func.fish
function my_func --description "What this does"
# implementation
end
- One function per file
- Filename must match function name exactly
- Use
--descriptionflag for discoverability (functions my_func)
Abbreviations
# In config.fish or a dedicated file
abbr --add gs git status
abbr --add gp git push
- Use
abbrfor git shortcuts and common commands - Use
--addflag explicitly - Keep abbreviations 2–4 chars long
config.fish Structure
config.fish
├── Environment variables (set -x)
├── PATH additions (fish_add_path)
├── Abbreviations (abbr --add)
└── Source other configs if needed
- Do not put function definitions in
config.fish— usefunctions/directory - Keep
config.fishshort and readable
Startup Performance
- Avoid heavy commands in
config.fish(e.g.nixevaluations, slowevalcalls) - Use
fish_add_pathinstead ofset -x PATH— it deduplicates automatically - Check startup time with:
fish --command "exit" --profile /tmp/fish-profile.txt
Notes
- fish config directory:
~/.config/fish/ - Managed via dotfiles repository — edit files there, not directly in
~/.config/fish/ - For Nix-managed fish config, changes must go through
home-managermodules
Related Skills
- For Nix/home-manager fish module config, see ../nix/SKILL.md
- For dotfiles file operations, see ../linux/SKILL.md
- See default/SKILL.md for general rule violation handling.
- If asked to write POSIX/bash syntax for a fish script, clarify that fish uses different syntax and rewrite correctly