docs: 更新 git 命令文档

2026-11-04 00:18:00 +08:00
parent e7e53d09a6
commit 99921bf1d7
2 changed files with 103 additions and 3 deletions
@@ -2,7 +2,7 @@

 > 返回 [README.md](README.md)

-按日期范围批量调整提交时间，或修改最后一次提交的时间，然后强推。
+管理 Git 提交历史：修改提交时间、合并提交、撤销提交、清理工作区、同步远程。

 ```bash
 kopsc git retime 2026-10-01 2026-10-15            # 预览：会改哪些提交、改成什么时间
@@ -10,9 +10,23 @@ 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                           # 放弃所有本地改动，以远程为主
 ```

-> ⚠️ **这会改写历史并强推**，提交 SHA 会变化。默认只预览、不改任何东西，必须显式加 `--yes` 才会执行。
+> ⚠️ **部分命令会改写历史或丢弃改动**。默认只预览、不改任何东西，必须显式加 `--yes` 才会执行。

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

@@ -56,6 +70,87 @@ kopsc git time 2026-11-05 22:30:00 --no-push      # 只改本地，不推送
 | `--no-push` | 只改写本地，不推送 |
 | `-y`, `--yes` | 确认执行（没有它只预览） |

+## 合并提交（git.squash）
+
+`kopsc git squash <数量>` 将最近 N 个提交合并为一个新提交。
+
+```bash
+kopsc git squash 3                    # 预览：合并最近 3 个提交
+kopsc git squash 3 -m "新消息" --yes   # 合并并指定新消息
+```
+
+默认使用第一个（最旧的）提交的消息，可用 `-m` 指定新消息。
+
+### 选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `<数量>` | 必填，要合并的提交数量（必须 > 1） |
+| `-m <消息>` | 新提交的消息（默认用第一个提交的消息） |
+| `-y`, `--yes` | 确认执行 |
+
+## 撤销提交（git.undo）
+
+`kopsc git undo` 撤销最后一次提交。
+
+```bash
+kopsc git undo                    # 撤销提交，改动保留在暂存区
+kopsc git undo --hard --yes       # 完全丢弃改动
+```
+
+### 选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `--hard` | 完全丢弃改动（默认 --soft 保留到暂存区） |
+| `-y`, `--yes` | 确认执行 |
+
+## 清理工作区（git.clean）
+
+`kopsc git clean` 删除未跟踪的文件和目录。
+
+```bash
+kopsc git clean                   # 预览将删除的文件
+kopsc git clean --yes             # 确认删除
+kopsc git clean --dry-run         # 只看不删
+```
+
+### 选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `--dry-run`, `-n` | 只预览，不实际删除 |
+| `-y`, `--yes` | 确认删除 |
+
+## 同步远程（git.sync）
+
+`kopsc git sync` 同步当前分支到远程。
+
+```bash
+kopsc git sync                    # 同步当前分支
+```
+
+自动识别远程分支（main/master），执行 `git fetch` 后 rebase 或 fast-forward。
+
+## 放弃本地改动（git.discard）
+
+`kopsc git discard` 放弃所有本地改动，以远程为主。
+
+```bash
+kopsc git discard                 # 预览将丢弃的改动
+kopsc git discard --yes           # 确认丢弃
+```
+
+⚠️ **这是破坏性操作**，会丢弃所有未提交的改动、新增的文件，重置到远程分支状态。
+
+自动识别远程分支（main/master）。
+
+### 选项
+
+| 选项 | 说明 |
+| --- | --- |
+| `-y`, `--yes` | 确认执行 |
+
 ## 批量改写提交时间（git.retime）

 `kopsc git retime <开始日期> <结束日期> [选项]` 把该日期范围内（含两端）的提交，
@@ -148,7 +148,7 @@ kopsc 的命令按用途分组，每组的完整说明（命令表、选项、
 | **diagnose** | 容器 / Pod 状态根因诊断（自动识别 Docker 与 K8s） | [README.diagnose.md](README.diagnose.md) |
 | **proc** | 本机进程：列出进程、后台运行、等待退出、按资源排序、按名称终止、进程树 | [README.proc.md](README.proc.md) |
 | **java** | Java 应用：按 JDK 版本套用调优参数并运行 jar | [README.java.md](README.java.md) |
-| **git** | Git 历史：按日期范围调整提交时间、修改最后一次提交时间并强推 | [README.git.md](README.git.md) |
+| **git** | Git 历史：修改提交时间、合并提交、撤销提交、清理工作区、同步远程、放弃本地改动 | [README.git.md](README.git.md) |
 | **pkg** | 系统软件包：列出、搜索、安装、卸载、查看详情、刷新包管理器索引 | [README.pkg.md](README.pkg.md) |
 | **user** | 用户管理：列出用户、授予或移除 root/sudo 权限、查看用户信息 | [README.user.md](README.user.md) |
 | **file** | 文件查找：按大小、修改时间、名称查找文件、查找空文件/空目录 | [README.file.md](README.file.md) |
@@ -189,6 +189,11 @@ kopsc 的命令按用途分组，每组的完整说明（命令表、选项、
 | 跑 Java 应用 | `kopsc java run app.jar`、`kopsc java run --jdk 17 --print-flags app.jar` |
 | 调整提交时间 | `kopsc git retime 2026-10-01 2026-10-15`（加 `--yes` 才执行） |
 | 修改最后一次提交时间 | `kopsc git time 2026-11-05 22:30:00`（加 `--yes` 才执行） |
+| 合并提交 | `kopsc git squash 3`（加 `--yes` 才执行） |
+| 撤销提交 | `kopsc git undo`（加 `--yes` 才执行） |
+| 清理工作区 | `kopsc git clean`（加 `--yes` 才执行） |
+| 同步远程 | `kopsc git sync` |
+| 放弃本地改动 | `kopsc git discard`（加 `--yes` 才执行） |
 | 搜索软件包 | `kopsc pkg search nginx` |
 | 安装软件包 | `kopsc pkg install nginx --yes` |
 | 卸载软件包 | `kopsc pkg remove nginx --yes` |