tomevault-io Git Workflow Patterns
Overview
Ensures consistent Git practices across all agent workflows, favoring isolated work environments (worktrees) and clean lifecycle closure.
Branch Setup
Option A: Standard Branching
Use for quick, single-task fixes where isolated environments are not required.
git checkout main && git pull origin main
git checkout -b feature/{feature-name}
Option B: Isolated Worktree (RECOMMENDED)
Use for complex features or PR reviews to keep the main workspace clean.
# Use automated script for features
./scripts/worktree-feature.sh {feature-name}
cd ../.worktrees/feature-{feature-name}
# OR for PR reviews
./scripts/worktree-review.sh {pr-number}
cd ../.worktrees/pr-{pr-number}
Why worktrees?
- Parallel work without stashing.
- Isolated dependencies.
- No interruption of main branch state.
Branch Lifecycle Closure (MANDATORY)
[!CAUTION] BLOCKING STEP. Never proceed to task completion with an open, unmerged feature branch unless explicitly documented.
Option A: Work Merged via PR (Recommended)
If the PR was merged via GitHub:
# Switch to main and clean up
git checkout main
git pull origin main
git branch -d feature/{name} # Delete local
Option B: Local-Only Work (Direct Merge)
If work was small and doesn't need a PR:
# Merge locally and clean up
git checkout main
git merge feature/{name} --no-ff -m "merge: {feature}"
git branch -d feature/{name} # Delete local
git push origin main
Option C: Abandon Work
git checkout main
git branch -D feature/{name} # Force delete local
git push origin --delete feature/{name} # Delete remote (if exists)
Option D: Keep WIP (Escape Hatch)
If the branch must stay open (e.g., waiting for review):
export SKIP_BRANCH_CHECK=1
git push
Option E: Worktree Cleanup
# From main workspace
git worktree remove ../.worktrees/{name}
./scripts/worktree-cleanup.sh # Prune metadata
Instrumentation
./scripts/log-skill.sh "git-workflow" "workflow" "{calling_workflow_name}"
Converted and distributed by TomeVault — claim your Tome and manage your conversions.