Using skip-existing in Repeatable Image Pipelines

Image conversion often happens more than once. A team converts a folder for launch, then adds three new product photos a week later, then updates one hero image after a design review. Re-running the full conversion every time can waste time and may overwrite outputs that have already passed review.

That is where --skip-existing helps. In GetWebP CLI, it tells the converter to skip an output file when that file already exists. Used carefully, it supports repeatable image pipelines. Used carelessly, it can hide stale outputs and mixed settings.

Treating --skip-existing as a magic repeatability switch is a mistake. It does not compare source hashes, read a review manifest, or prove that an existing .webp was created from the latest source. It only checks whether the computed output path already exists.

Use It for Incremental Additions#

The cleanest use case is adding new source images to an existing folder:

getwebp ./images/originals \
  -o ./images/optimized \
  --quality 82 \
  --skip-existing

Existing outputs stay in place. New files are generated. This is useful when a folder receives a few new blog images, product photos, or documentation screenshots after an initial conversion.

The assumption is that the existing outputs are still approved and that the same settings remain appropriate.

Write that assumption down. A repeat run is safe only when these are true:

Do Not Use It to Change Quality Settings#

If you change the quality setting and also use --skip-existing, old files may remain at the old setting while new files use the new setting:

getwebp ./images/originals \
  -o ./images/optimized \
  --quality 88 \
  --skip-existing

That may be intentional, but often it is accidental. The folder now contains outputs created under different rules. If the goal is to regenerate everything at a new setting, do not skip existing files. Use a new output folder or clean the generated folder after confirming originals are safe.

Record Why a Repeat Run Happened#

Repeatable pipelines need a short log. It can be as simple as:

2025-10-16
Command: getwebp ./originals -o ./optimized --quality 82 --skip-existing
Reason: added five new product photos
Reviewed: product detail page and category cards

This helps later when someone asks why some files have newer timestamps or why the output folder changed after launch.

For CI or agent workflows, keep the structured report too:

mkdir -p ./reports

getwebp ./images/originals \
  -o ./images/optimized \
  --quality 82 \
  --skip-existing \
  --json > ./reports/repeat-run.ndjson

The JSON output reference documents skipped per-file results. In a convert.completed event, skipped files appear with status: "skipped" and reason: "existing".

jq -r '
  select(.type == "convert.completed")
  | .data.results[]
  | select(.status == "skipped")
  | [.file, .reason]
  | @tsv
' ./reports/repeat-run.ndjson > ./reports/skipped-files.tsv

That list is not proof that the skipped outputs are current. It is a list of files the repeat run did not regenerate.

Pair It With Dry Run#

Before a repeat run, preview the input set:

getwebp ./images/originals \
  -o ./images/optimized \
  --quality 82 \
  --dry-run

Dry run helps confirm that the command points to the intended folder and format. In GetWebP CLI, --dry-run previews which files would be considered and writes nothing. It should not be used as proof that existing outputs are fresh or visually approved.

--skip-existing then controls the real repeat run:

getwebp ./images/originals \
  -o ./images/optimized \
  --quality 82 \
  --skip-existing

The two steps solve different problems: preview reduces path mistakes, while skip behavior avoids rewriting approved outputs.

Watch for Stale Source Changes#

--skip-existing can be risky when a source file changes but the output filename stays the same. For example, homepage-hero.jpg might be replaced with a new design, but homepage-hero.webp already exists. If the pipeline skips it, the published WebP may not reflect the updated source.

This is why filenames and manifests matter. If the image identity changes, consider changing the filename or explicitly regenerating that output. If only a new file was added, skipping existing outputs is safer.

A simple source manifest can record the source identity before a repeat run:

find ./images/originals -type f \
  \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.webp' -o -iname '*.avif' -o -iname '*.heic' -o -iname '*.heif' \) \
  -print0 |
  sort -z |
  xargs -0 shasum -a 256 > ./reports/source-manifest.sha256

Compare that manifest with the previous approved run. If a source hash changed and the output path already exists, --skip-existing will skip the file unless you regenerate it intentionally.

If your installed CLI supports --manifest, remember that a manifest written during a --skip-existing run records successful conversions from that run. Skipped existing files may need a previous manifest or separate inventory record so the audit trail remains complete.

Check Output Name Collisions#

--skip-existing works at the output path. That makes naming collisions important:

images/originals/team/photo.jpg
images/originals/team/photo.png
images/optimized/photo.webp

When two sources map to the same output filename, one existing output can cause a later source to be skipped or overwritten depending on the command. GetWebP warns about output filename conflicts, but teams should prevent the pattern with naming rules.

Before a recursive repeat run, check for duplicate output basenames:

find ./images/originals -type f \
  \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.webp' -o -iname '*.avif' -o -iname '*.heic' -o -iname '*.heif' \) \
  -exec basename {} \; |
  sed -E 's#\.[^.]+$#.webp#' |
  sort |
  uniq -d

If this prints names, fix the source naming or split the run before relying on --skip-existing.

Use Separate Output Folders for Major Rebuilds#

For major redesigns, quality-setting changes, or format strategy changes, create a new output folder:

optimized-webp-q82/
optimized-webp-q88-test/

Then review the new folder before replacing the published assets. This avoids half-updated folders and gives the team a clear rollback path.

Review the Output Folder After Running#

After using --skip-existing, inspect the output folder:

• were the expected new files created?
• did old approved files remain untouched?
• are timestamps consistent with the intended run?
• did any source change fail to regenerate?
• does a sample from the new files pass visual review?
• do skipped files match the intended skip list?
• did the run emit any conflict or truncation warning?

Do not assume a successful command means a successful publishing update.

Decide Who Can Regenerate Existing Files#

In a team workflow, not every repeat run should have the same authority. Content editors may be allowed to add new approved images with --skip-existing, while a developer or design lead may own full regeneration when settings change.

This boundary keeps routine additions fast without letting quiet rebuilds change every published asset. It also clarifies who reviews the visual result when an existing file is intentionally replaced.

Keep Format Decisions Grounded#

Google's WebP documentation explains the format used by the outputs, while MDN's image file type guide helps teams decide when WebP, PNG, JPEG, SVG, or AVIF should be used.

--skip-existing is not a quality setting and not a migration strategy by itself. It is a repeat-run control. Use it when the existing outputs are still valid, avoid it when settings or sources changed, and document the reason every time a pipeline is repeated.