Dotfiles

简洁、偏现代 CLI 工作流的个人开发环境配置，当前覆盖 zsh、starship、ghostty、Pi，以及 coding agent 全局规则。

用法模型

方向	命令	作用
仓库 → 本机	./install.sh	把仓库里的托管配置复制到本机；装完后本机文件与仓库解耦
本机 → 仓库	./sync-from-local.sh	在确认后，把本机托管配置写回仓库；不自动 git add / commit / push

要点：

• 使用真实文件副本，不依赖长期软链。日常改本机配置不会改动仓库。
• 两个脚本都按程序整组决策：一组内全部保留或全部替换，避免半套新旧配置混用。
• 默认答案是 N（不覆盖）。

Features

• zsh 使用 antidote 管理插件，集成 zoxide、eza、bat、ripgrep、fd 和 neovim。
• starship 只保留目录、Git 分支、Git 状态和命令提示符。
• ghostty 使用 JetBrains Mono Nerd Font Mono 和适合高频开发的基础终端设置。
• 配置在仓库与本机之间以真实文件副本传递，不依赖长期软链。

Managed configuration

程序	仓库路径	本机路径
Starship	starship/starship.toml	~/.config/starship.toml
Zsh	zsh/.zshrc、zsh/.zsh_plugins.txt	~/.zshrc、~/.zsh_plugins.txt
Ghostty	ghostty/config	~/.config/ghostty/config
Pi	pi/settings.json、pi/web-search.json、pi/extensions/statusline/	~/.pi/agent/settings.json、~/.pi/web-search.json、~/.pi/agent/extensions/statusline/
Agent rules	agent-rules/AGENTS.global.md（单文件）	~/.pi/agent/AGENTS.md、~/.grok/AGENTS.md、~/.codex/AGENTS.md、~/.claude/CLAUDE.md

Agent rules 是独立配置组（与 Pi 设置分开）：

• 安装：四个本机路径与仓库比较；任一路径缺失、内容不同、软链冲突或类型不匹配 → 整组需一次确认；选 y 则四个路径全部写成仓库副本。
• 回写：先要求四个本机规则内容一致且可信；一致后与仓库比较，最多询问并写入一次。

Agent 规则只保存跨项目个人习惯，不包含具体仓库结构。Pi 的 auth.json、sessions/、npm/、trust.json 等认证和运行数据不受管理。

zsh/.zsh_plugins.zsh 是 antidote 生成的插件加载文件，不会安装或反向同步。

Neovim

Brewfile 负责安装 Neovim；配置继续由独立的 specode/nvim-config 仓库管理。本仓库不会复制、同步或改动 ~/.config/nvim。

Requirements

• macOS
• Homebrew
• rsync（macOS 自带，用于精确复制目录）

Brewfile 包含 starship、antidote、eza、bat、zoxide、fd、ripgrep、neovim 和 JetBrains Mono Nerd Font。

Installation（首次安装）

git clone git@github.com:specode/dotfiles.git ~/Code/dotfiles
cd ~/Code/dotfiles
./install.sh

install.sh 会先只读比较全部托管路径，并按程序展示结果。决策单位始终是整个程序（该程序下全部托管路径一起保留或一起替换）。

状态处理：

• 可自动安装：该程序本机没有冲突（路径缺失，或仅有旧版指向本仓库的正确软链）时，整组直接复制，无需确认。
• 需确认覆盖：该程序任一托管路径内容不同、软链冲突或类型不匹配时，对该程序询问一次。
  • y：先把该程序已有托管路径移到 ~/.dotfiles-backups/<时间>/<程序>/，再整组写入仓库副本。
  • N：整组全部不动——已有文件保持原样，同组里仍缺失的路径也不会单独补装。
• 所有选择完成后，若至少有一个程序要安装，才运行 brew bundle 并部署；若全部跳过，则不改依赖、不写文件。
• 标准输入无法提供选择时，会在安装依赖或修改文件前安全退出。

Pi 会先部署 statusline，再部署引用它的设置文件。

装完后本机配置与仓库文件无关：编辑 ~/.zshrc 等不会改动 git 工作区。

Update from repository（从仓库更新本机）

仓库有更新时，用同一条安装命令把变更部署到本机（不是 sync-from-local.sh）：

cd ~/Code/dotfiles
git pull
./install.sh

• 与仓库已一致的程序：跳过。
• 本机有差异的程序：按组询问是否用仓库覆盖（同样先备份）。
• sync-from-local.sh 不会把远程更新拉到本机；它只负责本机 → 仓库。

Sync from local（本机优化写回仓库）

仅在你想把本机上的配置改动晋升进仓库时运行：

cd ~/Code/dotfiles
./sync-from-local.sh

• 先检查差异，再按程序确认；默认 N。
• 不会自动 git add、提交或推送。写回后请自行检查再提交：

git status
git diff
# 确认后再 add / commit / push

Agent rules：四个本机副本必须内容一致且可信，才会与仓库比较并最多写入一次；任一缺失、类型异常、不可信软链或内容互不一致，则整组阻止写回。

其它会阻止对应配置组写回的情况：

• 必需的本机路径缺失、类型错误，或是未指向本仓库源路径的软链。
• 对应仓库路径已经有暂存、未暂存或未跟踪改动。
• 本机配置中发现常见私钥、Token、API Key 或密码特征。

目录同步会精确镜像新增、修改和删除，同时忽略 .git/、node_modules/、.DS_Store、日志和常见编辑器临时文件。

Structure

.
├── Brewfile
├── install.sh
├── sync-from-local.sh
├── lib/
│   └── managed-configs.sh
├── agent-rules/
│   └── AGENTS.global.md
├── ghostty/
│   └── config
├── pi/
│   ├── settings.json
│   ├── web-search.json
│   └── extensions/
│       └── statusline/
├── starship/
│   └── starship.toml
└── zsh/
    ├── .zsh_plugins.txt
    ├── .zsh_plugins.zsh
    └── .zshrc