Two Commits per Refactor: A Diff Gate That Keeps Pins Away From the Move

Refactoring messy repositories often stumbles during review rather than at execution. The most perilous commit is the one that intertwines test files with production code. This makes it impossible to distinguish between defective pins and faulty moves. Characterization tests serve a single purpose: verifying that behavior remains consistent.

This reliability hinges on keeping pins separate from moves. To enforce this separation, a script rather than human discipline should be employed. Step 1 involves defining which paths are pins and which are moves; a machine-readable map of the repository is required. Ambiguity can bring the gate to a halt. A minimal configuration file at the repository root is necessary to clarify this distinction.

The config file consists of three categories: test_globs, code_globs, and neutral_globs. Anything not fitting into these categories is considered an error, not a silent pass. A key point to note is that Python's fnmatch function allows '*' to match across directory boundaries. Consequently, tests/** includes all files within the 'tests' directory, which differs from gitignore syntax.

It is crucial not to presume that teammates interpret the globs in the same manner as the script author. Step 2 entails classifying each commit diff according to the aforementioned categories. This script is a proposed pattern, not a pre-existing tool. It is concise enough to be manually reviewed line by line. The script is named split_gate.py and can be invoked with a revision range, defaulting to the last commit (HEAD~1..HEAD).

The script will exit with different codes depending on the outcome: 0 for a clean commit, 1 for a mixed commit, 2 for an unclassified path, or 3 for a git error.