Git ops

Git-Ops: PRs + Rebases

History is a story other people read. Each commit should be a coherent, revertible step; each PR a reviewable unit. Optimize for the reviewer and for the person who runs git blame in a year.

Note: this environment does not support interactive git (git rebase -i, git add -i). Use the non-interactive techniques below. Use gh for GitHub operations. Only commit/push when asked; if you're on the default branch, branch first.

Branching & commits

• Branch off an up-to-date base: git fetch && git switch -c feat/short-topic origin/main. Name by intent (fix/…, feat/…, chore/…).
• Commit in logical units: one concern per commit, each one leaving the tree in a working state. Stage selectively (git add -p where supported, or by path) — don't git add -A a mixed bag.
• Commit messages: imperative subject ≤ ~50 chars ("Add rate limit to login"), blank line, then why in the body — the diff already shows what. Reference the issue/ticket.
• Never commit secrets, .env, build output, or debug logging. Check git diff --staged before every commit.

Keeping a branch current (rebase over merge)

• Prefer rebasing your feature branch onto the latest base for a linear, readable history: git fetch origin && git rebase origin/main.
• Reserve merge for integrating finished branches into the base (or when the branch is shared and others have based work on it — don't rebase shared history out from under people).
• After a rebase you must force-push with lease: git push --force-with-lease (never bare --force — lease refuses if someone else pushed, preventing clobbering their work). The harness denies bare --force; use the lease form.

Non-interactive rebase recipes

Since -i isn't available here:

• Squash a whole branch into one commit: git reset --soft $(git merge-base HEAD origin/main) && git commit -m "…" — moves the branch pointer back but keeps all changes staged, then one clean commit.
• Amend the latest commit: git commit --amend (message) or git add <files> && git commit --amend --no-edit (content).
• Undo the last commit, keep changes: git reset --soft HEAD~1.
• Autosquash fixups: commit with --fixup=<sha>, then git rebase --autosquash origin/main (non-interactive with GIT_SEQUENCE_EDITOR=true).
• Drop/reorder specific commits: cherry-pick the ones you want onto a fresh branch from base, in the order you want.

Resolving conflicts

• Read both sides before editing; understand why each change exists rather than blindly picking one. git log --merge -p <file> shows the conflicting commits.
• Resolve to what's correct, which may be neither side verbatim. Remove every conflict marker (grep -rn '^<<<<<<<\|^>>>>>>>\|^=======' to be sure none survive).
• After resolving: git add the files, run the tests/typecheck (pnpm test), then git rebase --continue. A build-broken "resolved" conflict is not resolved.
• git rebase --abort is always a safe escape hatch if it gets messy — back out and retry deliberately.

Authoring the pull request

• Title: what changes, imperatively. Body: the problem, the approach, and how you verified it (tests run, manual check). Link the issue.
• Keep PRs small and single-purpose — a 200-line focused PR gets a real review; a 2,000-line grab-bag gets a rubber stamp.
• Justify any new dependency in the PR body (project rule) — what it's for and why an existing tool won't do.
• Call out risk explicitly: migrations, config/env changes, anything not covered by tests, and the rollback plan.
• Self-review the diff first (/code-review on your working tree) and make sure CI is green before requesting review. Open with gh pr create.
• Respond to every review comment (change or explain); push follow-up commits during review, and squash to a clean history before merge if the team squashes.

Guardrails

• Don't rewrite history that's already merged or that others have pulled.
• Don't force-push shared branches; --force-with-lease only, on your own branch.
• Treat db/migrations/* as append-only after merge — new migration, never edit the old one (project rule + harness guard).
• Don't push unless asked. Confirm the target branch and remote before any push.