Keep image weight out of Git history with a pre-commit workflow

Large images do more than slow a page. Once committed, their original blobs remain part of Git history even if a later commit replaces them with smaller files. For teams trying to shrink Git repository size, the useful moment to act is before the first commit that adds the asset.

A workable stack is PiPic’s open-source CLI plus a Git pre-commit check. The CLI handles compression; the hook makes it harder to forget. The important detail is order: select staged images, compress those files, then update the staged snapshot before Git creates the commit.

Start with a narrow scope

Install the PiPic CLI package, published on npm as @pipic/cli, and follow its current documentation for the actual invocation. PiPic says the CLI can compress a folder in place or write to a fresh directory. For a commit gate, in-place replacement is the simpler path, but keep a clean checkout or another recoverable copy while testing the workflow.

PiPic supports JPG, PNG, WebP and AVIF images, with a limit of 8 MB per file and batches of up to 100. The CLI tier includes 100 images per month; its Pro plan covers 5,000 per month. These limits make it important to target changed assets rather than rescan a repository on every commit. A diff-based approach is also the focus of a workflow for protecting image quotas in monorepos.

Define which directories and formats count as web media. Exclude generated files, source artwork that should remain untouched, and any asset whose format or size falls outside the tool’s stated limits. A hook should report excluded files clearly rather than silently implying they were optimized.

Wire compression into the commit path

1. Have the hook read the staged path list and filter it to eligible image files. Use staged additions and modifications, not every image found in the working tree. This keeps unrelated local changes out of the operation.

2. Pass only those selected paths to the PiPic CLI, using the documented command and mode. If the selected set exceeds the supported batch size, split it into batches of no more than 100. Do not send files above 8 MB to the compressor; choose a separate review or rejection policy for them.

3. After compression, add the changed image paths to the index again. Git commits the index, not simply whatever happens to be in the working directory. Without this restaging step, the commit may contain the original staged image while the smaller file remains as an unstaged change.

4. Make failures visible. If compression fails, the service cannot be reached, or the monthly allowance is exhausted, stop the commit with a useful message. Do not silently let the original file through if the team’s rule is that new web assets must be compressed.

The hook should avoid touching already-staged non-image files and should not rewrite images that were not part of the staged change. Test it with a new image, a modified image, an unrelated staged text file, and a failure case. Keep the hook implementation small enough that a developer can tell which files it will change.

Check the result, not just the exit code

Compression is not a substitute for review. Inspect representative images after the first run, especially photographs with fine texture, transparent graphics, and assets where small visual defects are easy to notice. PiPic says it preserves dimensions and returns the same format; still confirm that the output works in the application and that the commit contains the intended version.

PiPic’s CLI sends the image being compressed to its service, not repository metadata, according to its published description. Files are deleted from PiPic’s servers immediately after compression, and the CLI states that it sends no telemetry. That may fit a team’s handling rules, but it is still a service upload. Check internal policy before using it on confidential or restricted assets.

Know what this does not fix

A pre-commit hook prevents some oversized assets from entering new commits. It does not erase large blobs already present in earlier commits, nor does it make a repository small again after an oversized file has been committed. Those cases require a separate Git asset cleanup decision, with coordination because rewriting shared history affects collaborators.

There is also a trade-off in making the hook a hard gate: a network-dependent compression step can block work when the service is unavailable or the monthly allowance runs out. Teams should decide who manages the CLI account and whether exceptional commits have a documented review path. The CLI offers 100 free images per month and a 5,000-image Pro plan; estimate usage from changed assets, not the total repository inventory.

For a deeper look at staged-file handling, the pre-commit design checklist covers the failure and restaging details that determine whether this guard actually protects history. The core rule is straightforward: compress only the staged images you intend to commit, then make sure the compressed bytes—not the old staged version—are what Git records.