Git workflow

Git workflow (branch to PR to merge)

When to use

Any time you move a change from your working tree into the shared history — cutting a task branch, opening or updating a PR, or digging yourself out after a bad commit. The shared branch (main) is sacred: it stays green and only receives reviewed, rebased work.

Pattern

Two guards hold the whole loop together:

1. Confirm your branch before every commit. A shared checkout or a worktree can switch under you between commands, so never assume — check, then commit.
2. Rebase onto latest main before requesting review, so CI tests the code as it will actually land, not a stale merge base.

Everything else — small PRs, honest descriptions, no reviews on red CI — falls out of protecting the shared branch.

Steps / idioms

1. Branch per task, never commit straight to main. Name by intent (feat/…, fix/…):

   git switch -c feat/tenant-filter main    # branch off a fresh main
   
   # ...work, then before EACH commit, confirm where you are:
   git branch --show-current                 # must NOT be main / a shared branch
   git add -p && git commit                  # message: see commit-message
   
   git fetch origin
   git rebase origin/main                    # replay onto latest before review
   git push -u origin HEAD                    # (push --force-with-lease after a rebase)
   

2. Keep PRs small. One reviewable idea per PR; if it grows, split it and stack the branches (each PR targets the one below it) rather than shipping a 40-file wall.

3. Write a description that answers what / why / how-to-test. Add before/after screenshots for any visual change so a reviewer verifies without checking out.

4. Don't request review on red CI. If you want early direction, open a Draft PR and say what feedback you're after; move it to Ready only once CI is green.

Resolving conflicts

A three-way merge conflict means git couldn't reconcile two edits; resolve by intent, not by mechanically picking a side.

• Lockfiles are generated, not merged. When uv.lock or pnpm-lock.yaml conflicts, don't hand-edit the hashes — take the merged manifest (pyproject.toml / package.json), then regenerate: git checkout --theirs uv.lock && uv lock, or git checkout --theirs pnpm-lock.yaml && pnpm install --lockfile-only. A manually stitched lockfile installs a set nobody resolved.
• Two migrations on one app — each branch added a migration to the same Django app, so both share a parent and the app has a branched history. Don't renumber by hand: rebase onto latest main, then python manage.py makemigrations --merge to write a tie migration that depends on both leaves. Rebasing first keeps the merge node last.
• Deleted-but-modified — one side deleted a file the other side changed, and git can't guess your intent. Decide deliberately: git rm <file> to honor the deletion, or git add <file> to keep the modified version. Never let git checkout --ours/--theirs silently drop the decision.

After any resolution, re-run the build and tests before continuing the rebase — a clean git status only means the text merged, not that it works.

Adapt to your repo

Rename the shared branch if it isn't main (master, develop, a release branch). Match your host's push protection and the branch-name convention your team uses (prefixes, ticket ids). If PRs auto-run CI, confirm the required checks before marking Ready; if you use stacked PRs, pick a tool or a plain base-branch chain and stay consistent.

Gotchas

• Amend only before you push. Rewriting a commit others may have pulled forces them into a painful reset — once it's shared, add a new commit instead.
• Undo merged history with git revert, never a force-push to a shared branch. Revert makes a new inverse commit that preserves history; force-pushing main rewrites everyone's base.
• A "lost" commit usually isn't. git reflog lists every HEAD you've been on; find the sha and git switch -c rescue <sha> (or git cherry-pick it) to recover.
• --force-with-lease over --force on your own branch — it refuses to clobber commits you haven't seen (e.g. a teammate's push to your PR).
• Rebasing a branch others share rewrites their base too; only rebase branches that are yours.

See also

• commit-message
• code-review
• ci-cd
• migrations