commit-workflow
Use when you're about to commit (especially with a mixed diff) to stage changes, split into atomic commits, and write Conventional Commit messages with emoji
Install
npx skills add https://github.com/drvoss/everything-copilot-cli/tree/main/skills/workflow/commit-workflow
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install drvoss-everything-copilot-cli@llmmart
git clone https://github.com/drvoss/everything-copilot-cli.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole drvoss/everything-copilot-cli collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Commit Workflow
When to Use
- Before every commit — to enforce conventional commit format consistently
- When a diff mixes multiple logical concerns (feat + refactor + docs)
- When you want emoji-annotated commits for visual git history
- In teams that enforce Conventional Commits via CI
Prerequisites
- Changes staged or present as unstaged modifications
- Optional: pre-commit hooks configured (
husky,pre-commit, or similar)
Workflow
1. Stage and Inspect
First make sure no merge, cherry-pick, revert, rebase, or git am is in progress. During one of
those, the index holds the operation's state: unstaging or splitting files can discard resolutions
already staged and blur which changes belong to the operation, and staging a conflicted file marks
it resolved even if it still has conflict markers.
# Each prints a commit ID only while that operation is in progress
git rev-parse -q --verify MERGE_HEAD
git rev-parse -q --verify CHERRY_PICK_HEAD
git rev-parse -q --verify REVERT_HEAD
# Unmerged (conflicted) files
git --no-pager diff --name-only --diff-filter=U
# Also reports "rebase in progress" or "am session"
git --no-pager status --long
If any of these show an operation in progress, do not use the split or stage-all steps below.
Resolve conflicts with the user, check each resolved file with git diff --check before staging
it, and finish with the operation's own command (git merge --continue,
git cherry-pick --continue, git revert --continue). For a rebase or git am, stop and ask the
user before going further.
If nothing is staged, stage everything and inspect what changed:
# Check current state
git --no-pager status --short
# Stage all if nothing is staged
$staged = git --no-pager diff --cached --name-only
if (-not $staged) { git add -A }
# Review the diff
git --no-pager diff --cached --stat
2. Run Pre-Commit Checks (Optional)
# Node.js projects
npm run lint; if ($LASTEXITCODE -eq 0) { npm run build }
# Python projects
ruff check .; if ($LASTEXITCODE -eq 0) { pytest --tb=short -q }
# Generic pre-commit hooks
pre-commit run --all-files
Skip with --no-verify flag on the final commit if checks are handled externally.
3. Analyze the Diff for Atomic Splits
git --no-pager diff --cached
Ask: Do these changes serve more than one logical purpose?
Split when changes involve:
- Different concerns (e.g., new feature and bug fix)
- Different file types (e.g., source code and documentation)
- Different modules with no dependency between them
If splitting, use git add -p to stage partial hunks:
git add -p # interactive hunk selection
4. Write the Commit Message
Format: <emoji> <type>(<scope>): <imperative description>
Type → Emoji mapping (most common):
| Type | Emoji | Use for |
|---|---|---|
feat |
✨ | New feature |
fix |
🐛 | Bug fix |
fix |
🚑️ | Critical hotfix |
docs |
📝 | Documentation only |
style |
💄 | Formatting, no logic change |
refactor |
♻️ | Code change without feat/fix |
perf |
⚡️ | Performance improvement |
test |
✅ | Adding or fixing tests |
chore |
🔧 | Build, tooling, config |
ci |
👷 | CI/CD changes |
revert |
⏪️ | Reverting a change |
wip |
🚧 | Work in progress |
security |
🔒️ | Security fix |
breaking |
💥 | Breaking change |
deps |
➕ | Add dependency |
deps |
➖ | Remove dependency |
Rules:
- First line ≤ 72 characters
- Imperative mood: "add feature" not "added feature"
- Scope is optional:
feat(auth): add JWT refresh
git commit -m "✨ feat(api): add pagination to /users endpoint"
5. Multi-Commit Flow (Split Changes)
# First logical unit
git add src/api/users.ts
git commit -m "✨ feat(api): add cursor-based pagination to users endpoint"
# Second logical unit
git add docs/api.md
git commit -m "📝 docs(api): document pagination parameters for users endpoint"
# Third logical unit (cleanup found along the way)
git add src/utils/query.ts
git commit -m "♻️ refactor(utils): extract page-size validation into shared helper"
Examples
Feature with Docs
git add -A
git commit -m "✨ feat(notifications): add real-time push alerts via WebSocket
- Implement WebSocket connection pool
- Add client-side reconnect logic with exponential backoff
- Write integration tests for disconnect/reconnect scenarios"
Hotfix
git add src/auth/token.ts
git commit -m "🚑️ fix(auth): prevent JWT secret from leaking into error logs"
Breaking Change
git commit -m "💥 feat(config)!: rename API_KEY to COPILOT_API_KEY
BREAKING CHANGE: rename environment variable API_KEY → COPILOT_API_KEY.
Update .env files and CI secrets before deploying."
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "Commit fast, clean up messages later" | Messages written later lose the original context. The intent at commit time is the most accurate. |
| "WIP commits will be squashed later" | PRs more often merge without squashing. Write meaningful commits from the start. |
| "Nobody reads commit messages" | git log, git blame, and git bisect all depend on commit messages. |
| "It's a small change, no type prefix needed" | Small changes are the easiest to classify. Without classification, changelogs become impossible. |
Red Flags
- Meaningless commit messages like
fix,update,changes,stuff - Multiple unrelated changes bundled in one commit
- No issue or PR reference in the commit message
- Hundreds of lines of changes committed as "minor fix"
- Tests and implementation in separate commits for the same feature
Verification
- Commit message follows the format above (
<emoji> <type>(<scope>): description) - Each commit contains exactly one logical change
- Breaking changes are marked with
BREAKING CHANGE: -
git log --onelinetells a readable story of the changes
Tips
- Check
git log --onelineafter — if you can't parse the history at a glance, the messages need work - One commit = one revert: if reverting a commit breaks something unrelated, it wasn't atomic
- Use
git commit --amendto fix the last message before pushing git add -pis your friend for splitting mixed diffs without stashing- CI commit lint: if you enforce the format with
commitlint, configure it to accept the leading emoji
See Also
add-to-changelog— keep CHANGELOG in sync after committing- Conventional Commits spec
- gitmoji reference
- Inspired by: awesome-claude-code/resources/slash-commands/commit
Files (everything-copilot-cli)
-
SKILL.md 7.1 KB
--- name: commit-workflow license: MIT description: Use when you're about to commit (especially with a mixed diff) to stage changes, split into atomic commits, and write Conventional Commit messages with emoji metadata: category: workflow agent_type: general-purpose --- # Commit Workflow ## When to Use - Before every commit — to enforce conventional commit format consistently - When a diff mixes multiple logical concerns (feat + refactor + docs) - When you want emoji-annotated commits for visual git history - In teams that enforce Conventional Commits via CI ## Prerequisites - Changes staged or present as unstaged modifications - Optional: pre-commit hooks configured (`husky`, `pre-commit`, or similar) ## Workflow ### 1. Stage and Inspect First make sure no merge, cherry-pick, revert, rebase, or `git am` is in progress. During one of those, the index holds the operation's state: unstaging or splitting files can discard resolutions already staged and blur which changes belong to the operation, and staging a conflicted file marks it resolved even if it still has conflict markers. ```powershell # Each prints a commit ID only while that operation is in progress git rev-parse -q --verify MERGE_HEAD git rev-parse -q --verify CHERRY_PICK_HEAD git rev-parse -q --verify REVERT_HEAD # Unmerged (conflicted) files git --no-pager diff --name-only --diff-filter=U # Also reports "rebase in progress" or "am session" git --no-pager status --long ``` If any of these show an operation in progress, do not use the split or stage-all steps below. Resolve conflicts with the user, check each resolved file with `git diff --check` before staging it, and finish with the operation's own command (`git merge --continue`, `git cherry-pick --continue`, `git revert --continue`). For a rebase or `git am`, stop and ask the user before going further. If nothing is staged, stage everything and inspect what changed: ```powershell # Check current state git --no-pager status --short # Stage all if nothing is staged $staged = git --no-pager diff --cached --name-only if (-not $staged) { git add -A } # Review the diff git --no-pager diff --cached --stat ``` ### 2. Run Pre-Commit Checks (Optional) ```powershell # Node.js projects npm run lint; if ($LASTEXITCODE -eq 0) { npm run build } # Python projects ruff check .; if ($LASTEXITCODE -eq 0) { pytest --tb=short -q } # Generic pre-commit hooks pre-commit run --all-files ``` Skip with `--no-verify` flag on the final commit if checks are handled externally. ### 3. Analyze the Diff for Atomic Splits ```powershell git --no-pager diff --cached ``` Ask: *Do these changes serve more than one logical purpose?* **Split when changes involve:** - Different concerns (e.g., new feature **and** bug fix) - Different file types (e.g., source code **and** documentation) - Different modules with no dependency between them If splitting, use `git add -p` to stage partial hunks: ```powershell git add -p # interactive hunk selection ``` ### 4. Write the Commit Message Format: `<emoji> <type>(<scope>): <imperative description>` **Type → Emoji mapping (most common):** | Type | Emoji | Use for | |------|-------|---------| | `feat` | ✨ | New feature | | `fix` | 🐛 | Bug fix | | `fix` | 🚑️ | Critical hotfix | | `docs` | 📝 | Documentation only | | `style` | 💄 | Formatting, no logic change | | `refactor` | ♻️ | Code change without feat/fix | | `perf` | ⚡️ | Performance improvement | | `test` | ✅ | Adding or fixing tests | | `chore` | 🔧 | Build, tooling, config | | `ci` | 👷 | CI/CD changes | | `revert` | ⏪️ | Reverting a change | | `wip` | 🚧 | Work in progress | | `security` | 🔒️ | Security fix | | `breaking` | 💥 | Breaking change | | `deps` | ➕ | Add dependency | | `deps` | ➖ | Remove dependency | **Rules:** - First line ≤ 72 characters - Imperative mood: "add feature" not "added feature" - Scope is optional: `feat(auth): add JWT refresh` ```powershell git commit -m "✨ feat(api): add pagination to /users endpoint" ``` ### 5. Multi-Commit Flow (Split Changes) ```powershell # First logical unit git add src/api/users.ts git commit -m "✨ feat(api): add cursor-based pagination to users endpoint" # Second logical unit git add docs/api.md git commit -m "📝 docs(api): document pagination parameters for users endpoint" # Third logical unit (cleanup found along the way) git add src/utils/query.ts git commit -m "♻️ refactor(utils): extract page-size validation into shared helper" ``` ## Examples ### Feature with Docs ```powershell git add -A git commit -m "✨ feat(notifications): add real-time push alerts via WebSocket - Implement WebSocket connection pool - Add client-side reconnect logic with exponential backoff - Write integration tests for disconnect/reconnect scenarios" ``` ### Hotfix ```powershell git add src/auth/token.ts git commit -m "🚑️ fix(auth): prevent JWT secret from leaking into error logs" ``` ### Breaking Change ```powershell git commit -m "💥 feat(config)!: rename API_KEY to COPILOT_API_KEY BREAKING CHANGE: rename environment variable API_KEY → COPILOT_API_KEY. Update .env files and CI secrets before deploying." ``` ## Common Rationalizations | Rationalization | Reality | |----------------|---------| | "Commit fast, clean up messages later" | Messages written later lose the original context. The intent at commit time is the most accurate. | | "WIP commits will be squashed later" | PRs more often merge without squashing. Write meaningful commits from the start. | | "Nobody reads commit messages" | `git log`, `git blame`, and `git bisect` all depend on commit messages. | | "It's a small change, no type prefix needed" | Small changes are the easiest to classify. Without classification, changelogs become impossible. | ## Red Flags - Meaningless commit messages like `fix`, `update`, `changes`, `stuff` - Multiple unrelated changes bundled in one commit - No issue or PR reference in the commit message - Hundreds of lines of changes committed as "minor fix" - Tests and implementation in separate commits for the same feature ## Verification - [ ] Commit message follows the format above (`<emoji> <type>(<scope>): description`) - [ ] Each commit contains exactly one logical change - [ ] Breaking changes are marked with `BREAKING CHANGE:` - [ ] `git log --oneline` tells a readable story of the changes ## Tips - **Check `git log --oneline` after** — if you can't parse the history at a glance, the messages need work - **One commit = one revert**: if reverting a commit breaks something unrelated, it wasn't atomic - **Use `git commit --amend`** to fix the last message before pushing - **`git add -p` is your friend** for splitting mixed diffs without stashing - **CI commit lint**: if you enforce the format with `commitlint`, configure it to accept the leading emoji ## See Also - [`add-to-changelog`](../../documentation/add-to-changelog/SKILL.md) — keep CHANGELOG in sync after committing - [Conventional Commits spec](https://www.conventionalcommits.org/) - [gitmoji reference](https://gitmoji.dev/) - *Inspired by: [awesome-claude-code/resources/slash-commands/commit](https://github.com/hesreallyhim/awesome-claude-code)*
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.