Git Expert Skill
1. Core Philosophy (The Brain)
"Think before you commit." Before executing any git command, you must adopt the mindset of a Senior Engineer. Your goal is not just to "save code," but to create a clean, reviewable, and safe project history.
Decision Protocol
Before acting, answer these questions:
- Atomicity: "Do these changes represent ONE logical task?"
- *If Mixed (e.g., formatting + logic)*: STOP. Plan to split using git add -p. - *If Multiple Features*: STOP. Split into separate commits.
- Clarity: "Can I describe this change in a single 'Subject' line?"
- *If No*: The commit is too big or mixed. STOP and go back to the inspection/staging phase to split the work.
- Safety: "Did I verify what I'm about to commit?"
- Check for secrets, debug logs, and unintended file deletions.
Interaction Strategy
If instructions are vague, ASK the user:
- "Should this be a single commit or split into logical parts?"
- "Are there specific scope requirements for this project?"
- "Would you like me to run tests/linting before committing?"
Language Protocol
- Standard:
typeandscopeshould generally remain in English (e.g.,feat,fix) to maintain tool compatibility. - Subject/Body:
- If the user prompts in English -> Use English. - If the user prompts in another language (e.g., Chinese) -> ASK: "Shall I generate the commit message in English (standard) or keep it in Chinese?" - *Context Awareness*: Check git log briefly. If the history is predominantly in a specific language, default to that language.
Sample Dialogues
- *Mixed Changes*: "I noticed you modified both the API logic and some CSS styling. To keep the history clean, should I split these into two separate commits: one for
fix(api)and one forstyle(ui)?" - *Vague Request*: "You asked to 'save work', but the changes look like a complete feature. Shall I commit this as
feat(user): add profile page?"
2. Commit Standards (The Law)
Strictly adhere to the Conventional Commits specification.
Format
<type>(<scope>): <subject>
<body>
<footer>Type Enumeration
| Type | Semantic Meaning | SemVer |
|---|---|---|
| feat | A new feature | MINOR |
| fix | A bug fix | PATCH |
| docs | Documentation only | PATCH |
| style | Formatting (whitespace, semi-colons, etc.) | PATCH |
| refactor | Code change (no feature, no fix) | PATCH |
| perf | Performance improvement | PATCH |
| test | Adding or correcting tests | PATCH |
| build | Build system / dependencies | PATCH |
| ci | CI configuration / scripts | PATCH |
| chore | Maintainance (no src/test change) | PATCH |
| revert | Reverting a previous commit | PATCH |
Scope Inference
- Rule: Automatically infer the scope based on the file paths of staged changes.
- Example:
src/auth/login.ts-> scope:auth - Example:
components/Button.tsx-> scope:uiorcomponents - Example:
README.md-> scope:docs
Writing Rules
- Subject: Imperative, present tense ("Add" not "Added"). No trailing period. Max 72 chars.
- Body: Focus on WHY and WHAT, not HOW. Explain the motivation and contrast with previous behavior.
- Breaking Changes:
- Add ! after type/scope: feat(api)!: remove v1 endpoints - Add footer: BREAKING CHANGE: <description>
3. Execution & Tooling (The Hands)
Use this specific workflow to execute tasks safely.
Step 0: Branch Check & Setup
- Check Current Branch:
git branch --show-current - Action: If on protected branches (
main,master,dev):
- Create New Branch: Do not commit directly. - Naming Convention: <type>/<short-description> - Example: git checkout -b fix/login-error or feat/dark-mode
Step 1: Inspection
git status # What's the state?
git diff # Review unstaged changes
git diff --cached # Review staged changes (Sanity Check)Step 2: Staging (The "Atomic" Step)
- Prefer
git add -p(patch mode) to interactively choose hunks. This ensures you only stage what you intended. - Avoid
git add.unless you have explicitly verified every file.
Step 3: Verification (The "Zero-Failure" Check)
- Mandatory: Never commit code that hasn't been verified by the current project's toolchain. This prevents "broken-heart" commits and maintains a clean, buildable history.
- Protocol:
- Build/Compile: If the project has a build step (Astro, Vite, Cargo, Go build, Java/C#, Mobile), run it to ensure no syntax errors or sync issues. - Test/Check: Run the relevant unit tests (npm test, pytest, cargo test) or static analysis (cargo check, tsc). - Lint: Run npm run lint or equivalent to maintain style consistency.
- Agent Logic: If you are unsure which command to run, scan
package.json,Makefile,README.md, or ASK the user: "What is the standard command to verify the build/tests here?"
Step 4: Commit
git commit -m "<type>(<scope>): <subject>" -m "<body>"Step 5: Sync & Push (Optional but Recommended)
- Pre-Push Sync: Always advise
git pull --rebasebefore pushing to keep history linear. - Push:
git push origin <current-branch> - Verification: Ensure the remote branch target is correct.
Security & Safety Protocols (Non-negotiable)
- NEVER commit secrets (API keys,.env, credentials).
- NEVER update git config (user.name, user.email, core.editor, etc.).
- NEVER use
--force,--hard, or--no-verifyunless explicitly ordered by the user. - NEVER force push to shared branches (
main,master,dev). - ALWAYS verify the branch before committing.
- ERROR HANDLING: If a commit fails due to hooks (lint/test), FIX the issue and retry the commit standardly. Do not blindly use
--no-verifyor complex amend logic without understanding the error.
4. Examples
Simple Bug Fix
fix(api): handle null response in user endpoint
The user API could return null for deleted accounts, causing a crash
in the dashboard. Added a null check before accessing user properties.Feature with Scope
feat(alerts): add Slack thread replies for alert updates
When an alert is updated or resolved, post a reply to the original
Slack thread instead of creating a new message. This keeps related
notifications grouped together.Refactor
refactor: extract common validation logic to shared module
Move duplicate validation code from three endpoints into a shared
validator class. No behavior change.Breaking Change
feat(api)!: remove deprecated v1 endpoints
Remove all v1 API endpoints that were deprecated in version 23.1.
Clients should migrate to v2 endpoints.
BREAKING CHANGE: v1 endpoints no longer available.Revert
revert: feat(api): add new endpoint
This reverts commit abc123def456.
Reason: Caused performance regression in production.