Branching & Merging

Feature branches, merge, and rebase strategies for Python services shipping pyproject.toml, lockfiles, and Alembic migrations together.

Recipe

git checkout main && git pull --rebase origin main
git checkout -b feat/api-91-refunds
# work ...
git fetch origin && git rebase origin/main
git push -u origin feat/api-91-refunds
# open PR -> squash merge to main after CI green

When to reach for this:

• Starting ticket work isolated from main
• Integrating latest main before PR review
• Cutting release/x.y trains with Django/FastAPI apps
• Backporting hotfixes with cherry-pick

Working Example

# Feature branch lifecycle
git switch -c feat/worker-retries main
uv run pytest -q
git commit -am "feat(worker): retry smtp errors [WRK-12]"
git fetch origin
git rebase origin/main
# conflict in uv.lock -> regenerate lock after resolving pyproject
uv lock
git add pyproject.toml uv.lock
git rebase --continue
git push --force-with-lease origin feat/worker-retries

What this demonstrates:

• Branch from updated main
• Rebase integrates upstream without merge commits on feature branch
• Lockfile conflicts resolved by regeneration not manual edit
• Force-with-lease safe force push after rebase

Deep Dive

How It Works

• Fast-forward - Branch pointer moves when no divergent commits.
• Merge commit - Combines two histories with merge node.
• Rebase - Replays commits on new base - rewrites SHAs.
• Squash merge - PR becomes one commit on main.

Branch Types

Python Notes

# Cherry-pick migration fix to release branch
git switch release/2.3
git cherry-pick abc1234  # commit with Alembic revision
uv run alembic upgrade head
uv run pytest -q

Gotchas

• Long-lived feature branches - Lockfile and migration conflicts explode. Fix: merge or rebase main daily.
• Squash losing revert info - Hard to bisect. Fix: meaningful PR title becomes squash message.
• Rebase after PR review started - Confuses reviewers with force push. Fix: communicate or merge instead.
• Merging main into release/* - Pulls unvetted features. Fix: cherry-pick only.
• Alembic revision conflicts - Duplicate heads after parallel branches. Fix: merge heads migration before deploy.
• Binary wheel conflicts - Rare in git; large artifacts should not be in repo. Fix: Git LFS or package index.

Alternatives

FAQs

Related

• Essential Git Commands - daily commands
• Merge Conflict Resolution Checklist - calm process
• Git Worktrees - parallel checkouts
• CI/CD Pipelines - branch protections

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.