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.

1. 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/…):

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

1. 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.

1. 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.

1. 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 to honor the deletion, or git add 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 (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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Deadlymind
• Source: Deadlymind/nanolama
• License: MIT

Install and usage instructions live in the source repository linked above.