[PATCH 1/3] btrfs-progs: random fixes of btrfs-filesystem documentation

[PATCH 1/3] btrfs-progs: random fixes of btrfs-filesystem documentation

[Satoru Takeuchi]

From: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>

 - Simplify and unify the description of both man and usage.
 - Fix to show -m and -d is not exclusive
   with "<path>|<uuid>|<device>|<label>".
 - Add the description about short options for "--mounted" and
   "--all-devices", "-m" and "-d" respectively.
 - Move the descriptions of options to "Options" section.

Signed-off-by: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>

---
 Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
 cmds-filesystem.c                  | 15 ++++++++++-----
 2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/Documentation/btrfs-filesystem.txt b/Documentation/btrfs-filesystem.txt
index c9c0b00..fe68496 100644
--- a/Documentation/btrfs-filesystem.txt
+++ b/Documentation/btrfs-filesystem.txt
@@ -20,15 +20,21 @@ SUBCOMMAND
 *df* <path> [<path>...]::
 Show space usage information for a mount point.
 
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).
 +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
+If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
+information of all the btrfs filesystems both mounted and unmounted.
++
+The show command finds btrfs filesystems by scanning all the devices
+in /proc/partitions by default.
++
+`Options`
++
+-d|--alldevices::::
+scan all the devices under /dev
+-m|--mounted:::: 
+scan only mounted filesystems
 
 *sync* <path>::
 Force a sync for the filesystem identified by <path>.
diff --git a/cmds-filesystem.c b/cmds-filesystem.c
index 38011e5..5a80a98 100644
--- a/cmds-filesystem.c
+++ b/cmds-filesystem.c
@@ -578,11 +578,16 @@ out:
 }
 
 static const char * const cmd_show_usage[] = {
-	"btrfs filesystem show [options] [<path>|<uuid>|<device>|label]",
-	"Show the structure of a filesystem",
-	"-d|--all-devices   show only disks under /dev containing btrfs filesystem",
-	"-m|--mounted       show only mounted btrfs",
-	"If no argument is given, structure of all present filesystems is shown.",
+	"btrfs filesystem show [-d|-m] [<path>|<uuid>|<device>|<label>]",
+	"Show the structure of btrfs filesystem(s).",
+	"If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows",
+	"information of all the btrfs filesystems both mounted and unmounted.",
+	"",
+	"The show command finds btrfs filesystems by scanning all the devices",
+	"in /proc/partitions by default.",
+	"",
+	"-d|--all-devices   scan all the devices under /dev",
+	"-m|--mounted       scan only mounted filesystems",
 	NULL
 };
 
-- 
1.9.3

Re: [PATCH 1/3] btrfs-progs: random fixes of btrfs-filesystem documentation

[Eric Sandeen]

On 8/11/14, 2:11 AM, Satoru Takeuchi wrote:
> From: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
> 
>  - Simplify and unify the description of both man and usage.
>  - Fix to show -m and -d is not exclusive
>    with "<path>|<uuid>|<device>|<label>".
>  - Add the description about short options for "--mounted" and
>    "--all-devices", "-m" and "-d" respectively.
>  - Move the descriptions of options to "Options" section.
> 
> Signed-off-by: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
> 
> ---
>  Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
>  cmds-filesystem.c                  | 15 ++++++++++-----
>  2 files changed, 24 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/btrfs-filesystem.txt b/Documentation/btrfs-filesystem.txt
> index c9c0b00..fe68496 100644
> --- a/Documentation/btrfs-filesystem.txt
> +++ b/Documentation/btrfs-filesystem.txt
> @@ -20,15 +20,21 @@ SUBCOMMAND
>  *df* <path> [<path>...]::
>  Show space usage information for a mount point.
>  
> -*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
> -Show the btrfs filesystem with some additional info.
> +*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
> +Show the structure of btrfs filesystem(s).
>  +
> -If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
> -information of all the btrfs filesystem both mounted and unmounted.
> -If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
> -filesystem(s);
> -If '--all-devices' is passed, all the devices under /dev are scanned;
> -otherwise the devices list is extracted from the /proc/partitions file.

> +If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
> +information of all the btrfs filesystems both mounted and unmounted.

that doesn't seem quite correct; 

# btrfs filesystem show -m

does not specify '<path>|<uuid>|<device>|<label>' but it only shows
mounted filesystems, not all filesystems.

As I understand it, the -d and -m options control how the command
finds devices; the '<path>|<uuid>|<device>|<label>' argument is
used as a filter for what is found.

> ++
> +The show command finds btrfs filesystems by scanning all the devices
> +in /proc/partitions by default.

I think I would document it something like this:

show [-m|-d] [<path>|<uuid>|<device>|<label>]
	Show the structure of btrfs filesystem(s).

	By default, the show command scans all devices found in /proc/partitions.	
	If [-d|--all-devices] is specified, all devices found under /dev are scanned.
	If [-m|--mounted] is specified, only mounted (btrfs?) devices are scanned.

	By default, the structure of all discovered filesystems is shown.
	If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems
	matching that identifier are shown.

(What seems to be missing, though, is why would the user ever choose to use '-d?')

-Eric

Re: [PATCH 1/3] btrfs-progs: random fixes of btrfs-filesystem documentation

[Eric Sandeen]

On 8/11/14, 10:05 AM, Eric Sandeen wrote:
> On 8/11/14, 2:11 AM, Satoru Takeuchi wrote:
>> From: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
>>
>>  - Simplify and unify the description of both man and usage.
>>  - Fix to show -m and -d is not exclusive
>>    with "<path>|<uuid>|<device>|<label>".
>>  - Add the description about short options for "--mounted" and
>>    "--all-devices", "-m" and "-d" respectively.
>>  - Move the descriptions of options to "Options" section.
>>
>> Signed-off-by: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
>>
>> ---
>>  Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
>>  cmds-filesystem.c                  | 15 ++++++++++-----
>>  2 files changed, 24 insertions(+), 13 deletions(-)
>>
>> diff --git a/Documentation/btrfs-filesystem.txt b/Documentation/btrfs-filesystem.txt
>> index c9c0b00..fe68496 100644
>> --- a/Documentation/btrfs-filesystem.txt
>> +++ b/Documentation/btrfs-filesystem.txt
>> @@ -20,15 +20,21 @@ SUBCOMMAND
>>  *df* <path> [<path>...]::
>>  Show space usage information for a mount point.
>>  
>> -*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
>> -Show the btrfs filesystem with some additional info.
>> +*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
>> +Show the structure of btrfs filesystem(s).
>>  +
>> -If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
>> -information of all the btrfs filesystem both mounted and unmounted.
>> -If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
>> -filesystem(s);
>> -If '--all-devices' is passed, all the devices under /dev are scanned;
>> -otherwise the devices list is extracted from the /proc/partitions file.
> 
>> +If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
>> +information of all the btrfs filesystems both mounted and unmounted.
> 
> that doesn't seem quite correct; 
> 
> # btrfs filesystem show -m
> 
> does not specify '<path>|<uuid>|<device>|<label>' but it only shows
> mounted filesystems, not all filesystems.
> 
> As I understand it, the -d and -m options control how the command
> finds devices; the '<path>|<uuid>|<device>|<label>' argument is
> used as a filter for what is found.
> 
>> ++
>> +The show command finds btrfs filesystems by scanning all the devices
>> +in /proc/partitions by default.
> 
> I think I would document it something like this:
> 
> show [-m|-d] [<path>|<uuid>|<device>|<label>]
> 	Show the structure of btrfs filesystem(s).
> 
> 	By default, the show command scans all devices found in /proc/partitions.	
> 	If [-d|--all-devices] is specified, all devices found under /dev are scanned.
> 	If [-m|--mounted] is specified, only mounted (btrfs?) devices are scanned.
> 
> 	By default, the structure of all discovered filesystems is shown.
> 	If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems
> 	matching that identifier are shown.
> 
> (What seems to be missing, though, is why would the user ever choose to use '-d?')

Incidentally, there is some strange behavior here when looking for multiple filesystems which match.

Make 2 filesystems w/ the same label:

[root@bp-05 tmp]# btrfs filesystem label /dev/sdc1 testlabel2
[root@bp-05 tmp]# btrfs filesystem label /dev/sdc5 testlabel2

Show matching filesytems:

[root@bp-05 tmp]# btrfs filesystem show testlabel2
Label: 'testlabel2'  uuid: 8c6ec835-5628-439b-9749-d92f62573ce8
	Total devices 1 FS bytes used 112.00KiB
	devid    1 size 30.00GiB used 2.04GiB path /dev/sdc5

Label: 'testlabel2'  uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
	Total devices 1 FS bytes used 384.00KiB
	devid    1 size 30.00GiB used 2.04GiB path /dev/sdc1

Btrfs v3.14.2

That works fine, but if one is mounted:

[root@bp-05 tmp]# mount /dev/sdc1 /mnt/test

only the mounted filesystem is shown:

[root@bp-05 tmp]# btrfs filesystem show testlabel2
Label: 'testlabel2'  uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
	Total devices 1 FS bytes used 384.00KiB
	devid    1 size 30.00GiB used 2.04GiB path /dev/sdc1

Btrfs v3.14.2

That's unexpected.

Mount the other fs, and both are shown again:

[root@bp-05 tmp]# mount /dev/sdc5 /mnt/scratch
[root@bp-05 tmp]# btrfs filesystem show testlabel2
Label: 'testlabel2'  uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
	Total devices 1 FS bytes used 384.00KiB
	devid    1 size 30.00GiB used 2.04GiB path /dev/sdc1

Label: 'testlabel2'  uuid: 8c6ec835-5628-439b-9749-d92f62573ce8
	Total devices 1 FS bytes used 384.00KiB
	devid    1 size 30.00GiB used 2.04GiB path /dev/sdc5

Btrfs v3.14.2


-Eric

Re: [PATCH 1/3] btrfs-progs: random fixes of btrfs-filesystem documentation

[Satoru Takeuchi]

Hi Eric,

(2014/08/12 2:14), Eric Sandeen wrote:
> On 8/11/14, 10:05 AM, Eric Sandeen wrote:
>> On 8/11/14, 2:11 AM, Satoru Takeuchi wrote:
>>> From: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
>>>
>>>   - Simplify and unify the description of both man and usage.
>>>   - Fix to show -m and -d is not exclusive
>>>     with "<path>|<uuid>|<device>|<label>".
>>>   - Add the description about short options for "--mounted" and
>>>     "--all-devices", "-m" and "-d" respectively.
>>>   - Move the descriptions of options to "Options" section.
>>>
>>> Signed-off-by: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
>>>
>>> ---
>>>   Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
>>>   cmds-filesystem.c                  | 15 ++++++++++-----
>>>   2 files changed, 24 insertions(+), 13 deletions(-)
>>>
>>> diff --git a/Documentation/btrfs-filesystem.txt b/Documentation/btrfs-filesystem.txt
>>> index c9c0b00..fe68496 100644
>>> --- a/Documentation/btrfs-filesystem.txt
>>> +++ b/Documentation/btrfs-filesystem.txt
>>> @@ -20,15 +20,21 @@ SUBCOMMAND
>>>   *df* <path> [<path>...]::
>>>   Show space usage information for a mount point.
>>>   
>>> -*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
>>> -Show the btrfs filesystem with some additional info.
>>> +*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
>>> +Show the structure of btrfs filesystem(s).
>>>   +
>>> -If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
>>> -information of all the btrfs filesystem both mounted and unmounted.
>>> -If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
>>> -filesystem(s);
>>> -If '--all-devices' is passed, all the devices under /dev are scanned;
>>> -otherwise the devices list is extracted from the /proc/partitions file.
>>
>>> +If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
>>> +information of all the btrfs filesystems both mounted and unmounted.
>>
>> that doesn't seem quite correct;
>>
>> # btrfs filesystem show -m
>>
>> does not specify '<path>|<uuid>|<device>|<label>' but it only shows
>> mounted filesystems, not all filesystems.
>>
>> As I understand it, the -d and -m options control how the command
>> finds devices; the '<path>|<uuid>|<device>|<label>' argument is
>> used as a filter for what is found.
>>
>>> ++
>>> +The show command finds btrfs filesystems by scanning all the devices
>>> +in /proc/partitions by default.
>>
>> I think I would document it something like this:
>>
>> show [-m|-d] [<path>|<uuid>|<device>|<label>]
>> 	Show the structure of btrfs filesystem(s).
>>
>> 	By default, the show command scans all devices found in /proc/partitions.	
>> 	If [-d|--all-devices] is specified, all devices found under /dev are scanned.
>> 	If [-m|--mounted] is specified, only mounted (btrfs?) devices are scanned.
>>
>> 	By default, the structure of all discovered filesystems is shown.
>> 	If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems
>> 	matching that identifier are shown.
>>
>> (What seems to be missing, though, is why would the user ever choose to use '-d?')
> 
> Incidentally, there is some strange behavior here when looking for multiple filesystems which match.
> 
> Make 2 filesystems w/ the same label:
> 
> [root@bp-05 tmp]# btrfs filesystem label /dev/sdc1 testlabel2
> [root@bp-05 tmp]# btrfs filesystem label /dev/sdc5 testlabel2
> 
> Show matching filesytems:
> 
> [root@bp-05 tmp]# btrfs filesystem show testlabel2
> Label: 'testlabel2'  uuid: 8c6ec835-5628-439b-9749-d92f62573ce8
> 	Total devices 1 FS bytes used 112.00KiB
> 	devid    1 size 30.00GiB used 2.04GiB path /dev/sdc5
> 
> Label: 'testlabel2'  uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
> 	Total devices 1 FS bytes used 384.00KiB
> 	devid    1 size 30.00GiB used 2.04GiB path /dev/sdc1
> 
> Btrfs v3.14.2
> 
> That works fine, but if one is mounted:
> 
> [root@bp-05 tmp]# mount /dev/sdc1 /mnt/test
> 
> only the mounted filesystem is shown:
> 
> [root@bp-05 tmp]# btrfs filesystem show testlabel2
> Label: 'testlabel2'  uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
> 	Total devices 1 FS bytes used 384.00KiB
> 	devid    1 size 30.00GiB used 2.04GiB path /dev/sdc1
> 
> Btrfs v3.14.2
> 
> That's unexpected.
> 
> Mount the other fs, and both are shown again:
> 
> [root@bp-05 tmp]# mount /dev/sdc5 /mnt/scratch
> [root@bp-05 tmp]# btrfs filesystem show testlabel2
> Label: 'testlabel2'  uuid: a43cd507-02a2-46d2-a754-322cb7bdc346
> 	Total devices 1 FS bytes used 384.00KiB
> 	devid    1 size 30.00GiB used 2.04GiB path /dev/sdc1
> 
> Label: 'testlabel2'  uuid: 8c6ec835-5628-439b-9749-d92f62573ce8
> 	Total devices 1 FS bytes used 384.00KiB
> 	devid    1 size 30.00GiB used 2.04GiB path /dev/sdc5
> 
> Btrfs v3.14.2

I'll dig into it. Thank you for let me know.

Satoru

> 
> 
> -Eric
> --
> To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH 1/3] btrfs-progs: random fixes of btrfs-filesystem documentation

[Satoru Takeuchi]

Hi Eric,

(2014/08/12 2:05), Eric Sandeen wrote:
> On 8/11/14, 2:11 AM, Satoru Takeuchi wrote:
>> From: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
>>
>>   - Simplify and unify the description of both man and usage.
>>   - Fix to show -m and -d is not exclusive
>>     with "<path>|<uuid>|<device>|<label>".
>>   - Add the description about short options for "--mounted" and
>>     "--all-devices", "-m" and "-d" respectively.
>>   - Move the descriptions of options to "Options" section.
>>
>> Signed-off-by: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
>>
>> ---
>>   Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
>>   cmds-filesystem.c                  | 15 ++++++++++-----
>>   2 files changed, 24 insertions(+), 13 deletions(-)
>>
>> diff --git a/Documentation/btrfs-filesystem.txt b/Documentation/btrfs-filesystem.txt
>> index c9c0b00..fe68496 100644
>> --- a/Documentation/btrfs-filesystem.txt
>> +++ b/Documentation/btrfs-filesystem.txt
>> @@ -20,15 +20,21 @@ SUBCOMMAND
>>   *df* <path> [<path>...]::
>>   Show space usage information for a mount point.
>>   
>> -*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
>> -Show the btrfs filesystem with some additional info.
>> +*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
>> +Show the structure of btrfs filesystem(s).
>>   +
>> -If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
>> -information of all the btrfs filesystem both mounted and unmounted.
>> -If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
>> -filesystem(s);
>> -If '--all-devices' is passed, all the devices under /dev are scanned;
>> -otherwise the devices list is extracted from the /proc/partitions file.
> 
>> +If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
>> +information of all the btrfs filesystems both mounted and unmounted.
> 
> that doesn't seem quite correct;
> 
> # btrfs filesystem show -m
> 
> does not specify '<path>|<uuid>|<device>|<label>' but it only shows
> mounted filesystems, not all filesystems.

Oh, I forgot to add "[" and "]". 

> 
> As I understand it, the -d and -m options control how the command
> finds devices; the '<path>|<uuid>|<device>|<label>' argument is
> used as a filter for what is found.

Yes, my understanding is so too.

> 
>> ++
>> +The show command finds btrfs filesystems by scanning all the devices
>> +in /proc/partitions by default.
> 
> I think I would document it something like this:
> 
> show [-m|-d] [<path>|<uuid>|<device>|<label>]
> 	Show the structure of btrfs filesystem(s).
> 
> 	By default, the show command scans all devices found in /proc/partitions.	
> 	If [-d|--all-devices] is specified, all devices found under /dev are scanned.
> 	If [-m|--mounted] is specified, only mounted (btrfs?) devices are scanned.
> 
> 	By default, the structure of all discovered filesystems is shown.
> 	If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems
> 	matching that identifier are shown.

OK, I'll fix my patch based on your comment.
# Of course, I'll replace "(btrfs?)" with something proper words.

Can I add your "Signed-off-by" to my v2 patch?

> 
> (What seems to be missing, though, is why would the user ever choose to use '-d?')

I'm not sure. I guess, for example, in large systems, -d takes too
many times for scanning all devices under /dev or something?

Thank you for your comments!

Satoru

> 
> -Eric
> 

Re: [PATCH 1/3] btrfs-progs: random fixes of btrfs-filesystem documentation

[Eric Sandeen]

> On Aug 11, 2014, at 4:51 PM, Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com> wrote:
> 
> Hi Eric,
> 
...
> 
> 
> OK, I'll fix my patch based on your comment.
> # Of course, I'll replace "(btrfs?)" with something proper words.

I assumed it only scans btrfs but didn't know for sure :)

> Can I add your "Signed-off-by" to my v2 patch?

Oh, sure, if you use my text, that makes sense.

thanks,
-Eric


>> 
>> (What seems to be missing, though, is why would the user ever choose to use '-d?')
> 
> I'm not sure. I guess, for example, in large systems, -d takes too
> many times for scanning all devices under /dev or something?
> 
> Thank you for your comments!
> 
> Satoru
> 
>> 
>> -Eric
> 

[PATCH 1/3 v2] btrfs-progs: random fixes of btrfs-filesystem documentation

[Satoru Takeuchi]

From: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>

  - Simplify the description of both man and usage.
  - Add the description about short options for '--all-devices
    and '--mounted', '-d' and '-m' respectively.
  - Fix to show -d and -m is not exclusive
    with '<path>|<uuid>|<device>|<label>'.
  - Move the descriptions of options to "Options" section in manpage.

Signed-off-by: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
Signed-off-by: Eric Sandeen <sandeen@redhat.com>

---
changelog:
  - v2: Fix the description based on Eric's comment
---
  Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
  cmds-filesystem.c                  | 15 ++++++++++-----
  2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/Documentation/btrfs-filesystem.txt b/Documentation/btrfs-filesystem.txt
index c9c0b00..fe68496 100644
--- a/Documentation/btrfs-filesystem.txt
+++ b/Documentation/btrfs-filesystem.txt
@@ -20,15 +20,21 @@ SUBCOMMAND
  *df* <path> [<path>...]::
  Show space usage information for a mount point.
  
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).
  +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
+If none of '<path>|<uuid>|<device>|<label>' is passed, btrfs shows
+information of all the btrfs filesystems both mounted and unmounted.
++
+The show command finds btrfs filesystems by scanning all the devices
+in /proc/partitions by default.
++
+`Options`
++
+-d|--alldevices::::
+scan all the devices under /dev
+-m|--mounted::::
+scan only mounted filesystems
  
  *sync* <path>::
  Force a sync for the filesystem identified by <path>.
diff --git a/cmds-filesystem.c b/cmds-filesystem.c
index 38011e5..3e9f33b 100644
--- a/cmds-filesystem.c
+++ b/cmds-filesystem.c
@@ -578,11 +578,16 @@ out:
  }
  
  static const char * const cmd_show_usage[] = {
-	"btrfs filesystem show [options] [<path>|<uuid>|<device>|label]",
-	"Show the structure of a filesystem",
-	"-d|--all-devices   show only disks under /dev containing btrfs filesystem",
-	"-m|--mounted       show only mounted btrfs",
-	"If no argument is given, structure of all present filesystems is shown.",
+	"btrfs filesystem show [-d|-m] [<path>|<uuid>|<device>|<label>]",
+	"Show the structure of btrfs filesystem(s).",
+	"",
+	"By default, the show command scans all devices found in /proc/partitions.",
+	"If [-d|--all-devices] is specified, all devices found under /dev are scanned.",
+	"If [-m|--mounted] is specified, only mounted btrfs devices are scanned.",
+	"",
+	"By default, the structure of all discovered filesystems is shown.",
+	"If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems",
+	"matching that identifier are shown.",
  	NULL
  };
  
-- 
1.9.3

[PATCH 1/3 v3] btrfs-progs: random fixes of btrfs-filesystem documentation

[Satoru Takeuchi]

Oops, I sent a wrong patch. Here is the correct one.

===
From: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>

  - Simplify the description of both man and usage.
  - Add the description about short options for '--all-devices'
    and '--mounted', '-d' and '-m' respectively.
  - Fix to show -d and -m is not exclusive
    with '<path>|<uuid>|<device>|<label>'.
  - Move the descriptions of options to "Options" section in manpage.

Signed-off-by: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
Signed-off-by: Eric Sandeen <sandeen@redhat.com>

---
changelog:
  - v2: Fix the description based on Eric's comment
  - v3: Fix the incomplete update of btrfs-filesystem.txt
---
  Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
  Documentation/btrfs-replace.txt    |  1 +
  cmds-filesystem.c                  | 15 ++++++++++-----
  3 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/Documentation/btrfs-filesystem.txt b/Documentation/btrfs-filesystem.txt
index c9c0b00..63cb91e 100644
--- a/Documentation/btrfs-filesystem.txt
+++ b/Documentation/btrfs-filesystem.txt
@@ -20,15 +20,21 @@ SUBCOMMAND
  *df* <path> [<path>...]::
  Show space usage information for a mount point.
  
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).
  +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
+By default, the show command scans all devices found in /proc/partitions.
++
+By default, the structure of all discovered filesystems is shown.
+If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems
+matching that identifier are shown.
++
+`Options`
++
+-d|--all-devices::::
+all devices found under /dev are scanned
+-m|--mounted::::
+only mounted btrfs devices are scanned
  
  *sync* <path>::
  Force a sync for the filesystem identified by <path>.
diff --git a/Documentation/btrfs-replace.txt b/Documentation/btrfs-replace.txt
index eecf9b0..476e351 100644
--- a/Documentation/btrfs-replace.txt
+++ b/Documentation/btrfs-replace.txt
@@ -49,6 +49,7 @@ containing a valid btrfs filesystem.
  A valid filesystem is assumed if a btrfs superblock is found which contains a
  correct checksum. Devices which are currently mounted are
  never allowed to be used as the <targetdev>.
++
  -B::::
  no background replace.
  
diff --git a/cmds-filesystem.c b/cmds-filesystem.c
index 38011e5..3e9f33b 100644
--- a/cmds-filesystem.c
+++ b/cmds-filesystem.c
@@ -578,11 +578,16 @@ out:
  }
  
  static const char * const cmd_show_usage[] = {
-	"btrfs filesystem show [options] [<path>|<uuid>|<device>|label]",
-	"Show the structure of a filesystem",
-	"-d|--all-devices   show only disks under /dev containing btrfs filesystem",
-	"-m|--mounted       show only mounted btrfs",
-	"If no argument is given, structure of all present filesystems is shown.",
+	"btrfs filesystem show [-d|-m] [<path>|<uuid>|<device>|<label>]",
+	"Show the structure of btrfs filesystem(s).",
+	"",
+	"By default, the show command scans all devices found in /proc/partitions.",
+	"If [-d|--all-devices] is specified, all devices found under /dev are scanned.",
+	"If [-m|--mounted] is specified, only mounted btrfs devices are scanned.",
+	"",
+	"By default, the structure of all discovered filesystems is shown.",
+	"If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems",
+	"matching that identifier are shown.",
  	NULL
  };
  
-- 
1.9.3

[PATCH 1/3 v4] btrfs-progs: random fixes of btrfs-filesystem documentation

[Satoru Takeuchi]

Here is the *really* correct one. I seems to need a break ;-(

===
From: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>

  - Simplify the description of both man and usage.
  - Add the description about short options for '--all-devices'
    and '--mounted', '-d' and '-m' respectively.
  - Fix to show -d and -m is not exclusive
    with '<path>|<uuid>|<device>|<label>'.
  - Move the descriptions of options to "Options" section in manpage.

Signed-off-by: Satoru Takeuchi <takeuchi_satoru@jp.fujitsu.com>
Signed-off-by: Eric Sandeen <sandeen@redhat.com>

---
changelog:
  - v2: Fix the description based on Eric's comment.
  - v3: Fix the incomplete update of btrfs-filesystem.txt.
  - v4: Remove a unnecessary change about btrfs-replace documentation.
---
  Documentation/btrfs-filesystem.txt | 22 ++++++++++++++--------
  cmds-filesystem.c                  | 15 ++++++++++-----
  2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/Documentation/btrfs-filesystem.txt b/Documentation/btrfs-filesystem.txt
index c9c0b00..63cb91e 100644
--- a/Documentation/btrfs-filesystem.txt
+++ b/Documentation/btrfs-filesystem.txt
@@ -20,15 +20,21 @@ SUBCOMMAND
  *df* <path> [<path>...]::
  Show space usage information for a mount point.
  
-*show* [--mounted|--all-devices|<path>|<uuid>|<device>|<label>]::
-Show the btrfs filesystem with some additional info.
+*show* [-d|-m] [<path>|<uuid>|<device>|<label>]::
+Show the structure of btrfs filesystem(s).
  +
-If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
-information of all the btrfs filesystem both mounted and unmounted.
-If '--mounted' is passed, it would probe btrfs kernel to list mounted btrfs
-filesystem(s);
-If '--all-devices' is passed, all the devices under /dev are scanned;
-otherwise the devices list is extracted from the /proc/partitions file.
+By default, the show command scans all devices found in /proc/partitions.
++
+By default, the structure of all discovered filesystems is shown.
+If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems
+matching that identifier are shown.
++
+`Options`
++
+-d|--all-devices::::
+all devices found under /dev are scanned
+-m|--mounted::::
+only mounted btrfs devices are scanned
  
  *sync* <path>::
  Force a sync for the filesystem identified by <path>.
diff --git a/cmds-filesystem.c b/cmds-filesystem.c
index 38011e5..3e9f33b 100644
--- a/cmds-filesystem.c
+++ b/cmds-filesystem.c
@@ -578,11 +578,16 @@ out:
  }
  
  static const char * const cmd_show_usage[] = {
-	"btrfs filesystem show [options] [<path>|<uuid>|<device>|label]",
-	"Show the structure of a filesystem",
-	"-d|--all-devices   show only disks under /dev containing btrfs filesystem",
-	"-m|--mounted       show only mounted btrfs",
-	"If no argument is given, structure of all present filesystems is shown.",
+	"btrfs filesystem show [-d|-m] [<path>|<uuid>|<device>|<label>]",
+	"Show the structure of btrfs filesystem(s).",
+	"",
+	"By default, the show command scans all devices found in /proc/partitions.",
+	"If [-d|--all-devices] is specified, all devices found under /dev are scanned.",
+	"If [-m|--mounted] is specified, only mounted btrfs devices are scanned.",
+	"",
+	"By default, the structure of all discovered filesystems is shown.",
+	"If any one of [<path>|<uuid>|<device>|<label>] is specified, only filesystems",
+	"matching that identifier are shown.",
  	NULL
  };
  
-- 
1.9.3

Re: [PATCH 1/3 v4] btrfs-progs: random fixes of btrfs-filesystem documentation

[David Sterba]

On Tue, Aug 12, 2014 at 05:06:01PM +0900, Satoru Takeuchi wrote:
> +By default, the show command scans all devices found in /proc/partitions.

The default scanning method is blkid, /proc/partitions used to be the
default before that. Scanning /proc/partitions is not done through the
'show' command, only during open_ctree afaics.

Re: [PATCH 1/3] btrfs-progs: random fixes of btrfs-filesystem documentation

[David Sterba]

On Mon, Aug 11, 2014 at 10:05:52AM -0700, Eric Sandeen wrote:
> (What seems to be missing, though, is why would the user ever choose to use '-d?')

That's a fallback method if blkid or udev are not available. We've had
reports in the past that this functionality should not be dropped.

Re: [PATCH 1/3] btrfs-progs: random fixes of btrfs-filesystem documentation

[Eric Sandeen]

On 8/19/14, 10:10 AM, David Sterba wrote:
> On Mon, Aug 11, 2014 at 10:05:52AM -0700, Eric Sandeen wrote:
>> (What seems to be missing, though, is why would the user ever choose to use '-d?')
> 
> That's a fallback method if blkid or udev are not available. We've had
> reports in the past that this functionality should not be dropped.

Seems like using /proc/partitions would make more sense in that case
than a recursive scan of every file under /dev, wouldn't it?
Any details on those reports?

I'm just wondering when you might possibly have success looking deep
into the /dev tree if you didn't have success in /proc/partitions.

It looks like the functionality was added with:

commit 0dbd99fb3e117cd5f87eda492b6b4fab1b5bea23
Author: Goffredo Baroncelli <kreijack@inwind.it>
Date:   Wed Jun 15 21:55:25 2011 +0200

    Scan the devices listed in /proc/partitions
    
    During the commands:
        - btrfs filesystem show
        - btrfs device scan
    the devices "scanned" are extracted from /proc/partitions. This
    should avoid to scan devices not suitable for a btrfs filesystem like cdrom
    and floppy or to scan not existant devices.
    The old behavior (scan all the block devices under /dev) may be
    forced passing the "--all-devices" switch.

but I'm not sure why it was preserved.

It just seems a bit bizarre to have so many ways to get the same info.

Thanks,
-Eric

Re: [PATCH 1/3] btrfs-progs: random fixes of btrfs-filesystem documentation

[David Sterba]

On Tue, Aug 19, 2014 at 10:33:44AM -0500, Eric Sandeen wrote:
> Seems like using /proc/partitions would make more sense in that case
> than a recursive scan of every file under /dev, wouldn't it?
> Any details on those reports?

It does make sense.

> I'm just wondering when you might possibly have success looking deep
> into the /dev tree if you didn't have success in /proc/partitions.

I haven't figured out any advantage of /dev.

> It just seems a bit bizarre to have so many ways to get the same info.

I think keeping blkid as default and /proc/filesystems as fallback
should cover the usecases. This meanas that the option -d stays, and the
scanning method can be changed to BTRFS_SCAN_PROC (fi show and dev scan).