Where files are used#
What is scanned#
| Source | References found |
|---|---|
| Posts of every type (not revisions, auto-drafts or attachments) | Uploads URLs in the content and excerpt; wp-image-N classes; [caption id="attachment_N"]; [gallery ids]; block attributes (id, mediaId, ids) |
| Post meta | The featured image; Yoast's social images; ACF image, file and gallery fields by their field type, also inside repeaters and flexible content; uploads URLs in any other value |
| Options | ACF options pages (same rules); the site icon; the custom logo; Yoast's settings; uploads URLs in any value (transients, caches and plugin state are skipped) |
| Term meta and descriptions | ACF term fields and uploads URLs |
| Theme files | Uploads URLs in the active theme's (and parent theme's) CSS, SCSS, Twig, PHP, JS, JSON, HTML and SVG; node_modules, vendor and hidden folders are skipped |
A URL resolves through the file index to the exact file and its attachment. A size suffix that is no longer in the metadata (an old theme size) counts for its attachment.
The index is kept current from post, meta, option and term changes and from BB Migrate theme pushes. wp bb-media usage
(or Rescan on the Media index screen) scans everything again; on coalesce.io that takes about a second.
The reports#
| Report | |
|---|---|
| Unused attachments | No reference anywhere above, uploaded more than 30 days ago. An attachment naming the same file as a used one counts as used, since deleting it would delete that file. |
| Used only by drafts or trash | Referenced only by drafts, pending, private or trashed posts (--live) |
| Unused unattached files | Files in uploads no attachment owns and nothing references |
| Referenced but missing | Indexed files that something references but that are not on disk |
wp bb-media unused, wp bb-media unused --files, wp bb-media where <id|url>, or the CSV on the Media index
screen (attachments and files, with a column for "only drafts or trash"). Cells that a spreadsheet would read as a
formula are written as text.
What the scan cannot see#
- An attachment ID written into a template or plugin code (
wp_get_attachment_image( 393 )), or a file named only in code that builds its path. - References outside the site: emails, other sites, documents, social posts linking to an uploads URL.
- Content in tables plugins keep outside posts, meta, options and terms.
So the reports are a list for review. Check a sample in the browser before deleting anything, and delete through WordPress (the Media library) so its sizes and copies go with it. BB Media deletes nothing.