Git Workflow

---
name: Git Workflow
description: Defines git workflow patterns including branching strategy, commit conventions, and PR practices.
---

# 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`

```bash
# 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:

- `develop` branch
- `release` branches
- `hotfix` branches (fix directly from main)

---

## Workflow Steps

### 1. Start New Work

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```markdown
## 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

1. **Self-review**: Review your own PR first
2. **CI checks**: Ensure all CI checks pass
3. **Request review**: Tag appropriate reviewers
4. **Address feedback**: Respond to all comments
5. **Approval**: Get at least one approval
6. **Merge**: Squash and merge to main

---

## Merge Strategies

### Squash and Merge (Default)

Combines all commits into a single commit on main:

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Create branch from current state
git checkout -b recover-branch

# Or discard changes and return to branch
git checkout main
```

### Problem: Accidentally Deleted Branch

```bash
# Find commit hash
git reflog

# Recreate branch
git checkout -b recovered-branch <commit-hash>
```

### Problem: Large Files Committed

```bash
# 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

```bash
# 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

```bash
# 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