Add Branch Hygiene workflow section to SUBAGENT_WORKFLOW.md

Document:
- How to detect contamination via git log and branch --contains
- Prevention with explicit base: git checkout -b new-branch main
- Fix using git rebase --onto
- Force push with --force-with-lease for safety

Addresses Issue #1 comment 281
This commit is contained in:
shokollm
2026-03-27 11:32:45 +00:00
parent dc26098918
commit bb11d665a3

View File

@@ -91,3 +91,80 @@ OPEN → IN_PROGRESS (subagent claims it)
- Research/docs: `docs/issue-{N}-{short-title}`
- Fixes/tools: `fix/issue-{N}-{short-title}`
## Branch Hygiene
When branches are created incorrectly (e.g., from HEAD instead of main), they become contaminated with unwanted commits. This section provides a standard workflow for detecting and fixing this.
### How Contamination Happens
- Running `git checkout -b new-branch` (without explicit base) creates a branch from the current HEAD
- If HEAD is not aligned with main (e.g., detached HEAD, or a different branch), the new branch inherits that history
- The branch then contains commits that don't belong to the intended base
### Detection
**Symptom:** `git log` shows commits from a different/wrong branch at the start of the history.
**Command to identify contamination:**
```bash
# Find commits that exist in wrong-branch but not in main
git log main..wrong-branch --oneline
# Check if a specific commit is contained in main
git branch --contains <commit-id>
# If empty output, the commit is NOT in main (contamination)
# Or compare the first commit of your branch to main's tip
git merge-base main your-branch
# If this doesn't match the first commit on your branch, there's contamination
```
### Prevention
**Always use explicit base when creating branches:**
```bash
# Correct - branch from main explicitly
git checkout -b new-branch main
# Incorrect - branch from current HEAD (may not be main)
git checkout -b new-branch # DANGEROUS if HEAD isn't main
```
### Fix Procedure
If contamination is detected, use `git rebase --onto` to move the branch to the correct base:
```bash
# Syntax: git rebase --onto <new-base> <old-base> <branch-to-move>
git rebase --onto main wrong-branch new-branch
# Example:
# - main is the correct base
# - wrong-branch is the contaminated branch (the old base that was used incorrectly)
# - new-branch is your current branch that has wrong commits
# After rebase, verify with:
git log --oneline main..
git branch --contains <original-first-commit-id> # Should be empty
```
### Force Push with Lease
After rebasing, a force push is required. Use `--force-with-lease` for safety:
```bash
git push --force-with-lease origin new-branch
```
`--force-with-lease` is safer than `--force` because it will fail if someone else has pushed to the branch since you last fetched, preventing accidental overwrites.
### Quick Reference
| Scenario | Command |
|----------|---------|
| Create clean branch | `git checkout -b new-branch main` |
| Detect contamination | `git log main..my-branch` (if non-empty, contaminated) |
| Check commit presence | `git branch --contains <commit-id>` |
| Fix contaminated branch | `git rebase --onto main wrong-base my-branch` |
| Safe force push | `git push --force-with-lease origin my-branch` |