# Git Expert

> Git workflow expert — conventional commits, history exploration, worktree management, PR creation, squash, and safety. Activates for any git-related task including committing, branching, history, and repository analysis. Use when this capability is needed.

- Skill: `tomevault-io/git-expert-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/git-expert-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-expert-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/git-expert-3

---


# 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](WORKFLOWS.md) § Commit + [CONVENTIONS.md](CONVENTIONS.md) + [EXAMPLES.md](EXAMPLES.md) | `git status`, `git diff`, `git add`, `git commit` |
| Quick checkpoint | [WORKFLOWS.md](WORKFLOWS.md) § Checkpoint | `git add -u`, `git commit --no-verify` |
| Squash WIP commits | [WORKFLOWS.md](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](WORKFLOWS.md) § PR | `git push -u`, `gh pr create` |
| Session activity | [WORKFLOWS.md](WORKFLOWS.md) § Session Log | `git log --since="1 hour ago"` |
| Manage worktrees | [WORKTREE.md](WORKTREE.md) | CLI via `bunx @side-quest/git worktree <command>` |
| Review a PR | [WORKFLOWS.md](WORKFLOWS.md) § Review PR | `gh pr view`, `gh pr diff`, `gh api` |
| Generate changelog | [WORKFLOWS.md](WORKFLOWS.md) § Changelog | `git log`, `git tag`, `git describe` |
| Compare branches | [WORKFLOWS.md](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

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

See [CONVENTIONS.md](CONVENTIONS.md) for full spec and [EXAMPLES.md](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 |

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/nathanvale) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->