Who this is for. Developers setting up a site's uploads or running an import. After this page you can predict what an upload does to an existing file, choose the settings for a new site, and run a repeatable migration without piling up copies.
The four duplicate strategies
When an upload's name is already taken in the target folder, the duplicate strategy decides what happens. The site's default is the setting Files.defaultDuplicateStrategy, shipped as use. An upload through the API can override it with a duplicate parameter, which accepts the same four values.
| Strategy | When the name is already taken |
|---|---|
use (default) | Compares the upload's checksum (MD5) with the existing file's active revision. Identical content: the existing file is reused and nothing changes. Different content: the upload is stored under a new name, as with rename. If the existing filename is the other kind (an image where a file is uploaded, or the reverse), the upload fails. |
rename | Always keeps both, without comparing content: the new upload gets -1, -2 and so on before the extension (hero-1.jpg), counting up until the name is free. |
update | Adds the upload as a new revision of the existing file or image and makes it active. |
error | Refuses the upload: the new filename fails validation, because its name is already taken in that folder. |
Only update changes what an existing address delivers. With the other three, everything that already links to the address keeps getting the same bytes. Why that works is on Folders, filenames and file revisions.
Where an upload lands
| Setting | Default | Effect |
|---|---|---|
Files.defaultImagesFolder | images | The folder an image goes to when the upload names no folder. |
Files.defaultFilesFolder | files | The same, for any other file. |
Files.uploadFileSubfolder | id | "Specify into which subfolder Drag and Drop file uploads are put by default for existing records": a subfolder named after the record's id (id) or its slug (slug). |
The recommended combination for a new site
Keep the shipped defaults: the use strategy and subfolders named by id.
usechecks content before replacing anything, which is safer thanupdateas a default, and it does not pile up numbered copies when the same file is uploaded again, which is the cost ofrename.- Subfolders named by id stay right when an author later changes a record's slug. A subfolder named by slug would then no longer match the record it was named after.
What each strategy means for a content migration
| Strategy | On a re-run of the same import |
|---|---|
use | Unchanged files are reused. A file whose content changed since the last run is stored as a numbered copy beside the original, and existing links keep showing the old version. |
rename | Every file that already exists is uploaded again as a numbered copy. |
update | Every file is added as a new revision behind its existing address, so changed files are replaced in place and links follow. |
error | Every file that already exists is refused. Suits a pipeline that must never collide and handles the refusal itself. |
For a migration that runs more than once, use update while it runs, either as the site's default or with duplicate=update on each upload, and switch back to use when it is done.