feat: 新增 git retime,把指定日期范围的提交时间改到 21:00-23:00 并强推

- 保留每个提交的原日期,只重排时分秒到 21:00-23:00;同日严格递增,
  间隔 5-40 分钟且秒位随机;窗口不足时自动压紧并在预览中标注
- 支持 --window/--since/--until、--interval(含 match-remote)、--seed、
  --remote、--branch、--no-push
- 安全措施:默认只预览(退出码 2)、脏工作区拒绝、改写前创建
  refs/kopsc-backup/<分支>-<时间戳> 备份、推送前比对 tree 哈希、
  只用 --force-with-lease
- BuiltinRequest 增加 Confirmed,使内置命令能获知 CLI 已确认 --yes
- 文档:新增 README.git.md,主 README 补充导航与示例
This commit is contained in:
2026-11-01 09:49:03 +08:00
parent f62c1f4872
commit f3b90d205c
19 changed files with 2581 additions and 4 deletions
+88
View File
@@ -0,0 +1,88 @@
# Git 历史(`kopsc git <子命令>`)
> 返回 [README.md](README.md)
按日期范围批量调整提交时间,然后强推。用于把一批提交的时分秒统一挪到某个时间段。
```bash
kopsc git retime 2026-10-01 2026-10-15 # 预览:会改哪些提交、改成什么时间
kopsc git retime 2026-10-01 2026-10-15 --yes # 确认后真正改写并强推
```
> ⚠️ **这会改写历史并强推**,提交 SHA 会全部变化。默认只预览、不改任何东西,必须显式加 `--yes` 才会执行。
## 改写提交时间(git.retime)
`kopsc git retime <开始日期> <结束日期> [选项]` 把该日期范围内(含两端)的提交,
**保留各自的原日期**,只把时分秒重排到 **21:00–23:00** 之间,然后 `git push --force-with-lease`。
```bash
kopsc git retime 2026-10-01 2026-10-15 # 默认窗口 21:00-23:00
kopsc git retime 2026-10-01 2026-10-15 --interval 10-25 # 间隔改为 10-25 分钟
kopsc git retime 2026-10-01 2026-10-15 --window 20:00-22:30 # 换一个时间段
kopsc git retime 2026-10-01 2026-10-15 --seed 42 # 固定随机种子,结果可复现
kopsc git retime 2026-10-01 2026-10-15 --no-push --yes # 只改本地,不推送
```
### 时间怎么分配
- 每个提交落在**自己原来的日期**上,日期不变。
- 同一天内的提交按原顺序**严格递增**。
- 相邻提交间隔是 **5–40 分钟**的随机值,**秒位也随机**(如 `21:07:43` → `21:32:11`),
与真实手工提交一致,不会出现整齐的 `:00` 秒。
- 当天第一条提交在 21:00–21:20 之间随机开始。
- 如果某天提交太多、21:00–23:00 放不下所有间隔,会**自动压紧为窗口内均匀分布**,
预览表中该行标注「⚠ 已压缩间隔」。
### 预览示例
```text
改写: 2 个提交(分支 main,远程 origin)
强推: 是 --force-with-lease → origin/main
目标: origin/main
窗口: 21:00-23:00(保留原日期)
提交 原时间 新时间 主题
1111111 2026-10-01 10:00:00 21:13:12 feat: 初始提交
2222222 2026-10-01 22:10:00 21:25:03 docs: 补充说明
```
无 `--yes` 时输出预览并**以退出码 2 结束**,不修改任何东西。范围内没有提交时正常退出。
### 安全措施
| 措施 | 说明 |
| --- | --- |
| 默认只预览 | 不加 `--yes` 不碰仓库 |
| 工作区检查 | 有未提交改动时直接拒绝(先 `git stash` 或提交) |
| 自动备份 | 改写前创建 `refs/kopsc-backup/<分支>-<时间戳>` 指向原提交 |
| 内容校验 | 推送前比对新旧提交的 tree 哈希,内容不一致则中止 |
| 租约强推 | 只用 `--force-with-lease`,绝不覆盖远程上本地未知的新提交 |
回滚(本地):命令结束时也会打印这行
```bash
git update-ref refs/heads/main refs/kopsc-backup/main-20261101-093000
# 或
git reset --hard refs/kopsc-backup/main-20261101-093000
```
### 选项
| 选项 | 说明 |
| --- | --- |
| `<开始日期> <结束日期>` | 必填,格式 `YYYY-MM-DD`,含两端 |
| `--window HH:MM-HH:MM` | 时间窗口,默认 `21:00-23:00`(`--since` / `--until` 为等价别名) |
| `--interval 5-40` | 相邻提交间隔(分钟),默认 5-40;也可写 `--interval match-remote` 参照远程分支的间隔 |
| `--seed N` | 随机种子,同一批提交用同一种子得到相同结果 |
| `--remote <名称>` | 强推到哪个远程,默认取唯一远程 |
| `--branch <名称>` | 改写的分支,默认当前分支 |
| `--no-push` | 只改写本地,不推送 |
| `-y`, `--yes` | 确认执行(没有它只预览) |
### 注意事项
- **强推会影响协作者**:其他人本地历史会与远程分叉,需要重新拉取。
- 仓库若开启**分支保护**,强推会被拒绝。此时**本地历史已经改写**,请用上面的备份引用回滚。
- 只处理**本地**已有提交;尚未推送的提交同样适用(`--no-push` 只改本地)。
- 页面显示的是**作者时间**,命令会同时改写作者时间与提交时间,避免两者矛盾。