laily
59e2356f5c
Daily ff subcommands never updated the repo; only `ff update` did. Add a pouch-style interval auto-update at the ff entry (default 24h), skip dirty/fail/timeout without aborting the current command, and cover the skip/pull cases with a fish regression.
109 lines
5.9 KiB
Markdown
109 lines
5.9 KiB
Markdown
# dotfile 维护约定
|
||
|
||
个人 dotfiles 仓库（`~/.dotfile`）。本文件供 AI coding agent 与维护者共用：新增或改造配置/脚本时请遵循以下规则。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
ff script -h # 列出 script/ 下所有脚本及说明
|
||
ff script <name> # 运行脚本
|
||
make -f Makefile.scripts <name> # 同上（make 入口）
|
||
ff region # 切换 CN_REGION（国内/国外镜像）
|
||
ff reload # 重载 fish 配置
|
||
ff update # 立即 git pull origin main 并 reload
|
||
fish fish/tests/ff-auto-update.fish # ff 自动更新回归
|
||
```
|
||
|
||
## 目录职责
|
||
|
||
| 路径 | 用途 |
|
||
|------|------|
|
||
| `script/` | 可执行脚本（安装、初始化、工具）；已加入 fish `PATH` |
|
||
| `script/common/` | 脚本共享片段（`help.sh`、`os-arch.sh`） |
|
||
| `fish/default.fish` | 共享 fish 配置（进 git） |
|
||
| `~/.config/fish/config.fish` | 本机 wrapper，仅 `source` default.fish + 可选 `custom.fish` |
|
||
| `fish/functions/`、`fish/completions/` | fish 函数与补全；`fish-init` 会软链到 `~/.config/fish/` |
|
||
| `git/`、`nvim/`、`tmux/`、`zsh/`、`cursor/`、`ghostty/` 等 | 各工具**真实配置**，由对应 `*-init` 软链到系统路径 |
|
||
| `mise/config.toml` | 跨机器共享；`mise-install` 链到 `~/.config/mise/conf.d/dotfile.toml`。本机工具在 `~/.config/mise/config.toml` |
|
||
| `Makefile.scripts` | `make <script-name>` 运行 `script/<name>.sh` |
|
||
|
||
## 脚本命名
|
||
|
||
- **`*-install.sh`**：安装软件/运行时（如 `docker-install`、`nvim-install`、`mise-install`）
|
||
- **`*-init.sh`**：把 dotfile 配置**软链接**到系统默认路径（如 `git-init`、`fish-init`、`nvim-init`）
|
||
- **工具脚本**：动词或名词（`dns-clean`、`scan-ip`、`nosudo`、`docker-group`、`dirsize`）
|
||
- 文件名与 `make` / `ff script` 子命令一致（无扩展名调用）
|
||
|
||
## 新增脚本 checklist
|
||
|
||
1. 放在 `script/`，shebang + **一行 `#` 功能描述**（供 `ff script -h` 自动展示）
|
||
2. `source "$SCRIPT_DIR/common/help.sh"`，实现 `usage()`，支持 **`-h` / `--help`**
|
||
3. 需要平台判断时用 `script/common/os-arch.sh`
|
||
4. 依赖国内镜像的安装脚本读取 **`CN_REGION=1`**（`toggle-region` / `ff region`）
|
||
5. 若需 fish 补全，更新 `fish/completions/ff.fish`（描述从脚本头注释提取）
|
||
|
||
## init 脚本模式
|
||
|
||
- 目标路径已有文件：**先备份**（`*.bak` 或 `*.backup.<timestamp>`），再 `ln -sf` 指向 `~/.dotfile/...`
|
||
- 已存在且指向正确的软链：**幂等跳过**
|
||
- 示例：`git-init` → `~/.gitconfig`；`nvim-init` → `~/.config/nvim`；`ghostty-init` → 各平台 Ghostty 配置目录
|
||
- **fish-init** 特殊：不链整个 `config.fish`，只在顶部插入 `source ~/.dotfile/fish/default.fish`，并链 `functions/`、`completions/`
|
||
|
||
## install 脚本模式
|
||
|
||
- 优先用系统包管理器（brew/apt），其次官方安装脚本或 Release 二进制到 `~/.local/bin`
|
||
- Debian/Ubuntu 安装类脚本应支持 `CN_REGION` 切换镜像（参考 `docker-install.sh`）
|
||
- 需要 root 的脚本在 usage 里写 `sudo`，不要静默假设
|
||
- **mise**：共享 `mise/config.toml` 链到 `~/.config/mise/conf.d/dotfile.toml`；`mise use -g` 写本机 `~/.config/mise/config.toml`，不进 git。旧的指向仓库的全局软链由 `mise-install` 解开
|
||
|
||
## Fish / `ff` 入口
|
||
|
||
- 跑脚本：`ff script <name>` 或 `ff s <name>`（走 `execute-script.fish`）
|
||
- 列脚本：`ff script -h`
|
||
- 新增 `ff` 子命令时：改 `fish/functions/ff.fish` + `fish/completions/ff.fish`
|
||
- **自动更新**：日常 `ff` 命令超过间隔（默认开、24h）会顺带 `git pull --ff-only origin main` 更新 `~/.dotfile`，成功且有新提交后再 reload。配置在本机 `~/.config/ff/config`（`enabled`、`interval`），时间戳 `~/.local/share/ff/state`，不要进 git。跳过：`FF_NO_AUTO_UPDATE=1` 或 `ff --no-auto-update …`。显式 `ff update` 立即拉取并刷新时间戳，这次不再走自动更新。脏工作区、超时、网络失败时 stderr 一行并继续当前命令。回归：`fish fish/tests/ff-auto-update.fish`
|
||
|
||
## Git 配置
|
||
|
||
- 公共配置在 `git/.gitconfig`
|
||
- **身份**：不设全局 `user.name` / `user.email`，`user.useConfigOnly = true`。未匹配目录时拒绝 commit，避免错用身份
|
||
- `~/.dotfile/`、`~/code/`、`~/.pouch/` → `git/.gitconfig.personal`（个人，进仓库，已写 name/email）
|
||
- `~/workrepo/` → `~/.gitconfig.work`（公司，仅本机；`git-init` 会生成空模板）
|
||
- include 目标文件必须存在，否则该目录下 git 命令会 fatal
|
||
- **凭据**（所有 Git 版本）：`git/git-credential.sh` 写在主配置里，使用 `!$HOME/.dotfile/...`（Git 不展开 `~`）
|
||
- macOS：`osxkeychain` → 回退 `store`（`~/.git-credentials`）
|
||
- Linux：`libsecret` → 回退 `store`
|
||
- 平台扩展（可选）：`git/.gitconfig.darwin` / `.gitconfig.linux` 仅在高版本 Git 下通过 includeIf 加载
|
||
- `help.autocorrect`：主配置为 `0`（兼容旧 Git）；Git ≥ 2.36 的平台文件里为 `prompt`
|
||
|
||
## 边界（不要做的事）
|
||
|
||
- 不要把密钥、webhook、本机专用路径写进 git（`script/clash.sh` 等已在 `.gitignore`）
|
||
- 不要改 `~/.config/fish/config.fish` 进仓库；本机差异放 `custom.fish`
|
||
- 不要把本机 `mise use -g` 的工具写进 `mise/config.toml`；写 `~/.config/mise/config.toml`
|
||
- 不要把 `~/.config/ff/config` 或 `~/.local/share/ff/state` 写进 git（本机自动更新配置）
|
||
- 不要为 init 复制整份配置到 `$HOME`；**优先软链接**到 dotfile
|
||
- 脚本改动保持最小 diff，风格与相邻脚本一致（bash、`set -euo pipefail` 视情况）
|
||
- 未经明确要求不要 `git commit` / `git push`
|
||
|
||
## 参考模板（新 bash 脚本）
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# 一行功能描述
|
||
|
||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||
source "$SCRIPT_DIR/common/help.sh"
|
||
|
||
usage() {
|
||
cat <<'EOF'
|
||
用法: ...
|
||
选项:
|
||
-h, --help 显示此帮助
|
||
EOF
|
||
}
|
||
|
||
dotfile_help_requested "${1:-}" && dotfile_show_help
|
||
# ... 正文
|
||
```
|