Oh My Fish 完整实战指南:Fish Shell 框架的安装、命令、配置与插件开发
Oh My Fish 完整实战指南:Fish Shell 框架的安装、命令、配置与插件开发
Oh My Fish(OMF)是面向 Fish Shell](http://fishshell.com) 的框架,为核心基础设施,用于安装能够扩展或改变 Shell 外观的软件包(packages),同时帮助开发者统一管理配置、主题与插件。本指南以仓库根目录 [README.md 为主体,结合 init.fish、lib/require.fish、lib/autoload.fish 以及 pkg/omf 下的命令实现源码,系统讲解从安装、日常命令、启动机制、Dotfiles 管理到插件/主题创建的全流程,读完即可上手安装 OMF 并编写自己的第一个插件。
维护状态提示:Oh My Fish 已经多年未维护,部分功能可能不适用于你的环境,少量主题和包目前存在损坏,代码也亟待大规模重构;当前维护者精力有限,若你有意成为维护者,可发送邮件至 oh-my-fish [at] googlegroups.com。本文以当前仓库实际内容为准,安装与使用前请知悉该前提。
一、Oh My Fish 是什么
Oh My Fish 提供核心基础设施,允许你安装用于扩展或修改 Shell 外观的软件包。它的定位是:快速(fast)、可扩展(extensible)、易于使用(easy to use)。从仓库目录结构可以看出,框架本体由 init.fish(启动入口)、lib/(核心库:自动加载与依赖加载)、pkg/omf(omf 命令实现)、templates/config.fish(安装模板)等组成,全部用 Fish 脚本实现,不依赖任何编译产物。
框架中的包(package)分为三大类(见 docs/en-US/FAQ.md):
- 配置工具类:如在启动时检测系统是否存在
pyenv并代为执行初始化命令的包; - 主题类:改变提示符外观,如默认的
default主题(含右侧提示符)以及文档中列举的 agnoster、bobthefish 等数十款主题(完整列表见 docs/Themes.md); - 传统 Shell 工具类:如跨 Linux/macOS 的剪贴板工具包。
使用 OMF 并不要求你先学习任何额外知识:安装后可以像平时一样继续使用 Fish,想深入时随时输入 omf help 查看帮助。
二、安装与升级
2.1 环境要求
- fish shell,版本 2.2 或更高;
- git,版本 1.9.5 或更高。
2.2 默认安装
在终端中直接运行(使用默认配置开始):
curl https://raw.githubusercontent.com/oh-my-fish/oh-my-fish/master/bin/install | fish
该命令会下载安装脚本并开始安装。
2.3 自定义安装路径
先下载安装脚本,再指定安装路径与配置路径:
curl https://raw.githubusercontent.com/oh-my-fish/oh-my-fish/master/bin/install > install
fish install --path=~/.local/share/omf --config=~/.config/omf
其中 --path 对应 OMF 本体安装目录(即 $OMF_PATH,默认 ~/.local/share/omf),--config 对应配置目录(即 $OMF_CONFIG,默认 ~/.config/omf)。安装模板 templates/config.fish 展示了这两个变量的写入方式:若设置了 XDG_DATA_HOME 则 OMF_PATH 取 $XDG_DATA_HOME/omf,否则取 $HOME/.local/share/omf;OMF_CONFIG 可在模板中按需取消注释并指定,最后通过 source $OMF_PATH/init.fish 加载框架。
2.4 校验安装脚本完整性
将下载的安装脚本与仓库中的 bin/install.sha256 校验和比对:
curl -sL https://raw.githubusercontent.com/oh-my-fish/oh-my-fish/master/bin/install.sha256 | shasum -a 256 --check
2.5 通过 Git 或离线源码包安装
# with git
$ git clone https://github.com/oh-my-fish/oh-my-fish
$ cd oh-my-fish
$ bin/install --offline
# with a tarball
$ curl https://raw.githubusercontent.com/oh-my-fish/oh-my-fish/master/bin/install > install
$ fish install --offline=omf.tar.gz
运行 install --help 可查看可自定义的全部安装选项。
2.6 升级已有安装
⚠️ 升级前请先备份 dotfiles 及其他敏感数据。
curl -L github.com/oh-my-fish/oh-my-fish/raw/master/bin/install | sh
之后可以安全移除旧的 $fish_path:
rm -rf "$fish_path"
2.7 已知问题
- 由于 fish 2.6 在某些终端模拟器上存在回归缺陷,右提示符(right prompt)会导致 Shell 无法使用。OMF 的
default主题自带右提示符,因此在修复发布前需要使用其他主题(见 issue #541)。
2.8 将 Fish 设为默认 Shell(FAQ)
若希望系统默认使用 Fish(见 docs/en-US/FAQ.md),先把 Fish 加入 /etc/shells:
echo "/usr/local/bin/fish" | sudo tee -a /etc/shells
再切换默认 Shell:
chsh -s /usr/local/bin/fish
如需切回(按需替换 /bin/bash 为 /bin/tcsh 或 /bin/zsh):
chsh -s /bin/bash
三、核心命令:omf 使用全览
Oh My Fish 附带一个小巧的实用工具 omf,用于获取和安装新的包与主题。命令分发的入口实现在 pkg/omf/functions/omf.fish:它先解析 -h/--help、-v/--version 等选项,再通过 pkg/omf/functions/core/omf.command.fish 将命令名(含别名)映射到 omf.cli.* 函数并执行。别名映射关系(从源码可见):install/get/i/in → install,list/ls/l → list,remove/rm/r/uninstall → remove,update/up/u → update,search/s → search,theme/t → theme,describe/d → describe,repositories/repo → repositories,new/n → new,channel → channel 等。
3.1 omf update [omf] [<package>...]
更新 Oh My Fish、所有包仓库以及所有已安装的包。
- 不带参数调用时:更新核心与所有已安装的包;
- 只更新核心:
omf update omf; - 选择性更新:只列出需要更新的包名,也可以把
omf一并列入以同时更新核心。
3.2 omf install [<name>|<url>|<user/repo>]
安装一个或多个包。
- 直接通过 URL 安装:
omf install URL; - 通过 GitHub 仓库安装:
omf install user/repo; - 不带参数调用时:根据 bundle 文件安装缺失的包。
3.3 omf repositories [list|add|remove]
管理用户安装的包仓库(package repositories)。包仓库是 omf install 等命令获取包的来源;默认官方仓库始终已安装并可用。
3.4 omf list
列出已安装的包。
3.5 omf theme <theme>
应用一个主题。直接输入 omf theme 可列出可用主题;安装前可先到 docs/Themes.md 预览主题效果。从 pkg/omf/functions/cli/omf.cli.theme.fish 的源码可以看出:无参数时它会读取 $OMF_CONFIG/theme 文件(不存在则回退为 default),分别以"Installed"和"Available"两组展示已装主题与索引中的可用主题;带一个参数时调用 omf.theme.set 切换主题,若主题未安装则提示先 omf install <name>。
3.6 omf remove <name>
移除一个主题或包。如果包是通过 user/repo 安装的,name 使用 repo 部分即可。
包可以使用卸载钩子(uninstall hooks),卸载时可以完成自定义资源清理,详见 docs/en-US/Packages.md。
3.7 omf reload
通过 exec 用全新 Shell 进程替换当前进程,从而重载 Oh My Fish 与所有插件。
该命令会尽量规避
exec带来的副作用,并在存在后台进程时阻止重载,做到尽可能安全。
3.8 omf new plugin | theme <name>
生成一个新的插件或主题脚手架。
该命令会在
$OMF_CONFIG/{pkg | themes}/下创建带模板的新目录。仓库内对应的模板见 pkg/omf/templates/pkg(插件)与 pkg/omf/templates/themes(主题)。
3.9 omf search -t|--theme / -p|--package <name>
在 Oh My Fish 的数据库中搜索指定的包、主题或两者。支持模糊搜索,例如不确定名字时可以直接 omf search simple。
3.10 omf channel
获取或更改更新通道(update channel)。
默认提供两个通道:stable 通道提供带有最新 tagged 版本的稳定更新;dev 通道提供正在开发中的最新变更。当前设置的通道决定 omf update 会升级到哪个版本。
3.11 omf doctor
在提交 issue 之前用来排查故障。
3.12 omf destroy
卸载 Oh My Fish。
四、进阶:启动机制与 Dotfiles
4.1 启动流程
Oh My Fish 安装器会向 fish 的用户配置文件目录(~/.config/fish/conf.d/)添加一个片段(snippet),该片段会调用 OMF 的启动代码。
注意:该目录中的脚本按文件系统看到的顺序被 source,因此可能需要给脚本文件名加数字前缀来控制顺序。例如:
a_script.fish会比omf.fish片段更早执行;如果a_script.fish依赖 OMF 管理的插件,建议把脚本改名为xx_a_script.fish;- 想让某个脚本在
omf.fish之前运行,可以给它加00_前缀; - 也可以使用
~/.config/omf/before.init.fish来达到同样目的。
每次打开新 Shell 时,启动代码会先初始化 Oh My Fish 的安装路径与配置路径(~/.config/omf,默认),随后 source init.fish 脚本,由它自动加载包、主题以及你的自定义 init 文件。FAQ 中(见 docs/en-US/FAQ.md)将其归纳为:运行 $OMF_CONFIG/before.init.fish(若存在)→ 自动加载 $OMF_PATH/ 下的已装包与主题 → 自动加载配置路径 → 自动加载 $OMF_PATH 与 $OMF_CONFIG 下的 functions 目录 → 运行 $OMF_CONFIG/init.fish(若存在)。
结合 init.fish 源码可以还原完整启动链路:
- 若未设置
OMF_CONFIG,则依据XDG_CONFIG_HOME(默认$HOME/.config)推导出OMF_CONFIG并导出为全局变量(L1-L5); - 若存在
$OMF_CONFIG/before.init.fish则先 source 它(L7-L8); - 读取当前主题:从
$OMF_CONFIG/theme读取,文件不存在则回退为default(L11-L13); - 组装核心函数路径
$OMF_PATH/lib与$OMF_PATH/lib/git、主题函数路径,插入fish_function_path实现按需自动加载(L15-L21); - 调用
require --path {$OMF_PATH,$OMF_CONFIG}/pkg/*加载所有包(L24); - 备份原有
fish_user_key_bindings并重定义之:source$OMF_CONFIG/key_bindings.fish、所有包/主题的key_bindings.fish,最后调用原始绑定(L27-L47); - 调用
require --no-bundle --path $OMF_CONFIG加载用户配置(L49); - source 当前主题的
conf.d/*.fish(L52-L55)。
4.2 Dotfiles 目录
$OMF_CONFIG 目录代表 Oh My Fish 的用户状态,非常适合加入 dotfiles 或纳入版本控制。其中有三个重要文件:
theme—— 当前主题;bundle—— 当前已安装的包/主题列表;channel—— OMF 获取更新的通道(stable / dev)。
你还可以创建并定制这些特殊文件:
init.fish—— Shell 启动后 source 的自定义脚本;before.init.fish—— Shell 启动前 source 的自定义脚本;key_bindings.fish—— 自定义按键绑定,可自由使用bind命令。
4.2.1 在 init.fish 中设置变量
init.fish 中最常见的启动命令是变量定义。这类变量通常需要在任何 Shell 会话中都可用,因此应定义为全局变量,例如:
# Golang developers might need this one
set -xg GOPATH $HOME/gocode
# Python developers otherwise
set -xg PYTHONDONTWRITEBYTECODE 1
4.2.2 关于 bundle
每当安装或移除包/主题时,bundle 文件都会被更新。你也可以手动编辑它,然后运行 omf install 使变更生效。请注意:加入 bundle 的包/主题会被自动安装,但从 bundle 中移除的包/主题不会从用户安装中删除。
4.2.3 旧版 fish 的兼容
- 在 fish 2.2 中没有
conf.d目录,启动代码必须放在 fish 配置文件(~/.config/fish/config.fish)中; - 强烈建议把自定义启动命令放进
init.fish而不是~/.config/fish/config.fish,这样可以让整个$OMF_CONFIG目录处于版本控制之下; - 如果需要启动命令在 Oh My Fish 开始加载插件之前运行,请放入
before.init.fish;如果不确定,通常放在init.fish最好。
五、创建包(Creating Packages)
Oh My Fish 使用一套完善且定义清晰的插件架构来简化插件开发,包括 init/uninstall 钩子、函数与补全的自动加载机制。完整文档见 docs/en-US/Packages.md。下面以创建一个提供 hello_world 命令的包为例。
包名只能包含小写字母和连字符(用于分隔单词)。
5.1 用脚手架生成包结构
使用 omf new 命令生成结构(主题则用 omf new theme my_theme_name):
$ omf new plugin hello_world
该命令会把当前目录切换到新创建的包中,其结构如下:
$ ls -l
README.md
init.fish
functions/hello_world.fish
completions/hello_world.fish
始终在
README.md中描述你的包是如何工作的。
建议阅读 fish 的自动补全文档,并在适用时为你的工具提供补全。
functions/hello_world.fish 定义了一个简单函数:
function hello_world -d "Prints hello world"
echo "Hello World!"
end
包中的每个函数都必须声明在 functions 目录下各自独立的文件中。这是 fish 自动加载机制的要求——它按需加载函数,避免在启动时加载未使用的函数。
命名空间注意事项:fish 没有私有作用域。如果包需要拆分多个函数,请用独特前缀(如包名 hello_world_print_help)避免命名冲突;为不污染命令命名空间,私有函数建议用双下划线前缀(如 __function_name_print_help)。
5.2 钩子(Hooks)体系
Oh My Fish 提供一套 "hooks" 系统,允许为包编写在特定事件发生时运行的脚本,可用于高级安装、自定义资源管理等。钩子就是按触发事件命名、以 init.fish/key_bindings.fish 等特定文件呈现的普通 Fish 脚本,绝大多数钩子位于包项目目录的 hooks 目录中。
启动时触发的钩子(
init.fish与key_bindings.fish)会拖慢 Shell 启动,务必避免在启动时执行慢代码;如果包不需要某个钩子文件,请删掉它。
钩子执行时的工作目录始终是包的根目录。当前支持的钩子如下:
init
Shell 首次加载时运行一次。脚本位于包的根目录 init.fish。钩子内可访问三个包相关变量:
$package:包名$path:包安装路径$dependencies:包依赖
例如 init.fish 内容为:
echo "hello_world initialized"
则首次打开终端时会在顶部看到 hello_world initialized 一行。该钩子适合修改环境、加载资源、自动加载函数等;即使包不导出任何函数,也可以用该事件为包增加功能或动态创建函数。
从 lib/require.fish 源码可以看到 init 钩子背后的加载逻辑:require 会收集 $package_path/functions*、$package_path/completions* 加入 fish_function_path/fish_complete_path(L31-L46),随后逐个 source 包的 init.fish,并注入 $path(包根目录)、$package(包名)变量,同时按 bundle 文件递归 require 依赖(L48-L80)。依赖解析由 lib/require.fish 完成:bundle 中 package <name> 形式的每一行都会被递归加载。此外 init.fish 通过 require --path {$OMF_PATH,$OMF_CONFIG}/pkg/* 完成全部已装包的自动加载。
key_bindings
包或主题需要按键绑定时,应在 key_bindings 钩子中设置。脚本位于包根目录 key_bindings.fish,可在其中自由使用 bind 命令定义自定义按键绑定。
主题同样可以定义按键绑定!切换主题时 Oh My Fish 会重新加载按键绑定。
install
包首次安装时触发。脚本位于 hooks/install.fish。钩子内可访问:
$package:包名$path:包安装路径
该钩子适合下载额外资源、设置 Git 子模块、安装 Bash 脚本等第三方依赖。
update
包被更新后触发。脚本位于 hooks/update.fish。钩子内可访问 $package 与 $path,适合更新 Git 子模块或检查第三方依赖的新版本。
uninstall
包通过 omf remove <pkg> 移除前触发。脚本位于 hooks/uninstall.fish。钩子内可访问 $package 与 $path,用于清理自定义资源等。
注:为了向后兼容,位于包根目录的
uninstall.fish也会被当作卸载钩子运行。钩子也可以通过监听{$package}_uninstall或uninstall_$package事件来触发。
5.3 公开发布你的包
公开包的官方注册表由 oh-my-fish/packages-main 仓库管理。将包加入官方包数据库的说明见该仓库的 README。
六、附:常用参考速查
| 事项 | 仓库位置 |
|---|---|
| 框架启动入口 | init.fish |
| 自动加载实现(函数/补全路径管理) | lib/autoload.fish |
| 包加载与依赖解析 | lib/require.fish |
omf 命令分发入口 |
pkg/omf/functions/omf.fish |
| 命令别名映射 | pkg/omf/functions/core/omf.command.fish |
| CLI 子命令实现 | pkg/omf/functions/cli |
| 插件/主题脚手架模板 | pkg/omf/templates/pkg、pkg/omf/templates/themes |
| 包开发完整文档 | docs/en-US/Packages.md |
| 主题画廊(可预览) | docs/Themes.md |
| FAQ(启动细节、默认 Shell 切换等) | docs/en-US/FAQ.md |
安装模板(OMF_PATH/OMF_CONFIG 变量) |
templates/config.fish |
掌握上述安装流程、omf 子命令、启动顺序与钩子体系后,你就能独立完成"装好框架 → 管理主题/插件 → 用 bundle 版本化配置 → 用钩子开发自己的包"的完整工作流;若对启动细节仍有疑问,可继续阅读 docs/en-US/FAQ.md 中关于 "What does Oh My Fish do exactly" 的说明。