From f9dff2cff30abeb81ad52fd1010023e5077f34e2 Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 8 Aug 2026 10:47:07 -0400 Subject: [PATCH 1/4] docs(user): clarify deleted files management User Manual counterpart to PR #15421 Updates trash-bin documentation to clarify quota handling, shared-file deletions, storage limits, retention policies, restoration behavior, and administrator configuration. Assisted-by: Copilot:gpt-5.6-luna Signed-off-by: Josh --- user_manual/files/deleted_file_management.rst | 165 +++++++++++++----- 1 file changed, 117 insertions(+), 48 deletions(-) diff --git a/user_manual/files/deleted_file_management.rst b/user_manual/files/deleted_file_management.rst index b88d307606d..be53882b810 100644 --- a/user_manual/files/deleted_file_management.rst +++ b/user_manual/files/deleted_file_management.rst @@ -1,58 +1,127 @@ -====================== -Managing deleted files -====================== +============= +Deleted files +============= -When you delete a file in Nextcloud, it is not immediately deleted permanently, -only moved into the trash bin. It is not permanently deleted until you manually -delete it, or when the Deleted Files app deletes it to make room for new files. +When you delete a file or folder in Nextcloud, it is normally moved to the +trash bin instead of being deleted immediately. This allows you to restore it +later. -Find your deleted files by clicking the **Deleted files** button on the Files -page of the Nextcloud web interface. You can restore or permanently delete files from there. +Items in the trash bin are permanently deleted when one of the following +occurs: + +- You manually select *Delete permanently*. +- The Deleted Files app removes the item according to the configured retention + policy. +- The effective trash-bin size limit is exceeded and the item is eligible for + removal to free space. + +Find your deleted files by selecting **Deleted files** in the Files area of the +Nextcloud Web interface. From there, you can restore items, download them to +your device, or delete them permanently. + +When you restore an item, Nextcloud normally attempts to return it to its +original location. If that location no longer exists or is not writable, the +item is restored to the root of your Files area. If an item with the same name +already exists, Nextcloud gives the restored item a unique name. + +.. note:: If the Versions app is enabled, versions associated with a deleted + file are moved to the trash bin and are restored when the file is restored. Quotas ------ -Deleted files are not counted against your storage quota. Only your personal -files count against your quota, not files which were shared with you. -(See :doc:`quota` to learn more about quotas.) +Files and folders in your trash bin do not count against your normal storage +quota. + +See :doc:`quota` for more information about how storage quotas are calculated. What happens when shared files are deleted ------------------------------------------ -Deleting files gets a little complicated when they are shared files, as this -scenario illustrates: - -1. User1 shares a folder "test" with User2 and User3 -2. User2 (the recipient) deletes a file/folder "sub" inside of "test" -3. The folder "sub" will be moved to the trash bin of both User1 (owner) and - User2 (recipient) -4. But User3 will not have a copy of "sub" in their trash bin - -When User1 deletes "sub" then it is moved to User1's trash bin. It is -deleted from User2 and User3, but not placed in their trash bins. - -When you share files, other users may copy, rename, move, and share them with -other people, just as they can for any computer files; Nextcloud does not have -magic powers to prevent this. - -How the deleted files app manages storage space ------------------------------------------------ - -To ensure that users do not run over their storage quotas, the Deleted Files -app allocates a maximum of 50% of their currently available free space to -deleted files. If your deleted files exceed this limit, Nextcloud deletes the -oldest files (files with the oldest timestamps from when they were deleted) -until it meets the memory usage limit again. - -Nextcloud checks the age of deleted files every time new files are added to the -deleted files. By default, deleted files stay in the trash bin for 30 days. The -Nextcloud server administrator can adjust this value in the ``config.php`` file -by setting the ``trashbin_retention_obligation`` value. Files older than the -``trashbin_retention_obligation`` value will be deleted permanently. -Additionally, Nextcloud calculates the maximum available space every time a new -file is added. If the deleted files exceed the new maximum allowed space -Nextcloud will permanently delete those trashed files with the soonest expiration -until the space limit is met again. - -.. note:: Your administrator may have configured the trash bin retention period - to override the storage space management. See `admin documentation `_ for more details. +The behavior of deleted shared files depends on who deletes the item and who +owns it. + +For example, User1 shares a folder named ``TheProject/`` with User2 and User3: + +1. User2, a share recipient (sharee), deletes a folder or file named + ``Phase2`` inside ``TheProject/``. + + ``TheProject/Phase2`` is moved to the trash bin of User1, the owner, and a + copy is placed in User2's trash bin when possible. The item is removed from + the shared folder for User3, but User3 does not receive a copy in their + trash bin. + +2. User1, the owner, deletes ``TheProject/Phase2``. + + The item is moved to User1's trash bin and removed from the shared folder for + User2 and User3. It is not placed in their trash bins. + +The exact behavior can depend on the type of share and the permissions granted +by the share. Depending on those permissions, other users may be able to copy, +rename, move, or re-share shared files. These operations can affect which +account owns the resulting files and which trash bin receives a deleted item. + +.. note:: + + When a sharee deletes an item owned by another user, Nextcloud moves the item + to the owner's trash bin. A copy in the deleting user's trash bin is also + created (in most cases; the copy is on a best-effort basis and is not + guaranteed). + +How the Deleted Files app manages storage space +------------------------------------------------ + +The Deleted Files app manages trash-bin contents using two related rules: + +- A storage limit determines how much space the trash bin may use. +- A retention policy determines when deleted items become eligible for + permanent deletion. + +Trash-bin storage limit +~~~~~~~~~~~~~~~~~~~~~~~ + +For accounts with a storage quota, the default trash-bin limit is up to 50% of +the account's remaining quota space. This is calculated after the account's +active files have been taken into account; it is not 50% of the account's total +quota. + +For example, if your quota is 10 GB and your active files use 8 GB, the default +trash-bin allowance is calculated from the remaining 2 GB. + +For accounts without a storage quota, the default limit is calculated using +available filesystem space instead. Your administrator can override either +default by configuring a global or per-account trash-bin size. + +When the effective trash-bin limit is exceeded, Nextcloud removes eligible +deleted items, starting with the oldest items, until the limit is satisfied +again. + +Retention and permanent deletion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, deleted files are retained for at least 30 days. After that, +eligible items may be permanently deleted when space is needed; they are not +necessarily deleted immediately after 30 days. + +Your administrator can configure different minimum and maximum retention +periods. Depending on the configuration, items may be permanently deleted +after a maximum age even when storage space is not currently needed. Automatic +expiration can also be disabled. + +For policies with a configured minimum retention period, an item is eligible +for space-based cleanup only after that period has elapsed. Policies without a +minimum retention period may allow space-based cleanup regardless of the +item's age. Items that have exceeded a configured maximum retention period can +be permanently deleted regardless of whether space is currently needed. + +The relevant configuration setting is +``trashbin_retention_obligation``. For details about the available values and +their interaction with quotas and trash-bin sizes, see the +:doc:`Deleted Files <../../admin_manual/configuration_files/trashbin_configuration>` +section in the Administrator Manual. + +.. note:: + + The Deleted Files app may permanently delete an item before its maximum + retention period when the effective trash-bin limit is exceeded and the + item's minimum retention period has elapsed. From 3b918964528f0829d3958402baa6994545f8a302 Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 8 Aug 2026 11:05:07 -0400 Subject: [PATCH 2/4] docs(user): clarify storage quota documentation Clean-up/alignment with changes in the Deleted Files chapter. Clarifications regarding quota calculation, shared-file ownership, version storage, public-share uploads, interaction with deleted files, and trash-bin limits based on remaining quota space. Signed-off-by: Josh --- user_manual/files/quota.rst | 60 +++++++++++++++++++++++-------------- 1 file changed, 37 insertions(+), 23 deletions(-) diff --git a/user_manual/files/quota.rst b/user_manual/files/quota.rst index 90fca672227..e0e54c4da1d 100644 --- a/user_manual/files/quota.rst +++ b/user_manual/files/quota.rst @@ -2,38 +2,52 @@ Storage quota ============= -Your Nextcloud administrator has the option to set a storage quota on users. Look at -your Personal page to see what your quota is, and how much you have used. +Your Nextcloud administrator can set a storage quota for your account. Open +your Personal settings page to see your quota and how much storage you have +used. .. figure:: ../images/quota1.png :alt: Storage quota indicator on the Personal page It may be helpful to understand how your quota is calculated. -Metadata (thumbnails, temporary files, cache, and encryption keys) takes up -about 10% of disk space, but is not counted against user quotas. Some apps -store information in the database, such as the Calendar and Contacts apps. This -data is excluded from your quota. +Metadata such as thumbnails, temporary files, caches, and encryption keys can +use disk space without counting against your user quota. Some apps store data +in the database, such as the Calendar and Contacts apps. This data is not +included in the file-storage quota. -When other users share files with you, the shared files count against the -original share owner's quota. When you share a folder and allow other users or -groups to upload files to it, all uploaded and edited files count against your -quota. When you re-share files shared with you, the re-share still counts -against the quota of the original share owner. +When other users share files with you, the shared files normally count against +the original owner's quota. When you share a folder and allow other users or +groups to upload or edit files in it, those files count against your quota. +When you re-share files shared with you, the re-share normally continues to +count against the original owner's quota. -Encrypted files are a little larger than unencrypted files; the unencrypted size -is calculated against your quota. +Encrypted files can use more physical storage than unencrypted files. The +quota calculation uses the file size reported by Nextcloud's storage layer. -Deleted files that are still in the trash bin do not count against quotas. The -trash bin is set at 50% of quota. Deleted file aging is set at 30 days. When -deleted files exceed 50% of quota then the oldest files are removed until the -total is below 50%. +When the Versions app is enabled, older file versions are managed separately +from the normal storage quota according to the app's retention and storage +rules. -.. note:: Your administrator may have configured the trash bin retention period - to override the storage space management. See `administrator documentation `_ for more details. +If you create a public share through a URL and allow uploads, uploaded files +count against your quota. -When version control is enabled, the older file versions are not counted against -quotas. +Deleted files and the trash bin +------------------------------- -If you create a public share via URL and allow uploads, any uploaded files -count against your quota. +Files and folders in your trash bin do not count against your normal storage +quota. The trash bin nevertheless has its own storage limit. + +For accounts with a quota, the default amount of space available to the trash +bin is calculated as 50% of the account's remaining quota space. This is +calculated after the account's active files have been taken into account; it is +not 50% of the total quota. + +For accounts without a quota, the default trash-bin limit is calculated using +available filesystem space instead. An administrator can configure a global or +per-account trash-bin size that overrides the calculated default. + +Your administrator can also configure minimum and maximum trash-bin retention +periods, or disable automatic expiration. See the +:doc:`Deleted Files <../../admin_manual/configuration_files/trashbin_configuration>` +section of the Administrator Manual for details. From 235614c1d27a46f533ab3d71774caf866ccb6275 Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 8 Aug 2026 11:44:33 -0400 Subject: [PATCH 3/4] chore(user): replace cross-manual doc reference in Deleted FIles Since Admin is built separately from User we have to use an external link. Signed-off-by: Josh --- user_manual/files/deleted_file_management.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_manual/files/deleted_file_management.rst b/user_manual/files/deleted_file_management.rst index be53882b810..2dd0da71dc2 100644 --- a/user_manual/files/deleted_file_management.rst +++ b/user_manual/files/deleted_file_management.rst @@ -117,8 +117,8 @@ be permanently deleted regardless of whether space is currently needed. The relevant configuration setting is ``trashbin_retention_obligation``. For details about the available values and their interaction with quotas and trash-bin sizes, see the -:doc:`Deleted Files <../../admin_manual/configuration_files/trashbin_configuration>` -section in the Administrator Manual. +`Deleted Files section of the Administrator Manual +`_. .. note:: From 478abd17669bf7ab7a4d561d73519f39f068588e Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 8 Aug 2026 11:45:55 -0400 Subject: [PATCH 4/4] chore(user): replace cross-manual doc reference in Storage Quota Signed-off-by: Josh --- user_manual/files/quota.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/user_manual/files/quota.rst b/user_manual/files/quota.rst index e0e54c4da1d..f2572cccb27 100644 --- a/user_manual/files/quota.rst +++ b/user_manual/files/quota.rst @@ -48,6 +48,6 @@ available filesystem space instead. An administrator can configure a global or per-account trash-bin size that overrides the calculated default. Your administrator can also configure minimum and maximum trash-bin retention -periods, or disable automatic expiration. See the -:doc:`Deleted Files <../../admin_manual/configuration_files/trashbin_configuration>` -section of the Administrator Manual for details. +periods, or disable automatic expiration. See the `Deleted Files section of the Administrator Manual +`_ +for details.