Every flag, and why it exists.

Synopsis

Paths may be files or directories, in any number and any mix. A bare directory covers the files directly inside it; -r descends. A failure on one file never stops the run — the exit code reflects the worst outcome, but only after every other file has been attempted.

At a glance

scrubpony photo.jpg                        writes photo.scrubbed.jpg
scrubpony a.jpg b.jpg c.jpg                many files at once
scrubpony -l photo.jpg                     list segment structure, write nothing
scrubpony -r ~/Pictures/upload              recurse a whole directory tree
scrubpony -r -d ~/clean ~/Pictures/upload  mirror the tree into ~/clean, same names
scrubpony -i -r ~/Pictures/upload           in place, atomically, per file
scrubpony -n -r ~/Pictures                 dry run: what would be removed
scrubpony --check -r ~/Pictures            exit 2 if anything carries metadata
scrubpony --strict photo.jpg               also drop ICC, APP14, APP0
scrubpony --no-keep-orientation photo.jpg  drop the orientation tag as well

Options

The four modes

Exactly one of these is in effect on any run. --check takes precedence over -l, which takes precedence over -n; with none of them set, the tool scrubs.

Where the output goes

By default, beside the input: photo.jpg becomes photo.scrubbed.jpg. Fine for one photo and unpleasant across four thousand, where it leaves a tree of double the size with two versions of everything interleaved.

With -d DIR, the source tree is mirrored under the target, filenames unchanged, and the originals are never touched. This is the mode to reach for on a whole library. The two trees may not nest in either direction; that is refused rather than allowed to loop — an output directory inside the source means the second run reads what the first one wrote, and a source inside the output means scrubbing the scrubbed copies. Both are loops that look like progress.

With -i, the destination is the source. The temporary still lands beside it and is renamed over the top, so the original is replaced in one indivisible step or not at all. -i and -d ask for opposite things and are refused together.

Segment policy

This is the whole decision table. The marker code is never sufficient: APP1 is EXIF or XMP, APP2 is an ICC profile or an MPF block, and the identifier string at the front of the payload is what tells them apart.

The 36 bytes it writes back

Phones do not rotate pixels. They store the sensor's native orientation and record an EXIF tag telling viewers to turn the image before displaying it. Dropping EXIF drops that instruction, which is why most metadata strippers leave you with a folder of sideways photographs.

ScrubPony drops the original EXIF block entirely and writes back a minimal replacement carrying exactly one field:

That is the only place this tool writes metadata rather than removing it. The justification is that the block is 36 bytes, holds one field, and that field is not identifying — it says which way up the picture goes, which anyone can see by looking at it. --no-keep-orientation drops it too, for whom the angle the phone was held at is itself a signal.

Nothing is emitted when the orientation is 1 or absent. Spending 36 bytes to say "already upright" would be metadata for its own sake.

Editing in place

-i replaces the original. It is still a write-then-rename: the scrubbed copy is built beside the file, synced, and moved over the top in one indivisible step. Kill the process at any moment and the file on disk is either exactly what it was or exactly what it should become — never a partial of either.

Permissions and ownership are carried onto the replacement. A file that was 0600 does not come back world-readable.

A file that would not change is not touched at all — same inode, same mtime. That is decided by comparing the bytes, not by counting segments: a photo scrubbed once still carries our own orientation block, so a second pass drops one segment and writes an identical one back. Only the bytes settle it.

Three things -i costs you, all of them consequences of replacing the file rather than editing it:

• Extended attributes are lost. Finder tags, Spotlight comments and quarantine flags live on the inode, and the rename installs a new one.
• Hard links are broken. Other links to the old inode keep the unscrubbed content.
• The mtime is reset, deliberately — it is metadata too.

If any of those matter, use the default sibling output or -d and move the results into place yourself.

Checking without changing

--check reports and changes nothing, putting the verdict in the exit code so it can go in a pre-commit hook or an upload script:

$ scrubpony --check -r ~/Pictures/to-upload
~/Pictures/to-upload/IMG_4471.jpg: 3 segments of identifying metadata, including GPS
~/Pictures/to-upload/scan.jpg: 1 segment of identifying metadata
scrubpony: 2 of 118 carry identifying metadata (0 not JPEG, 0 skipped, 0 failed)
$ echo $?
2

A photo scrubbed once still carries the 36-byte orientation block, and policy still drops it, so counting dropped segments would report every rotated photo as dirty forever and the hook would get switched off within a week. --check counts identifying segments: a block that matches the bytes this tool emits, exactly, is not one of them. Anything with a second tag, a GPS pointer or a thumbnail is.

Exit codes

An error outranks a dirty verdict even though 2 is the larger number. A script that sees 2 concludes "found metadata, scrub it"; if a file was also unreadable, that is the thing it needs to know first, and a plain maximum would have hidden it.

Directories, symlinks and ordering

• Directories are first-class. Point it at a folder, not a file. A bare directory covers the files directly inside it; -r descends, to a maximum of 64 levels.
• Symlinks are never followed — not files, not directories, not even one named directly on the command line. A symlink loop is an infinite walk, and a symlink out of the tree is a way to modify files you did not mean to touch.
• Directory entries are sorted before use, so a dry run is diffable between runs.
• A second pass skips its own output. Running twice over the same folder does not produce photo.scrubbed.scrubbed.jpg; leftover temporaries are skipped too, and both are only mentioned under -v.
• Non-JPEG files are reported and skipped, decided by the SOI marker rather than the extension. A .jpg that is really a PNG is not a JPEG here.
• Per-file error isolation. One unreadable or malformed file does not stop the run.

What happens when something goes wrong

Nothing is written at all if the input turns out to be malformed partway through. A partially scrubbed file is worse than no file, because it looks finished. On any failure the temporary is discarded and the original — or the pre-existing destination — is left exactly as it was.

A run whose output would be larger than its input — beyond the exact size of the orientation block it may add back — is treated as a bug and refused rather than published: scrubbing only removes bytes.

Where to go next

• Verify the pixel claim yourself — two commands, no trust required.
• The guarantees — atomicity, the fail-closed policy, and what is deliberately out of scope.
• Guides — task-shaped walkthroughs for the four modes.
• Glossary — EXIF, XMP, MPF, ICC, SOS and the rest, in plain terms.