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

Note: These tasks use the gw Rust CLI (crates.io). Install with cargo install git-workflow.

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 -> browser -> merge watch -> cleanup)
               ⚠ Run ONCE after final push. If CI fails, stop watcher -> fix -> push -> relaunch.
7. Cleanup  -> (auto: merge detected -> git:cleanup runs)

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

After creating a PR, run in background:

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

3 phases run automatically:

1. CI wait — gh pr checks --watch waits for CI to pass
2. Open in browser — Uses $OPEN_URL_CMD if set, else default browser
3. Merge watch — Polls PR state every 30s
   • MERGED -> macOS notification + mise run git:cleanup -> exit
   • CLOSED -> message -> exit

Singleton rule — only ONE watcher per PR:

• git:open-pr must run only once per PR — after the final push, when no more changes are expected.
• If CI fails and you need to push a fix: stop the existing watcher with TaskStop first, fix and push, then launch a new git:open-pr.
• Never have multiple git:open-pr background tasks running for the same PR.
• Use --no-wait to skip CI wait phase when you just want the merge watcher.

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
• chore/ - Maintenance tasks
• docs/ - Documentation updates
• refactor/ - Code refactoring
• test/ - Test additions or fixes

Commit Message Format

Use Conventional Commits (one-line only):

<type>[optional scope]: <description>

Types

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

Examples

feat(providers): add Gemini log parser
fix: correct token count in session summary
chore: bump version to 0.8.0

PR Standards

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

About Worktrees

This project uses git worktree. Each worktree has a home branch.

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

The mise run git:* tasks handle this automatically.

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
   

Converted and distributed by TomeVault — claim your Tome and manage your conversions.