From 325256a23282e6c359561c3d7aa2cb58c33750d8 Mon Sep 17 00:00:00 2001
From: Qu Wenruo <wqu@suse.com>
Date: Mon, 6 Aug 2018 14:00:08 +0800
Subject: 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 <wqu@suse.com>
[ update ]
Signed-off-by: David Sterba <dsterba@suse.com>
---
 Documentation/btrfs-qgroup.asciidoc | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

(limited to 'Documentation/btrfs-qgroup.asciidoc')

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>.
 +
 --rescan::::
 (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
+information.
 --no-rescan::::
-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>.
++
+`Options`
++
+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.
 
+QUOTA RESCAN
+------------
+The rescan reads all extent sharing metadata and updates the respective qgoups
+accordingly.
+
+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.
+
 EXIT STATUS
 -----------
 *btrfs qgroup* returns a zero exit status if it succeeds. Non zero is
-- 
cgit v1.2.3

