Git Workflow

Complete git workflow patterns: GitHub Flow branching, atomic commits, and recovery operations. Essential for maintaining clean, reviewable history.

Argument Resolution

SUBCOMMAND = "$ARGUMENTS[0]" # Optional subcommand, e.g., "recovery", "branch", "stacked"

If no arguments, show full workflow reference.

$ARGUMENTS is the full string (CC 2.1.59 indexed access)

Branch Naming Convention

Feature branches (link to issue)

issue/<number>-<brief-description> issue/123-add-user-auth

When no issue exists

feature/<description> fix/<description> hotfix/<description>

Branch Rules:

main is always deployable
Branch from main , PR back to main
Branches live < 1-3 days
Delete branch after merge

Atomic Commit Checklist

[ ] Does ONE logical thing [ ] Leaves codebase working (tests pass) [ ] Message doesn't need "and" in title [ ] Can be reverted independently [ ] Title < 50 chars, body wraps at 72

Interactive Staging

Stage changes hunk-by-hunk

git add -p

Options:

y - stage this hunk

n - skip this hunk

s - split into smaller hunks

e - manually edit the hunk

q - quit

Review what's staged

git diff --staged # What will be committed git diff # What won't be committed

Commit Patterns

Separate concerns

git add -p && git commit -m "refactor: Extract database pool" git add -p && git commit -m "feat(#456): Add query caching"

Never combine unrelated changes

BAD: "feat: Add auth and fix formatting"

GOOD: Two separate commits

Recovery Quick Reference

The Safety Net

ALWAYS check reflog first - it has everything

git reflog

Shows ALL recent HEAD movements

Even "deleted" commits live here for 90 days

Common Recovery Scenarios

Scenario Not Pushed Already Pushed

Undo commit git reset --soft HEAD~1

git revert HEAD

Wrong branch cherry-pick + reset cherry-pick + revert

Lost commits git reset --hard HEAD@{N}

N/A

Bad rebase git rebase --abort or reflog reflog + force-with-lease

Quick Recovery Commands

Undo last commit, keep changes staged

git reset --soft HEAD~1

Find lost commits

git reflog | grep "your message"

Recover to previous state

git reset --hard HEAD@{1}

Safe force push (feature branches only)

git push --force-with-lease

Standard Workflow

1. Start fresh

git checkout main && git pull origin main git checkout -b issue/123-my-feature

2. Work with atomic commits

git add -p git commit -m "feat(#123): Add User model"

3. Stay updated

git fetch origin && git rebase origin/main

4. Push and PR

git push -u origin issue/123-my-feature gh pr create --fill

5. Cleanup after merge

git checkout main && git pull git branch -d issue/123-my-feature

Anti-Patterns

Avoid:

Long-lived branches (> 1 week)
Merging main into feature (use rebase)
Direct commits to main
Force push to shared branches
Commits that need "and" in message
Committing broken code

Best Practices Summary

Branch from main - Always start fresh
Stage interactively - Use git add -p
One thing per commit - If you say "and", split it
Rebase, don't merge - Keep history clean
Check reflog first - When something goes wrong
Force-with-lease - Safer than force push
Delete after merge - No stale branches

Related Skills

ork:commit
Create commits with conventional format and pre-commit validation
git-recovery
Quick recovery from common git mistakes using reflog operations
stacked-prs
Multi-PR development for large features with dependent PRs
ork:create-pr
Comprehensive PR creation with proper formatting

Key Decisions

Decision Choice Rationale

Branching model GitHub Flow Simple single-branch workflow, main is always deployable

Merge strategy Rebase over merge Keeps history clean and linear, easier to bisect

Branch naming issue/- Links work to tracking, enables automation

Commit granularity Atomic (one thing) Independent revert, clear history, easier review

Force push --force-with-lease only Prevents overwriting others' work on shared branches

Rules

Each category has individual rule files in rules/ loaded on-demand:

Category Rule Impact Key Pattern

Branch Protection ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/branch-protection.md

CRITICAL Protected branches, required PR workflow

Merge Strategy ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/merge-strategy.md

HIGH Rebase-first, conflict resolution, force-with-lease

History Hygiene ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/history-hygiene.md

HIGH Squash WIP, fixup commits, clean history

Recovery ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/recovery-reflog.md

CRITICAL Reflog recovery for lost commits and branches

Recovery ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/recovery-reset.md

CRITICAL Safe vs dangerous reset modes

Recovery ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/recovery-stash.md

HIGH Stash management and dropped stash recovery

Stacked PRs ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/stacked-pr-workflow.md

HIGH Stack planning, PR creation, dependency tracking

Stacked PRs ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/stacked-pr-rebase.md

HIGH Rebase management, force-with-lease, retargeting

Monorepo ${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/rules/monorepo-context.md

MEDIUM --add-dir, per-service CLAUDE.md, workspace detection

Total: 9 rules across 6 categories

References

Load on demand with Read("${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/references/<file>") :

File Content

github-flow.md

GitHub Flow branching guide

interactive-staging.md

Interactive staging patterns

reflog-recovery.md

Reflog recovery techniques

recovery-decision-tree.md

Recovery scenario decision tree

Checklists

Load on demand with Read("${CLAUDE_PLUGIN_ROOT}/skills/git-workflow/checklists/<file>") :