ghost-purge-images

Display or clean unused uploaded files: images, documents, audio, video & thumbnail files of your Ghost blog

🎁 Versions compatibility

Which Ghost version are you running?

| Ghost version | ghost-purge-images version | How to install | |---------------|----------------------------|-------------------------------------------| | 6 | latest | npm install -g ghost-purge-images | | 3, 4, 5 | 3.4.0 | npm install -g [email protected] | | >= 2.16 | 2.1.1 | npm install -g [email protected] | | <= 2.15.x | 2.0.3 | npm install -g [email protected] | | 0.7.2 - 1.x | 1.0.0 | npm install -g [email protected] |

✨ Update to the last version

In your blog server, login via ssh and run:

npm install -g ghost-purge-images

💡 This command will install or update ghost-purge-images globally in your server, it doesn't matter in which folder you run it

🤓 Observations

• Due Content & Admin API, some images associated to the next resouces will be removed:

  • Authors with zero published posts

  • Tags that are not associated with a post

  • Drafts (both posts/pages) will be removed too if you are not running Ghost v2.16 or newer

    💡 Why? Drafts are only available in Ghost Admin API included in Ghost 2.16

• Backup your content folder first!

🔑 Keys

This tool use:

• Ghost Content API for check authors & tags
• Ghost Admin API for check posts & pages, including drafts

Get the keys following this steps:

• On your Ghost admin, click on Integrations at the left menu
• Click on Add custom integration and set any name
• Copy the Content API & Admin API Keys to use them

💡 Need help? Check this step-by-step guide to create them

🚀 Execute

Login into your server via ssh:

• Where you have installed Ghost, usually:

cd /var/www/ghost

• Run a command, for example:

ghost-purge-images display --content-key=YOUR_CONTENT_KEY --admin-key=YOUR_ADMIN_KEY

⚡️ Commands

display

Print the list of all uploaded images that currently are not being used in any post, page or metadata. Attempts to predict any errors before running purge.

• Example: ghost-purge-images display --content-key=YOUR_CONTENT_KEY --admin-key=YOUR_ADMIN_KEY

purge

Delete all the unused files.

⚠️ WARNING: Take a backup before run this

• Example: ghost-purge-images purge --content-key=YOUR_CONTENT_KEY --admin-key=YOUR_ADMIN_KEY

🧩 Optional Params

• --fix-permissions

💡 If you don't have necessary permissions to delete files, running purge may cause errors, such as Error: EACCES: permission denied, unlink ANY_FILE_PATH.

You can allow the command to handle this for you.

• In purge, updates permissions to allow file deletion, and then reverts back to production-ready permissions after purge is complete. Note that this requires sudo, and restoring permissions may take a long time even on small sites.
• In display, shows the file statuses as if permissions were already fixed.

For backward compatibility, permissions are not automatically fixed. You can enable it with the flag ... --fix-permissions

• url

💡 By default, the URL in config.production.json will be used. This may be useful for Docker or custom configurations

Example: ... --url=https://yourblog.com/

• images-path

💡 The default images path is content/images

You can change it with the optional param ... --images-path=your/custom/path/here

• media-path

💡 The default media path is content/media

You can change it with the optional param ... --media-path=your/custom/path/here

• exclude-ext

💡 No default value, all extensions are included

You can exclude one or more file extensions. Examples:

• Excluding .webp files, adding the optional param ... --exclude-ext=webp
• Excluding .jpg and .gif files (add a comma), adding the optional param ... --exclude-ext=jpg,gif

📋 Changelog

See CHANGELOG.md

👋 Credits

David Burgos from Ghostboard.io

👏 Contributors

• scottleechua
• mesquka

✒️ License

See LICENSE file