本项目是一套 现代、高效、精炼、开箱即用 的 macOS 终端开发环境，所有配置集中版本控制，通过 GNU Stow 一键部署。
核心工具栈：Ghostty（终端）+ Zellij（复用器）+ Fish（Shell）+ Helix（编辑器）+ Mise（版本管理），视觉与交互风格全栈统一。
核心设计理念：
- 配置即代码：所有配置通过 Git 追踪与 Stow 符号链接管理，支持一键幂等重置。
- 终端即容器：终端仅作渲染容器（Ghostty），会话与布局调度收敛于复用器（Zellij），代码编辑则交由开箱即用的现代编辑器（Helix），彻底消除插件拼凑的心智负担。
- 环境即沙箱：终结全局变量污染与多版本管理器的混乱，依靠统一基座在一处声明全部语言沙箱（Mise）。
- 注释即文档：本项目的每一个配置文件本身就是最详尽的说明书，包含深度的中文注释、设计取舍与最佳实践指引。
Note
此 dotfiles 仅适用于 macOS，不兼容 Linux 或 Windows (WSL)，且没有跨平台适配计划。
- 0. TL;DR (快速开始)
- 1. 项目结构
- 2. 安装步骤
- 3. 配置指南
- 4. 使用方法
- 5. 常用维护命令 (Makefile)
- 6. 与官方默认的关键差异
- 7. 致谢 (Acknowledgments)
- 8. 开源协议 (License)
最简单的方法是使用一键安装脚本（Bootstrap）：
# 直接运行以下命令，会自动完成克隆仓库并执行安装脚本
bash -c "$(curl -fsSL https://raw.githubusercontent.com/windvalley/dotfiles/main/bootstrap.sh)"Note
install.sh (以及 bootstrap.sh) 支持多次执行（幂等），你可以放心地运行它来更新依赖或修复配置链接。
该脚本会自动安装 Homebrew（如果缺失）、ghostty、fish、zellij、helix、mise、stow, 并完成配置链接以及 Fish Shell 的初始化。
Tip
如果你想手动精准控制安装过程，请参考下面的详细步骤。
本仓库包含以下配置包及核心文件：
ghostty/: Ghostty（/ˈɡoʊs.ti/，Ghost + ty）终端配置fish/: Fish（/fɪʃ/，Friendly Interactive SHell）shell 配置zellij/: Zellij（/ˈzɛl.ɪdʒ/，源自阿拉伯语，马赛克瓷砖拼贴艺术）终端复用器，易于配置helix/: Helix（/ˈhiː.lɪks/，螺旋）现代模态编辑器，开箱即用karabiner/: Karabiner（/ˌkær.əˈbiː.nər/，德语，登山扣）键盘映射（交换 Caps Lock 和 Left Control）git/: Git 基础配置（别名、Delta 美化、全局忽略等）mise/: Mise（/miːz/，源自法语 mise en place，就位准备）工具版本管理器配置btop/: btop 现代系统资源监控工具配置bin/: 自定义命令脚本（自动链接到~/.local/bin）local/: 本地环境私有配置模板（用于环境变量脱敏及git多账号隔离）Makefile: 自动化构建与维护脚本.editorconfig: 跨编辑器格式化标准。内置了严格的格式控制（例如缩进模式、行尾序列 LF 强制设定、文件末空行保护等），确保项目源码整洁、消除跨平台和跨编辑器带来的格式问题。
仓库根目录下提供了一个 install.sh 脚本，可以自动化完成绝大部分安装和配置工作。
该脚本将执行以下操作：
- 环境准备：检查并自动安装 Homebrew（如果尚未安装）。
- 核心依赖：读取
Brewfile，安装所有 CLI 工具（stow, zellij, fish, helix, mise, bat, eza, fzf, ripgrep 等）与 GUI 应用（Ghostty, OrbStack, JetBrains Mono 字体等）。 - 字体安装：默认已通过 Brew 安装 JetBrains Mono，并询问是否安装其他扩展字体（Maple Mono, Geist Mono）。
- 软链配置：自动识别已存在的配置并备份，然后使用
stow将所有配置（含bin脚本）软链到对应的系统目录。 - 隐私配置模板：自动在用户目录创建 Git 信息模板（
.gitconfig.local/.work）和私密环境变量模板（config.local.fish）。 - Shell 初始化：将 Fish 设为默认 Shell，并自动迁移原 Zsh 的 PATH 环境变量到 Fish 中。
- 插件配置：安装 Fisher 插件管理器并同步所有 Fish 插件。
- 系统优化：提示是否应用 macOS 常用系统偏好设置（通过
macos.sh）。
使用方法：
cd "$HOME/dotfiles"
./install.shTip
非交互模式：如果在自动化环境（如 CI/CD 等）中执行，可追加 -y 或 --unattended 标志跳过所有确认自动安装：./install.sh -y
安装过程说明：
- 如果系统未安装 Homebrew，脚本默认会询问是否安装
- 如需手动安装 Homebrew，请访问 https://brew.sh
- 脚本会自动检测并迁移 zsh 的 PATH 设置到 fish
如果你更倾向于手动操作，请按以下顺序执行：
# 软链管理工具
brew install stow
# 终端
brew install --cask ghostty@tip
# 多窗口管理
brew install zellij
# 交互 Shell
brew install fish
# 文本编辑器(替代 vim/neovim)
brew install helix
# 软件版本管理工具
brew install mise
# Git 美化工具 (Diff 语法高亮)
brew install git-delta
# 现代、跨平台的系统资源监控工具
brew install btop
# 字体
brew install --cask font-jetbrains-mono-nerd-font
# 常用工具
brew install bat eza fzf zoxide grc gawk gnu-sed grep glow
# 音量控制
brew install switchaudio-osx说明：
zoxide: 智能目录跳转工具，替代传统的cd。用法：z <关键词>跳转目录，zi <关键词>交互式选择（需 fzf）。gnu-sed: 提供gsed，用于colorscheme/font-size/opacity等脚本。switchaudio-osx: 提供SwitchAudioSource，用于audio-volume。grc: 通用彩色输出查看器 (Generic Colouriser)，配合 fish 插件为ping/ls/docker/diff等命令提供彩色输出增强。glow: 终端 Markdown 阅读器，用于 Helix 预览功能。
git clone --depth=1 https://github.com/windvalley/dotfiles.git "$HOME/dotfiles"
# 更新
cd "$HOME/dotfiles"
git pull --rebaseTip
如果你的系统已安装 make，可以运行 make stow 一键链接，该命令及 install.sh 脚本均已内置了完善的目录保护机制，推荐直接使用，不用手动折腾。
如果坚持手动链接配置，为了确保 stow 能为 GUI 应用（如 Btop、Karabiner）以及扩展性强的工具创建纯净的目录级软链，需要对所有目标配置目录进行防御性清理：
# 如果目标工具的配置目录已经是真实目录（非软链），必须将其重命名或删除，切忌保留！
# 目的：确保 stow 时发现目标目录"不存在"，从而直接把整个目录映射为一个【纯目录级软链】。
# 否则 stow 会进入真实目录执行【文件级】软链，导致后续工具在本地新生成的文件脱离版本控制。
for pkg in ghostty helix zellij mise karabiner btop fish git; do
if [ -d ~/.config/$pkg ] && [ ! -L ~/.config/$pkg ]; then
mv ~/.config/$pkg ~/.config/$pkg.bak
elif [ -L ~/.config/$pkg ]; then
unlink ~/.config/$pkg
fi
done然后执行统一链接映射：
cd "$HOME/dotfiles"
# 统一链接所有标准配置包（全部遵循 XDG 规范，映射到 ~/.config/ 下）
stow --restow --target="$HOME" --dir="$HOME/dotfiles" --dotfiles ghostty helix zellij mise karabiner btop fish git
# 单独链接需要特定前置结构的包（例如将自定义命令放置在 ~/.local/bin 下）
mkdir -p "$HOME/.local/bin"
stow --restow --target="$HOME/.local/bin" --dir="$HOME/dotfiles" bin将 fish 设为默认 shell：
which fish | sudo tee -a /etc/shells
chsh -s $(which fish)重启终端后（或执行 exec fish -l），在 fish 里执行：
# 检查是否已经切换成功
echo $SHELL
# 让 fish 识别 Homebrew 安装的程序
fish_add_path (brew --prefix)/bin
# 生成命令补全（自动从 man 页面解析）
fish_update_completions
# 主题（只影响语法高亮，不影响 prompt；prompt 由 tide 控制）
fish_config theme choose draculaImportant
从 zsh 切换到 fish 后，zsh 配置文件（~/.zshrc、~/.zprofile 等）中的 PATH 不会自动继承，可能导致已安装软件的命令找不到。
自动迁移（推荐）：install.sh 会自动检测 zsh 的 PATH 并将缺失的路径添加到 fish，无需手动操作。
手动迁移：如需手动添加路径，使用 fish_add_path：
fish_add_path ~/.cargo/bin
fish_add_path ~/.local/binTip
fish_add_path 是持久化的（写入 universal 变量），只需执行一次，重启后仍然生效。
可用 printf '%s\n' $PATH 查看当前所有路径。
在实际使用中，我们经常需要配置一些仅属于当前机器或包含敏感信息的环境变量（例如 OPENAI_API_KEY、公司内网代理、特定机器别名等）。
为了防止这些信息被 Git 追踪并泄露到公开仓库中，本 dotfiles 已预设了本地分离机制：
- 将本仓库中的示例模板复制到对应目录并去除
.example后缀：cp ~/dotfiles/local/config.local.fish.example ~/.config/fish/config.local.fish - 将你所有的私密配置写入新生成的文件：
# ~/.config/fish/config.local.fish set -gx AI_CMD "opencode run" # 配置全局 AI 命令，供 aic 等辅助工具使用 set -gx OPENAI_API_KEY "sk-xxxxxxxxx" abbr -a -g work-vpn "sudo launchctl restart com.corp.vpn"
Note
config.local.fish 以及 *.local 均已被 .gitignore 忽略，你可以安全地在本地使用它们，不用担心通过 stow 软链后被意外 git push 给共享出去。
fisher 是 fish 的插件管理器。
通过在 config.fish 中设置 fisher_path，所有插件相关的文件会被彻底隔离在 ~/.local/share/fisher 下，避免污染 ~/.config/fish 目录。
# ⚠️ 重要：安装前先清理 fisher_path 目录，避免残留数据导致安装冲突
rm -rf ~/.local/share/fisher
# 安装 Fisher
curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source && fisher install jorgebucaran/fisher
# 安装插件 (将从 dotfiles 配置列表中同步安装)
fisher install (cat ~/.config/fish/fish_plugins)更多见：fish/dot-config/fish/README.md
tide 是 fish 的 prompt 插件。
# 一键自动化配置
tide configure --auto \
--style=Lean \
--prompt_colors='16 colors' \
--show_time='24-hour format' \
--lean_prompt_height='Two lines' \
--prompt_connection=Disconnected \
--prompt_spacing=Compact \
--icons='Many icons' \
--transient=Yes
# 或者交互式按照个人喜好配置
tide configure根目录下提供了 macos.sh 脚本，利用 defaults write 一键配置符合开发者习惯的深层系统偏好：
- 键盘体验：设置极速的键盘重复率（KeyRepeat），禁用长按显示特殊字符。
- 访达 (Finder)：显示所有文件扩展名、状态栏、路径栏，按名称排序时文件夹置顶，禁用
.DS_Store在网络/USB驱动器上的生成。 - 触控板/鼠标：开启“轻点来点按”。
- 程序坞 (Dock)：开启自动隐藏，不显示最近使用的应用程序。
- Safari：开启“开发”菜单和网页检查器。
你可以随时通过运行以下命令来应用或重新应用这些设置：
make macos
# 或者 ./macos.shWarning
该脚本在执行前可能会要求输入管理员密码（sudo -v），且包含了高度个人主观偏好的系统设定。
强烈建议你在执行前，先打开 macos.sh 快速浏览一遍带有详细中文解释的源码。你可以轻松地注释掉任何与你习惯不符的 defaults write 命令。
1. 配置用户信息及多账号分离 (Local Overrides)
为了防止工作邮箱和个人邮箱混用，或意外泄露身份信息，本仓库的 ~/.config/git/config 中移除了硬编码的用户信息，采用基于 include 特性的分离机制。
设置个人全局身份（必须）： 在你的 Home 目录创建被 Git 忽略的本地配置文件（可以将模板直接复制过去修改）：
cp ~/dotfiles/local/dot-gitconfig.local.example ~/.gitconfig.local
# 然后编辑 ~/.gitconfig.local，填入你的个人信息设置公司工作隔离身份（可选）：
如果你在某台电脑上需要同时处理公司代码，假设你的工作目录全在 ~/work/ 及其子目录下，复制模板作为专属的工作配置：
cp ~/dotfiles/local/dot-gitconfig.work.example ~/.gitconfig.work
# 然后编辑 ~/.gitconfig.work，填入你的公司邮箱只要你在这个目录进行 git commit，Git 会利用配置中的 includeIf "gitdir:~/work/" 条件自动切换到你的公司邮箱，彻底杜绝身份错误。
2. 自定义全局忽略文件
仓库中已包含通用的 ~/.config/git/ignore（Git XDG 标准位置，自动发现）。如果你有特定的文件需要全局忽略（例如 IDE 配置、临时文件等），可以直接编辑该文件：
# 添加自定义忽略规则 (例如忽略所有 .log 文件)
echo "*.log" >> ~/.config/git/ignoreTip
上述修改会直接更新 ~/dotfiles/git/dot-config/git/ignore，建议将这些变更提交到你自己的 dotfiles 仓库中。
配置文件：~/.config/ghostty/config
注意：标签页功能已禁用（由 Zellij 统一管理），多窗口功能仍可用。
快捷键：
| 快捷键 | 功能 |
|---|---|
Cmd + Shift + , |
重载配置（修改配置文件后按此快捷键生效） |
Cmd + ; |
打开 Quick Terminal（自定义快捷键） |
Note
建议使用 Zellij 的标签页和面板功能替代 Ghostty 原生标签页和分屏功能，以获得更灵活的布局控制和跨会话保持能力。
配置文件：~/.config/zellij/config.kdl
自动启动：本配置在 fish 中集成了 Zellij 自动启动逻辑，打开新终端窗口时会自动启动或挂载到 Zellij 会话。以下情况会自动跳过：
- 已在 Zellij 会话中
- 通过 SSH 连接
- 在 Ghostty 的 Quick Terminal 中
- 设置了环境变量
ZELLIJ_AUTO_DISABLE zellij setup --check配置预检失败时（自动 fallback 到纯 fish 并提示修复方法）
Tip
如果 Zellij 出现问题导致终端无法正常打开，可在其他终端中执行 set -Ux ZELLIJ_AUTO_DISABLE 1 永久禁用自动启动。
模式系统：Zellij 有多个模式，按 Ctrl + p/t/n/h/s/o/a 直接进入对应模式，按 Ctrl + g 进入锁定模式（禁用所有快捷键）。
常用快捷键：
| 快捷键 | 功能 |
|---|---|
Ctrl + g |
进入/退出锁定模式（禁用所有快捷键） |
Ctrl + p |
进入面板模式 |
Ctrl + t |
进入标签页模式 |
Ctrl + n |
进入调整大小模式 |
Ctrl + h |
进入移动模式 |
Ctrl + s |
进入滚动模式 |
Ctrl + o |
进入会话管理模式 |
Ctrl + a |
进入 TMUX 兼容模式 |
面板模式 (Ctrl + p)：
| 快捷键 | 功能 |
|---|---|
h/j/k/l |
Vim 风格切换面板 |
d |
向下拆分面板 |
r |
向右拆分面板 |
n |
新建面板 |
x |
关闭当前面板 |
f |
全屏/退出全屏 |
标签页模式 (Ctrl + t)：
| 快捷键 | 功能 |
|---|---|
n |
新建标签页 |
x |
关闭当前标签页 |
1-9 |
切换到指定标签页 |
h/k |
前一个标签页 |
l/j |
后一个标签页 |
调整大小模式 (Ctrl + n)：
| 快捷键 | 功能 |
|---|---|
h/j/k/l |
增大对应方向的面板大小 |
H/J/K/L |
缩小对应方向的面板大小 |
+/- |
等比放大/缩小 |
全局快捷键（无需进入模式）：
| 快捷键 | 功能 |
|---|---|
Cmd + 1-9 |
切换到指定标签页 |
布局：
- 默认布局：
dev-workspace - 布局定义位置：
~/.config/zellij/layouts/dev-workspace.kdl - 修改布局：编辑上述文件，定义自己的分屏和标签页结构
- 手动加载布局：
zellij --layout <布局名>
配置文件：~/.config/fish/config.fish
Fish 常用命令：
| 命令 | 功能 |
|---|---|
fish_update_completions |
更新命令补全 |
fish_add_path <path> |
添加路径 |
fish_config |
打开交互配置 |
自定义函数（输入 c 可列出所有命令及说明）：
| 命令 | 功能 |
|---|---|
d |
快速显示当前日期时间 |
nh <cmd> |
后台运行命令，丢弃输出 (nohup 简写) |
ch <cmd> |
查询 cheat.sh 快速获取命令帮助 |
wt [city] |
查询 3 日简易天气预报 (支持指定城市) |
lunar [date] |
万年历，查询公历+农历+生肖+干支 (支持指定日期如 2025-01-29) |
myip |
获取本机局域网 IP、公网 IP 及地理位置 |
port <num> |
查看本地特定端口的 TCP/UDP 监听状态及进程情况 |
ports |
查看本机所有正在监听的 TCP 端口及进程列表 |
extract <file> |
万能解压缩工具，自动识别压缩包格式（zip, tar, gz, rar, 7z...）并解压 |
mkcd <dir> |
创建目录并使用 cd 直接跳转进入 |
proxy / unproxy |
一键开启/关闭终端全局网络代理 (用于解决代码拉取缓慢) |
gitignore <语言> |
从 GitHub 模板快速输出标准项目 .gitignore 内容 (例: gitignore Node) |
backup <file/dir> |
为敏感文件或目录极速创建带有精确时间戳的完整备份副本 |
copy [file] |
将文件内容或前一个命令的标准输出(| copy)极速复制到 Mac 剪贴板 |
f [query] |
搜索文件并使用 Helix 打开。若关键字匹配唯一结果则直接打开 |
aic |
根据代码变更自动生成 Git 提交信息。支持中英交互切换、Prompt 微调及重写功能 |
ait |
自动根据 Git 变更历史生成 Changelog 并提交打 Tag。支持中英交互切换、Prompt 微调及重写功能 |
b [query] |
搜索文件并使用 bat 查看。若关键字匹配唯一结果则直接打开 |
rec [name] |
极简终端操作录屏工具 (基于 asciinema)，支持录制、回放(rec play)与网页分享(rec upload) |
gtd <tag> |
一键同时删除本地和远端的 Git Tag |
Tip
更多自定义命令（如 colorscheme、font-size、opacity 等）见 4.8 自定义命令（bin/）。
内置缩写 (Abbreviations)：
缩写在输入后按空格时自动展开为完整命令。
| 缩写 | 展开为 |
|---|---|
mkdir |
mkdir -p |
ls |
eza |
ll |
eza -l |
... |
../.. (以此类推 ...., .....) |
vi / vim / h |
hx |
cs / fs / o / vol |
colorscheme / font-size / opacity / audio-volume |
g |
git |
ga / gs / gd / gds |
git add / git status / git diff / git diff --staged |
gc / gca |
git commit / git commit --amend |
gp / gl / gco |
git push / git pull / git checkout |
gr / grs |
git restore / git restore --staged |
gg |
git log |
Vi 模式： Fish 支持 Vi 风格编辑模式，本配置已默认启用。
| 快捷键 | 功能 |
|---|---|
Esc |
进入 Vi 普通模式 |
i/a |
进入插入模式 (光标前/光标后) |
h/l |
光标左/右移动 |
k/j |
上一条/下一条命令历史（基于输入过滤） |
w/b |
下一个/上一个单词 |
0/$ |
行首/行尾 |
d |
删除 (配合移动命令，如 dw, dd) |
y |
复制 (配合移动命令，如 yw, yy) |
p |
粘贴 |
u |
撤销 |
Ctrl+e |
在普通模式/插入模式下，使用当前默认编辑器 (hx) 全屏编辑当前命令行 |
在 Vi 普通模式下可以使用所有 Vim 风格的编辑命令。
配置文件：~/.config/helix/config.toml
新手指南：Helix 快速上手指南 (Neovim 用户版)
模式：Normal（正常）、Insert（插入）、Select（选择）
核心快捷键：
| 快捷键 | 功能 |
|---|---|
i |
进入插入模式 |
Esc |
返回正常模式 |
v |
进入/退出选择模式 |
h/j/k/l |
左/下/上/右 |
w/b |
下一个/上一个单词 |
gg/ge |
文件开头/结尾 |
x |
选中当前行 |
y/p |
复制/粘贴 |
u/U |
撤销/重做 |
/ |
搜索 |
n/N |
下一个/上一个匹配 |
:w |
保存 |
:q |
退出 |
:wq |
保存并退出 |
LSP 功能：
| 快捷键 | 功能 |
|---|---|
gd |
跳转到定义 |
gy |
跳转到类型定义 |
gr |
查看引用 |
gi |
跳转到实现 |
Space+k |
显示悬浮文档 |
Space+a |
代码操作 |
Space+r |
重命名符号 |
Space+s |
文档符号列表 |
Space+S |
工作区符号列表 |
Space+d |
显示诊断信息 |
]d / [d |
跳转到下/上一个诊断 |
Space+m |
Markdown 预览 (Glow) |
LSP 配置：
- 语言配置：
~/.config/helix/languages.toml - 检查健康状态：
hx --health或hx --health go - 安装 LSP：
本项目采用
mise集中管理所有语言服务器，详情请参考 4.5 Mise 工具版本管理。 - 重启 LSP：
:lsp-restart - 查看文档：
:config-open打开配置，:config-reload重载
核心理念：
摒弃传统通过 npm i -g, pip install, go install 全局滥装工具导致的系统污染和版本冲突。
本配置将所有的运行时框架（Node/Python/Go）和语言服务器（LSP）全部统一收敛交由 mise 管理，实现两层优雅隔离：
- 全局防灾保底：全局配置 (
~/.config/mise/config.toml) 中声明了各大语言最新版本 (@latest) 的 LSP 工具链，保证了在任何普通目录打开编辑器都有充足的补全提示能力。 - 纯净的项目级沙盒：进入特定项目时，使用
mise use可生成只对当前目录生效的.mise.toml进行精准隔离。- 关于 Runtime（运行环境）：强烈建议锁定具体版本（如
node@16）以保证团队构建一致性。 - 关于 LSP（语言服务器）：通常建议在项目中也使用
@latest获取最新的代码高亮、提示和性能优化；仅当最新版 LSP 与古董级老项目出现不兼容时，才妥协锁定 LSP 的旧版本。
- 关于 Runtime（运行环境）：强烈建议锁定具体版本（如
配置文件：~/.config/mise/config.toml
Note
关于特殊 LSP 的说明：
部分底层工具由于平台依赖较强或构建极其复杂（如 rust-analyzer 和 clangd），本配置未通过 mise 管理，仍建议通过 brew 安装以获得最佳稳定性和补全体验：
- Rust:
brew install rust-analyzer - C/C++:
brew install llvm(包含clangd)
常用命令：
| 命令 | 功能 |
|---|---|
mise install |
根据当前目录 .mise.toml 或全局配置安装所有缺失工具 |
mise ls |
列出当前生效及已安装的工具版本 |
mise ls-remote <tool> |
查看该工具可配置的所有远程版本 |
mise use <tool>@<version> |
在当前项目生成 .mise.toml 并使用特定版本 |
mise use -g <tool>@<version> |
修改全局默认版本 |
mise current <tool> |
查看当前环境实际激活的版本来源（本地/全局） |
mise prune |
释放磁盘，清理不再使用的旧版本缓存 |
mise doctor |
环境变量诊断，排查不生效的原因 |
实战示例：
# 查询可用版本并安装
mise ls-remote go
mise use -g go@latest
# 项目内实战最佳实践：锁定特定版 Runtime + 最新版 LSP
cd my-old-project
mise use node@16
mise use npm:@vtsls/language-server@latest
# 极端情况：由于项目太老，最新的 LSP 解析报错，被迫降级锁定特定版 LSP
cd my-ancient-project
mise use npm:@vtsls/language-server@1.0.0Git 初始配置（用户信息、多账号隔离等）请参见 3.7 配置 Git。
配置文件：
~/.config/git/config: 核心配置（XDG 标准位置）~/.config/git/ignore: 全局忽略文件（XDG 标准位置）
核心特性：
- Delta 集成：使用
git-delta进行 Diff 语法高亮，支持行号、并排显示和颜色优化；syntax-theme由colorscheme脚本统一管理。 - 智能默认值：
pull.rebase = true: 保持提交历史线性整洁。push.autoSetupRemote = true: 自动关联远程分支。init.defaultBranch = main: 默认分支名为 main。rerere.enabled = true: 自动记忆冲突解决方案，提升 rebase 体验。
常用别名：
| 别名 | 命令 | 说明 |
|---|---|---|
git lg |
log --graph ... |
显示漂亮的提交图谱（精简版） |
git lga |
log --graph ... |
显示漂亮的提交图谱（详细版，含时间） |
git last |
log -1 HEAD |
查看最后一次提交 |
git cleanup |
... |
清理已合并的本地分支 |
# 安装或重新安装
#
# -nv 模拟安装（查看会做什么，但不实际执行）;
# --restow 重新安装（即重新创建符号链接，先删除再创建）;
# --target 指定符号链接目标目录;
# --dir 指定 dotfiles 源文件目录;
# --dotfiles 将 dot- 开头的包名转换为 . 开头的隐藏文件
#
# 示例：
stow -nv --restow --target=$HOME --dir=$HOME/dotfiles --dotfiles ghostty
# 卸载
stow -nv --delete --target=$HOME --dir=$HOME/dotfiles --dotfiles ghostty这些命令会在 stow bin 后出现在 ~/.local/bin：
colorscheme [name]: 同步切换 Ghostty、Helix、Zellij、Btop、Bat 和 Delta 主题。无参数时显示当前主题和可用主题列表，内置 8 个预设（dracula / tokyonight / gruvbox / kanagawa / nord / solarized-dark / one-dark / everforest），也支持直接传入工具原生主题名。配合 Git Clean Filter，切换主题不会导致仓库变脏。dot-theme-filter: Git 内部过滤器（非直接执行）。配合.gitattributes使用，在git add时自动将主题配置还原为默认值，实现配置文件的“逻辑解耦”。font-size <1-200>: 设置 Ghostty 字体大小opacity <0.0-1.0>: 设置 Ghostty 背景透明度audio-volume: 音量控制与输出设备切换（需要switchaudio-osx）preview-md <file>: 在 Zellij 浮动窗口中预览 Markdown 文件（需要glow）colors-print: 打印终端 256 色板print-256-hex-colors: 打印 256 色的十六进制色值validate-configs [tool|all]: 验证配置文件语法和完整性（支持 fish/git/zellij/helix/mise/ghostty/karabiner）dot-update: 一键聚合更新所有核心依赖包（包含 Homebrew, Mise 工具链, Fisher 插件, 以及 Helix Tree-sitter 语法库）
Tip
变更生效方式：
colorscheme：Zellij 实时生效；Ghostty 需按Cmd + Shift + ,重载配置；Helix 需执行:config-reload使已打开的 buffer 生效；Btop、Bat 与 Delta 下次执行命令时生效。注：Bat 与 Delta 不支持 tokyonight / kanagawa / one-dark / everforest，切换到这些主题时会自动跳过。font-size/opacity：修改的是 Ghostty 配置文件，需按Cmd + Shift + ,重载配置后生效。
本项目引入了 Makefile 来标准化日常维护任务，集成了安装、同步、验证和清理等操作。
| 命令 | 说明 |
|---|---|
make help |
显示帮助菜单（默认） |
make install |
运行 install.sh 安装脚本 |
make stow |
建立所有配置文件的软链接 |
make unstow |
删除所有软链接（卸载配置） |
make restow |
修复/重建所有软链接 |
make stow-<package> |
仅同步指定包 (如 make stow-fish, make stow-ghostty) |
make fish |
将 Fish 设置为默认 Shell |
make plugins |
更新 Fisher 插件 |
make macos |
配置 macOS 系统偏好设置 |
make validate |
运行完整的配置验证（包含工具检查） |
make lint |
静态分析 bin/ 脚本（shellcheck） |
make docs |
生成或更新 README 的目录 (TOC) |
make update |
拉取远程代码并更新所有核心工具链体系 (dot-update) |
make clean |
清理临时文件 (.bak, .tmp 等) |
本项目对各工具的默认配置做了若干有意识的定制。以下是所有偏离官方默认值的关键改动，帮助你快速了解本 dotfiles 的"个性化"部分。
| 改动 | 官方默认 | 本项目 | 原因 |
|---|---|---|---|
| Caps Lock ↔ Left Control 互换 | 保持原位置 | 交换位置（已排除 HHKB 键位的键盘） | Caps Lock 位置更适合高频的 Ctrl 操作（Emacs/Zellij/Helix/Vim 等均重度依赖 Ctrl） |
键位变更：
| 改动 | 官方默认 | 本项目 | 原因 |
|---|---|---|---|
Cmd + ; → Quick Terminal |
无绑定 | global:cmd+;=toggle_quick_terminal |
全局一键唤出/隐藏终端 |
Cmd + 1~9 |
切换 Ghostty 标签页 | unbind（解绑） |
让出给 Zellij 管理标签页切换 |
| 选中即复制 | copy-on-select = true |
copy-on-select = clipboard |
同时复制到主选区和系统剪贴板 |
行为变更：
| 改动 | 官方默认 | 本项目 | 原因 |
|---|---|---|---|
| 窗口状态恢复 | default |
window-save-state = never |
避免与 Zellij 会话恢复冲突 |
| 打字时隐藏鼠标 | false |
mouse-hide-while-typing = true |
减少视觉干扰 |
| 背景模糊 | false |
background-blur = 25 |
半透明时的毛玻璃效果 |
| 未聚焦分屏不透明度 | 0.7 |
unfocused-split-opacity = 0.3 |
更明显区分聚焦/非聚焦面板 |
| 环境变量 | 无 | env = GHOSTTY_RUNTIME=1 |
供 Fish 判断是否在 Ghostty 中运行 |
架构变更：
| 改动 | 官方默认 | 本项目 | 原因 |
|---|---|---|---|
| 快捷键体系 | 内置默认快捷键 | keybinds clear-defaults=true 全部重建 |
精简并统一 Vim 风格导航，移除未使用的绑定 |
| 默认布局 | default |
default_layout "dev-workspace" |
使用自定义的开发工作区布局 |
| 会话名 | 随机生成 | session_name "main" |
固定会话名，方便 attach |
| 自动附加 | false |
attach_to_session true |
打开新终端自动连接已有会话 |
| 主题 | default |
theme "dracula-pro" |
自定义 Dracula 变体，修复文本选中色的兼容问题 |
键位增强：
| 改动 | 说明 |
|---|---|
Cmd + 1~9 全局切换标签页 |
无需进入 tab 模式，配合 Ghostty 的 unbind 实现 |
所有模式添加 h/j/k/l 导航 |
面板/标签页/调整大小/移动/滚动均支持 Vim 风格 |
Ctrl + a 进入 tmux 兼容模式 |
为 tmux 用户提供肌肉记忆兼容层 |
行为变更：
| 改动 | 官方默认 | 本项目 | 原因 |
|---|---|---|---|
| 欢迎语 | 显示版本信息 | fish_greeting "" (关闭) |
保持终端启动干净 |
| 编辑模式 | Emacs 模式 | Vi 混合模式 (Vi + Emacs insert) | Vi 键位为主，保留 Ctrl-a/e 等 Emacs 快捷键 |
| 默认编辑器 | 无 | EDITOR=hx / VISUAL=hx |
统一使用 Helix |
| 分页器 | 无 | MANPAGER 使用 bat 语法高亮 |
Man 手册页更易读 |
| Homebrew 自动更新 | 启用 | HOMEBREW_NO_AUTO_UPDATE=1 |
避免每次安装包时卡在更新 |
| Fisher 插件路径 | ~/.config/fish |
~/.local/share/fisher |
隔离第三方插件，保持配置目录纯净 |
| Zellij 自动启动 | 不自动启动 | 在 Ghostty 中自动启动 | 无需手动 zellij，同时排除 SSH/Quick Terminal 等场景 |
键位变更：
| 改动 | 说明 |
|---|---|
Ctrl + e (normal 模式) |
用 Helix 全屏编辑当前命令行 |
| Vi 光标形状 | normal=block, insert=line, replace=underscore |
| Tide vi_mode 标识 | D → N（对齐 Vim 社区的 Normal 缩写习惯） |
键位变更：
| 改动 | 官方默认 | 本项目 | 原因 |
|---|---|---|---|
Ctrl + r |
无绑定 | :reload 重载当前文件 |
快速重载被外部修改的文件 |
Ctrl + ; |
无绑定 | repeat_last_motion |
重复上次 f/t 跳转（类似 Vim 的 ;） |
Space + m |
无绑定 | 使用 glow 预览 Markdown | 在浮动窗口中渲染 Markdown |
Space + o/i |
无绑定 | expand_selection / shrink_selection |
替代 Alt-o/i，避免 Alt 键冲突 |
插入模式 Ctrl + f/b/n/p/a/e |
无绑定 | Emacs 风格光标移动 | 无需退出插入模式即可快速移动光标 |
j / k |
按视觉行移动 | 按物理行移动 (move_line_down/up) |
配合软折行和行号跳转，避免 6j 跳转到错误位置 |
gj / gk |
按物理行移动 | 按视觉行移动 (move_visual_line_down/up) |
需要逐视觉行移动时使用 |
显示变更：
| 改动 | 官方默认 | 本项目 | 原因 |
|---|---|---|---|
| 行号 | 绝对行号 | line-number = "relative" |
配合 Vim 动作快速跳转 |
| 光标行/列高亮 | 均关闭 | cursorline = true / cursorcolumn = true |
快速定位光标位置 |
| 标签栏 | never |
bufferline = "multiple" |
多文件时显示缓冲区标签 |
| 色彩模式指示器 | false |
color-modes = true |
不同模式不同颜色 |
| Inlay hints | false |
display-inlay-hints = true |
显示类型提示等内联信息 |
| 行尾诊断 | disable |
end-of-line-diagnostics = "warning" |
行尾直接显示警告 |
| 内联诊断 | disable |
cursor-line = "warning" / other-lines = "warning" |
所有行内联显示诊断 |
| 保存时清理 | 均关闭 | trim-final-newlines / trim-trailing-whitespace = true |
保持文件整洁 |
| 软换行 | 关闭 | soft-wrap.enable = true |
长行自动换行 |
| 改动 | 官方默认 | 本项目 | 原因 |
|---|---|---|---|
| 默认编辑器 | vim |
core.editor = hx |
统一使用 Helix |
| 分页器 | less |
core.pager = delta |
Diff 语法高亮 |
| Pull 策略 | merge |
pull.rebase = true |
保持提交历史线性 |
| Push 行为 | 需手动设置上游 | push.autoSetupRemote = true |
省去 --set-upstream |
| 冲突风格 | merge |
merge.conflictstyle = diff3 |
同时显示 base/ours/theirs 三方 |
| 分支名 | master |
init.defaultBranch = main |
现代社区规范 |
| 重用冲突解决 | 关闭 | rerere.enabled = true |
自动记忆冲突解决方案 |
| 用户信息 | 硬编码在配置中 | 通过 include 引入本地文件 |
防止敏感信息入库 |
| 主题解耦 | 切换配色会导致仓库变脏 | 使用 Git Clean Filter 自动处理 | 确保 local 配色变更不产生 unstaged changes |
本项目的诞生离不开现代开源社区的繁荣生态，特别感谢以下卓越的项目构建了这套工作流的基石：
- Ghostty
- Zellij
- Fish / Fisher / Tide
- Helix
- Mise
- fzf / zoxide / eza / bat
- ripgrep / grc / GNU Coreutils / shellcheck
- git-delta / glow / btop / asciinema
- JetBrains Mono / Maple Mono / Geist Mono / Nerd Fonts
- Karabiner-Elements / switchaudio-osx
- GNU Stow
本项目采用 MIT License 开源协议。
你可以自由地使用、学习、修改和分发本项目的代码，将其作为你打造个人专属工作流的起点。