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 than 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 version retention; 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',

Restoring a Version

In the WebUI in the details view, there is a restore button next to the versions. It can be used to restore the file to a past version. Restore does not delete the old version, instead a new current version is created.

Note that retention policy can be applied after the restore operation, which could result in the old version being removed because of the retention policy. This behavior can be changed with the persistent major version feature discussed in the section below.

Extended Version Metadata

Save additional metadata (author, version tag, etc.) of each version of uploaded and edited files.

Extended Version Metadata

You can enable the feature via an entry in config.php.

The metadata is only collected after enabling the feature using the config.php configuration file. This means the author or version number will show only for new versions of the file and be empty for older versions.

Show the Author of a Version

Each update to the file that generates a new file version will additionally show the author in the Versions Tab. This is helpful to keep track of who changed a version.

Conscious Persistent Major Versions

ownCloud can automatically generate and increment version numbers for new file versions. 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. Major versions are persistent versions that are not subject to any retention policies set by ownCloud.

Publishing the version persists it until the original file is deleted by somebody with such permission or by the system administrator via occ versions:cleanup command. For more information check the versions retention section.
To create a new persistent major version, the user has to click on the check mark next to the version info tab. Check the image above.
The versions follow the X.Y format, where X is a major part and Y is a minor part of the version. Version tags cannot be modified by the user, they are auto-generated by ownCloud.

Enterprise File Retention

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