Bug 235850
| Summary: | bectl(8): create should mention it creates from booted system without any other argument | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | Larry Rosenman <ler> |
| Component: | Manual Pages | Assignee: | Mateusz Piotrowski <0mp> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | CC: | 0mp, doc, kevans |
| Priority: | --- | Keywords: | needs-patch |
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
(In reply to Larry Rosenman from comment #0) Mmm, I think I misunderstood something: I think that bectl always requires an argument, doesn't it? When you say: bectl create newbe it will use the currently running boot environment. For a person that is not familiar with the underlying libbe(3) create call, it's unclear that the currently running boot environment will be the one cloned to create the newbe environment. What I'm asking for is to add the statement from the libbe(3) create call documentation to the bectl(8) create command documentation that without a 3rd argument the currently running boot environment will be cloned to create the new boot environment. (In reply to Mateusz Piotrowski from comment #1) Right, he's talking specifically about the 'create' subcommand. I note that the man page here is kind of... bad. We should do the following: 1.) Get rid of the bectl create [-r] beName@snapshot line in SYNOPSIS 2.) Get rid of the same down in commands 3.) Amend the create command description to mention: If the .Fl e argument is specified, the new environment will be cloned from the given nonActiveBE | beName@snapshot. When the .Fl e argument is not specified, the new environment will be created from the currently booted environment. If .Nm is creating from another boot environment, a snapshot of that boot environment will be created to clone from. Of course, the markup is basically all wrong, but I think that gets the idea across. We should mention for those not familiar with bectl that the default is to use the currently booted environment, and we should mention for those maybe not necessarily familiar with some of the underlying ZFS terminology that create of anything other than beName@snapshot implies that a snapshot of that boot environment will be made for creation. A commit references this bug: Author: 0mp Date: Wed Apr 3 13:46:44 UTC 2019 New revision: 345845 URL: https://svnweb.freebsd.org/changeset/base/345845 Log: bectl.8: Clean up & clarify the create subcommand - Improve formatting - Use consistent variable names - Improve the description of the create subcommand (1) PR: 235850 (1) Submitted by: kevans (1) Reported by: ler (1) Reviewed by: kevans Approved by: src (kevans) Differential Revision: https://reviews.freebsd.org/D19666 Changes: head/sbin/bectl/bectl.8 Larry, could you have a look if it's fine? MUCH nicer! Thanks! A commit references this bug: Author: kevans Date: Mon Sep 9 17:53:16 UTC 2019 New revision: 352086 URL: https://svnweb.freebsd.org/changeset/base/352086 Log: MFC r345845-r345846: bectl(8) manpage clarity r345845: bectl.8: Clean up & clarify the create subcommand - Improve formatting - Use consistent variable names - Improve the description of the create subcommand (1) PR: 235850 r345846: bectl.8: Bump date after r345845 Changes: _U stable/12/ stable/12/sbin/bectl/bectl.8 |
The bectl(8) manpage under the create option should echo the libbe(3) be_create wording to say that it populates the BE from the running system if no other arguments are given. It will be created from a snapshot of the currently booted boot environ- ment.