repostack doctor

诊断 stack 配置和健康状况。

repostack doctor

执行流程

doctor 是纯诊断命令，不会修改任何文件。它按顺序执行以下检查：

1. repostack.yaml 检查

• 文件是否存在。
• 是否能被成功解析为有效 YAML。
• 如果失败：标记为 error 并直接停止后续检查（因为后续都依赖配置）。

2. 用户配置检查

• 若定义了 users：
  • 检查 .repostackrc 是否存在。
  • 检查其中指定的用户是否在 users 列表中。
  • 任一失败标记为 error。
• 若未定义 users：
  • 检查 .repostackrc 是否存在。
  • 若存在标记为 warning（提示多余的 rc 文件）。

3. .gitignore 检查

• 检查 .gitignore 是否包含 .repostackrc。
• 仅在以下情况执行：
  • 配置中定义了 users，或
  • .repostackrc 文件已存在。
• 若 .gitignore 缺失或不包含该规则，标记为 warning。

4. Repo 状态检查

• 遍历 config.repos 中的每个 repo：
  • 路径是否存在？
  • 路径是否为 Git 仓库？
  • 任一失败标记为 error。

5. Lock 文件检查

• 检查 repostack.lock.yaml 是否存在。
• 缺失时标记为 warning（并提示运行 repostack snapshot）。

6. Stack root Git 检查

• 检查当前目录是否为 Git 仓库。
• 不是则标记为 warning。

7. Repo 父目录 .gitignore 检查

• 对每个 repo，检查其父目录的 .gitignore 是否包含该 repo 的目录名。
• 目的是防止子 repo 被意外提交到 stack root 的 Git 历史中。
• 失败时标记为 warning。

8. 未跟踪 Git 仓库扫描

• 在 stack root 下扫描深度为 2 的目录结构。
• 跳过已注册的 repo 和 .git 目录。
• 如果发现独立的 Git 仓库但未在 repostack.yaml 中注册，标记为 warning。
• 扫描过程中的权限错误会被静默忽略。

输出格式

doctor 会按 step 输出检查过程。每个 step 结束时会显示一个摘要状态：

• OK：该 step 没有发现问题
• WARN (N)：该 step 中发现了 N 条 warning
• ERROR (N)：该 step 中发现了 N 条 error

step 内的具体问题仍然会逐条打印：

• info：绿色标记
• warning：黄色标记
• error：红色标记

涉及文件

副作用

• 无。这是一个只读诊断命令。

错误与边界情况

• 只有 repostack.yaml 缺失或解析失败时才会提前终止。
• 其他单项检查失败只会记录问题，不会中断流程。
• 未跟踪仓库扫描深度硬编码为 2，深层嵌套的仓库不会被检测到。
• 命令结束后：
  • 只要存在任意 error，进程返回 1
  • 只有 warning 时返回 0
  • 完全无问题时返回 0

输出示例

Config file OK
Config OK
Users OK (1 info)
  ● Using user: alice
Repos ERROR (1)
  ■ Repo 'foo': path not found at foo
Lock file WARN (1)
  ▲ Lock file not found. Run: repostack snapshot
Stack root WARN (1)
  ▲ Stack root is not a git repository. Recommended for time-travel workflow

适用场景

• 排查配置问题
• 验证环境设置
• CI/CD 前置检查