Files Versions

Introduction

Every time when a file gets rewritten to the storage, the versions app (files_versions) creates a new backup copy of the file. Versions are visible for the user in the webinterface only and do not get synced to clients. An admin can control the retention behaviour of versioned files.

How Versions are Created

When a backup copy is created , it is stored inside a folder files_versions which is inside the users root folder. The app will add the suffix .v followed by the unix timestamp of the creation date of the backup copy.

.
├── files
│   └── welcome.txt
└── files_versions
    ├── welcome.txt.v1556203470
    ├── welcome.txt.v1556203501
    └── welcome.txt.v1556203567
File versioning only gets triggered if the change is made via the ownCloud ecosystem. It does not get triggered if the change is made at a mounted filesystem directly.

Versions are displayed in the WebUI in the details view in the right sidebar if you click on the file row in the file listing. You can restore the current file to one of the earlier backup copies in the list, by clicking on the restore icon of the specific version.

File Versions in the WebUI

How Versions are Deleted

The versions app deletes old file versions automatically to ensure that users do not exceed their storage quotas. This is done by automatic background jobs which clean up the versions following a specific pattern. This pattern defines the expiration date for each backup version.

Default Versions Delete Patterns

This is the default pattern used to delete old versions:

  • For the last second we keep one version

  • For the last 10 seconds ownCloud keeps one version every 2 seconds

  • For the last minute ownCloud keeps one version every 10 seconds

  • For the last hour ownCloud keeps one version every minute

  • For the last 24 hours ownCloud keeps one version every hour

  • For the last 30 days ownCloud keeps one version every day

  • If the versions are older than 30 days ownCloud keeps one version every week

The versions are adjusted along this pattern every time a new version is created and the background job was executed.

Example

Time Period before last Expiration Maximum Number of Versions:

1 second

1

10 seconds

5

1 minute

6

1 hour

59

1 day

23

30 days

30

The versions app never uses more that 50% of the user’s storage quota. If the stored versions exceed this limit, ownCloud deletes the oldest file versions until it meets the disk space limit again.
Adjust the 'versions_retention_obligation' setting in config.php to avoid filling up the user’s quota. For details see the section below.

Change the Expiration Settings

You may alter the default pattern in config.php. The default setting is auto, which sets the default pattern:

'versions_retention_obligation' => 'auto',

Possible Config Values

auto

Default value if nothing is set

D, auto

Keep versions at least for D days, apply expiration rules to all versions that are older than D days

auto, D

Delete all versions that are older than D days automatically, delete other versions according to expiration rules

D1, D2

Keep versions for at least D1 days and delete when they exceed D2 days.

disabled

Disable Versions; no files will be deleted.

Example 1:

Keep all versions for at least 10 days, apply expiration rules to all versions that are older than 10 days. This will keep a lot more versions during the last 10 days compared to the default pattern.

'versions_retention_obligation' => '10, auto',

Example 2:

Apply expiration rules to all versions that are created during the last 30 days and do not keep any versions older than 30 days.

'versions_retention_obligation' => 'auto, 30',

Example 3:

Do not apply any expiration rules. Delete all versions after 30 days.

'versions_retention_obligation' => '30, 30',

Show the Author of a Version

You can enable and disable to show the author of a version in the versions history via an entry in config.php. For details see: Save and display the author of each version of uploaded and edited files. This is helpful to keep track of who changed a version.

After adding the author, the version screen changes in the following way:

Author of a changed saved file

Conscious Persistent Major Versions

ownCloud can automatically generate version numbers for file versions. To enable this feature, the config setting to show a version’s author must be enabled as described above. Based on this feature, one can define the actual version to be a major version which gets a major version number and all new upcoming versions start counting from this major number. To do so, the user has to click on the check mark on the left of the actual version to publish it as a major version.

Enterprise File Retention

Enterprise customers have additional tools for managing file retention policies; see Advanced File Tagging With the Workflow App.