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.
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
|
Default value if nothing is set |
|
Keep versions at least for D days, apply expiration rules to all versions that are older than D days |
|
Delete all versions that are older than D days automatically, delete other versions according to expiration rules |
|
Keep versions for at least |
|
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',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.
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.