path: root/Documentation
diff options
authorQu Wenruo <>2018-08-06 14:00:08 +0800
committerDavid Sterba <>2018-10-31 18:24:14 +0100
commit325256a23282e6c359561c3d7aa2cb58c33750d8 (patch)
treeb6a914dae6b01be55921ba1979a38088f017bf5a /Documentation
parentdda84b8a162a0bfb85a9b81376579c7b48ef73d0 (diff)
btrfs-progs: doc: Update btrfs-qgroup regarding the rescan conditions
Add a new section, QUOTA RESCAN, to explain why and when we need a full quota rescan when assigning/removing qgroup relationship. Also, since 'remove' shares the same options of 'assign', add reference to 'assign' options for 'remove' subcommand. Signed-off-by: Qu Wenruo <> [ update ] Signed-off-by: David Sterba <>
Diffstat (limited to 'Documentation')
1 files changed, 24 insertions, 2 deletions
diff --git a/Documentation/btrfs-qgroup.asciidoc b/Documentation/btrfs-qgroup.asciidoc
index ad10f04d..dff08674 100644
--- a/Documentation/btrfs-qgroup.asciidoc
+++ b/Documentation/btrfs-qgroup.asciidoc
@@ -48,9 +48,12 @@ identified by <path>.
(default since: 4.19) Automatically schedule quota rescan if the new qgroup
-assignment would lead to quota inconsistency.
+assignment would lead to quota inconsistency. See 'QUOTA RESCAN' for more
-Explicitly ask not to do a rescan.
+Explicitly ask not to do a rescan, even if the assignment will make the quotas
+inconsitent. This may be useful for repeated calls where the rescan would add
+unnecessary overhead.
*create* <qgroupid> <path>::
Create a subvolume quota group.
@@ -83,6 +86,10 @@ limit space exclusively assigned to this qgroup.
*remove* <src> <dst> <path>::
Remove the relationship between child qgroup <src> and parent qgroup <dst> in
the btrfs filesystem identified by <path>.
+The same as *assign* subcommand.
*show* [options] <path>::
Show all qgroups in the btrfs filesystem identified by <path>.
@@ -131,6 +138,21 @@ If multiple <attr>s is given, use comma to separate.
To retrieve information after updating the state of qgroups,
force sync of the filesystem identified by <path> before getting information.
+The rescan reads all extent sharing metadata and updates the respective qgoups
+The information consists of bytes owned exclusively ('excl') or shared/referred
+to ('rfer'). There's no explicit information about which extents are shared or
+owned exclusively. This means when qgroup relationship changes, extent owners
+change and qgroup numbers are no longer consistent unless we do a full rescan.
+However there are cases where we can avoid a full rescan, if a subvolume whose
+'rfer' number equals its 'excl' number, which means all bytes are exclusively
+owned, then assigning/removing this subvolume only needs to add/subtract 'rfer'
+number from its parent qgroup. This can speed up the rescan.
*btrfs qgroup* returns a zero exit status if it succeeds. Non zero is