# Git Workflow > Git workflow standards - branch management, commit conventions, and PR creation process. Use when planning work that involves git operations or PR submissions. Use when this capability is needed. - Skill: `tomevault-io/git-workflow-28` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/git-workflow-28` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-workflow-28/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/git-workflow-28 --- # Git Workflow and Conventions Worktree-aware Git workflow using `mise run git:*` tasks. ## Quick Reference ```sh # 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 # 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 # 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 (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 -- ``` 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 ``, 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: ```sh # 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: | Status Output | Action | |--------------|--------| | `Next: start new work` | `mise run git:new feature/...` | | `Next: commit changes` | `git add -A && git commit -m "..."` | | `Next: push to remote` | `git push -u origin ` | | `Next: create pull request` | `gh pr create -a "@me" -t "..."` | | `Waiting: PR #N in review` | Wait for CI/review, or start parallel work | | `Next: cleanup merged branch` | `mise run git:cleanup` | | `Next: rebase on latest main` | `git fetch && git rebase origin/main` | | `Next: sync (base 'X' was merged)` | `mise run git:sync` | ## 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: ``` [optional scope]: [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 ```sh # 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): ```sh mise run git:pause "waiting for refactor Y" # Creates WIP commit, comments on PR if exists, switches to home ``` 2. **Create & ship the refactor**: ```sh 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**: ```sh 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](https://github.com/zawakin/tree2md) — distributed by [TomeVault](https://tomevault.io).