commit-own-changes · diff
git:20260724.eba32ae to git:20260725.231f8ad
30 added, 38 removed. Audit A to A.
---
name: commit-own-changes
description: 提交改动时防止带入其他无关的未提交修改。事关安全，在执行任何 `git add`，`git commit` 命令前 **必须** 使用本技能。
---
# commit-own-changes
- 提交改动时防止带入其他无关的未提交修改。
+ 基于 git-hunk 精准选择提交范围，防止带入其他无关的未提交修改。
## 工作流程
- 1. **获取锁**（防止同一时间其他 Agent 进行 Git 操作；会自动等待直到上一个锁释放）
+ 1. **获取锁**
- **重要：** 锁文件为 `.git/agent.lock`（单文件，sh/ps1 同一格式）。acquire 会等待直到获得锁；设置足够长的超时并耐心等待。**禁止**手动检查/删除锁文件。**禁止**跳过本步骤进行后续操作。
+ 防止同一时间其他 Agent 进行 Git 操作：
```bash
{skill_dir}/scripts/git-lock.sh acquire <task-id> # Linux/macOS
```
```powershell
{skill_dir}\scripts\git-lock.ps1 -Action acquire -TaskId <task-id> # Windows
```
- > `<task-id>` 建议用本次任务的极简英文 summary，
- > 如 `fix-login-crash`、`add-dark-mode`。获取锁和释放锁时必须使用同一 ID。
+ `<task-id>` 建议用本次任务的极简英文 summary，如 `fix-login-crash`、`add-dark-mode`。获取锁和释放锁时必须使用同一 ID。
- > 若 acquire 执行失败（输出不包含 `acquired`），立即中止，**不得继续后续步骤**。向用户报告异常。
+ **重要：** acquire 会自动等待直到上一个锁释放；请不要设置超时时间，耐心等待。禁止手动检查/删除锁文件。禁止跳过本步骤进行后续操作。
+ 若 acquire 执行失败（输出不包含 `acquired`），立即中止提交，向用户报告异常。
- 2. **查看 git 状态**，确认有哪些文件是需要提交的
+ 2. **列举修改状态**
+ 确认有哪些 hunk 是需要提交的：
+
```powershell
- git status
+ git-hunk list
```
- **清除暂存**（防止过去残留的暂存项干扰本次提交）
+ 可以使用 `show` 确认 hunk 的内容：
```powershell
- git restore --staged .
+ git-hunk show <hunk_ids...>
```
- 3. **分文件暂存修改**
+ 3. **清除暂存区**
- 对每个需要提交的文件，先查看变更并获取 refs：
+ 防止过去残留的暂存项干扰本次提交：
```powershell
- npx git-stage-lines diff <changed_file>
+ git restore --staged .
```
- 如果文件的所有改动都属于本轮提交、不存在混合意图，直接全量暂存：
+ 4. **暂存**
+ 如果文件的所有改动都属于本轮提交，直接全量暂存：
+
```powershell
- git add <changed_file>
+ git add <files...>
```
- 否则用 git-stage-lines 精确选择。提供两种方式，按场景任选其一：
-
- - **Refs（精确，推荐）** — 从 `diff` 输出的 refs（如 `+12`, `-20`）选择要暂存的行：
-
- ```powershell
- npx git-stage-lines <changed_file>:<refs> --json
- ```
-
- `+N` 写作 `N`，`-N` 保持 `-N`，例如 `git-stage-lines src/app.ts:-12,12,15,20 --json`。
-
- - **Ranges（快速）** — 如果你知道自己改了哪些行号范围，直接按工作树行号选择：
-
- ```powershell
- npx git-stage-lines <changed_file> <ranges> --mode both --json
- ```
-
- 例如 `git-stage-lines src/app.ts 10-15,20-30 --mode both --json`。
+ 否则用 git-hunk stage 精确选择：
- 范围是"模糊匹配"的：`10-30` 只会暂存该范围内**实际有改动**的行，中间的未改动行（如 16~19）不受影响。因此如果改了 10~15 和 20~30，`10-30` 可以一次性覆盖。
+ ```powershell
+ git-hunk stage <hunk_ids...>
+ ```
> 特别地：如果你和其他 Agent 的修改区域重叠（或你的改动被其他 Agent 删除/修改了），不要在本次提交中包含那一部分，但继续正常完成剩余的提交。在提交 message 中备注冲突情况并向用户说明即可。
- 4. **提交**
+ 5. **提交**
> 注意：PowerShell 不支持 heredoc，提交消息必须使用 -F - 指定
```powershell
"<type>: <title>`n`n- <file>: <changes>`n- <file>: <changes>" | git commit -F -
```
- 5. **释放锁**
+ 6. **释放锁**
```bash
{skill_dir}/scripts/git-lock.sh release <task-id> # Linux/macOS
```
```powershell
{skill_dir}\scripts\git-lock.ps1 -Action release -TaskId <task-id> # Windows
```
## 原则
- 同时有多个 Agent 在工作。请勿假设只有你自己修改过某一文件。
- 禁止 `git add -A`。
- - 优先用 `git add <file>` 全量暂存（当文件所有改动都属于本轮提交时），避免不必要的逐行操作。
- - 用 refs 方式时，refs 必须从 `npx git-stage-lines diff` 获取，不要凭推测。
- - 用 ranges 方式时，确保 `--mode both` 以避免新增/删除行号混淆。
+ - 在适用时，建议在一行脚本内完成第 3~6 步以提高效率。例：
+
+ ```powershell
+ git restore --staged . && git add foo.md && git-hunk stage a1b2c3 && "<type>: <title>`n`n- <file>: <changes>`n- <file>: <changes>" | git commit -F - && {skill_dir}\scripts\git-lock.ps1 -Action release -TaskId <task-id>
+ ```