Semantic Commit
Split work-in-progress changes into clean, reviewable conventional commits, verifying before each commit.
Applicability
Use when:
- Multiple unrelated changes are unstaged/staged together
- User asks for "semantic commits", "logical commits", or "커밋 분리"
- After a multi-item implementation session before pushing
Skip when:
- There is only one logical change (just commit it directly)
- User explicitly asks for a single combined commit
Steps
1. Understand the Full Diff
Run in parallel:
git status
git diff HEAD
git diff --cached
Read each changed file if the diff alone is insufficient to determine intent.
Treat the existing index as owned work.
Do not reset, unstage, or replace it without explicit approval.
Save the change you are about to split as one patch, so Step 4 can tell your hunks from anyone else's:
git diff HEAD --binary --no-textconv > <scratch>/planned.patch
git diff --cached --binary --no-textconv > <scratch>/staged.patch # HEAD to the index as found
git diff --binary --no-textconv > <scratch>/unstaged.patch # the index as found to the working tree
git status --porcelain --untracked-files=all # lists every untracked file, also inside new directories
git diff --no-index --binary --no-textconv /dev/null <untracked-file> >> <scratch>/planned.patch # once per untracked file; exits 1 by design
git diff HEAD compares HEAD with the working tree, so a line that was staged and later changed back in the working tree is in the index but not in planned.patch, and committing the index first leaves a later group to stage the reversal.
staged.patch and unstaged.patch record both steps from HEAD through the index to the working tree, so every line a group can stage appears in one of the three patches, and all three count as planned in Step 4.
git diff HEAD also leaves untracked files out, and plain git status --porcelain shows a new directory as one ?? dir/ line; the --no-index form records each untracked file with its content and mode.
Every patch in this skill is built with --binary --no-textconv: without --binary a changed binary file reads only Binary files differ, and a repository's textconv driver replaces the real bytes with converted text that git apply rejects.
2. Group by Concern
Assign each changed file to a group:
| Type |
When |
feat(scope) |
New user-facing behavior |
fix(scope) |
Bug correction |
perf(scope) |
Performance improvement, no behavior change |
refactor(scope) |
Code restructure, no behavior change |
test(scope) |
Test additions or changes only |
build(scope) |
Build system, deps, bundler, packaging |
ci(scope) |
CI/CD config and pipelines |
chore(scope) |
Tooling, version bump, misc maintenance |
docs(scope) |
Documentation only |
style(scope) |
Formatting, import order, no logic change |
Rules:
- One file → one group by default.
If a file genuinely spans two concerns, split it at hunk level (see Hunk-Level Splitting) and list it in both groups, marking which part goes where.
- Test files travel with their production file when both change together.
- Never mix
feat and fix in the same commit.
- Pick
scope from the affected module/package/feature area (see Scopes below).
3. Present the Plan
Show the proposed commit sequence before executing:
Proposed commits:
1. feat(auth): add refresh-token rotation
Files: src/api/..., src/auth/session.ts (hunk 1 only — the rotation path)
2. test(auth): cover refresh-token rotation edge cases
Files: tests/auth/...
3. build(deps): bump jsonwebtoken to 9.0.2
Files: package.json, package-lock.json
4. fix(auth): reject a refresh token past its expiry
Files: src/auth/session.ts (hunks 2-3 only — the expiry check)
A file split across groups appears under each one, naming the hunks that belong there.
Wait for user confirmation ("go" / "네" / "좋습니다") before committing.
4. Commit Each Group
For each group in order:
Inspect the full index with git diff --cached --name-only and git diff --cached.
If it contains a file or hunk outside this group, stop and ask for direction.
Stage only the files in this group: git add <files>.
For a file split across groups, stage only its hunks (see Hunk-Level Splitting).
Verify the complete candidate index before every commit:
git diff --cached --name-only
git diff --cached --check
git diff --cached
Confirm that the full index contains only the planned group and intended hunks.
Compare it with planned.patch, staged.patch, and unstaged.patch from Step 1 by content, not by hunk shape: every added or removed line, mode change, and path in git diff --cached --binary --no-textconv must come from one of them, or from a fix you made yourself during verification (Step 4.5).
The comparison runs both ways: every change the plan assigns to this group must also still be there, because a parallel edit can revert one of your hunks while another planned hunk keeps the file dirty.
Hunk boundaries, context lines, and line numbers will differ, because a split hunk and each earlier commit of this run change the base the diff is taken against.
Anything else, such as new content, an executable bit, or a new or deleted file, was written by a parallel writer: the user in another editor, another agent session, or a tool.
The index is the only way such an edit reaches a commit, so this one comparison covers it however it got there; stop and ask, and do not stage, stash, or restore it.
Then record the reviewed tree: reviewed=$(git write-tree).
Run the project's verification commands against the isolated candidate (see Verification below).
Fix any issues before committing.
Re-run the full-index verification after each fix.
Commit with the message on the subject line:
git commit -m "type(scope): description"
For a body, use a heredoc:
git commit -m "$(cat <<'EOF'
type(scope): description
Optional body explaining the why.
EOF
)"
Compare what was committed with what you reviewed, and read the full diff rather than its --stat: git diff "$reviewed" HEAD.
A pre-commit hook that formats and re-stages this group's own files produces formatting-only lines there, which is expected.
Any other path, or any content that is not formatting, such as a hunk you withheld for a later group that a hook's git add pulled into the same file, means a hook or a parallel writer changed the index during the commit; stop and report it, and do not amend.
This detection is best-effort.
It covers what reaches the index, and in the candidate a formatter, a self-staging script, or a new non-ignored file.
It does not detect a hook that rewrites files without staging them (for example gofmt -w . with no git add): the hook runs in the main checkout, so it can change withheld hunks and later-group files there while this diff stays empty.
No Co-authored-by: Claude or similar AI trailer.
5. Report
After all commits, output:
Committed:
abc1234 feat(auth): add refresh-token rotation
def5678 test(auth): cover refresh-token rotation edge cases
ghi9012 build(deps): bump jsonwebtoken to 9.0.2
Hunk-Level Splitting
git add -p is fully driveable over a pipe — it reads answers from stdin, so no TTY is needed:
git diff -- <file> # count and read the hunks first
printf 'y\nn\n' | git add -p -- <file> # one y/n answer per hunk, in diff order
git diff --cached -- <file> # confirm exactly the intended hunks are staged
Rules:
Read the full diff and count the hunks before answering — provide exactly one answer per hunk.
On EOF git add -p quits without staging further hunks, so an answer-count mismatch under-stages silently; the git diff --cached confirmation is mandatory, not optional.
If two concerns are interleaved inside a single hunk, do not use s (its split points are line-count driven and rarely land on the concern boundary).
Fall back to patch editing: git diff -- <file> > /tmp/part.patch, delete the unwanted hunks/lines from the patch, then git apply --cached --recount /tmp/part.patch.
--recount is not optional once lines are deleted from inside a hunk: the @@ counts go stale and git apply rejects the whole file with corrupt patch rather than applying what is left. It is harmless when whole hunks were dropped instead.
After partial staging, the working tree and the index differ, so checks run on the working tree would test code that is not being committed.
Isolate the commit candidate in a detached worktree, never by stashing the shared working tree:
git worktree add --detach <scratch>/candidate HEAD
git diff --cached --binary --no-textconv > <scratch>/candidate.patch
git -C <scratch>/candidate apply --index <scratch>/candidate.patch
Run verification inside <scratch>/candidate, installing dependencies there first when the checks need them, and prefer each tool's check-only mode.
Before committing, confirm that the candidate still is what you staged:
git -C <scratch>/candidate diff --quiet exits 0 (no unstaged rewrite),
git -C <scratch>/candidate write-tree equals $reviewed from Step 4.3 (no rewrite the verifier staged itself), and
git -C <scratch>/candidate ls-files --others --exclude-standard lists nothing (no new non-ignored file that the commit would lack).
Ignored outputs are out of scope: the candidate holds only HEAD plus the staged diff, so anything a verifier writes to an ignored path is derived from the candidate, and the repository has declared that path as never committed.
Also confirm that git write-tree in the main checkout still equals $reviewed; if it does not, a parallel writer changed the main index during verification, so stop and ask as Step 4.3 requires, whatever the candidate shows.
Otherwise, any candidate mismatch means a verifier changed the candidate only, so the main index no longer matches what passed: carry the change into the main checkout, stage it, and verify again.
Then commit from the main checkout as usual.
Run git worktree remove --force <scratch>/candidate whenever a verification attempt ends, whether it passed, failed, or found a mismatch, and build a fresh candidate for the next attempt: a second git worktree add on the existing path fails with already exists, and --force is required because apply --index always leaves the candidate with staged changes.
The worktree holds HEAD plus the staged diff and nothing else, so an untracked file that belongs to a later group stays out of test discovery and out of the compiler.
Before building the patch, confirm that the index contains only the planned group.
A stash resets the files in the shared tree, which other writers are still using.
If the user saves a file there while it is reset, the save lands on the reverted copy, git stash apply refuses to overwrite it, and another session can drop the stash before you apply it (observed 2026-10-12).
When a check truly cannot run outside this checkout and a stash is unavoidable, push it with a unique message (git stash push -m semantic-commit-<timestamp> ...) and find its commit by that message in git stash list --format='%H %gs', not by position.
Another session can push a stash between your push and your lookup, and then stash@{0} names its entry instead of yours; the message still names yours.
Recover through that SHA.
Do not blindly re-git add a partially staged file after a formatter runs — that would pull the withheld hunks back in.
Use the formatter's --check mode as the gate for such files, or re-split from scratch.
Verification
Detect the verify commands from the project — do not assume any single stack.
Prefer the project's own declared scripts (npm package.json scripts, Makefile/justfile targets, CONTRIBUTING.md, CI config) over the defaults below.
| Manifest / signal |
Format / fix |
Lint / typecheck |
Test |
package.json |
npm run format / prettier |
npm run lint / eslint / tsc --noEmit |
npm test |
pubspec.yaml |
dart format . |
flutter analyze or dart analyze |
flutter test / dart test |
Cargo.toml |
cargo fmt |
cargo clippy -- -D warnings |
cargo test |
pyproject.toml / requirements.txt |
ruff format / black |
ruff check / mypy |
pytest |
go.mod |
gofmt -w / go fmt |
go vet / golangci-lint |
go test ./... |
*.csproj / *.sln |
dotnet format |
dotnet build -warnaserror |
dotnet test |
| shell scripts |
shfmt -w |
shellcheck |
bats / project test script |
For JS/TS, detect the package manager from the lockfile — pnpm-lock.yaml → pnpm, yarn.lock → yarn, bun.lockb → bun, else npm — and substitute it for npm above (e.g. pnpm test).
In a workspace/monorepo, scope to the changed package (pnpm --filter <pkg> test).
Format commands rewrite files — after formatting a staged group, re-run git add on the affected files (or use the formatter's --check mode purely as the gate).
Scale verification to the commit: a docs-only or style-only commit needs format/lint, not the full test suite.
Run the full test suite at least after the final commit.
If the project has no test or lint setup, say so rather than inventing commands.
Scopes
Use a short scope naming the affected area.
Derive scopes from the repository's own structure — top-level packages, feature folders, or modules.
Common cross-cutting scopes: deps, ci, release, config, docs.
If a change is genuinely repo-wide, omit the scope (chore: ...).
Exit Criteria
- All changes are committed (no unstaged/staged leftovers)
- Lint/typecheck passes after every commit
- Tests pass after the final commit
- No commit mixes unrelated concerns
1---2name: semantic-commit3description: Use when staged/unstaged changes mix multiple unrelated concerns and need splitting into clean conventional commits, or when asked for "semantic commits", "logical commits", or "커밋 분리". Works in any language or ecosystem.4allowed-tools: Bash, Read, Glob5metadata:6 source: https://skillmd.com/skills/andrewdongminyoo/semantic-commit7 category: commits-ci-release8---910# Semantic Commit1112Split work-in-progress changes into clean, reviewable conventional commits, verifying before each commit.1314## Applicability1516Use when:1718- Multiple unrelated changes are unstaged/staged together19- User asks for "semantic commits", "logical commits", or "커밋 분리"20- After a multi-item implementation session before pushing2122Skip when:2324- There is only one logical change (just commit it directly)25- User explicitly asks for a single combined commit2627## Steps2829### 1. Understand the Full Diff3031Run in parallel:3233```bash34git status35git diff HEAD36git diff --cached37```3839Read each changed file if the diff alone is insufficient to determine intent.40Treat the existing index as owned work.41Do not reset, unstage, or replace it without explicit approval.4243Save the change you are about to split as one patch, so Step 4 can tell your hunks from anyone else's:4445```bash46git diff HEAD --binary --no-textconv > <scratch>/planned.patch47git diff --cached --binary --no-textconv > <scratch>/staged.patch # HEAD to the index as found48git diff --binary --no-textconv > <scratch>/unstaged.patch # the index as found to the working tree49git status --porcelain --untracked-files=all # lists every untracked file, also inside new directories50git diff --no-index --binary --no-textconv /dev/null <untracked-file> >> <scratch>/planned.patch # once per untracked file; exits 1 by design51```5253`git diff HEAD` compares `HEAD` with the working tree, so a line that was staged and later changed back in the working tree is in the index but not in `planned.patch`, and committing the index first leaves a later group to stage the reversal.54`staged.patch` and `unstaged.patch` record both steps from `HEAD` through the index to the working tree, so every line a group can stage appears in one of the three patches, and all three count as planned in Step 4.55`git diff HEAD` also leaves untracked files out, and plain `git status --porcelain` shows a new directory as one `?? dir/` line; the `--no-index` form records each untracked file with its content and mode.56Every patch in this skill is built with `--binary --no-textconv`: without `--binary` a changed binary file reads only `Binary files differ`, and a repository's `textconv` driver replaces the real bytes with converted text that `git apply` rejects.5758### 2. Group by Concern5960Assign each changed file to a group:6162| Type | When |63| ----------------- | ------------------------------------------- |64| `feat(scope)` | New user-facing behavior |65| `fix(scope)` | Bug correction |66| `perf(scope)` | Performance improvement, no behavior change |67| `refactor(scope)` | Code restructure, no behavior change |68| `test(scope)` | Test additions or changes only |69| `build(scope)` | Build system, deps, bundler, packaging |70| `ci(scope)` | CI/CD config and pipelines |71| `chore(scope)` | Tooling, version bump, misc maintenance |72| `docs(scope)` | Documentation only |73| `style(scope)` | Formatting, import order, no logic change |7475Rules:7677- One file → one group by default.78 If a file genuinely spans two concerns, split it at hunk level (see Hunk-Level Splitting) and list it in both groups, marking which part goes where.79- Test files travel with their production file when both change together.80- Never mix `feat` and `fix` in the same commit.81- Pick `scope` from the affected module/package/feature area (see Scopes below).8283### 3. Present the Plan8485Show the proposed commit sequence **before executing**:8687```markdown88Proposed commits:89901. feat(auth): add refresh-token rotation91 Files: src/api/..., src/auth/session.ts (hunk 1 only — the rotation path)922. test(auth): cover refresh-token rotation edge cases93 Files: tests/auth/...943. build(deps): bump jsonwebtoken to 9.0.295 Files: package.json, package-lock.json964. fix(auth): reject a refresh token past its expiry97 Files: src/auth/session.ts (hunks 2-3 only — the expiry check)98```99100A file split across groups appears under each one, naming the hunks that belong there.101102Wait for user confirmation ("go" / "네" / "좋습니다") before committing.103104### 4. Commit Each Group105106For each group in order:1071081. Inspect the full index with `git diff --cached --name-only` and `git diff --cached`.109 If it contains a file or hunk outside this group, stop and ask for direction.1102. Stage only the files in this group: `git add <files>`.111 For a file split across groups, stage only its hunks (see Hunk-Level Splitting).1123. Verify the complete candidate index before every commit:113114 ```bash115 git diff --cached --name-only116 git diff --cached --check117 git diff --cached118 ```119120 Confirm that the full index contains only the planned group and intended hunks.121 Compare it with `planned.patch`, `staged.patch`, and `unstaged.patch` from Step 1 by content, not by hunk shape: every added or removed line, mode change, and path in `git diff --cached --binary --no-textconv` must come from one of them, or from a fix you made yourself during verification (Step 4.5).122 The comparison runs both ways: every change the plan assigns to this group must also still be there, because a parallel edit can revert one of your hunks while another planned hunk keeps the file dirty.123 Hunk boundaries, context lines, and line numbers will differ, because a split hunk and each earlier commit of this run change the base the diff is taken against.124 Anything else, such as new content, an executable bit, or a new or deleted file, was written by a parallel writer: the user in another editor, another agent session, or a tool.125 The index is the only way such an edit reaches a commit, so this one comparison covers it however it got there; stop and ask, and do not stage, stash, or restore it.126 Then record the reviewed tree: `reviewed=$(git write-tree)`.1271284. Run the project's verification commands against the isolated candidate (see Verification below).1295. Fix any issues before committing.130 Re-run the full-index verification after each fix.1316. Commit with the message on the subject line:132133 ```bash134 git commit -m "type(scope): description"135 ```136137 For a body, use a heredoc:138139 ```bash140 git commit -m "$(cat <<'EOF'141 type(scope): description142143 Optional body explaining the why.144 EOF145 )"146 ```1471487. Compare what was committed with what you reviewed, and read the full diff rather than its `--stat`: `git diff "$reviewed" HEAD`.149 A pre-commit hook that formats and re-stages this group's own files produces formatting-only lines there, which is expected.150 Any other path, or any content that is not formatting, such as a hunk you withheld for a later group that a hook's `git add` pulled into the same file, means a hook or a parallel writer changed the index during the commit; stop and report it, and do not amend.151 This detection is best-effort.152 It covers what reaches the index, and in the candidate a formatter, a self-staging script, or a new non-ignored file.153 It does not detect a hook that rewrites files without staging them (for example `gofmt -w .` with no `git add`): the hook runs in the main checkout, so it can change withheld hunks and later-group files there while this diff stays empty.154155No `Co-authored-by: Claude` or similar AI trailer.156157### 5. Report158159After all commits, output:160161```log162Committed:163 abc1234 feat(auth): add refresh-token rotation164 def5678 test(auth): cover refresh-token rotation edge cases165 ghi9012 build(deps): bump jsonwebtoken to 9.0.2166```167168## Hunk-Level Splitting169170`git add -p` is fully driveable over a pipe — it reads answers from stdin, so no TTY is needed:171172```bash173git diff -- <file> # count and read the hunks first174printf 'y\nn\n' | git add -p -- <file> # one y/n answer per hunk, in diff order175git diff --cached -- <file> # confirm exactly the intended hunks are staged176```177178Rules:179180- Read the full diff and count the hunks **before** answering — provide exactly one answer per hunk.181 On EOF `git add -p` quits without staging further hunks, so an answer-count mismatch under-stages silently; the `git diff --cached` confirmation is mandatory, not optional.182- If two concerns are interleaved inside a single hunk, do not use `s` (its split points are line-count driven and rarely land on the concern boundary).183 Fall back to patch editing: `git diff -- <file> > /tmp/part.patch`, delete the unwanted hunks/lines from the patch, then `git apply --cached --recount /tmp/part.patch`.184 `--recount` is not optional once lines are deleted from inside a hunk: the `@@` counts go stale and `git apply` rejects the whole file with `corrupt patch` rather than applying what is left. It is harmless when whole hunks were dropped instead.185- After partial staging, the working tree and the index differ, so checks run on the working tree would test code that is not being committed.186 Isolate the commit candidate in a detached worktree, never by stashing the shared working tree:187188 ```bash189 git worktree add --detach <scratch>/candidate HEAD190 git diff --cached --binary --no-textconv > <scratch>/candidate.patch191 git -C <scratch>/candidate apply --index <scratch>/candidate.patch192 ```193194 Run verification inside `<scratch>/candidate`, installing dependencies there first when the checks need them, and prefer each tool's check-only mode.195 Before committing, confirm that the candidate still is what you staged:196 - `git -C <scratch>/candidate diff --quiet` exits `0` (no unstaged rewrite),197 - `git -C <scratch>/candidate write-tree` equals `$reviewed` from Step 4.3 (no rewrite the verifier staged itself), and198 - `git -C <scratch>/candidate ls-files --others --exclude-standard` lists nothing (no new non-ignored file that the commit would lack).199 Ignored outputs are out of scope: the candidate holds only `HEAD` plus the staged diff, so anything a verifier writes to an ignored path is derived from the candidate, and the repository has declared that path as never committed.200 Also confirm that `git write-tree` in the main checkout still equals `$reviewed`; if it does not, a parallel writer changed the main index during verification, so stop and ask as Step 4.3 requires, whatever the candidate shows.201 Otherwise, any candidate mismatch means a verifier changed the candidate only, so the main index no longer matches what passed: carry the change into the main checkout, stage it, and verify again.202 Then commit from the main checkout as usual.203 Run `git worktree remove --force <scratch>/candidate` whenever a verification attempt ends, whether it passed, failed, or found a mismatch, and build a fresh candidate for the next attempt: a second `git worktree add` on the existing path fails with `already exists`, and `--force` is required because `apply --index` always leaves the candidate with staged changes.204 The worktree holds `HEAD` plus the staged diff and nothing else, so an untracked file that belongs to a later group stays out of test discovery and out of the compiler.205 Before building the patch, confirm that the index contains only the planned group.206 A stash resets the files in the shared tree, which other writers are still using.207 If the user saves a file there while it is reset, the save lands on the reverted copy, `git stash apply` refuses to overwrite it, and another session can drop the stash before you apply it (observed 2026-10-12).208 When a check truly cannot run outside this checkout and a stash is unavoidable, push it with a unique message (`git stash push -m semantic-commit-<timestamp> ...`) and find its commit by that message in `git stash list --format='%H %gs'`, not by position.209 Another session can push a stash between your push and your lookup, and then `stash@{0}` names its entry instead of yours; the message still names yours.210 Recover through that SHA.211212- Do not blindly re-`git add` a partially staged file after a formatter runs — that would pull the withheld hunks back in.213 Use the formatter's `--check` mode as the gate for such files, or re-split from scratch.214215## Verification216217Detect the verify commands from the project — **do not assume any single stack.**218Prefer the project's own declared scripts (npm `package.json` scripts, `Makefile`/`justfile` targets, `CONTRIBUTING.md`, CI config) over the defaults below.219220| Manifest / signal | Format / fix | Lint / typecheck | Test |221| ------------------------------------- | --------------------------- | ---------------------------------------- | ---------------------------- |222| `package.json` | `npm run format` / prettier | `npm run lint` / eslint / `tsc --noEmit` | `npm test` |223| `pubspec.yaml` | `dart format .` | `flutter analyze` or `dart analyze` | `flutter test` / `dart test` |224| `Cargo.toml` | `cargo fmt` | `cargo clippy -- -D warnings` | `cargo test` |225| `pyproject.toml` / `requirements.txt` | `ruff format` / black | `ruff check` / mypy | `pytest` |226| `go.mod` | `gofmt -w` / `go fmt` | `go vet` / golangci-lint | `go test ./...` |227| `*.csproj` / `*.sln` | `dotnet format` | `dotnet build -warnaserror` | `dotnet test` |228| shell scripts | `shfmt -w` | `shellcheck` | bats / project test script |229230For **JS/TS**, detect the package manager from the lockfile — `pnpm-lock.yaml` → `pnpm`, `yarn.lock` → `yarn`, `bun.lockb` → `bun`, else `npm` — and substitute it for `npm` above (e.g. `pnpm test`).231In a workspace/monorepo, scope to the changed package (`pnpm --filter <pkg> test`).232233Format commands rewrite files — after formatting a staged group, re-run `git add` on the affected files (or use the formatter's `--check` mode purely as the gate).234Scale verification to the commit: a `docs`-only or `style`-only commit needs format/lint, not the full test suite.235Run the full test suite at least after the final commit.236If the project has **no** test or lint setup, say so rather than inventing commands.237238## Scopes239240Use a short scope naming the affected area.241Derive scopes from the repository's own structure — top-level packages, feature folders, or modules.242Common cross-cutting scopes: `deps`, `ci`, `release`, `config`, `docs`.243If a change is genuinely repo-wide, omit the scope (`chore: ...`).244245## Exit Criteria246247- All changes are committed (no unstaged/staged leftovers)248- Lint/typecheck passes after every commit249- Tests pass after the final commit250- No commit mixes unrelated concerns