tomevault-io Git Workflow and Branching Strategy
Overview
NXTG-Forge follows a trunk-based development approach with short-lived feature branches. This workflow emphasizes continuous integration, small frequent commits, and maintaining a deployable main branch.
Branch Strategy
Main Branch (main)
- Always deployable: Every commit on main should be production-ready
- Protected: Requires pull requests and passing CI checks
- Source of truth: All feature branches originate from main
Feature Branches
- Short-lived: Typically 1-3 days
- Single purpose: One feature or fix per branch
- Naming convention:
feat/description,fix/description,refactor/description
# Feature branch examples
feat/user-authentication
feat/payment-integration
fix/login-validation-bug
refactor/clean-architecture-migration
docs/api-documentation
No Long-Lived Branches
We do not use:
developbranchreleasebrancheshotfixbranches (fix directly from main)
Workflow Steps
1. Start New Work
# 1. Ensure main is up to date
git checkout main
git pull origin main
# 2. Create feature branch
git checkout -b feat/user-authentication
# 3. Verify branch
git branch --show-current
# Output: feat/user-authentication
2. Make Changes
# 1. Work on feature
# Edit files...
# 2. Check status frequently
git status
# 3. Stage changes
git add forge/auth/
git add tests/unit/test_auth.py
# 4. Commit with descriptive message
git commit -m "Add JWT authentication middleware
- Implement JWT token validation
- Add token expiration checking
- Create authentication decorator
- Add unit tests for middleware
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"
3. Keep Branch Updated
# Rebase frequently to stay current
git fetch origin
git rebase origin/main
# If conflicts occur
# 1. Resolve conflicts in files
# 2. Stage resolved files
git add <resolved-files>
# 3. Continue rebase
git rebase --continue
4. Push Changes
# First push (set upstream)
git push -u origin feat/user-authentication
# Subsequent pushes
git push
# Force push after rebase (use with caution)
git push --force-with-lease
5. Create Pull Request
# Using GitHub CLI
gh pr create \
--title "Add user authentication" \
--body "$(cat <<'EOF'
## Summary
- Implements JWT-based authentication
- Adds authentication middleware
- Includes comprehensive tests
## Test Plan
- [x] Unit tests for JWT validation
- [x] Integration tests for auth flow
- [x] Manual testing with Postman
🤖 Generated with Claude Code
EOF
)"
# OR create via GitHub web interface
6. Code Review and Merge
# After approval, merge via GitHub UI
# OR use CLI
gh pr merge --squash
# Delete feature branch
git branch -d feat/user-authentication
git push origin --delete feat/user-authentication
Commit Message Guidelines
Format
<type>: <subject>
<body>
<footer>
Types
- feat: New feature
- fix: Bug fix
- refactor: Code restructuring (no behavior change)
- docs: Documentation changes
- test: Adding or updating tests
- chore: Maintenance tasks
- perf: Performance improvements
- style: Code style changes (formatting, no logic change)
Examples
Good Commit Messages
feat: Add user authentication system
Implement JWT-based authentication:
- JWT token generation and validation
- Authentication middleware for FastAPI
- User login/logout endpoints
- Password hashing with bcrypt
Tests include unit tests for token validation and
integration tests for auth flow.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
fix: Correct validation error in user registration
The email validation was rejecting valid emails with
plus signs (e.g., user+tag@example.com). Updated regex
to comply with RFC 5322.
Fixes #123
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
refactor: Extract database connection to separate module
Move database connection logic from main.py to
infrastructure/database.py for better separation of
concerns and testability.
No behavior changes.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Poor Commit Messages
fix: bug # Too vague
wip # Work in progress shouldn't be committed
update code # Not descriptive
asdf # Meaningless
Commit Frequency
DO:
- Commit after completing a logical unit of work
- Commit when tests pass
- Commit before switching contexts
- Commit at end of work session
DON'T:
- Commit broken code
- Commit commented-out code
- Commit with failing tests
- Commit large unrelated changes together
Pull Request Guidelines
PR Title
Use same format as commit messages:
feat: Add user authentication system
fix: Correct email validation in registration
refactor: Extract database connection logic
docs: Update API documentation for v2
PR Description Template
## Summary
<!-- 1-3 bullet points describing the changes -->
- Implements JWT-based authentication
- Adds login/logout endpoints
- Includes middleware for route protection
## Motivation
<!-- Why is this change needed? What problem does it solve? -->
Users need a secure way to authenticate and access protected
resources. Current system has no authentication mechanism.
## Changes
<!-- Detailed list of changes made -->
- Added JWT token generation in `auth/jwt.py`
- Created authentication middleware in `auth/middleware.py`
- Implemented login/logout endpoints in `api/auth.py`
- Added user model with password hashing
- Created authentication tests
## Test Plan
<!-- How was this tested? -->
- [x] Unit tests for JWT token validation
- [x] Unit tests for password hashing
- [x] Integration tests for login/logout flow
- [x] Manual testing with Postman
- [x] Tested edge cases (expired tokens, invalid passwords)
## Checklist
- [x] Tests added/updated
- [x] Documentation updated
- [x] No linting errors
- [x] Follows Clean Architecture
- [x] Backward compatible
🤖 Generated with Claude Code
PR Size Guidelines
- Small PR: < 200 lines changed (preferred)
- Medium PR: 200-500 lines changed (acceptable)
- Large PR: > 500 lines changed (break into smaller PRs)
Benefits of small PRs:
- Faster reviews
- Easier to understand
- Less risk of conflicts
- Quicker feedback loop
Review Process
- Self-review: Review your own PR first
- CI checks: Ensure all CI checks pass
- Request review: Tag appropriate reviewers
- Address feedback: Respond to all comments
- Approval: Get at least one approval
- Merge: Squash and merge to main
Merge Strategies
Squash and Merge (Default)
Combines all commits into a single commit on main:
# Feature branch commits:
# - Add user model
# - Add authentication
# - Fix linting errors
# - Address review feedback
# After squash merge:
# feat: Add user authentication system
Advantages:
- Clean linear history
- Easy to revert entire feature
- Hides work-in-progress commits
Use when:
- Multiple commits in feature branch
- Want clean history on main
Rebase and Merge
Replays commits onto main:
# Maintains individual commits but rebases them
git rebase origin/main
git push --force-with-lease
Advantages:
- Preserves commit history
- Shows incremental progress
- Better for debugging with git bisect
Use when:
- Commits are already well-organized
- Want to preserve detailed history
Never Use: Merge Commit
Creates merge commit:
# DON'T DO THIS
git merge feat/my-feature
Why avoid:
- Creates merge commits that clutter history
- Makes history harder to follow
- Complicates git bisect
Handling Conflicts
Prevention
# Rebase frequently to avoid large conflicts
git fetch origin
git rebase origin/main
# Keep branches short-lived
# Merge within 1-3 days of creation
Resolution
# 1. Start rebase
git rebase origin/main
# 2. Git shows conflicts
# CONFLICT (content): Merge conflict in forge/auth/middleware.py
# 3. Open conflicted files
# Look for conflict markers:
<<<<<<< HEAD
# Current main branch code
=======
# Your feature branch code
>>>>>>> feat/user-authentication
# 4. Resolve conflicts (keep one, combine, or rewrite)
# 5. Stage resolved files
git add forge/auth/middleware.py
# 6. Continue rebase
git rebase --continue
# 7. Push (force with lease for safety)
git push --force-with-lease
Abort if Needed
# If conflicts are too complex, abort and retry
git rebase --abort
# Consider alternative approaches:
# - Break feature into smaller pieces
# - Coordinate with other developers
# - Refactor conflicting code first
Git Hooks
NXTG-Forge uses git hooks for automation (see .claude/hooks/):
Pre-commit Hook
Runs before each commit:
- Formats code with Black
- Runs linting (Ruff)
- Checks type hints (MyPy)
- Validates commit message format
Post-commit Hook
Runs after each commit:
- Updates state.json
- Logs commit to session tracking
Pre-push Hook
Runs before push:
- Runs tests
- Checks coverage threshold
- Validates no secrets committed
Common Scenarios
Scenario 1: Update Feature Branch with Latest Main
# Option A: Rebase (preferred)
git checkout feat/my-feature
git fetch origin
git rebase origin/main
git push --force-with-lease
# Option B: Merge (if rebase is problematic)
git checkout feat/my-feature
git merge origin/main
git push
Scenario 2: Accidentally Committed to Main
# If not pushed yet
git reset HEAD~1 # Undo commit, keep changes
git checkout -b feat/my-feature # Create feature branch
git add .
git commit -m "..."
git push -u origin feat/my-feature
# If already pushed (coordinate with team)
git revert <commit-hash> # Create revert commit
git push
Scenario 3: Need to Update Commit Message
# If not pushed yet
git commit --amend
# If already pushed (avoid if others pulled)
git commit --amend
git push --force-with-lease
Scenario 4: Split Large Commit
# Reset to before commit
git reset HEAD~1
# Stage and commit in pieces
git add forge/auth/models.py
git commit -m "Add user model"
git add forge/auth/middleware.py
git commit -m "Add authentication middleware"
git add tests/
git commit -m "Add authentication tests"
Scenario 5: Cherry-pick Specific Commit
# Get commit hash from another branch
git log feat/other-feature
# Cherry-pick to current branch
git cherry-pick <commit-hash>
# Resolve conflicts if any
Best Practices
DO
✅ Commit early, commit often: Small, frequent commits ✅ Write descriptive messages: Explain why, not just what ✅ Rebase before merging: Keep history clean ✅ Review your own PRs: Catch issues before others ✅ Keep branches short-lived: Merge within days ✅ Test before committing: Ensure tests pass ✅ Use meaningful branch names: Clear purpose ✅ Squash WIP commits: Clean up before merge
DON'T
❌ Commit broken code: Always ensure code works ❌ Push directly to main: Always use pull requests ❌ Force push to main: Never rewrite public history ❌ Commit secrets: Use environment variables ❌ Leave commented code: Remove or uncomment ❌ Create long-lived branches: Increases conflicts ❌ Skip code review: Even small changes need review ❌ Ignore CI failures: Fix before merging
Git Configuration
Recommended Git Config
# User info
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
# Editor
git config --global core.editor "code --wait"
# Default branch
git config --global init.defaultBranch main
# Rebase on pull
git config --global pull.rebase true
# Auto-stash during rebase
git config --global rebase.autoStash true
# Prune on fetch
git config --global fetch.prune true
# Colored output
git config --global color.ui auto
Aliases
# Useful shortcuts
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual 'log --oneline --graph --all'
Troubleshooting
Problem: Detached HEAD
# Create branch from current state
git checkout -b recover-branch
# Or discard changes and return to branch
git checkout main
Problem: Accidentally Deleted Branch
# Find commit hash
git reflog
# Recreate branch
git checkout -b recovered-branch <commit-hash>
Problem: Large Files Committed
# Remove from history (careful!)
git filter-branch --tree-filter 'rm -f large-file.bin' HEAD
# Or use BFG Repo-Cleaner (faster)
bfg --delete-files large-file.bin
Problem: Need to Undo Last Commit
# Keep changes, undo commit
git reset --soft HEAD~1
# Discard changes, undo commit
git reset --hard HEAD~1
# Create revert commit (if pushed)
git revert HEAD
Quick Reference
Essential Commands
# Status and info
git status
git log --oneline --graph
git branch --all
git remote -v
# Create and switch branches
git checkout -b feat/new-feature
git checkout main
# Staging and committing
git add <files>
git commit -m "message"
git commit --amend
# Syncing with remote
git fetch origin
git pull origin main
git push origin feat/branch
git push --force-with-lease
# Rebasing
git rebase origin/main
git rebase --continue
git rebase --abort
# Cleaning up
git branch -d feat/branch
git push origin --delete feat/branch
git clean -fd
# Stashing
git stash
git stash pop
git stash list
Integration with Claude Code
Automatic Commit Messages
Claude Code generates commit messages automatically:
feat: Add user authentication system
- Implement JWT token generation and validation
- Add authentication middleware for FastAPI
- Create login/logout endpoints
- Add password hashing with bcrypt
- Include comprehensive unit and integration tests
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Git Hooks Integration
NXTG-Forge hooks (.claude/hooks/) integrate with git workflow:
- Pre-task: Validates git status, warns of uncommitted changes
- Post-task: Suggests creating commits for completed work
- On-file-change: Tracks changes, updates state
- On-error: Suggests checkpoints before major fixes
Last Updated: 2026-01-06 Version: 1.0.0 Workflow: Trunk-Based Development Merge Strategy: Squash and Merge
Source: nxtg-ai/forge-plugin — distributed by TomeVault.