@youngwat/git-file-manager 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 youngwat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,442 @@
-# Temporary Holding Version
+# @youngwat/git-file-manager
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Git 救火工具。解决两件在真实开发里高频、但用原生 git 命令做起来很别扭的事：
+
+1. **`rescue`** —— 代码提交错分支了：把指定的 commit（连续 / 不连续都行）剪切到功能分支，
+   同时让**错误分支的历史彻底还原**——那些 commit 连同改动一起消失，`git log` 干净，不留 revert 记录。
+2. **`sync`** —— 把指定 commit（连续 / 不连续）里的文件改动，**按原目录结构**同步到另一个目录。
+
+零运行时依赖，全部基于 `child_process` 调用本机 git，Node.js >= 18.20.4。
+
+---
+
+## 1. 安装
+
+```bash
+npm i -g @youngwat/git-file-manager
+```
+
+安装后有三种等价写法（`git-file-manager` 这个 bin 名让 git 能直接转发子命令）：
+
+```bash
+git file-manager rescue ...
+git-file-manager rescue ...
+gfm rescue ...
+```
+
+临时用一次也可以：`npx @youngwat/git-file-manager rescue ...`
+
+---
+
+## 2. 场景一：提交错分支，剪切到功能分支
+
+### 2.1 典型情形
+
+你在 `develop` 上顺手写了功能代码，连提了 3 个 commit，其中第 1、3 个属于 `feature/login`，
+第 2 个是无关的依赖升级。现在想：
+
+- 第 1、3 个 commit **连同改动**搬到 `feature/login`；
+- `develop` 上**看不到这两个 commit**，也不要有 revert 提交；
+- 第 2 个 commit 原样留在 `develop`。
+
+### 2.2 一条命令
+
+```bash
+# commit id 直接跟在命令后面（可以有多个，也可以混区间）
+git file-manager rescue --from develop --to feature/login a1b2c3d 9f8e7d6 --dry-run
+
+# 确认无误再真正执行
+git file-manager rescue --from develop --to feature/login a1b2c3d 9f8e7d6
+```
+
+输出示例：
+
+```text
+>> rescue 计划
+  源分支   : develop (a1b2c3d)
+  目标分支 : feature/login (9f8e7d6)
+  基点     : 5c4b3a2
+  方式     : 迁移并保留原 commit
+
+  迁移到 feature/login 的 commit（旧 -> 新，共 2 个）
+    + a1b2c3d feat: 登录页 UI
+    + 9f8e7d6 fix: 表单校验
+
+  将从 develop 的历史中移除（共 2 个）
+    - a1b2c3d feat: 登录页 UI
+    - 9f8e7d6 fix: 表单校验
+
+  保留并重放（共 1 个）
+    = b2c3d4e chore: 依赖升级
+
+! develop 已经推送到远端（origin/develop），本次历史重写后必须 force-push：
+      git push --force-with-lease origin develop
+      协作方需要 git fetch && git reset --hard origin/develop
+```
+
+### 2.3 怎么指定 commit
+
+commit id 直接跟在命令后面就行，也可以写 `--commits`，两者等价且可以混用：
+
+```bash
+git file-manager rescue --from develop --to feature/login a1b2c3d 9f8e7d6
+git file-manager rescue --from develop --to feature/login --commits "a1b2c3d,9f8e7d6"
+```
+
+> **PowerShell 用户注意**：`--commits a1b2c3d,9f8e7d6` 里的逗号会被 PowerShell 当成数组分隔符，命令被拆成两个参数。
+> 本工具会自动把它们合并回来，但最省心的写法是**直接跟在命令后面**，或者用引号包起来。
+
+支持的表达式：
+
+| 写法 | 含义 |
+| --- | --- |
+| `A..B` | 从 A 到 B，**含两端** |
+| `A..B` + `--exclusive` | 从 A 到 B，**不含 A**（等价 git 原生语义） |
+| `A,B,C` | 逐个列举，可任意混用 |
+| `A..C,E` | 混合：A~C 区间加 E 这个单独提交 |
+| `--last 3` | 取 `--from` 分支顶端最近 3 个（替代 `--commits`） |
+| `HEAD~3` | 任何 git 能解析的 revision 都可以 |
+
+解析结果会在计划里**逐个列出**（sha + subject），执行前一定看得到。
+`--commits` 与 `--last` 二选一。
+
+### 2.4 它到底做了什么
+
+```text
+① 把选中的 commit 按旧 -> 新顺序 cherry-pick 到 --to 分支（内容先落地，不会丢）；
+② 源分支：detach 到基点 base，把「没被选中的 commit」按原顺序重放一遍，
+   然后 git branch -f 把源分支指到新历史。
+```
+
+选中的 commit 从此**不在源分支历史里**——不是 `git revert`，不会留下多余记录，文件改动也随之回退。
+
+### 2.5 为什么不用 `git rebase --onto`
+
+手工做法是每个要丢的 commit 跑一次：
+
+```bash
+git rebase --onto C2^ C2 develop     # 丢掉 C2
+git rebase --onto C4^ C4 develop     # 丢掉 C4
+```
+
+一旦**选中的 commit 相邻**、或者**不连续且改动互相重叠**，第二次 rebase 就找不到 C4 了，
+或者冲突反复出现，要人工反复分段。本工具用「重置到 base + 重放保留集合」一次做完，不依赖 commit 之间的相对位置。
+
+### 2.6 安全网与撤销
+
+- 执行前会建两条 backup ref：`refs/gfm/backup/<时间戳>/<分支>`（源分支和目标分支各一条），
+  被 ref 引用的对象不会被 gc 回收，随时能回去；
+- 现场记录在 `.git/gfm/last-operation.json`；
+- 撤销：`git file-manager undo`；查看历史备份：`git file-manager undo --list`；
+- `--dry-run` 只打印计划，不动任何东西。
+
+### 2.7 遇到冲突怎么办
+
+工具会停住并保存进度，不会乱来：
+
+```bash
+# 手工解决冲突
+git status
+# 编辑冲突文件后
+git add <已解决的文件>
+git file-manager rescue --continue     # 接着跑完剩下的
+
+# 或者整体放弃，两个分支都回到操作前
+git file-manager rescue --abort
+```
+
+### 2.8 注意事项（重要）
+
+- **源分支已推送**：工具只提示、不替你 push。历史重写后需要
+  `git push --force-with-lease origin <源分支>`，并通知协作方重新拉取。
+- **merge commit**：默认拒绝剪切含 merge commit 的区间（重放会丢合并信息），
+  确实要跑可以加 `--allow-merges`，风险自负。
+- **工作区必须干净**：默认拒绝在脏工作区执行，除非 `--allow-dirty`。
+- 源分支和目标分支必须是**本地分支**，不能写 `origin/xxx`。
+
+---
+
+## 3. 场景二：按 commit 把文件改动同步到另一个目录
+
+### 3.1 典型情形
+
+- 把某个组件在若干 commit 里的改动，同步到另一个工程（目录结构相同）；
+- 从主仓库挑几个 commit 的文件，铺到部署目录 / 另一个工作副本 / 非 git 目录。
+
+### 3.2 一条命令
+
+```bash
+# commit id 直接跟在命令后面（也可以写 --commits "a1b2c3d,9f8e7d6"）
+git file-manager sync a1b2c3d 9f8e7d6 --to ../another-app --dry-run
+
+# 真正同步
+git file-manager sync a1b2c3d 9f8e7d6 --to ../another-app
+```
+
+```text
+>> sync 计划
+  目标目录 : D:\work\another-app
+  模式     : content（按 commit 时点的内容写入）
+  commit   : 2 个 -> a1b2c3d, 9f8e7d6
+
+  动作  文件                 大小      说明
+  覆盖  src/api/user.ts     12.4 KB   覆盖
+  新增  src/api/login.ts     3.1 KB   新建
+  删除  src/api/old.ts       2.0 KB   跳过（未加 --delete）
+```
+
+### 3.3 两种模式怎么选
+
+| | `--mode content`（默认） | `--mode patch` |
+| --- | --- | --- |
+| 做法 | 取文件在该 commit 时点的**完整内容**，写到目标目录同相对路径 | 生成这些 commit 的 diff，`git apply` 到目标目录 |
+| 目标目录要求 | 无要求，普通目录也行，两边基线可以不同 | 需要与源 commit 的父版本一致，否则 apply 失败 |
+| 目标目录已有本地改动 | 会被覆盖（用 `--backup` 可留副本） | 一般能保留，冲突时 apply 失败 |
+| 幂等 | 是，内容相同自动跳过、不落盘 | 否，重复 apply 会失败 |
+| 适用 | 「把这批文件按当时的样子铺过去」 | 「把这几个改动打到同基线的另一个副本上」 |
+
+### 3.4 常用选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `--paths a,b,glob` | 只同步匹配的路径，支持 `*` `?` `**`；不含通配符时按目录前缀匹配 |
+| `--exclude a,b` | 排除路径，语法同上 |
+| `--delete` | 同步删除源 commit 中删掉的文件（**默认只报告不删**） |
+| `--backup` | 覆盖/删除前，把目标旧文件备份到 `<to>/.gfm-backup/<时间戳>/` |
+| `-n, --dry-run` | 只打印计划，不写任何文件 |
+
+### 3.5 行为细节
+
+- 同一文件在多个 commit 被改动时，取**最后一次**改动的版本（content 模式）；
+- 重命名（R）按「写新路径 + 旧路径删除」处理，旧路径删除同样受 `--delete` 控制；
+- 文件内容按二进制读写，图片/字体等二进制文件不会被破坏；
+- 写入前会校验目标路径没有越出 `--to` 目录；
+- 和 `rescue` 联动：rescue 打印的原 sha 依然可用，直接拿它跑 sync 即可。
+
+---
+
+## 4. 命令参考
+
+```text
+git file-manager <命令> [选项]
+git file-manager rescue --from <分支> --to <分支> <commit id...>
+git file-manager sync <commit id...> --to <目录>
+
+命令
+  rescue   把提交错分支的 commit 剪切到功能分支，并把源分支彻底还原
+  sync     把指定 commit 的文件改动，按原目录结构同步到另一个目录
+  undo     回滚最近一次 rescue；--list 查看历史备份
+```
+
+rescue：
+
+| 选项 | 说明 |
+| --- | --- |
+| `--from <分支>` | 错误提交所在的分支（默认当前分支） |
+| `--to <分支>` | 目标功能分支（必须是已存在的本地分支） |
+| `--commits <表达式>` | 见 2.3 |
+| `--last <N>` | 取 `--from` 上最近 N 个 commit |
+| `--exclusive` | 区间不含左端（git 原生语义） |
+| `--base <commit>` | 源分支重建基点，默认取最早已选中 commit 的父提交 |
+| `--no-move` | 只清理源分支，不把 commit 迁到 `--to` |
+| `--squash` | 迁到 `--to` 时压成一个 commit（该模式不支持冲突续跑） |
+| `--allow-dirty` | 允许脏工作区执行 |
+| `--allow-merges` | 允许 merge commit |
+| `--continue` / `--abort` | 冲突续跑 / 整体回滚 |
+| `-n, --dry-run` | 只打印计划 |
+
+sync：
+
+| 选项 | 说明 |
+| --- | --- |
+| `--commits` / `--last` / `--exclusive` | 同 rescue |
+| `--from <分支>` | 解析 `--last` 的起点（默认 HEAD） |
+| `--to <目录>` | 目标目录 |
+| `--mode content\|patch` | 默认 content |
+| `--paths` / `--exclude` / `--delete` / `--backup` | 见 3.4 |
+| `-n, --dry-run` | 只打印计划 |
+
+undo：
+
+| 选项 | 说明 |
+| --- | --- |
+| （无） | 回滚最近一次 rescue（两个分支都回到操作前） |
+| `--list` | 列出所有 backup ref 与最近一次操作 |
+| `--ref <ref>` | 把对应分支回滚到指定的 backup ref |
+
+通用：`-v, --verbose` 打印执行的每条 git 命令，`-h, --help`，`--version`。
+
+---
+
+## 5. 常见问题
+
+**Q：源分支已经 push 过了，还能用吗？**
+能，但历史重写后必须 force-push（`--force-with-lease`）。工具会在计划阶段就把这一点提示出来，但不会替你执行。
+
+**Q：`--commits A..B` 为什么少了 A？**
+默认是含两端的（`A..B` = A 到 B）。如果你习惯了 git 原生语义（不含 A），加 `--exclusive`。
+
+**Q：cherry-pick 到目标分支时提示「内容已存在，跳过」？**
+说明该 commit 的改动已经在目标分支上了（可能是之前手工搬过一部分）。工具会跳过并生成空提交提示，不会制造无意义的空 commit。
+
+**Q：rescue 之后我发现搞错了？**
+`git file-manager undo` 一条命令把两个分支都还原到操作前。backup ref 会一直保留，`undo --list` 能看到历史现场。
+
+**Q：为什么不自动 push？**
+改写历史和推送是不可逆的对外操作。工具只做本地变换并打印建议命令，由你决定何时、往哪推。
+
+**Q：sync 为什么默认不删文件？**
+删除比覆盖危险。默认只报告「源 commit 里删了哪些文件」，要真删请显式加 `--delete`（配 `--backup` 更稳）。
+
+**Q：`--mode patch` 报 apply 失败？**
+说明目标目录的基线和你给的 commit 父版本不一致。改用默认的 `--mode content` 即可（它是覆盖式的，不依赖基线）。
+
+**Q：会不会把 `.git` 里的东西搞坏？**
+所有操作都通过 git 命令完成；`.git/gfm/` 下只放状态文件与 backup ref（`refs/gfm/`），不碰其他 ref 和对象。
+
+---
+
+## 6. 开发
+
+```bash
+git clone <repo> && cd git-file-manager
+npm test              # node --test test/*.test.js
+```
+
+### 6.1 手工自测（约 10 分钟）
+
+不想安装也能测：用 `node <仓库路径>/src/cli.js` 代替下文的 `gfm`。要顺便验证 bin 名与 `git file-manager` 转发，先在 git-file-manager 目录跑一次 `npm link`。
+
+> 下面所有命令**不使用任何 shell 变量**，可以一行行复制执行。commit id 用
+> `$(git log --format=%H --grep='dev-1' main)` 现取；末尾那个 `main` 是分支限定，
+> 免得 undo 之后又从 `feature/login` 上取到同名的提交。
+
+**准备 playground**（临时目录，随便造，不碰真实项目）：
+
+```powershell
+Set-Location $env:TEMP
+Remove-Item -Recurse -Force gfm-selftest -ErrorAction SilentlyContinue
+New-Item -ItemType Directory gfm-selftest | Out-Null
+Set-Location gfm-selftest
+git init -q -b main
+git config user.name selftest; git config user.email selftest@example.com
+git config commit.gpgsign false; git config core.autocrlf false
+'base' > a.txt;    git add -A; git commit -qm 'base'; git branch feature/login
+'b'    > b.txt;    git add -A; git commit -qm 'dev-1 要搬走'
+'deps' > deps.txt; git add -A; git commit -qm 'dev-2 留在 main'
+'c'    > c.txt;    git add -A; git commit -qm 'dev-3 要搬走'
+'doc'  > README.md; git add -A; git commit -qm 'dev-4 留在 main'
+git log --oneline      # dev-4 / dev-3 / dev-2 / dev-1 / base
+```
+
+**① 先看计划，零副作用**
+
+```powershell
+gfm rescue --from main --to feature/login $(git log --format=%H --grep='dev-1' main) $(git log --format=%H --grep='dev-3' main) --dry-run
+git rev-parse main
+```
+
+通过判据：「迁移到 feature/login」和「将从 main 的历史中移除」各 2 条（dev-1、dev-3），「保留并重放」是 dev-2、dev-4；`git rev-parse main` 前后一致。
+
+**② 真正剪切**
+
+```powershell
+gfm rescue --from main --to feature/login $(git log --format=%H --grep='dev-1' main) $(git log --format=%H --grep='dev-3' main)
+```
+
+| 检查项 | 命令 | 期望 |
+| --- | --- | --- |
+| 功能分支拿到 2 个提交 | `git log --format='%h %s' feature/login` | dev-3、dev-1、base |
+| 源分支没有多余记录 | `git log --format='%h %s' main` | dev-4、dev-2、base |
+| 文件改动一起回退 | `git show main:c.txt` | 报 path 不存在（报错即通过） |
+| 保留的提交没被动过 | `git log --format='%s' -1 main` | dev-4 留在 main |
+| 旧顶端不再属于任何分支 | `git branch --contains (git rev-parse "main@{1}")` | 空输出 |
+| 安全网在位 | `git for-each-ref --format='%(refname)' refs/gfm/backup` | 2 条（main、feature_login） |
+
+**③ 撤销**
+
+```powershell
+gfm undo
+git log --format='%h %s' main      # dev-4、dev-3、dev-2、dev-1、base 全回来
+```
+
+**④ sync 到另一个目录**（在 gfm-selftest 目录里执行，`--to` 用的是相对路径）
+
+```powershell
+Remove-Item -Recurse -Force ..\gfm-selftest-out -ErrorAction SilentlyContinue
+gfm sync $(git log --format=%H --grep='dev-1' main) $(git log --format=%H --grep='dev-3' main) --to ..\gfm-selftest-out --dry-run
+New-Item -ItemType Directory ..\gfm-selftest-out -Force | Out-Null
+'OLD' > ..\gfm-selftest-out\b.txt
+gfm sync $(git log --format=%H --grep='dev-1' main) $(git log --format=%H --grep='dev-3' main) --to ..\gfm-selftest-out --backup
+get-content ..\gfm-selftest-out\b.txt     # 应输出 b
+Get-ChildItem -Recurse -File ..\gfm-selftest-out | Select-Object FullName
+gfm sync $(git log --format=%H --grep='dev-1' main) $(git log --format=%H --grep='dev-3' main) --to ..\gfm-selftest-out   # 写入 0 个，跳过 2 个
+```
+
+通过判据：目标目录结构与源一致；`--backup` 那次旧文件出现在 `<out>\.gfm-backup\<时间戳>\`；最后一次执行不写盘。
+
+**⑤ 冲突 -> abort / continue**
+
+```powershell
+node -e "require('fs').writeFileSync('x.txt','1\n2\n')"; git add -A; git commit -qm 'x-1 要搬走'
+node -e "require('fs').writeFileSync('x.txt','1\n2\n3\n')"; git add -A; git commit -qm 'x-2 留在 main'
+git branch -f feature/c $(git log --format=%H --grep='base' main)
+
+# 第一次：迁移成功，重写源分支时必然冲突，退出码 1
+gfm rescue --from main --to feature/c $(git log --format=%H --grep='x-1' main)
+gfm rescue --abort                        # 整体放弃，main 回到操作前
+git log --format='%s' main
+
+# 再来一次：解决冲突后接着跑完
+gfm rescue --from main --to feature/c $(git log --format=%H --grep='x-1' main)
+node -e "require('fs').writeFileSync('x.txt','1\n3\n')"
+git add x.txt
+gfm rescue --continue
+git log --format='%h %s' main             # x-2、dev-4、dev-3、dev-2、dev-1、base
+```
+
+**⑥ 负向用例**（都应退出码 1 并给出明确提示）
+
+| 场景 | 做法 | 期望提示 |
+| --- | --- | --- |
+| 脏工作区 | 改一个已跟踪文件后 rescue | 工作区不干净 |
+| 目标分支不存在 | `--to nope` | 不是本地分支 |
+| commit 不在源分支 | 传 feature 上的 sha | 不在分支 xxx 上 |
+| 表达式为空 | `--commits ,` | --commits 没有解析出任何 commit |
+| 冲突没解决就续跑 | 冲突后不 `git add` 直接 `--continue` | 仍有未解决的冲突 |
+| 路径越界 | `sync --paths ../x` | 目标路径越界 |
+
+退出码在 PowerShell 里看 `$LASTEXITCODE`。想从头再来，重新执行「准备 playground」那段即可。
+### 6.2 自动化测试覆盖
+
+测试会在**系统临时目录**里 `git init` 造夹具仓库，不触碰任何真实仓库。当前覆盖：
+
+- rescue：连续区间、不连续、`--last`、`--squash`、`--dry-run`、参数守卫（不在分支上 / 脏工作区 / 分支不存在）、冲突后 `--abort` 回滚；
+- sync：content 新增与修改、幂等跳过、中文路径、`--paths` 过滤、`--delete`、`--dry-run`、patch 模式、`--backup`。
+
+代码结构：
+
+```text
+src/cli.js              入口：参数解析、命令分发、帮助
+src/git.js              git 封装（spawnSync，参数数组直传，中文/空格安全）
+src/commitSpec.js       commit 表达式解析与拓扑排序
+src/backup.js           backup ref 与操作状态文件
+src/log.js              终端输出与错误类型
+src/commands/rescue.js  功能一
+src/commands/sync.js    功能二
+src/commands/undo.js    回滚
+```
+
+## 7. 发布
+
+```bash
+release\release.bat              # 按当前版本发布
+release\release.bat patch        # 先 bump patch 再发布
+release\release.bat --dry-run    # 只做体检
+```
+
+发布脚本会校验包名、git 干净、npm 登录状态、`npm pack --dry-run` 产物清单，然后 `npm publish`。
+
+## 8. License
+
+MIT

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@youngwat/git-file-manager",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Git 救火工具：把提交错分支的 commit 剪切到功能分支并彻底还原源分支；把指定 commit 的文件改动按原目录结构同步到另一个目录",
+  "keywords": [
+    "git",
+    "cli",
+    "cherry-pick",
+    "commit",
+    "branch",
+    "sync",
+    "rescue"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.20.4"
+  },
+  "bin": {
+    "git-file-manager": "src/cli.js",
+    "gfm": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "pack:check": "npm pack --dry-run",
+    "release": "release\\release.bat",
+    "release:pack": "npm pack --dry-run"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/harmonious-serenity/s-sh.git"
+  }
 }

package/src/backup.js

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * 安全网：backup ref + 操作状态文件。
+ *
+ * - backup ref 挂在 refs/gfm/backup/<时间戳>/<分支> 下，被 ref 引用的对象不会被 gc
+ *   回收，所以 undo 可以可靠地把分支指回操作前的 sha；
+ * - .git/gfm/last-operation.json 记录最近一次 rescue 的现场，供 --continue / undo 使用。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const git = require('./git');
+
+const REF_PREFIX = 'refs/gfm/backup';
+
+function gfmDir() {
+  const dir = path.join(git.gitDir(), 'gfm');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+const stateFile = () => path.join(gfmDir(), 'last-operation.json');
+
+function stamp(date = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}${p(date.getMonth() + 1)}${p(date.getDate())}-`
+    + `${p(date.getHours())}${p(date.getMinutes())}${p(date.getSeconds())}`;
+}
+
+const sanitize = (name) => String(name).replace(/[^A-Za-z0-9._-]+/g, '_');
+
+/** 建一条 backup ref，返回 ref 名 */
+function createRef(label, sha, id) {
+  const ref = `${REF_PREFIX}/${id}/${sanitize(label)}`;
+  git.run(['update-ref', ref, sha]);
+  return ref;
+}
+
+const refSha = (ref) => git.revParse(ref);
+const deleteRef = (ref) => git.run(['update-ref', '-d', ref], { allowFail: true });
+
+function saveState(state) {
+  fs.writeFileSync(stateFile(), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(stateFile(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function clearState() {
+  try { fs.rmSync(stateFile(), { force: true }); } catch { /* ignore */ }
+}
+
+function listBackups() {
+  return git.lines(['for-each-ref', '--format=%(refname)%09%(objectname)%09%(creatordate:iso8601)', REF_PREFIX])
+    .map((line) => {
+      const [ref, sha, date] = line.split('\t');
+      return { ref, sha, date };
+    });
+}
+
+module.exports = {
+  REF_PREFIX,
+  gfmDir,
+  stamp,
+  createRef,
+  refSha,
+  deleteRef,
+  saveState,
+  readState,
+  clearState,
+  listBackups,
+};