Put image compression before the commit, not after it

Images often enter a repository through a routine commit: a new product screenshot, a revised illustration, a handful of photos. If nobody checks their weight, those files become part of project history, where later compression will not remove the earlier copies. A pre-commit image-compression hook moves the check to the point where it can prevent that first addition.

The practical shift is not a new image format. It is treating compression as a local repository rule rather than a cleanup task after a page feels slow or a clone takes too long. PiPic offers an open-source CLI published as @pipic/cli for scripted compression. The exact command and hook configuration should come from its current CLI documentation; the important design is the sequence around that command.

Make the hook work from the staged set

A pre-commit hook runs before Git creates a commit, but there is a distinction that matters: files in the working tree are not necessarily identical to the versions already staged. A hook that compresses a path in place can accidentally pick up unrelated edits, or leave the compressed result outside the staged snapshot. Either outcome makes the commit less predictable.

Build the hook around staged paths. Have it identify newly added or modified image files, limit its scope to the formats your project accepts, and skip deleted files. Before changing a file, check whether its working-tree contents differ from the staged version. The safest simple policy is to stop and ask the developer to resolve that difference first. A more involved hook can extract the staged version to a temporary location, compress it, and update the index from that result.

When compression changes a working-tree file, the hook must add that exact path to the index again. Otherwise, the commit may still contain the pre-compression version. Keep the file list narrow: do not stage every changed file in the repository just because one image needed processing.

Set limits and failure rules before adoption

PiPic handles JPG, PNG, WebP and AVIF images up to 8 MB per file. That ceiling is a useful place to define an explicit exception path. A hook should report an over-limit file and stop, or route it through a documented manual review. Silently skipping it defeats the purpose: the commit succeeds and the uncompressed image enters history without anyone noticing.

Quota is another operational constraint. PiPic's CLI tier includes 100 free images per month, with a Pro plan for 5,000 images per month. A team making the hook mandatory should estimate how many files it will process and choose a plan that fits its usage. It should also decide what happens when the service is unavailable or the quota is exhausted. For a repository with a strict asset policy, failing the commit gives a clear signal; for a less restrictive project, an explicit, recorded override may be more practical. Avoid a silent fallback that makes enforcement look reliable when it is not.

• Process only staged image files that the project intends to keep.
• Stop on file conflicts, unsupported inputs, size limits or compression errors.
• Re-stage only files that the hook changed.
• Make any bypass visible and explain when it is acceptable.

Check the result, not just the hook status

Compression is not a substitute for asset review. Confirm that the output keeps the expected format and dimensions, and inspect visual details that can reveal damage: fine text, sharp edges, gradients and transparency. PiPic says it preserves the input format and dimensions; a repository can still add its own checks for naming, directory placement and expected file types.

Test the hook against a small set of cases before sharing it: an image that can be compressed, an image already near its target size, a file above the size ceiling, and a path with unstaged edits. Then verify the staged diff. The desired result is straightforward: the commit contains the compressed image, not a mixture of staged and unstaged work.

This local gate is different from moving compression into a build pipeline. A build step can improve generated output, but it does not necessarily keep original assets out of Git history. The distinction is covered in the earlier comparison of build-time compression and a separate CLI step. A pre-commit hook addresses repository input; a build step addresses what the project produces or serves.

For teams trying to keep a Git repository small, the rule is useful only when it is narrow, repeatable and honest about exceptions. Start with a few image directories, agree on failure behavior, and check the staged result in review. Then expand coverage. The hook should prevent avoidable bloat without turning every image commit into a mystery operation.