Agent-almanac commit-changes

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/commit-changes" ~/.claude/skills/pjt222-agent-almanac-commit-changes-8f4c79 && rm -rf "$T"

manifest: i18n/zh-CN/skills/commit-changes/SKILL.md

source content

提交变更

选择性暂存文件，编写清晰的提交消息，并验证提交历史。

适用场景

将逻辑工作单元保存到版本控制
创建带有描述性规范化消息的提交
修改最近的提交（消息或内容）
在提交之前审查将被提交的内容

输入

必需：一个或多个已更改的文件用于提交
可选：提交消息（如未提供将自动起草）
可选：是否修改上一次提交
可选：共同作者归属

步骤

第 1 步：审查当前变更

检查工作树状态并查看差异：

# See which files are modified, staged, or untracked
git status

# See unstaged changes
git diff

# See staged changes
git diff --staged

预期结果： 清晰了解所有已修改、已暂存和未跟踪的文件。

失败处理： 如果

git status

失败，验证你是否在 git 仓库内（

git rev-parse --is-inside-work-tree

）。

第 2 步：选择性暂存文件

暂存特定文件而非使用

git add .

或

git add -A

，以避免意外包含敏感文件或无关变更：

# Stage specific files by name
git add src/feature.R tests/test-feature.R

# Stage all changes in a specific directory
git add src/

# Stage parts of a file interactively (not supported in non-interactive contexts)
# git add -p filename

在提交之前审查已暂存的内容：

git diff --staged

预期结果： 只有预期的文件和变更被暂存。没有

.env

、凭证或大型二进制文件。

失败处理： 使用

git reset HEAD <file>

取消暂存意外添加的文件。如果敏感数据被暂存，在提交之前立即取消暂存。

第 3 步：编写提交消息

使用规范化提交格式。始终通过 HEREDOC 传递消息以确保正确格式化：

git commit -m "$(cat <<'EOF'
feat: add weighted mean calculation

Implements weighted_mean() with support for NA handling and
zero-weight filtering. Includes input validation for mismatched
vector lengths.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

规范化提交类型：

类型	使用场景
`feat`	新功能
`fix`	Bug 修复
`docs`	仅文档变更
`test`	添加或更新测试
`refactor`	既不修复也不添加的代码变更
`chore`	构建、CI、依赖更新
`style`	格式化、空白（无逻辑变更）

预期结果： 提交创建成功，带有描述性消息，解释为什么而非仅仅什么。

失败处理： 如果 pre-commit 钩子失败，修复问题，使用

git add

重新暂存，然后创建新提交（不要使用

--amend

，因为失败的提交从未被创建）。

第 4 步：修改上次提交（可选）

仅在提交尚未推送到共享远程仓库时修改：

# Amend message only
git commit --amend -m "$(cat <<'EOF'
fix: correct weighted mean edge case for empty vectors

EOF
)"

# Amend with additional staged changes
git add forgotten-file.R
git commit --amend --no-edit

预期结果： 上一次提交就地更新。

git log -1

显示修改后的内容。

失败处理： 如果提交已被推送，不要修改。改为创建新提交。强制推送修改后的提交到共享分支会导致历史分叉。

第 5 步：验证提交

# View the last commit
git log -1 --stat

# View recent commit history
git log --oneline -5

# Verify the commit content
git show HEAD

预期结果： 提交出现在历史中，具有正确的消息、作者和文件变更。

失败处理： 如果提交包含错误的文件，使用

git reset --soft HEAD~1

撤销提交同时保持变更暂存，然后正确地重新提交。

验证清单

只有预期的文件包含在提交中
没有提交敏感数据（令牌、密码、
```
.env
```
文件）
提交消息遵循规范化提交格式
消息正文解释了为什么做出变更
```
git log
```
显示具有正确元数据的提交
Pre-commit 钩子（如有）已通过

常见问题

一次提交太多内容：每次提交应代表一个逻辑变更。将无关变更拆分为单独的提交
盲目使用
git add .
：始终先审查
```
git status
```
。优先按名称暂存特定文件
修改已推送的提交：绝不修改已推送到共享分支的提交。这会重写历史并给协作者带来问题
模糊的提交消息："fix bug"或"update"什么都没说。描述变更了什么以及为什么
内容修改时忘记
--no-edit
：向上次提交添加遗忘的文件时，使用
```
--no-edit
```
保留现有消息
钩子失败导致
--amend
：当 pre-commit 钩子失败时，提交从未被创建。使用
```
--amend
```
会修改上一次提交。修复钩子问题后始终创建新提交