Your Screenshot Automation Is Bloating Your Git Repo

Source: Dev.to

The Problem: Screenshots Bloating the Repo

I automated my documentation screenshots a while back. Every week, one command regenerates 30+ PNGs. No more manual screenshotting. Life was good—until I checked the repo size.

• Repo size: 412 MB for a docs project.
• Why: Git stores binary files as complete copies. Each time a screenshot is regenerated—even if only one pixel changed—Git saves the entire file again.
• Impact: 30 screenshots updated weekly → ~156 MB of history per year.
• Consequences: New contributors clone the repo and wait; CI pipelines download hundreds of megabytes of old PNGs nobody will ever look at again.

Solution: Use Git LFS

Git LFS replaces your images with tiny pointer files (≈130 bytes each). The actual images live on a separate server, but checkout works normally—you don’t notice the difference.

One‑time Setup

git lfs install
git lfs track "heroshots/*.png"
git add .gitattributes
git commit -m "configure Git LFS"

Your normal Git workflow (git add, git commit, git push) stays the same. LFS handles the routing behind the scenes.

Migrating Existing Images

git lfs migrate import --include="heroshots/*.png"
git push --force-with-lease

The repo mentioned above shrank from 412 MB to 28 MB after migration.

CI Integration (GitHub Actions)

If you run screenshot updates in GitHub Actions, enable LFS during checkout:

- uses: actions/checkout@v4
  with:
    lfs: true

Without this, the CI job receives only the pointer files (130‑byte text files), causing the screenshot comparison step to fail.

When to Use Git LFS

• Skip LFS if you have a handful of screenshots that rarely change. Plain Git is fine.
• Use LFS for automated screenshot workflows:
  • 30+ images, updated weekly
  • Teams of contributors
  • Open‑source projects with many cloners

Quick Rule of Thumb

Further Reading

More details are available in the heroshot documentation.