Repostack logoRepostack

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 仓库。
  • 不是则标记为 error。

7. Repo 父目录 .gitignore 检查

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

8. 未跟踪 Git 仓库扫描

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

输出格式

每条检查结果以图标前缀显示：

  • ✓ 绿色 — 正常
  • ⚠ 黄色 — 警告（建议修复，但命令仍返回 0）
  • ✗ 红色 — 错误（严重问题）

涉及文件

文件操作
repostack.yaml读取
.repostackrc读取
.gitignore读取
repostack.lock.yaml读取（仅检查存在性）
各 repo 目录及父目录读取

副作用

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

错误与边界情况

  • 只有 repostack.yaml 缺失或解析失败时才会提前终止。
  • 其他单项检查失败只会记录问题，不会中断流程。
  • 未跟踪仓库扫描深度硬编码为 2，深层嵌套的仓库不会被检测到。

输出示例

✓ repostack.yaml exists
✓ .gitignore contains .repostackrc
✓ Using user: alice
✓ Repo 'foo': OK
✓ Repo 'bar': OK
⚠ Lock file not found. Run: repostack snapshot
✓ Stack root is a git repository

适用场景

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

repostack users [command] [name]