Clarification of 'btrfs send' and 'btrfs receive' functionality and 'btrfs recieve <path>' expected input

[croogrog]

The current documentation on btrfs send and btrfs recieve is unclear. I recommend changing the descriptions of both to clarify by addressing 2 questions

1. In btrfs receive what is the intended use for ? (I *think it's a new subvolume)

2. What is written by btrfs receive? (I *think it writes exactly what btrfs send tells it to but this only shifts the question to btrfs send.)

If the functionality of btrfs receive <path> is to create a new subvolume then write one or more subvolumes to it this should be expressly stated. Maybe change the description to:

Receive a stream of changes and replicate one or more subvolumes that were previously generated by btrfs send. The received subvolumes are stored to a new subvolume at , unless --dump option is given.

Though if a new subvolume is being created maybe changing to / would be more clear and resemble other btrfs documentation.

This just brings up more questions. I don't know anything about the format of output from btrfs send <subvol1>...<subvolN>

How does btrfs send handle single and multiple subvolumes? (I *guess it will differ for a single volume where the contents are provided rather than nesting it)
For the case of multiple subvoIumes is nesting preserved or are they all at the same level? (I *guess they are all immediately below the root level)

How single and multiple subvolumes are handled matters especially if not identically. So please add something to the description regarding the overall structure of the output of 'btrfs send'

By now I have been doing a lot of thinking and guessing so I should mention:
*think means I have some evidence to infer the statement from the docs.
*guess means I have no evidence and am using my own arbitrary expectations of interface and functionality to infer the statement.

Everything below here is my thinking and guessing and why I even wrote this in the first place.

I wanted to migrate to a larger ssd with a different partition scheme. Having developed some familiarity with btrfs I thought it would be more convenient to use a live usb with the btrfs tools to migrate my filesystem and then change a few values in key files like fstab, install grub to the new boot partition and be back up and running. Since google has decided that reddit is a credible source, I went strait to the btrfs docs. And for the first time I wasn't sure how to actually use the commands after reading them. Basically I had those 2 questions left hanging. Sure I could do some trial and error to figure out exactly what is happening. But I don't have the spare devices to practice on and I have no intention of copying over 100GB more than one time. I want to get it right the first time so I looked over the docs a little more thoroughly and scraped together what I could. Then I guessed that the design would work similarly to cp or dd and started writing this.

From btrfs recieve docs:

btrfs receive [options]
...
Receive a stream of changes and replicate one or more subvolumes that were previously generated by btrfs send. The received subvolumes are stored to path, unless --dump option is given.

To me this suggests is an existing directory or subvolume where one or more subvolumes are written to.

btrfs receive will fail in the following cases:

1. receiving subvolume already exists

To me this suggests that should not exist and it will be a created subvolume.

The btrfs send docs contain no info on how subvolumes are managed at all so I just have to guess.

I would like to use btrfs send & receive in a similar way to cp or dd so my guessing is based on these expectations:

btrfs send <subvolume> | btrfs recieve <dest>/<new_subvolume> # this would create <new_subvolume> in <dest> with the contents of <subvolume> btrfs send <subvol1>..<subvolN> | btrfs recieve <dest>/<new_subvolume> # this would create <new_subvolume> in <dest> with <subvol1>..<subvolN> nested at top level with their respective contents btrfs send <subvol1> [..<subvolN>] | btrfs recieve <dest>/ # this would create <subvol1>..<subvolN> in <dest>/ with their respective contents

Now that I look at these again I think that if corrected this would make an excellent example for the documentation.