kenaito-kopsc/README.git.md

Git 历史（kopsc git <子命令>）

返回 README.md

管理 Git 提交历史：修改提交时间、合并提交、撤销提交、清理工作区、同步远程。

kopsc git retime 2026-10-01 2026-10-15            # 预览：会改哪些提交、改成什么时间
kopsc git retime 2026-10-01 2026-10-15 --yes      # 确认后真正改写并强推

kopsc git time 2026-11-05 22:30:00                # 预览：修改最后一次提交的时间
kopsc git time 2026-11-05 22:30:00 --yes          # 确认后修改并强推

kopsc git squash 3                                # 预览：合并最近 3 个提交
kopsc git squash 3 -m "新消息" --yes               # 合并并指定新消息

kopsc git undo                                    # 撤销最后一次提交，保留改动
kopsc git undo --hard --yes                       # 完全丢弃最后一次提交

kopsc git clean                                   # 预览将清理的文件
kopsc git clean --yes                             # 确认清理

kopsc git sync                                    # 同步当前分支到远程

kopsc git discard                                 # 预览将丢弃的改动
kopsc git discard --yes                           # 放弃所有本地改动，以远程为主

⚠️ 部分命令会改写历史或丢弃改动。默认只预览、不改任何东西，必须显式加 --yes 才会执行。

修改最后一次提交时间（git.time）

kopsc git time <时间> 把本地最后一次提交的作者时间和提交时间改为用户指定的时间，然后强制推送。

kopsc git time 2026-11-05 22:30:00                # 预览
kopsc git time 2026-11-05 22:30:00 --yes          # 修改并强推
kopsc git time 2026-11-05 22:30:00 --no-push      # 只改本地，不推送

时间格式

时间格式必须是 yyyy-MM-dd HH:mm:ss，如 2026-11-05 22:30:00。格式不正确会报错。

预览示例

修改最后一次提交的时间

提交: abc1234 feat: 新增功能
当前时间: 2026-11-05 10:15:30
修改为:   2026-11-05 22:30:00

将强推到 origin/main

这是破坏性操作，会改变提交历史。加 --yes 确认执行。

实现细节

同时修改 Author Date 和 Committer Date，确保远程页面（如 Gitea）显示正确时间。

选项

选项	说明
<时间>	必填，格式 yyyy-MM-dd HH:mm:ss
--remote <名称>	强推到哪个远程，默认取唯一远程
--branch <名称>	操作的分支，默认当前分支
--no-push	只改写本地，不推送
-y, --yes	确认执行（没有它只预览）

合并提交（git.squash）

kopsc git squash <数量> 将最近 N 个提交合并为一个新提交。

kopsc git squash 3                    # 预览：合并最近 3 个提交
kopsc git squash 3 -m "新消息" --yes   # 合并并指定新消息

默认使用第一个（最旧的）提交的消息，可用 -m 指定新消息。

选项

选项	说明
<数量>	必填，要合并的提交数量（必须 > 1）
-m <消息>	新提交的消息（默认用第一个提交的消息）
-y, --yes	确认执行

撤销提交（git.undo）

kopsc git undo 撤销最后一次提交。

kopsc git undo                    # 撤销提交，改动保留在暂存区
kopsc git undo --hard --yes       # 完全丢弃改动

选项

选项	说明
--hard	完全丢弃改动（默认 --soft 保留到暂存区）
-y, --yes	确认执行

清理工作区（git.clean）

kopsc git clean 删除未跟踪的文件和目录。

kopsc git clean                   # 预览将删除的文件
kopsc git clean --yes             # 确认删除
kopsc git clean --dry-run         # 只看不删

选项

选项	说明
--dry-run, -n	只预览，不实际删除
-y, --yes	确认删除

同步远程（git.sync）

kopsc git sync 同步当前分支到远程。

kopsc git sync                    # 同步当前分支

自动识别远程分支（main/master），执行 git fetch 后 rebase 或 fast-forward。

放弃本地改动（git.discard）

kopsc git discard 放弃所有本地改动，以远程为主。

kopsc git discard                 # 预览将丢弃的改动
kopsc git discard --yes           # 确认丢弃

⚠️ 这是破坏性操作，会丢弃所有未提交的改动、新增的文件，重置到远程分支状态。

自动识别远程分支（main/master）。

选项

选项	说明
-y, --yes	确认执行

批量改写提交时间（git.retime）

kopsc git retime <开始日期> <结束日期> [选项] 把该日期范围内（含两端）的提交， 保留各自的原日期，只把时分秒重排到 21:00–23:00 之间，然后 git push --force-with-lease。

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       # 只改本地，不推送

# 连日期一起重排：把提交均匀分布到 2026-11-01 至 2026-11-15
kopsc git retime 2026-10-01 2026-10-15 --start-date 2026-11-01 --end-date 2026-11-15

时间怎么分配

默认保留每个提交的原日期，只改时分秒；加 --start-date 才会重排日期（见下）。

• 每个提交落在自己原来的日期上，日期不变。
• 同一天内的提交按原顺序严格递增。
• 相邻提交间隔是 5–40 分钟的随机值，秒位也随机（如 21:07:43 → 21:32:11）， 与真实手工提交一致，不会出现整齐的 :00 秒。
• 当天第一条提交在 21:00–21:20 之间随机开始。
• 如果某天提交太多、21:00–23:00 放不下所有间隔，会自动压紧为窗口内均匀分布， 预览表中该行标注「⚠ 已压缩间隔」。

重排日期（--start-date / --end-date）

加 --start-date 后，范围内的提交按原顺序重新分配日期，均匀铺在 [--start-date, --end-date] 之间（不给 --end-date 时就只有起始那一天）。

kopsc git retime 2026-10-01 2026-10-15 --start-date 2026-11-01                 # 全部集中在 11-01
kopsc git retime 2026-10-01 2026-10-15 --start-date 2026-11-01 --end-date 2026-11-15   # 铺满 15 天

窗口:   21:00-23:00（在 2026-11-01 至 2026-11-15 之间均匀分布）

提交     原时间               新时间               主题
f89cdd9  2026-10-01 01:00:00  2026-11-01 21:18:12  c1
e06e019  2026-10-01 02:00:00  2026-11-03 21:09:49  c2
99f29b6  2026-10-01 03:00:00  2026-11-06 21:13:52  c3
f25f7c3  2026-10-01 04:00:00  2026-11-08 21:06:54  c4
8abca35  2026-10-01 05:00:00  2026-11-11 21:02:31  c5
bea6552  2026-10-01 06:00:00  2026-11-13 21:10:34  c6

• 按比例铺开：第 i 个提交（从 0 开始）落在第 i × 天数 ÷ 提交数 天。 提交远少于天数时也是均匀铺满区间，不会全部堆在第一天。
• 同一天放多个提交时，它们仍按顺序落在该日 21:00–23:00 之间，严格递增。
• --end-date 必须配合 --start-date，且不能早于 --start-date。

预览示例

改写:   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，绝不覆盖远程上本地未知的新提交

回滚（本地）：命令结束时也会打印这行

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 <名称>	改写的分支，默认当前分支
--start-date <YYYY-MM-DD>	重排日期的起始日（默认保留每个提交的原日期）
--end-date <YYYY-MM-DD>	重排的截止日期，提交均匀分布到 [--start-date, --end-date]；不给则只用起始那一天
--no-push	只改写本地，不推送
-y, --yes	确认执行（没有它只预览）

注意事项

• 强推会影响协作者：其他人本地历史会与远程分叉，需要重新拉取。
• 仓库若开启分支保护，强推会被拒绝。此时本地历史已经改写，请用上面的备份引用回滚。
• 只处理本地已有提交；尚未推送的提交同样适用（--no-push 只改本地）。
• 页面显示的是作者时间，命令会同时改写作者时间与提交时间，避免两者矛盾。