Git Workflow

Git Workflow and Conventions

Worktree-aware Git workflow using mise run git:* tasks.

Quick Reference

# Basic operations
mise run git:status            # Show current state + next action
mise run git:home              # Switch to home branch + sync with origin/main
mise run git:new <branch>      # Create new branch from origin/main
mise run git:cleanup [branch]  # Delete merged branch + return to home

# PR lifecycle (CI wait → browser open → merge watch → cleanup)
mise run git:open-pr <pr#>     # All-in-one: CI → open → watch → cleanup

# Pause / discard / undo
mise run git:pause [message]   # WIP commit + return to home (for switching tasks)
mise run git:abandon           # Discard all changes + return to home
mise run git:undo              # Soft reset HEAD~1 (undo last commit)

# Stacked PRs
mise run git:sync              # Sync current branch after base PR merge
# → Starts via Bash(run_in_background=true)
# → Check with /tasks, auto-cleanup on merge

Pitfalls

• Do not run git checkout main — use mise run git:home instead (worktree conflict)
• Do not use git stash — use mise run git:pause instead (creates WIP commit for safer worktree switching)
• Do not manually rebase stacked PRs — use mise run git:sync instead (updates GitHub PR base + rebases)

Standard Workflow: Code → PR

Every code change should become a PR. Follow this flow:

1. Branch   → mise run git:new feature/your-feature
2. Code     → make changes
3. Commit   → git add -A && git commit -m "feat: ..."
4. Push     → git push -u origin feature/your-feature
5. PR       → gh pr create -a "@me" -t "feat: ..."
6. Open     → mise run git:open-pr <pr#>  (CI wait → open in browser → merge watch → cleanup)
7. Cleanup  → (auto: merge detected → git:cleanup runs)

git:open-pr — PR Lifecycle Management (Claude Code Background Task)

After creating a PR, Claude runs this in the background:

Claude: [Bash(run_in_background=true)] mise run git:open-pr -- <pr#>

Three phases run automatically:

1. CI wait — gh pr checks --watch waits for CI to pass
2. Open in browser — Opens PR page (Chrome profile → default browser → print URL)
3. Merge watch — Polls PR state every 30 seconds
   • MERGED → macOS notification + mise run git:cleanup → done
   • CLOSED → message output → done

Task management:

• /tasks - View active background tasks
• Task can be stopped from the task list

Claude behavior: When background task output arrives via <system-reminder>, Claude MUST:

1. Read the output file with TaskOutput or Read
2. Report the result to the user immediately
3. Show key information: merged/closed status, cleanup success/failure

Run mise run git:status at any point to see what to do next.

If you have uncommitted changes on home branch

This happens when you made changes before creating a branch. Fix it:

# 1. Create branch (keeps your changes)
mise run git:new feature/your-feature

# 2. Now follow git:status
mise run git:status
# → Will suggest: commit, push, create PR

Proactive Workflow

Always run mise run git:status and follow the "Next:" action.

The status command automatically detects:

• Working directory state (clean/uncommitted changes)
• Sync state with upstream (pushed/unpushed/behind)
• PR state (none/open/merged/closed)

And suggests the appropriate next action:

Branch Naming Convention

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation updates
• refactor/ - Code refactoring
• test/ - Test additions or fixes

Commit Message Format

Use Conventional Commits format:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Types

• feat: New feature
• fix: Bug fix
• chore: Maintenance tasks
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• perf: Performance improvements
• test: Adding or modifying tests

Examples

feat(api): add user authentication endpoint
fix: correct button alignment on mobile
docs: update README installation steps

PR Standards

• Language: Follow project convention
• Title: Descriptive. Use commit message if single commit
• Body: Explain changes and context
• Size: Keep PRs small and focused

About Worktrees

This workflow supports git worktrees. Each worktree has a home branch.

• Home branch = directory name (e.g., web-2/ → web-2 branch)
• Never checkout main directly (may be used by another worktree)
• Always branch from origin/main

The mise run git:* tasks handle this automatically, so you don't need to think about worktrees.

Workflow: Stacked PRs

When working on features that depend on unmerged work:

Creating Stacked PRs

# 1. Create base PR (depends on main)
mise run git:new feature/base
# ... commit, push, create PR ...

# 2. Create child PR (depends on base)
git checkout feature/base
git checkout -b feature/child
# ... commit, push ...
gh pr create --base feature/base -t "feat: child feature"

After Base is Merged

When the base PR is merged, gw status will detect this and suggest syncing:

Base PR: #123 [MERGED] ✓
─────────────────────
→ Next: sync (base 'feature/base' was merged)

  mise run git:sync

Run mise run git:sync to:

1. Update child PR's base to main
2. Rebase child branch on origin/main
3. Force push the updated branch

Do not manually git rebase — always use git:sync to keep GitHub PR base and local branch in sync.

Workflow: Incidental Refactoring (Yak Shaving Protocol)

When you discover necessary refactoring during feature work, don't mix it into the feature branch.

The Flow

1. Pause current work (WIP commit + return to home):

   mise run git:pause "waiting for refactor Y"
   # Creates WIP commit, comments on PR if exists, switches to home
   

2. Create & ship the refactor:

   mise run git:new refactor/descriptive-name
   # ... implement the fix ...
   mise run git:status  # Follow the "Next:" action
   # ... commit, push, PR, merge, cleanup ...
   

3. Resume feature work:

   git checkout feature/original-branch
   mise run git:undo  # Undo the WIP commit (changes return to staged area)
   mise run git:status  # Continue from where you left off
   

Source: zawakin/tree2md — distributed by TomeVault.