laily
783965d826
Use numeric 0 in main config so legacy Git does not fail on parse; keep prompt in platform includes for Git 2.36+. Co-authored-by: Cursor <cursoragent@cursor.com>
98 lines
4.3 KiB
Markdown
98 lines
4.3 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 配置
|
||
```
|
||
|
||
## 目录职责
|
||
|
||
| 路径 | 用途 |
|
||
|------|------|
|
||
| `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/`、`mise/` 等 | 各工具**真实配置**，由对应 `*-init` 软链到系统路径 |
|
||
| `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`，不要静默假设
|
||
|
||
## Fish / `ff` 入口
|
||
|
||
- 跑脚本：`ff script <name>` 或 `ff s <name>`（走 `execute-script.fish`）
|
||
- 列脚本：`ff script -h`
|
||
- 新增 `ff` 子命令时：改 `fish/functions/ff.fish` + `fish/completions/ff.fish`
|
||
|
||
## Git 配置
|
||
|
||
- 公共配置在 `git/.gitconfig`
|
||
- **凭据**（所有 Git 版本）：`git/git-credential.sh` 写在主配置里，不依赖 `includeIf ondarwin/onlinux`（需 Git 2.36+）
|
||
- 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`
|
||
- 不要为 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
|
||
# ... 正文
|
||
```
|