On Tue, Feb 11, 2020 at 08:29:22AM +0800, Qu Wenruo wrote:
>
>
> On 2020/2/11 上午12:09, David Sterba wrote:
> > On Mon, Feb 10, 2020 at 05:02:01PM +0800, Qu Wenruo wrote:
> >> Since commit ecd4bb607f35 ("btrfs-progs: docs: enhance btrfs-filesystem
> >> manual page"), the man page of `btrfs filesystem` shows `sync`
> >> subcommand will wait for all existing orphan subvolumes to be dropped.
> >
> > But this is not what the docs say, nor what the ioctl claims to do.
> >
> > 'trigger cleaning of deleted subvolumes' means that it just starts the
> > process in some way (eg. by waking up the cleaner kthread that does the
> > actual cleaning).
>
> Then at least we shouldn't really confuse the end user (me included)
> about the cleanup.
Yeah, documentation improvements are welcome.
> In fact the cleaner wake up doesn't really have a user-observable impact.
The observable impact is that the cleaning starts immediatelly and not
after the periodic wakeup. This was the original intention behind
2fad4e83e1259 ("btrfs: wake up transaction thread from SYNC_FS ioctl").
I don't remember exactly, maybe it was on IRC somebody asking for it.
> We should at least avoid mentioning such thing.
That there's some connection between 'fi sync' and the cleaning should
be IMHO mentioned in the docs. The tools provide some commands as
building blocks and some as all-in-one, so there should be enough
information to let user decide what to do.
It's not easy to find the balance between the level of detail and amount
of related information, also to maintain consistency accross all
documents. As if writing documentation is hard, idk.
