split-commit-into-stack

Split Commit Into Stack

Turn one large commit into a stack where each PR is a coherent story that compiles and passes on its own. The work is mostly analysis: the mechanics are five commands, but choosing the cut and proving it holds is where the value is.

Most of the cost of a big PR is that a reviewer cannot tell which changes belong to which decision. A split earns its keep when it separates decisions, not when it merely reduces line count.

Step 0: Measure before proposing anything

Measure the whole branch against its base, not the tip against its parent: a branch that already holds several commits is split as one diff, and HEAD~1 would silently measure, inspect and later reset only the last of them.

base="$(git merge-base "$(gt parent)" HEAD)"   # the branch's base, whatever the commit count
git --no-pager log --oneline "$base"..HEAD     # several commits that already match the concerns: see Graphite notes
git --no-pager diff --numstat "$base" HEAD | awk '{i+=$1;d+=$2; printf "+%-6d -%-6d %s\n",$1,$2,$3} END {printf "TOTAL +%d -%d\n",i,d}'
git --no-pager diff --name-status "$base" HEAD

Every later step reads "$base" from this shell, so run them in the same one or set it again.

Two numbers change the conversation before any splitting is discussed:

• Production vs test insertions. A 3,500-line diff where 1,000 lines are one new test file is not a 3,500-line review. Report the production-only figure; sometimes it dissolves the problem and no split is warranted.
• Per-concern totals. Group files by concern (below) and total each. If one group is 85% of the diff and is atomic, splitting the remaining 15% is the entire available win
  • say so plainly rather than proposing a heroic three-way split.
• Whether one file serves both concerns. Two or three such files is normal and Step 4 usually dissolves them; a dozen means the concerns are not actually separable and the honest answer is to leave the commit whole.

Use --name-status and not just --numstat: added (A) and deleted (D) files change what the git add commands must look like, and a deletion left in the wrong PR breaks the build in a way that is annoying to diagnose later.