Quick answer
A safe replacement has three parts.
Before: confirm what you are replacing, whether it should be a replacement at all, whether anything else uses that file, that a backup can be written, and that your server can do what you are asking.
During: back up before you overwrite, keep track of every row, and make sure a retry cannot redo work that already succeeded.
After: open the actual public file, check the pages that use it, deal with the cache, look at everything that failed or was held back, and confirm you can still undo it.
Copying a file successfully is not the end. The job is done when the right document is in the right place and you have seen it.
Before: is this a replacement at all?
Replace when it is the same document and the page still means “the current one”.
Publish as new when it is a new edition, a dated record, or a revision that should exist alongside the old one.
Get this wrong and everything else in the checklist is beside the point.
Before: where is it going?
Confirm the file or Media Library entry, the custom field if there is one, the product or resource it belongs to, and what happens to the public URL.
Do not let a filename make that decision.
Before: is the file used anywhere else?
Check whether anything outside this job points at it.
If it does, decide: include those pages deliberately, give one of them its own copy, send the new file somewhere else, or skip the row.
What you must not do is overwrite it and find out later.
Before: are two files aimed at the same place?
If two of the incoming files want the same home, both rows should stop until you say which is which.
Before: can the server actually do this?
Check the file type is allowed, the upload is readable, there is somewhere to put the files, the backup folder is writable, and — if you are combining PDFs or processing images — the tools that needs are present.
Before: can a backup be written?
Confirm the original can be copied, and that where it went is recorded: the original, the copy, and which row they belong to.
During: keep track of every row
Every row should be in a known state: waiting, ready, blocked, running, replaced, failed, undone.
That state is what the run reads. Not a progress message on a screen.
During: make retries safe
If the run dies after a row succeeded, retrying must not replace that file a second time.
During: work in chunks
For a big batch, process a manageable number at a time, show progress, and pick up from where each row actually got to.
After: open the real file
Not the page that links to it — the file itself.
Check the content, the revision or date inside it, and the page count or size if that tells you something.
After: check the pages
Load a page or two that use the file. If it is used in several places, check the ones that matter.
After: deal with the cache
If the old version is still showing: check the file on the server, then your CDN, then your browser, then the page cache, then — for images — the generated sizes.
After: reconcile the batch
Look at what was replaced, what was added, what was held back, what failed, and what is still unresolved.
A batch with unresolved rows is not finished, however good the success count looks.
After: confirm you can undo
Check the backup is still there and undo still works before you consider the job closed.
The short version
Before
- [ ] decided: replacement or new publication
- [ ] confirmed where each file is going
- [ ] checked what else uses those files
- [ ] checked no two files are aimed at the same place
- [ ] confirmed file types and server can handle it
- [ ] confirmed backups can be written
During
- [ ] backup written before the overwrite
- [ ] every row’s state recorded
- [ ] retries cannot redo finished work
- [ ] large batch running in chunks
After
- [ ] opened the public file
- [ ] checked the important pages
- [ ] checked the cache
- [ ] dealt with failures and held-back rows
- [ ] undo still available
Example: an 80-file batch
Before running:
- 65 ready
- 7 need checking
- 3 are new documents
- 3 held back because the file is used elsewhere
- 2 where two files want the same place.
The checklist stops you thinking of that as “80 files ready”. Fifteen of them are not, and only the reviewed ones should run.
One file, or a folder of them
For a single file you know the home of, most of this is trivial.
For a big batch, add: how many files you expected, whether any two incoming files are the same, whether any two are aimed at the same place, how many rows are unresolved, whether the run can resume, and a proper reconcile at the end.
The checklist should get longer as the risk does.
A “ready to run” number
Before you can start the destructive part, the batch should be able to tell you plainly: this many rows are ready, this many are excluded, this many are blocked or unresolved.
You should never have to work that out by scrolling a table of 300 rows.
You cannot check 500 pages by hand
For very large batches, nobody is opening every page.
Use two levels: let the plugin verify every row it can, and spot-check a handful yourself across the different kinds of document and page.
Anything the automatic check could not confirm should show up as an exception rather than being quietly counted as fine.
Summary
A safe replacement is a decision you made on purpose, a write you can undo, and a public result you have actually looked at.
The checklist is there to make all three explicit.
Related: Bulk replace files · Large-batch safety · Undoing a replacement