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/wenyan-lite/skills/commit-changes" ~/.claude/skills/pjt222-agent-almanac-commit-changes-53208e && rm -rf "$T"

manifest: i18n/wenyan-lite/skills/commit-changes/SKILL.md

source content

提交變更

選擇性暫存文件、撰寫清晰的提交訊息，並驗證提交歷史。

適用時機

將一個邏輯工作單元保存至版本控制
以描述性、符合慣例的訊息建立提交
修訂最近一次提交（訊息或內容）
提交前審查將納入提交的變更

輸入

必要：一個或多個待提交的變更文件
選擇性：提交訊息（若未提供則代為擬定）
選擇性：是否修訂前次提交
選擇性：共同作者標註

步驟

步驟一：審查當前變更

檢查工作樹狀態並察看差異：

# 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

）。

步驟二：選擇性暫存文件

以具名方式暫存特定文件，避免使用

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>

取消暫存誤加的文件。若敏感資料已暫存，提交前立即取消暫存。

步驟三：撰寫提交訊息

採用慣例式提交格式。務必透過 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`	錯誤修復
`docs`	僅文件
`test`	新增或更新測試
`refactor`	既不修復亦不新增功能之代碼變更
`chore`	構建、CI、依賴更新
`style`	格式、空白（無邏輯變更）

預期： 提交已建立，訊息具描述性，說明為何而非僅何事。

失敗時： 若 pre-commit 鉤子失敗，修復問題，以

git add

重新暫存，並建立新提交（勿用

--amend

，因失敗的提交從未建立）。

步驟四：修訂最後一次提交（選擇性）

僅在提交尚未推送至共享遠端時修訂：

# 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

顯示修訂後的內容。

失敗時： 若提交已推送，勿修訂。改建新提交。對共享分支強制推送已修訂提交會造成歷史分歧。

步驟五：驗證提交

# 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
```
。優先以具名方式暫存特定文件。
修訂已推送提交：切勿修訂已推送至共享分支的提交。此舉改寫歷史，為協作者帶來困擾。
模糊的提交訊息：「修復錯誤」或「更新」毫無訊息量。描述變更了什麼及為何。
內容修訂時遺漏
--no-edit
：將遺漏文件加入最後一次提交時，用
```
--no-edit
```
保留既有訊息。
鉤子失敗後使用
--amend
：當 pre-commit 鉤子失敗，提交從未建立。使用
```
--amend
```
將修改前次提交。修復鉤子問題後應建立新提交。