Skip to content

README.md

Latest commit

 

History

History
executable file
·
180 lines (123 loc) · 6.11 KB

README.md

File metadata and controls

executable file
·
180 lines (123 loc) · 6.11 KB
Raw

Pre-commit hooks for image optimization

This directory contains pre-commit hooks that automatically optimize images before they are committed to the repository.

What the hooks do

  • Automatically detect staged image files (.png, .jpeg, .jpg, .gif, .svg)
  • Run image_optim to compress and optimize raster images (.png, .jpeg, .jpg, .gif)
  • Re-stage optimized images automatically
  • Ensure all committed raster images are properly optimized
  • Check staged SVGs against a size limit and abort the commit if an oversized SVG is referenced from any file in help/ (otherwise just warn)

Benefits

  • Reduced repository size
  • Faster page loads for documentation
  • Consistent image quality across all contributors
  • No manual optimization required

Prerequisites

  • Ruby 3.0 or higher
  • Bundler
  • Git

Setup

Automatic setup (Recommended)

.githooks/setup-hooks.sh

Manual setup

git config core.hooksPath .githooks
chmod +x .githooks/*

Complete project setup

  1. Clone the repository:

    git clone <repository-url>
cd commerce-operations.en

  2. Enable pre-commit hooks:

    .githooks/setup-hooks.sh

  3. Install Jekyll dependencies:

    cd _jekyll
bundle install

Testing the hooks

  1. Add an image file to your repository
  2. Stage it: git add <image-file>
  3. Try to commit: git commit -m 'test'
  4. The hook should automatically optimize the image

Expected output

Found 1 staged image(s). Running optimization...

Checking images ...
path/to/your/image.png    100.00%
Pre-commit image checks complete!

Unit tests

The hook's SVG link-detection logic (which decides whether an oversized SVG is referenced from help/) is covered by unit tests that need only Ruby's bundled minitest — no gems or _jekyll setup:

ruby .githooks/test/svg_link_checker_test.rb

Image guidelines

  • PNG: Use for screenshots and UI elements (will be optimized automatically)
  • JPEG: Use for photographs (will be optimized automatically)
  • GIF: Use for animations (will be optimized automatically)
  • SVG: Use for icons and simple graphics (not optimized, but checked against a size limit; commit fails only if the oversized SVG is linked from help/)

The pre-commit hooks will automatically optimize .png, .jpeg/.jpg, and .gif images on commit, and will check staged SVGs against a size limit (140 KB).

If a staged SVG exceeds the limit and is referenced from a file in help/, the commit is aborted. If the oversized SVG isn't referenced anywhere in help/, the hook only prints a warning and the commit proceeds. Convert oversized SVGs to PNG instead:

cd _jekyll
bundle exec rake images:svg_to_png path=../help/assets/image.svg

The path is relative to _jekyll, so images under help/ are referenced as ../help/....

Manual optimization

For manual image optimization:

cd _jekyll
bundle exec rake images:optimize path=../path/to/images

Configuration

The hooks use the configuration file _jekyll/.image_optim.yml to customize optimization settings:

  • PNG: Uses advpng, optipng, and pngquant
  • JPEG: Uses jhead, jpegoptim, and jpegtran
  • GIF: Uses gifsicle
  • SVG: Not optimized (excluded from image_optim to preserve vector graphics and animations), but checked against a 140 KB size limit

Troubleshooting

Hook not running

  • Check hook configuration: git config core.hooksPath
  • Ensure the hook file is executable: chmod +x .githooks/pre-commit
  • Verify you're in the correct repository with _jekyll directory

Optimization failures

  • Verify bundle install has been run in the _jekyll directory
  • Check that the adobe-comdox-exl-rake-tasks gem is installed (provides the images:optimize, images:check_size, and images:svg_to_png rake tasks the hook runs)
  • Review the .image_optim.yml configuration file

SVG exceeds size limit

  • The commit is aborted if a staged SVG exceeds 140 KB and is referenced from a file in help/ (otherwise the hook only warns and the commit proceeds)
  • Convert the SVG to PNG: cd _jekyll && bundle exec rake images:svg_to_png path=../help/assets/image.svg (the path is relative to _jekyll, so images under help/ are referenced as ../help/...)
  • Then stage the PNG in place of the SVG and commit again

Performance issues

  • Adjust thread count in _jekyll/.image_optim.yml
  • Set DEBUG=1 environment variable for detailed error information

How it works

  1. Pre-commit trigger: When you run git commit, the hook automatically executes
  2. Image detection: Scans staged files for image extensions
  3. Optimization: Runs image_optim on each staged PNG, JPEG, or GIF
  4. Re-staging: Automatically adds optimized images back to the staging area
  5. SVG size check: Checks each staged SVG against the 140 KB size limit
  6. Commit proceeds: If optimization succeeds and no oversized SVG is referenced from help/, the commit continues normally; otherwise the commit is aborted (an oversized SVG not referenced from help/ only triggers a warning)

Supported image formats

  • PNG (.png) - Lossless and lossy compression
  • JPEG (.jpg, .jpeg) - Lossy compression with metadata cleanup
  • GIF (.gif) - Animation and static optimization
  • SVG (.svg) - Not optimized (commit as-is to preserve quality), but checked against a 140 KB size limit; the commit is aborted if the limit is exceeded and the SVG is referenced from help/ (otherwise the hook only warns)

Best practices

  1. Test the hook: Try committing a small image first to ensure it works
  2. Review changes: Check the git diff to see optimization results
  3. Monitor performance: Large images may take time to optimize
  4. Version control: Hooks are stored in this .githooks/ directory

Support

For issues with the pre-commit hooks:

  1. Check the hook output for error messages
  2. Verify your image_optim setup is working
  3. Test with the manual rake tasks first
  4. Review the hook logs and configuration
  5. Check the hook configuration: git config core.hooksPath