# Git Workflow

> Trunk-based git workflow with worktrees, switch/restore over checkout, Conventional Commits, force-with-lease. Use whenever the user asks me to commit, push, branch, or rebase.

- Skill: `kevin-liu-01/git-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kevin-liu-01/git-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kevin-liu-01/git-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: MIT
- Author: kevin-liu-01 (https://skillmd.com/u/kevin-liu-01)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kevin-liu-01/git-workflow

---


# Git Workflow

## Switch over checkout

Use `git switch` for branch operations. Never `git checkout`. `checkout --` silently destroys uncommitted work, and `checkout <branch>` is ambiguous when a file shares the name. `switch` only switches branches. Use `git restore` for file-level operations.

## Trunk-based, small PRs

Target ≤ 200 lines of changed code per PR (excluding generated files). Larger changes get split into stacked diffs. Stack with worktrees, not branch-switching:

```bash
git fetch origin && git switch dev && git pull --ff-only
mkdir -p ../wt
git worktree add -b feat/a ../wt/a dev
git worktree add -b feat/b ../wt/b feat/a    # stacked on feat/a
```

After `feat/a` merges, rebase downstream branches:

```bash
git -C ../wt/b fetch origin && git -C ../wt/b rebase origin/dev
```

## Conventional Commits

`type(scope): description`. Type is `feat`, `fix`, `refactor`, `docs`, `test`, `chore`. Imperative mood, lowercase, no period, ≤72 chars.

```
feat(auth): add org-level permissions
fix(billing): handle zero-balance edge case
refactor(api): extract validation to middleware
```

**Never use "and" in a commit message.** If you need "and", you're describing two changes that should be two commits. Split them.

## Force pushes

After a rebase, use `--force-with-lease`, never `--force`. Never force-push to main/master.

## Heredoc for multi-line commit messages

```bash
git commit -m "$(cat <<'EOF'
type(scope): one-liner subject

Optional body explaining why, not what.

Refs #123
EOF
)"
```

## Pre-commit checklist

1. `git status -sb` -- review staged + unstaged changes.
2. `git diff` -- eyeball every hunk.
3. `git add -p` -- stage precisely; split unrelated hunks across commits.
4. `pnpm typecheck && pnpm lint && pnpm test` (or the project's equivalent).
5. `git commit -m "..."` -- Conventional, ≤72 chars.

## Never

- `--no-verify`, `--no-gpg-sign` (unless explicitly requested).
- `git rebase -i` from a tool call (interactive, will hang).
- `--amend` once pushed (unless explicitly requested + force-with-lease).
- `git config` updates from a tool call.