How do you split a large Git change into a series of commits a maintainer can review?

## Why the shape of the series matters When you cannot push to a project, your change is judged as text by someone who did not write it. Reviewers read commits, not branches. A single 2,000-line commit forces an all-or-nothing verdict and hides the interesting change inside mechanical noise; the same work as eight focused commits can be reviewed incrementally, partially approved, and — crucially — bisected later when something breaks in production a year on. ## The two invariants Two properties do most of the work. **Each commit is one logical change.** If the message needs the word "and", or a bulleted list of unrelated items, the commit is probably two commits. A useful test: could this commit be reverted on its own without breaking something unrelated? **Each commit is good on its own.** The tree at every commit should build and pass tests. This is what makes `git bisect` usable: bisect assumes intermediate commits are testable, and a series with broken middles turns a bisect run into a guessing game. It also means you never introduce a call to a function that only appears three commits later. ## Separating mechanical from semantic The highest-leverage habit is isolating changes that a reviewer can skim from changes they must think about. A rename touching 60 files, an import reordering, a formatter run, a file move — each belongs in its own commit whose message says exactly that ("rename Foo to Bar, no behaviour change"). Then the commit that alters behaviour is twenty lines and the reviewer can actually concentrate on it. Mixing the two is the most common reason a review stalls: nobody can tell which of the 60 changed files matter. ## Ordering as an argument A good series reads like a proof. Typical shapes: - **Prepare, then change.** Extract a seam or add a parameter with no callers using it; then switch the callers; then remove the old path. - **Test-first.** Add a failing test that demonstrates the bug in one commit, fix it in the next — the reviewer sees the bug is real before seeing the fix. Some projects prefer the fix and its test together so no commit is red; follow the project's convention. - **Fix, then extend.** Land the small correct fix early so it can be backported, and put the larger refactor behind it. Documentation and changelog entries usually ride with the commit they describe rather than being swept into a trailing "docs" commit. ## Messages carry the reasoning Each commit message should make the commit reviewable without the pull request or mail thread. A short imperative summary line, a blank line, then the *why*: what was wrong, what alternatives you rejected, what the reader should watch out for. The diff already says what changed; the message is where the intent lives, and it is the only part that survives into `git log` years later. ## Reshaping what you actually wrote Nobody writes a clean series on the first try — real work is committed messily and reshaped afterwards. Interactive rebase reorders, squashes and edits commits; `git add -p` splits a dirty working tree into staged pieces; `git commit --fixup` plus an autosquash rebase folds review fixes into the commit they belong to instead of appending "address review comments" commits. The important discipline is to do this reshaping *before* you send, and to fold later review fixes into the original commit rather than stacking corrections on top, so the merged history contains only the version that was agreed. ## Verifying the whole series, not the tip It is easy to test only `HEAD`. To check every commit, `git rebase -i --exec 'make test' <base>` replays the range and runs the command after each commit, stopping where it fails. `git log --oneline <base>..HEAD` and `git log -p <base>..HEAD` let you read the series the way a reviewer will. Finally, rebase onto the current upstream tip immediately before sending: a series that does not apply is a series that does not get reviewed. ## How big is too big There is no universal number, but the practical guide is reviewer attention: a commit a reviewer can hold in their head, and a series short enough to review in one sitting. When a change genuinely cannot be made small, split it by *stage* rather than by *file* — a series of ten commits each spanning the same three files but each doing one step is far more reviewable than ten commits each rewriting one file completely.