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: type and scope should 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 for style(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: ui or components
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 --rebase before 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-verify unless 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-verify or 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.

git-commit-expert