git-expert

Git Expert

Unified git workflow skill. Routes to the right procedure based on what the user needs.

Routing

User wants...	Reference	Key commands
Create a commit	WORKFLOWS.md § Commit + CONVENTIONS.md + EXAMPLES.md	git status, git diff, git add, git commit
Quick checkpoint	WORKFLOWS.md § Checkpoint	git add -u, git commit --no-verify
Squash WIP commits	WORKFLOWS.md § Squash	git merge-base, git reset --soft, git commit
Explore history	Decision tree below	git log, git blame, git show, git diff
Create PR	WORKFLOWS.md § PR	git push -u, gh pr create
Session activity	WORKFLOWS.md § Session Log	git log --since="1 hour ago"
Manage worktrees	WORKTREE.md	CLI via bunx @side-quest/git worktree <command>
Review a PR	WORKFLOWS.md § Review PR	gh pr view, gh pr diff, gh api
Generate changelog	WORKFLOWS.md § Changelog	git log, git tag, git describe
Compare branches	WORKFLOWS.md § Compare	git merge-base, git diff, git log

History Exploration Decision Tree

Question	Git commands
"What changed recently?"	git log --oneline -10, git status --porcelain -b, git diff --stat
"What changed in <area>?"	git log --oneline -10 -- <path>, git log --all --grep="<area>"
"When did we add/change X?"	git log --all --grep="<X>", git log -S "<X>", git log -G "<X>"
"Who changed this?"	git blame <file>, git log --follow -- <file>
"Compare branches"	git log --oneline main..HEAD, git diff main...HEAD --stat
"Show specific commit"	git show <hash> --stat, git show <hash>
"What branches exist?"	git branch -a, git branch --show-current
"What did we do this session?"	git log --oneline --since="1 hour ago", git status
"Review this PR"	gh pr view <PR>, gh pr diff <PR>, gh api .../pulls/<PR>/comments
"Generate changelog"	git describe --tags --abbrev=0, git log <tag>..HEAD --oneline
"Compare these branches"	git merge-base <base> HEAD, git diff <base>...HEAD --stat

Safety Rules

These are non-negotiable:

• NEVER force push (git push --force / -f)
• NEVER git reset --hard without explicit user confirmation
• NEVER git clean -f without explicit user confirmation
• NEVER git checkout . or git restore . without user confirmation
• NEVER commit secrets (.env, credentials, API keys)
• NEVER use git add . or git add -A — always stage specific files
• NEVER skip hooks (--no-verify) except for WIP/checkpoint commits on feature branches
• ALWAYS check branch before committing -- if on main/master, create a feature branch first (no exceptions, including WIP checkpoints)
• ALWAYS verify on feature branch before squash (abort if main)
• ALWAYS use HEREDOC format for multi-line commit messages
• ASK user if commit scope or message is unclear
• SPLIT large changes into atomic commits

Lifecycle Hooks

This plugin runs 5 hooks that fire automatically — you don't invoke them, but be aware of their effects:

Hook	Event	What It Does
session-start	SessionStart	Loads git context (branch, recent commits, status)
git-safety	PreToolUse	Blocks destructive git commands, all commits on main/master, --no-verify on non-WIP commits, and protected file edits
command-logger	PostToolUse	Logs Bash commands to ~/.claude/logs/git-command-log.jsonl
session-summary	PreCompact	Extracts salient transcript items and saves git compaction summary
auto-commit	Stop	Creates WIP checkpoint commit for tracked changes on stop (feature branches only)

If a hook blocks an action, resolve the underlying git safety issue rather than bypassing hook behavior.

Commit Format

<type>(<scope>): <subject>

See CONVENTIONS.md for full spec and EXAMPLES.md for examples.

Type	Use for
feat	New feature
fix	Bug fix
docs	Documentation only
refactor	Code change (no feature/fix)
test	Adding/updating tests
chore	Maintenance
perf	Performance
style	Formatting
build	Build system
ci	CI/CD
revert	Revert changes