How Filestash handles versioning

In line with the plugin driver architecture of Filestash, we have different implementations available for versioning, each designed around a different storage model. This guide covers how each one works.

Option 1: folder-based versioning

On every save, Filestash checks if the file already exists. If it does, the current version is moved into a sibling folder named <filename>.versions with a UTC timestamp:

README.md
README.md.versions/
  v_20260309T143021
  v_20260308T091542

The .versions folders are invisible in the file manager. They are filtered from directory listings at the middleware level, so users never see them. When a file is renamed or moved, its .versions folder travels with it.

Deleting a file does not destroy it immediately. It gets moved to a Trash folder at the root of the user’s storage, with the original path encoded in the filename, giving you a recoverable trash bin on top of version history.

This plugin works with any filesystem-based backend: local disk, SFTP, FTP, SMB, and so on. No server-side configuration required.

Option 2: archive-based versioning

With this approach, versioning is entirely transparent at the storage level. From the user’s perspective, they browse and edit a regular file like README.md. On disk however, the backend stores it as README.md.tar.gz, with each saved version appended as a new entry in the archive.

This means the entire history of a file lives in a single artifact. There are no sibling folders, no separate version files. The current version is always the latest entry in the archive.

This plugin is a good fit when you want version history to be self-contained and portable, or when your storage backend handles many small files poorly.

Option 3: S3 versioning

If your backend is S3 or an S3-compatible service (MinIO, Ceph, etc.), the simplest approach is to let S3 handle versioning natively. Enable versioning on your bucket, activate the plugin in Filestash, and that’s it. Every upload creates a new object version on S3’s side. Filestash reads the version list via the S3 API and exposes it in the UI exactly like the other plugins.

No version data is managed by Filestash itself. Retention, lifecycle rules, and storage costs are all handled at the S3 level.