Repostack logoRepostack

repostack sync

将本地 stack 状态与声明/锁定状态对齐。

repostack sync
repostack sync --yes

选项

选项说明
-y, --yes跳过未提交修改的确认提示，强制 checkout

执行流程

加载配置
  • 读取 repostack.yaml 和 .repostackrc。

下载缺失 repo
  • 复用 pull 的逻辑：遍历所有 repo，对本地缺失的路径执行 git clone。

读取 lock 文件
  • 读取 repostack.lock.yaml。
  • 如果 lock 文件包含 checksum，会先进行 SHA-256 校验：
    • 计算除 checksum 字段外整个对象的哈希值。
    • 若与文件中的 checksum 不符，抛出错误：Lock file checksum mismatch...。
  • 如果没有 checksum（旧版 lock），以 debug 日志提示后跳过校验。

对每个 repo 执行同步
  • 运行 git fetch --all --tags 更新远程引用。
  • 如果 lock 文件中存在该 repo 的 revision，则执行 git checkout <revision> 将其切换到精确版本。
    • 安全提示：若 repo 存在未提交的修改，且未使用 --yes，会先提示确认： 
      Repo "xxx" has uncommitted changes. Checkout <revision> anyway? (y/N)
      用户拒绝或按 Ctrl+C 会中止整个 sync。
  • 如果 lock 文件中没有该 repo 的 pinned revision，仅 fetch，不切换分支或 detached HEAD。

重写 lock 文件
  • 根据各 repo 当前的实际状态重新生成 repostack.lock.yaml（包含新的 checksum）。

涉及文件

文件操作
repostack.yaml读取
.repostackrc读取
repostack.lock.yaml读取 / 写入（覆盖）

Git 操作

  • git clone（缺失 repo）
  • git fetch --all --tags（每个 repo）
  • git checkout <revision>（仅当 lock 中 pinned 了 revision）
  • git rev-parse --abbrev-ref HEAD 和 git rev-parse HEAD（重写 snapshot）

错误信息

场景错误信息
Lock 文件 checksum 不匹配Lock file checksum mismatch: expected ..., got .... The lock file may have been corrupted or manually edited.
Git fetch/checkout 失败直接抛出底层 Git 错误
用户未配置This stack requires a user configuration...
用户拒绝 checkout 有未提交修改的 repoAborted: user declined to checkout <repo>

边界情况

  • lock 文件缺失：sync 仍会执行 pull 和 fetch，但不会对任何 repo 执行 checkout。最终会根据当前状态生成一份新的 lock 文件。
  • 空仓库：如果 repo 没有 commit，分支和 revision 会被记录为字符串 "(no commits)"。
  • Detached HEAD：sync 会 detached checkout 到具体 revision，而不是分支的最新提交。
  • 未提交修改保护：默认情况下，如果 repo 有未提交的本地修改，sync 会提示确认；使用 --yes 可跳过确认直接执行（适合自动化脚本）。

适用场景

  • 切换 stack root 的 Git 分支后恢复特定版本组合
  • 协作时同步到团队统一的 repo 状态
  • 确保本地状态与 lock 文件一致

示例

repostack sync

repostack pull

repostack list