Maintenance

維護指南

日常維護 dotfiles 的流程、慣例與注意事項。

常見任務

任務	指令
重新連結 dotfiles	start/link_dotfiles
重建 Claude hooks(Go 變更後)	make -C claude.symlink/go-tools install
提交並推送(AI commit message)	dp(zsh function)
更新 Homebrew bundle	brew bundle --file=Brewfile
macOS 系統預設值	osx/set-defaults.sh

慣例

Shell 腳本

• Bash 3.2 相容性:start/ 內的腳本必須在全新 macOS(Homebrew 安裝前)可執行 —— 禁用關聯陣列(assoc arrays)、禁用 ${var,,} 等 Bash 4+ 語法。
• 新的 shell 腳本提交前先跑 shellcheck。

Commit 風格

• 採用 conventional commits:feat:、fix:、chore:、docs:、refactor:、perf: 等。
• 不自動 commit;由 dp 或手動觸發。

機密管理

• 機密一律放在被 gitignore 的 .env 檔(**/.env);.env.example 記錄需要哪些 key。
• husky pre-commit 會執行 gitleaks 掃描,絕不提交憑證。

claude.symlink 的追蹤策略

• claude.symlink/ 大部分內容被 gitignore,只有白名單路徑被追蹤(見 .gitignore 第 58–67 行)。新增要追蹤的檔案時記得更新白名單。
• claude.symlink/CLAUDE.md 是全域 Claude 指示檔(SuperClaude 設定),不是 repo 文件 —— repo 文件請放根目錄 CLAUDE.md 或 docs/。

新增一個工具設定(topic)

1. 建立目錄,例如 foo/。
2. 要連結到 $HOME 的檔案命名為 foo.symlink(或目錄 foo.symlink/)。
3. 執行 start/link_dotfiles 驗證連結。
4. 若有相依套件,加進 Brewfile。

跨機器同步

• 主要透過 git pull + start/link_dotfiles。
• Linux 機器用 start/setup_linux.sh。
• 文件(Quarto book)在 docs/,push 後由 Netlify 自動部署。