Overwriting and versioning files

Files stored on the VIP File System can be overwritten programmatically or with VIP-CLI. Overwriting a file is useful for eliminating the need to set a redirect to a newer version of the file. Redirects cannot be configured for any URLs that include /wp-content/uploads/*. 

Versioning of files uploaded through WordPress

Attempting to overwrite a file by uploading a new version of the file with the same name to the WordPress Media Library will not work as expected. By default, WordPress will not overwrite an existing file (e.g. image.jpg). Instead, a newer file uploaded with the same file name will be uploaded as a separate file with an underscore and a 6 character hash appended to it (e.g. image_8b7971.jpg).

Versioning of files on the VIP File System

Files on the VIP File System, however, can be overwritten with new content. The updated version of the file will be available at the same path and file name.

• Files must be overwritten directly by name, at their exact location.
• A limit of 2000 modifications are permitted for overwriting and versioning any particular file path. Modifications beyond this limit will result in an error being thrown with an HTTP 405 Method Not Allowed response status code. Because of this, not all use cases for overwriting and versioning are ideal or supported. Plugins or features that use identical filenames (e.g. files with high volumes of updates such as logging) are likely to hit this limit.
• Because files in the File System are typically not frequently modified, they have a very long cache-control header (up to 1 year). To ensure that requests to a recently modified file obtain the latest version, the file may need to be explicitly purged from the edge cache after replacement.

Overwriting with VIP-CLI

VIP-CLI command: vip import media [options] [command]

Overwrite a file by importing a newer version of the file with VIP-CLI.

• On the user’s local machine, create a directory structure that mimics the remote file’s path beginning with uploads/ as the top-most directory, and the newer version of the file nested within it. For example, to overwrite a file located at the remote file path https://example.com/uploads/2022/12/image.jpg, the directory structure on the local machine should be uploads/2022/12/image.jpg.
• Archive the local uploads/ directory and upload it to a publicly accessible remote URL.
• Include the --overwriteExistingFiles option (or -o ) when importing the archived file to force the silent overwriting of the existing file. For example:
  vip @example-app.production import media "https://www.dropbox.com/s/uploads.tar.gz" -o
• If the newer version of the file does not immediately load as expected, the older version of the file may need to be purged from the cache with vip cache purge-url [options].