Precommit Large File Gate

Workflow

1. Enumerate staged files: use git diff --cached --name-only to get the list of files staged for commit.
2. Measure each file's size: run git cat-file -s :<filepath> to get the blob size without reading the file to disk.
3. Apply threshold rules: compare each file's size against the threshold table; classify as allow, warn, or block.
4. Check against the allowlist: for any file that would be blocked, check its path against the allowlist in ./thresholds-and-allowlists.md; downgrade to warn if it matches.
5. Emit actionable block message: if any file is blocked, print:

   ERROR: <filepath> is <size>KB, exceeding the <threshold>KB pre-commit limit.
   To remove from staging: git restore --staged <filepath>
   To add a permanent allowlist exception: update precommit-large-file-gate/thresholds-and-allowlists.md
   

6. Exit with correct code: exit 1 (block) if any file exceeds its threshold and is not allowlisted; exit 0 (allow) otherwise.
7. Run the test matrix: verify behavior against the cases in ./test-matrix.md — at minimum: 1-byte file (allow), threshold-exact file (warn), threshold+1 file (block), allowlisted large file (allow).

References

• Thresholds and Allowlists
• Enforcement Pattern
• Test Matrix