Branch Integration Workflow

Experiment Overview

| Item | Details | |------|---------| | Date | 2024-12-31 | | Goal | Safely review and integrate remote branches when gh CLI unavailable | | Environment | Git repository with multiple remote feature branches | | Status | Success |

Context

Problem: Need to review and merge remote branches, but gh CLI may not be available. Must safely identify which branches can merge cleanly and which have conflicts.

Solution: Use git commands to analyze branches, test merges non-destructively, and integrate cleanly.

Verified Workflow

1. Fetch All Remote Branches

# Update local references to all remote branches
git fetch --all

# List all remote branches
git branch -r

Example output:

origin/claude/python-3.14-upgrade-analysis-fmdvv
origin/claude/update-training-v2.7.0-Zl9eH
origin/feature/v3.0-multi-agent
origin/release/v2.3.0
origin/stable

2. Analyze Branch Status

Check how far behind/ahead each branch is relative to stable:

# For each branch, check commits ahead/behind stable
for branch in origin/claude/python-3.14-upgrade-analysis-fmdvv origin/feature/v3.0-multi-agent; do
  echo "=== $branch ==="
  git log $branch --oneline -3
  echo "Behind stable by:"
  git rev-list --count $branch..stable
  echo ""
done

3. Build Analysis Table

| Branch | Behind Stable | Content Summary | Recommendation | |--------|---------------|-----------------|----------------| | claude/python-3.14-* | 4 commits | Docs, CI updates | Merge | | claude/update-training-* | 4 commits | Tests, notebook | Merge | | feature/v3.0-* | 14 commits | Major feature | Review conflicts | | release/v2.3.0 | 105 commits | Old release | Delete |

4. Test Merge Non-Destructively

CRITICAL: Always test merge before actually merging.

# Ensure clean working directory
git stash  # if needed

# Create temporary test branch from stable
git checkout -b test-merge-branch stable

# Attempt merge without committing
git merge --no-commit --no-ff origin/branch-name

Possible outcomes:

• "Automatic merge went well" → Safe to merge
• "CONFLICT" → Needs manual resolution

# Check what would be merged
git diff --cached --stat

# Abort the test merge
git merge --abort

# Clean up test branch
git checkout stable
git branch -D test-merge-branch

# Restore stashed changes
git stash pop  # if stashed earlier

5. Merge Clean Branches

Once confirmed clean:

# Merge with automatic commit message
git merge origin/branch-name --no-edit

# Or with custom message
git merge origin/branch-name -m "Merge branch-name: description"

6. Run Tests After Merge

# Always verify after merge
python -m pytest tests/ -v --tb=short

7. Handle Branches with Conflicts

For branches that don't merge cleanly:

# Check specific conflicts
git checkout -b resolve-conflicts stable
git merge --no-commit origin/conflicting-branch

# See conflicted files
git status | grep "both modified"

# Example output:
# both modified: CLAUDE.md
# both modified: alpaca_trading/training/__init__.py

Options:

1. Defer: Complex conflicts may need dedicated session
2. Resolve: Simple conflicts can be fixed manually
3. Rebase: Branch author should rebase onto stable first

8. Delete Obsolete Branches

For branches significantly behind with no unique value:

# Delete local branch
git branch -D old-branch

# Delete remote branch (if authorized)
git push origin --delete old-branch

Decision Matrix

| Commits Behind | Merges Cleanly | Action | |----------------|----------------|--------| | < 10 | Yes | Merge immediately | | < 10 | No | Review conflicts, resolve if simple | | 10-50 | Yes | Merge, verify tests carefully | | 10-50 | No | Defer - significant conflict resolution needed | | > 50 | Any | Likely obsolete - consider deleting |

Failed Attempts

| Attempt | Why it Failed | Lesson Learned | |---------|---------------|----------------| | Merge without testing first | Conflicts discovered mid-merge, messy abort | Always test with --no-commit first | | Merge multiple branches at once | Hard to identify which caused test failures | Merge one at a time, test between | | Assume clean merge = safe | Tests can still fail after clean merge | Always run tests after merge | | Force push to fix bad merge | Rewrites history, breaks collaborators | Never force push to shared branches | | Skip stashing local changes | Test merge fails due to dirty working tree | Always start with clean working directory |

Commands Reference

# List remote branches
git branch -r

# Check branch divergence
git rev-list --count stable..origin/branch  # Commits in branch not in stable
git rev-list --count origin/branch..stable  # Commits in stable not in branch

# Find common ancestor
git merge-base stable origin/branch

# See branch commit history
git log origin/branch --oneline -10

# Test merge (non-destructive)
git merge --no-commit --no-ff origin/branch

# See merge changes
git diff --cached --stat

# Abort test merge
git merge --abort

# Actual merge
git merge origin/branch --no-edit

# Delete remote branch
git push origin --delete branch-name

Checklist

• [ ] Fetch all remote branches
• [ ] Analyze each branch (commits behind, content summary)
• [ ] Build decision table
• [ ] For each merge candidate:
  • [ ] Stash local changes if needed
  • [ ] Create test branch
  • [ ] Test merge with --no-commit
  • [ ] Review changes with git diff --cached --stat
  • [ ] Abort test merge
  • [ ] Delete test branch
  • [ ] Restore stash if needed
• [ ] Merge clean branches one at a time
• [ ] Run tests after each merge
• [ ] Push merged changes

Key Insights

• Test before merge: --no-commit --no-ff is non-destructive
• One at a time: Merge branches individually to isolate issues
• Tests are truth: Clean merge doesn't guarantee working code
• Old branches decay: >50 commits behind usually means obsolete
• Clean working tree: Stash changes before testing merges

References

• Git merge documentation: https://git-scm.com/docs/git-merge
• Example session: Merged python-3.14-upgrade and update-training-v2.7.0 branches