# 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-34` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/git-workflow-34` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-workflow-34/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-34 --- # 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 ``` > **Note**: These tasks use the `gw` Rust CLI ([crates.io](https://crates.io/crates/git-workflow)). 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 (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 -- ``` 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 ``, 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 - `chore/` - Maintenance tasks - `docs/` - Documentation updates - `refactor/` - Code refactoring - `test/` - Test additions or fixes ## Commit Message Format Use Conventional Commits (one-line only): ``` [optional scope]: ``` ### 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 ```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 ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lanegrid) — claim your Tome and manage your conversions.