git-workflow

name	git-workflow
description	> Use when this capability is needed.

Git Workflow

Two modes: Commit (daily, ~90% of use) and Setup (one-time config). Detect which one the user needs from context and jump straight in.

---

Mode 1 — Commit

Step 1: Gather context

Run in parallel:

git status --short
git diff HEAD
git log --oneline -5

Step 2: Analyze and group

Group changed files by concern. For each group:

• What changed (files + nature of change)
• Why it changed (infer from diff content)
• Which type fits (see table below)

Split decision:

Single commit	Split into multiple
Same type AND scope	Mixed types (feat + fix)
≤3 files	Mixed scopes (auth + billing)
≤50 lines total diff	>10 files across unrelated areas
Splitting would break intermediate state	Deps mixed with code changes
	Formatting mixed with logic changes

Step 3: Build commit message

Format: emoji type(scope): subject

Type → Emoji mapping:

Type	Emoji	When to use
init	🎉	Project kickoff
feat	✨	New user-facing feature
fix	🐛	Bug fix
hotfix	🚑️	Critical production fix
docs	📝	Documentation only
style	💄	CSS/visual changes, formatting
refactor	♻️	Code restructure, no behavior change
perf	⚡️	Performance improvement
test	✅	Add or update tests only
update-deps	⬆️	Dependency upgrades
configs	🔧	Config file changes
chore	🔨	Maintenance, tooling, other
breaking	💥	Breaking changes
deploy	🚀	Deployment

Pick the highest-priority type that matches. Priority: feat > fix > refactor > perf > test > docs > chore.

Scope rules:

• Lowercase, single word or hyphenated: auth, user-profile, api
• Derive from file paths: all files under src/auth/ → scope auth
• Omit if changes span many unrelated areas
• If user specifies a ticket/issue reference, use footer format (see below)

Subject rules:

• Imperative mood: "add", "fix", "remove" — not "added", "fixed", "removed"
• Lowercase first letter
• No period at end
• ≤100 chars total header length

Body — include when subject alone doesn't explain why:

• Separate from subject with one blank line
• Each bullet starts with a verb (Add, Fix, Remove, Update, Refactor, etc.)
• One fact per bullet — no filler
• Explain why, not what (the diff shows what)

Footer — for issue/ticket references:

• Format: Closes: #123 or Refs: ELWB-1234
• Only include when user mentions a ticket or the commit clearly closes an issue
• Multiple issues: one per line

Never include:

• AI attribution (no "Co-Authored-By", "Generated by", etc.)
• The commit author field already tracks who committed

Step 4: Propose to user

Display the full message in a code block:

✨ feat(auth): add OAuth2 PKCE flow

- Implement authorization code flow for mobile clients
- Add token exchange using oauth2-client library

Closes: #214

Ask: "Stage and commit with this message? (yes / edit / cancel)"

• yes → proceed to Step 5
• edit → ask what to change, revise, show again
• cancel → stop

Step 5: Execute

Staging rules:

• Use specific file paths: git add src/auth/login.ts src/auth/login.test.ts
• Never use git add ., git add -A, or git add *
• Never stage:
  • .env or any secrets/env files
  • bun.lock (only if commit is specifically a deps update)
  • worker-configuration.d.ts (generated file)
  • Any file matching .gitignore patterns

Commit using HEREDOC to preserve multi-line formatting:

git commit -m "$(cat <<'EOF'
✨ feat(scope): subject

- Bullet one
- Bullet two

Closes: #123
EOF
)"

After committing, run git log --oneline -3 and show the result.

Step 6: Multi-commit workflow

When splitting into multiple commits:

1. git restore --staged . — unstage everything
2. Commit in this order: deps first → refactors → features → fixes → docs
3. For each group:
   • git add <specific files>
   • git diff --cached --stat — verify what's staged
   • Commit with its own message
4. Each commit must leave the codebase in a working state

For partial file staging (one file has changes for different commits):

git add -p src/api/handler.ts    # stage only relevant hunks
git commit -m "🐛 fix(api): validate request body"

git add -p src/api/handler.ts    # stage remaining hunks
git commit -m "✨ feat(api): add rate limiting headers"

---

Mode 2 — Setup

When user asks about setting up git workflow tooling, read the appropriate reference file:

• references/hooks-and-tools.md — lefthook, commitlint, cz-git setup and configuration. Read when user asks to setup hooks, configure commit linting, or initialize git workflow for a new project.

• references/security.md — gitleaks configuration, secret scanning, what to do when secrets are found, commit signing, CODEOWNERS. Read when user asks about security scanning or secret management.

• references/commit-conventions.md — detailed rules on types, scopes, breaking changes, body/footer format, good/bad examples. Read when user asks about commit message conventions or wants examples.

• references/commit-workflow.md — manual staging strategies, hunk-level staging with git add -p, interactive workflow without Claude Code. Read when user asks about the manual commit process.

---

Source: anIcedAntFA/goshort — distributed by TomeVault.