Fish Shell 配置使用说明

适用环境：CachyOS (Arch Linux) · Fish 4.8 · Niri 平铺窗口管理器

1. 文件结构概览

~/.config/fish/
├── config.fish              ← 主配置文件（你日常编辑的入口）
├── secrets.fish             ← 敏感变量（API Key 等，不要提交到 Git）
├── fish_variables           ← Fish 全局变量持久化存储（自动管理，一般不需要手动编辑）
├── config.fish.bak          ← 旧版配置备份（可忽略）
├── conf.d/                  ← Fish 启动时自动 source 的补充配置
│   └── (已清空，迁移文件已删除)
├── completions/             ← 自定义命令补全定义
│   ├── fzf-fftools.fish     ← FFmpeg 工具箱补全
│   ├── fzf-pkg.fish         ← 包管理工具补全
│   ├── fzf-add-watermark.fish
│   ├── fzf-burn-subs.fish
│   ├── fzf-compress-video.fish
│   ├── fzf-concat-video.fish
│   ├── fzf-convert-media.fish
│   ├── fzf-extract-audio.fish
│   ├── fzf-merge-av.fish
│   ├── fzf-mute-video.fish
│   ├── fzf-speed-video.fish
│   ├── fzf-trim-video.fish
│   ├── fzf-validate-media.fish
│   └── fzf-video-to-gif.fish
├── functions/               ← Fish 自动加载的函数目录（当前为空，函数都写在 config.fish 里）
└── README.md                ← 本文档

外部依赖配置：
~/.config/starship.toml      ← Starship 提示符主题
~/.config/atuin/config.toml  ← Atuin 历史搜索配置

加载顺序

config.fish 主配置
  ├── 1. Starship 提示符初始化
  ├── 2. Zoxide 目录跳转初始化
  ├── 3. 环境变量 + secrets.fish
  ├── 4. fzf 模糊查找初始化
  ├── 5. Atuin 历史搜索初始化（接管 Ctrl+R）
  ├── 6. direnv / pay-respects 钩子
  ├── 7. 缩写（abbr）定义
  ├── 8. 自定义函数
  ├── 9. PATH 配置
  └── 10. CachyOS 预设加载（放在最后，本文件配置优先）
       ├── done 长命令通知
       ├── eza 别名（ls/la/ll/lt 等）
       ├── 系统管理别名（update/mirror/cleanup 等）
       ├── !! / !$ 历史展开支持
       ├── history 函数（带时间戳）
       └── backup / copy 函数

2. 核心工具链

本配置集成了以下现代命令行工具，它们共同构成了高效的终端工作流：

提示符与视觉

工具	作用	说明
Starship	跨 Shell 提示符引擎	显示 Git 状态、语言版本、命令耗时等，主题配置在 `~/.config/starship.toml`
bat	cat 的现代替代	语法高亮 + 行号 + Git 变更标记，主题为 Dracula
eza	ls 的现代替代	彩色图标 + 目录优先 + 树状视图

历史与导航

工具	作用	说明
Atuin	Shell 历史管理	全局搜索、跨终端同步、SQLite 存储。`Ctrl+R` 触发
zoxide	智能目录跳转	根据访问频率学习，`z 项目名` 直接跳转。`zi` 交互式选择
fzf	模糊查找器	文件搜索、历史搜索、包管理等场景的通用模糊选择 UI

系统管理

工具	作用	说明
direnv	目录级环境变量	进入项目目录自动加载 `.envrc`，离开自动卸载
pay-respects	命令纠错	命令报错后按 `f` 自动修正（thefuck 的 Rust 替代）

文件管理

工具	作用	说明
yazi	终端文件管理器	`yy` 命令启动，退出后自动 cd 到最后浏览的目录
ouch	万能压缩解压	自动识别格式，一个命令搞定 zip/tar/gz/zst/7z 等

开发辅助

工具	作用	说明
tldr	man 的速查替代	`man tar` 先显示 tldr 简明用法，找不到回退到完整 man
delta	git diff 美化	侧边并排对比、语法高亮（需手动配置，见第 9 节）
procs	ps 的现代替代	`pst` 树状视图，`psw` 实时刷新
tokei	代码行数统计	按语言分类统计项目代码量
onefetch	Git 仓库信息展示	显示语言分布、提交数、作者、许可证等

3. 快捷键速查

fzf 快捷键

快捷键	功能	说明
`Ctrl+T`	模糊搜索文件	在当前目录递归搜索文件，选中后插入路径到命令行
`Ctrl+R`	Atuin 历史搜索	全局模糊搜索 Shell 历史命令（Atuin 接管，非 fzf 原生）
`Alt+C`	~~目录跳转~~	已禁用：Alt 是 niri 的 Mod 键，避免冲突

Atuin 快捷键

快捷键	功能
`Ctrl+R`	打开 Atuin 搜索界面
`Enter`	执行选中的命令
`Tab`	将选中命令填入命令行（不执行）

zoxide 快捷键（alias）

命令	功能	示例
`z <关键词>`	跳转到匹配的目录	`z proj` → 跳到含 “proj” 的最常访问目录
`zi <关键词>`	交互式选择目录	`zi dot` → 用 fzf 选择所有匹配目录

CachyOS 预设的 bang-bang 支持

输入	功能	示例
`!!`	展开为上一条命令	`sudo !!` → 以 root 执行上条命令
`!$`	展开为上一条命令的最后一个参数	`cd !$` → cd 到上条命令的最后一个路径

命令纠错

触发	功能	示例
`f` + Enter	自动修正上条错误命令	输入 `apt install vim`（报错后），按 `f` 修正为 `sudo pacman -S vim`

4. 缩写（abbr）完整列表

Fish 的 abbr 在键入时自动展开为完整命令，但历史记录中保存的是展开后的完整命令。这与 alias 不同——alias 只在执行时替换，脚本中也能用。

Git 工作流（21 条）

缩写	展开为	用途
`gs`	`git status`	查看工作区状态
`ga`	`git add`	暂存文件
`gaa`	`git add --all`	暂存所有变更
`gc`	`git commit`	提交（打开编辑器）
`gcm`	`git commit -m`	提交并附带消息
`gca`	`git commit --amend`	修正上一次提交
`gp`	`git push`	推送到远程
`gpf`	`git push --force-with-lease`	安全强推（比 –force 更安全）
`gpl`	`git pull`	拉取远程更新
`gco`	`git checkout`	切换分支/恢复文件
`gcb`	`git checkout -b`	创建并切换新分支
`gb`	`git branch`	查看/管理分支
`gd`	`git diff`	查看未暂存的变更
`gds`	`git diff --staged`	查看已暂存的变更
`gl`	`git log --oneline --graph -15`	最近 15 条提交的图形日志
`glog`	`git log --oneline --graph --all`	全分支图形日志
`grh`	`git reset --hard`	硬重置到 HEAD（丢弃所有未提交变更，慎用）
`grs`	`git restore --staged`	取消暂存
`gsw`	`git switch`	切换分支（比 checkout 更现代）
`gsc`	`git switch -c`	创建并切换新分支
`gsh`	`git stash`	暂存当前工作
`gsp`	`git stash pop`	恢复最近的 stash

常用组合示例：

gaa              # 暂存所有变更
gcm "feat: add x"  # 提交
gp               # 推送
gsw main         # 切回 main
gsp              # 恢复 stash

系统管理（CachyOS alias）

缩写	展开为	用途
`please`	`sudo`	`please pacman -S vim` = sudo
`mk`	`mkdir -p`	递归创建目录

媒体工具

缩写	展开为	用途
`compress`	`ouch compress`	压缩文件（自动识别格式）
`extract`	`ouch decompress`	解压文件（自动识别格式）
`compress-list`	`ouch list`	预览压缩包内容

开发辅助

缩写	展开为	用途
`pst`	`procs --tree`	树状查看进程
`psw`	`procs --watch`	实时监控进程
`loc`	`tokei`	代码行数统计
`repo`	`onefetch`	Git 仓库信息展示

5. CachyOS 预设别名（alias）完整列表

这些 alias 由 /usr/share/cachyos-fish-config/cachyos-config.fish 提供，会在 config.fish 末尾自动加载。

文件列表（eza）

别名	展开为	说明
`ls`	`eza -al --color=always --group-directories-first --icons=always`	详细列表（含隐藏文件）
`la`	`eza -a --color=always --group-directories-first --icons=always`	所有文件（含隐藏）
`ll`	`eza -l --color=always --group-directories-first --icons=always`	长格式（不含隐藏）
`lt`	`eza -aT --color=always --group-directories-first --icons=always`	树状视图
`l.`	`eza -a \| grep -e '^\.'`	仅显示隐藏文件

目录导航

别名	展开为
`..`	`cd ..`
`...`	`cd ../..`
`....`	`cd ../../..`
`.....`	`cd ../../../..`
`......`	`cd ../../../../..`

系统管理

别名	展开为	说明
`update`	`sudo cachyos-rate-mirrors && sudo pacman -Syu`	先排镜像再全量更新
`mirror`	`sudo cachyos-rate-mirrors`	测速排序镜像源
`cleanup`	`sudo pacman -Rns (pacman -Qtdq)`	清理孤儿依赖
`fixpacman`	`sudo rm /var/lib/pacman/db.lck`	删除 pacman 锁文件
`grubup`	`sudo grub-mkconfig -o /boot/grub/grub.cfg`	更新 GRUB 配置
`jctl`	`journalctl -p 3 -xb`	本次启动以来的错误日志

压缩解压

别名	展开为
`tarnow`	`tar -acf`
`untar`	`tar -zxvf`

信息查询

别名	展开为	说明
`hw`	`hwinfo --short`	硬件信息概览
`big`	`expac -H M '%m\t%n' \| sort -h \| nl`	按大小排列已安装包
`gitpkg`	`pacman -Q \| grep -i "\-git" \| wc -l`	统计 -git 包数量
`rip`	`expac --timefmt='%Y-%m-%d %T' '%l\t%n %v' \| sort \| tail -200 \| nl`	最近安装的 200 个包
`psmem`	`ps auxf \| sort -nr -k 4`	按内存占用排序进程
`psmem10`	`ps auxf \| sort -nr -k 4 \| head -10`	内存占用 Top 10

其他

别名	展开为	说明
`grep`	`grep --color=auto`	彩色高亮匹配
`wget`	`wget -c`	断点续传
`apt`	`man pacman`	给 Arch 新手的彩蛋
`apt-get`	`man pacman`	同上

CachyOS 预设函数

函数	用法	说明
`backup <文件>`	`backup config.txt`	复制文件为 `文件名.bak`
`copy <源目录> <目标>`	`copy project project-backup`	递归复制目录
`history`	`history`	带时间戳的命令历史（`history \| grep ssh`）

6. 自定义函数

`yy` — Yazi 终端文件管理器

yy              # 在当前目录打开 yazi
yy /path/to/dir # 在指定目录打开

特点：退出 yazi 后，Shell 会自动切换到你最后浏览的目录。不需要手动 cd。

`cat` — 智能 cat（bat 替代）

cat file.txt     # 输出到终端 → 用 bat（语法高亮 + 行号）
cat file.txt | wc -l  # 管道中 → 用系统 cat（避免 bat 干扰管道）

设计原理：Fish 的补全系统内部会调用 cat 读取缓存文件，如果 cat 被 alias 成 bat --number，补全会出现乱码。这里用函数包裹，仅在交互式终端输出时使用 bat，管道和脚本中保持原始 cat 行为。

`man` — 智能 man（tldr 优先）

man tar          # 优先显示 tldr 速查表
man 3 printf     # 带章节号 → 直接用系统 man
man              # 无参数 → 直接用系统 man

设计原理：tldr 输出简洁实用，日常 80% 的场景够用。带章节号（如 man 3 printf）或 tldr 查不到时自动回退到完整 man page。

7. fzf 媒体工具箱

通过 completions/ 目录注册了 14 个基于 fzf 的媒体处理命令，提供交互式文件选择 + FFmpeg 处理。

包管理

命令	功能	子命令
`fzf-pkg`	Arch/AUR 包管理	`menu`（交互菜单）、`update`（更新系统）、`orphans`（清理孤儿包）、`cache`（清理缓存）、`foreign`（AUR 包列表）、`news`（Arch 新闻）、`stats`（包统计）

视频处理

命令	功能
`fzf-compress-video`	压缩视频（CRF 质量 + 分辨率缩放）
`fzf-trim-video`	无损裁剪视频片段（关键帧切割）
`fzf-speed-video`	调整播放速度（0.5x ~ 3.0x）
`fzf-mute-video`	移除音轨，生成无声视频
`fzf-concat-video`	拼接多个视频（stream copy，无损）
`fzf-video-to-gif`	视频片段转高质量 GIF
`fzf-burn-subs`	字幕烧录到视频画面（SRT/ASS）

音频处理

命令	功能
`fzf-extract-audio`	从视频提取音频（M4A/MP3/Opus/WAV）
`fzf-merge-av`	智能匹配分离的音视频文件并合并

其他

命令	功能
`fzf-fftools`	FFmpeg 工具箱总入口（`--yazi` 可在 yazi 中打开）
`fzf-add-watermark`	添加文字/图片水印（支持位置、透明度、字体等参数）
`fzf-convert-media`	智能格式转换（自动识别类型匹配目标格式）
`fzf-validate-media`	验证媒体文件完整性

8. 环境变量与秘密管理

基础环境变量

变量	值	说明
`EDITOR`	`nvim`	默认编辑器（git commit、sudoedit 等读取）
`VISUAL`	`$EDITOR`	图形编辑器回退
`LESS`	`--RAW-CONTROL-CHARS --no-init --quit-if-one-screen --ignore-case`	保留 ANSI 颜色、退出不清屏、短内容自动退出、忽略大小写
`BAT_THEME`	`Dracula`	bat 配色主题
`BAT_STYLE`	`numbers,changes,header`	bat 显示行号 + Git 变更标记 + 文件头

fzf 环境变量

变量	说明
`FZF_DEFAULT_COMMAND`	用 `fd` 替代 `find`，自动排除 .git/node_modules/.cache 等重目录
`FZF_DEFAULT_OPTS`	`--height 100% --layout=reverse --border --cycle --inline-info`（全屏、反序、循环、边框）
`FZF_CTRL_T_COMMAND`	文件搜索使用与 `FZF_DEFAULT_COMMAND` 相同的 fd 命令
`FZF_CTRL_T_OPTS`	预览窗口在右侧 60% 宽度，用 bat 显示前 100 行

敏感变量（secrets.fish）

API Key 等敏感信息存放在 ~/.config/fish/secrets.fish 中，通过 source 引入。不要将此文件提交到 Git 仓库。

# 如果使用 Git 管理 dotfiles，在 .gitignore 中添加：
echo "secrets.fish" >> ~/.config/fish/.gitignore

当前 secrets.fish 中存放的变量：

STRIX_LLM — LLM 模型标识
LLM_API_KEY — LLM API 密钥

如需添加新的敏感变量，直接编辑 secrets.fish 即可，无需修改 config.fish。

PATH 配置

路径	来源
`~/.local/share/pnpm/bin`	pnpm 包管理器
`~/.local/bin`	用户本地可执行文件
`~/.cargo/bin`	Rust Cargo（通过 CachyOS `fish_add_path`）

9. 可选增强与启用方法

delta — Git Diff 美化

delta 提供语法高亮、侧边并排对比、行号等特性，比默认的 git diff 美观得多。

# 一次性配置（写入 ~/.gitconfig，无需每次设置）：
git config --global core.pager delta
git config --global interactive.diffFilter "delta --color-only"
git config --global delta.line-numbers true
git config --global delta.side-by-side true
git config --global delta.syntax-theme TwoDark

xh — 现代 HTTP 客户端

xh 是 HTTPie 的 Rust 重写，比 curl 更直观。需要先安装：sudo pacman -S xh

# 安装后，取消 config.fish 第 227-237 行的注释即可启用以下缩写：
req https://api.example.com    # 发送 GET 请求
get https://api.example.com    # 明确 GET
post https://api.example.com name=foo  # POST 表单

Atuin 目录过滤模式

默认 Atuin 搜索全局历史。如果希望优先显示当前目录下的命令：

# 在 config.fish 第 42 行取消注释：
set -gx ATUIN_FILTER_MODE "directory"

pay-respects 触发词

默认按 f + Enter 触发纠错。如果更习惯 fuck：

# 在 config.fish 第 101 行取消注释：
set -gx PAY_RESPECTS_ALIAS "fuck"

开启终端欢迎信息（fastfetch）

当前已禁用自动运行的 fastfetch。如需恢复：

# 删除 config.fish 第 189 行的覆盖：
# function fish_greeting; end

10. 常见问题

Q: 为什么不用 `alias cat=bat` 而是用 function 包裹？

Fish 的补全系统内部（__fish_cached 等）会调用 cat 读取缓存文件。如果 cat 被 alias 成 bat --number，缓存输出会被加上行号，导致 pacman 等补全出现乱码。用 function 包裹可以在终端输出时使用 bat，在管道/脚本中回退到原始 cat。

Q: 为什么 Alt+C 被禁用了？

你的窗口管理器是 Niri，Alt 键作为 Mod 键使用。fzf 默认将 Alt+C 绑定为目录跳转快捷键，会与 Niri 冲突，因此在配置中显式解绑。

Q: abbr 和 alias 有什么区别？为什么混用？

	abbr	alias
展开时机	键入时（按空格/回车前）	执行时
脚本兼容	❌ 脚本中不展开	✅ 在脚本中也能替换
历史记录	保存展开后的完整命令	保存别名本身
适用场景	交互式终端日常使用	需要脚本兼容的场景

本配置中，高频交互命令用 abbr（Git 操作等），CachyOS 预设的兼容性命令用 alias（ls/cd 等）。两者共存互不冲突——abbr 优先展开，如果展开后的词恰好是 alias 名，还会再被 alias 替换。

Q: `update` 是什么？和 `sudo pacman -Syu` 有什么区别？

update（CachyOS alias）= sudo cachyos-rate-mirrors && sudo pacman -Syu，在系统更新前先测速排序镜像源，确保下载速度最快。比单纯的 pacman -Syu 多一步镜像优化。

Q: `yy` 和直接运行 `yazi` 有什么区别？

直接运行 yazi 退出后终端还在原来的目录。yy 会在 yazi 退出后自动 cd 到你最后在 yazi 中浏览的目录，无需手动再 cd。

Q: 如何添加自己的缩写或函数？

直接编辑 ~/.config/fish/config.fish，在对应区块添加即可。修改会在新开终端时生效，或在当前终端执行 source ~/.config/fish/config.fish 立即生效。

# 添加缩写：
abbr -a -- dc 'docker compose'

# 添加函数：
function mkcd
    mkdir -p $argv[1]
    cd $argv[1]
end

Q: 如何备份和迁移这份配置？

核心文件只有 config.fish 和 secrets.fish（不含 API Key）：

# 备份（排除敏感文件和缓存）
cp ~/.config/fish/config.fish ~/backup/
cp ~/.config/fish/completions/*.fish ~/backup/

# 迁移到新机器后，确保安装所有依赖：
# sudo pacman -S fish starship zoxide fzf fd atuin direnv tldr bat yazi eza procs tokei onefetch ouch

Fish Shell 配置使用说明

目录

1. 文件结构概览

加载顺序

2. 核心工具链

提示符与视觉

历史与导航

系统管理

文件管理

开发辅助

3. 快捷键速查

fzf 快捷键

Atuin 快捷键

zoxide 快捷键（alias）

CachyOS 预设的 bang-bang 支持

命令纠错

4. 缩写（abbr）完整列表

Git 工作流（21 条）

系统管理（CachyOS alias）

媒体工具

开发辅助

5. CachyOS 预设别名（alias）完整列表

文件列表（eza）

目录导航

系统管理

压缩解压

信息查询

其他

CachyOS 预设函数

6. 自定义函数

yy — Yazi 终端文件管理器

cat — 智能 cat（bat 替代）

man — 智能 man（tldr 优先）

7. fzf 媒体工具箱

包管理

视频处理

音频处理

其他

8. 环境变量与秘密管理

基础环境变量

fzf 环境变量

敏感变量（secrets.fish）

PATH 配置

9. 可选增强与启用方法

delta — Git Diff 美化

xh — 现代 HTTP 客户端

Atuin 目录过滤模式

pay-respects 触发词

开启终端欢迎信息（fastfetch）

10. 常见问题

Q: 为什么不用 alias cat=bat 而是用 function 包裹？

Q: 为什么 Alt+C 被禁用了？

Q: abbr 和 alias 有什么区别？为什么混用？

Q: update 是什么？和 sudo pacman -Syu 有什么区别？

Q: yy 和直接运行 yazi 有什么区别？

Q: 如何添加自己的缩写或函数？

Q: 如何备份和迁移这份配置？

`yy` — Yazi 终端文件管理器

`cat` — 智能 cat（bat 替代）

`man` — 智能 man（tldr 优先）

Q: 为什么不用 `alias cat=bat` 而是用 function 包裹？

Q: `update` 是什么？和 `sudo pacman -Syu` 有什么区别？

Q: `yy` 和直接运行 `yazi` 有什么区别？