Skip to content

Replace media files in place to preserve attachment URLs #275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
KhushalSainS wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Replace media files in place to preserve attachment URLs #275

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
750051f
Replace media files in place to preserve attachment URLs
KhushalSainS Nov 5, 2026
cabb087
Tag big-image replace scenarios and cover error paths
KhushalSainS Nov 5, 2026
8f75597
Add Behat coverage for non-image replacements
KhushalSainS Nov 5, 2026
3e6e228
Test the failed download path instead of non-image files
KhushalSainS Nov 5, 2026
f98ca12
Cover the missing attached file error path
KhushalSainS Nov 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 28 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -343,8 +343,22 @@ wp media regenerate [<attachment-id>...] [--image_size=<image_size>...] [--skip-

Replaces the file for an existing attachment while preserving its identity.

By default, the replacement is written over the attachment's existing file,
keeping its path and URL intact. This is a change from earlier versions,
which sideloaded the replacement into the current uploads directory and
therefore changed the attachment's URL. Use --new-file-name to restore that
behavior.

When replacing an image that is not itself a WordPress big-image "-scaled"
variant with one larger than the big-image threshold, the full-resolution
file is kept at the existing URL and the generated "-scaled" file is
discarded, so the URL still does not change. WordPress re-applies big-image
scaling whenever attachment metadata is regenerated, so a later
`wp media regenerate` may point the attachment at a "-scaled" file; use
--new-file-name if you want WordPress's standard big-image handling instead.

~~~
wp media replace <attachment-id> <file> [--skip-delete] [--porcelain]
wp media replace <attachment-id> <file> [--skip-delete] [--new-file-name] [--porcelain]
~~~

**OPTIONS**
Expand All @@ -356,7 +370,12 @@ wp media replace <attachment-id> <file> [--skip-delete] [--porcelain]
Path to the replacement file. Supports local paths and URLs.

[--skip-delete]
Skip deletion of old thumbnail files after replacement.
Skip deletion of the previous files after replacement.

[--new-file-name]
Store the replacement under its own file name in the current uploads
directory instead of overwriting the attachment's existing file. This
changes the attachment's URL.

[--porcelain]
Output just the attachment ID after replacement.
Expand All @@ -366,12 +385,17 @@ wp media replace <attachment-id> <file> [--skip-delete] [--porcelain]
# Replace an attachment file with a local file.
$ wp media replace 123 ~/new-image.jpg
Replaced file for attachment ID 123 with '/home/user/new-image.jpg'.
Success: Replaced 1 of 1 images.
Success: Replaced 1 of 1 attachments.

# Replace an attachment file with a file from a URL.
$ wp media replace 123 'http://example.com/image.jpg'
Replaced file for attachment ID 123 with 'http://example.com/image.jpg'.
Success: Replaced 1 of 1 images.
Success: Replaced 1 of 1 attachments.

# Replace a file and use the replacement's own name, changing the attachment URL.
$ wp media replace 123 ~/new-image.jpg --new-file-name
Replaced file for attachment ID 123 with '/home/user/new-image.jpg'.
Success: Replaced 1 of 1 attachments.

# Replace and output just the attachment ID.
$ wp media replace 123 ~/new-image.jpg --porcelain
Expand Down
Loading
Loading