[RFC PATCH] Deprecate btrfsctl, btrfs-show, btrfs-vol

[Goffredo Baroncelli <kreijack@libero.it>]

[-- Attachment #1: Type: Text/Plain, Size: 6356 bytes --]

Hi all,

the patch below deprecates the following programs

* btrfsctl
* btrfs-vol
* btrfs-show

the reason is simple, these programs are superseded by the btrfs utility,
both in terms of documentation, usability and bug. The goal is to avoid 
to duplicate codes and avoid update two programs.

What I am asking here is a comment about the WARNINGs and suggestions about 
the policy to adopt in deprecating these programs.
My suggestions are:
- put a warning in the documentation and in the program (see below)
- "freeze" the programs avoiding to add new functionality to the 
  "old utilities". 
- after six month remove the old utilities programs from the btrfs-progs 
  package

The aim is to support the old systems but discourage to use the old tools.

If btrfs would show regression respect the old tools, I am happy to know and 
I will work to solve the issues.

The patch adds a warning in the man pages, in the INSTALL file and in the 
programs.

$ ./btrfsctl 
**
** WARNING: this program is considered deprecated
** Please consider to switch to the btrfs utility
**
no valid commands given
usage: btrfsctl [ -d file|dir] [ -s snap_name subvol|tree ]
                [-r size] [-A device] [-a] [-c] [-D dir .]
        -d filename: defragments one file
        -d directory: defragments the entire Btree
        -s snap_name dir: creates a new snapshot of dir
        -S subvol_name dir: creates a new subvolume
        -r [+-]size[gkm]: resize the FS by size amount
        -A device: scans the device file for a Btrfs filesystem
        -a: scans all devices for Btrfs filesystems
        -c: forces a single FS sync
        -D: delete snapshot
        -m [tree id] directory: set the default mounted subvolume to the [tree id] or the 
directory


Below the patch, but it is possible to pull the changes from:

 	http://cassiopea.homelinux.net/git/btrfs-progs-unstable-all.git

branch

	btrfs-deprecated

Comments are welcome.

G.Baroncelli

 INSTALL             |    5 +++++
 btrfs-show.c        |    5 +++++
 btrfs-vol.c         |    5 +++++
 btrfsctl.c          |    5 +++++
 man/btrfs-show.8.in |    3 +++
 man/btrfsctl.8.in   |    3 +++
 6 files changed, 26 insertions(+)


diff --git a/INSTALL b/INSTALL
index 16b45a5..cbde78f 100644

--- a/INSTALL
+++ b/INSTALL
@@ -24,10 +24,15 @@ e2fsprogs-devel from various distros.
 Building the utilities is just make ; make install.  The programs go
 into /usr/local/bin.  The commands available are:
 
+btrfs: control program to manage the filesystem.
+
 mkfs.btrfs: create a filesystem
 
 btrfsctl: control program to create snapshots and subvolumes:
 
+	NOTE: this utility is deprecated. Please consider to switch
+	to the btrfs utility (see above)
+
 	mount /dev/sda2 /mnt
 	btrfsctl -s new_subvol_name /mnt
 	btrfsctl -s snapshot_of_default /mnt/default
diff --git a/btrfs-show.c b/btrfs-show.c
index c49626c..8210fd2 100644
--- a/btrfs-show.c
+++ b/btrfs-show.c
@@ -117,6 +117,11 @@ int main(int ac, char **av)
 	int ret;
 	int option_index = 0;
 
+	printf( "**\n"
+		"** WARNING: this program is considered deprecated\n"
+		"** Please consider to switch to the btrfs utility\n"
+		"**\n");
+
 	while(1) {
 		int c;
 		c = getopt_long(ac, av, "", long_options,
diff --git a/btrfs-vol.c b/btrfs-vol.c
index 4ed799d..fe6f240 100644
--- a/btrfs-vol.c
+++ b/btrfs-vol.c
@@ -78,6 +78,11 @@ int main(int ac, char **av)
 	struct btrfs_ioctl_vol_args args;
 	u64 dev_block_count = 0;
 
+	printf( "**\n"
+		"** WARNING: this program is considered deprecated\n"
+		"** Please consider to switch to the btrfs utility\n"
+		"**\n");
+
 	while(1) {
 		int c;
 		c = getopt_long(ac, av, "a:br:", long_options,
diff --git a/btrfsctl.c b/btrfsctl.c
index 92bdf39..d20c96a 100644
--- a/btrfsctl.c
+++ b/btrfsctl.c
@@ -107,6 +107,11 @@ int main(int ac, char **av)
 	char *fullpath;
 	u64 objectid = 0;
 
+	printf( "**\n"
+		"** WARNING: this program is considered deprecated\n"
+		"** Please consider to switch to the btrfs utility\n"
+		"**\n");
+	
 	if (ac == 2 && strcmp(av[1], "-a") == 0) {
 		fprintf(stderr, "Scanning for Btrfs filesystems\n");
 		btrfs_scan_one_dir("/dev", 1);
diff --git a/man/btrfs-show.8.in b/man/btrfs-show.8.in
index dd0b147..cb98b68 100644
--- a/man/btrfs-show.8.in
+++ b/man/btrfs-show.8.in
@@ -3,6 +3,9 @@
 btrfs-show \- scan the /dev directory for btrfs partitions and print results.
 .SH SYNOPSIS
 .B btrfs-show
+.SH NOTE
+.B btrfs-show
+is deprecated. Please consider to switch to the btrfs utility.	
 .SH DESCRIPTION
 .B btrfs-show
 is used to scan the /dev directory for btrfs partitions and display brief
diff --git a/man/btrfsctl.8.in b/man/btrfsctl.8.in
index c2d4488..558b484 100644
--- a/man/btrfsctl.8.in
+++ b/man/btrfsctl.8.in
@@ -10,6 +10,9 @@ btrfsctl \- control a btrfs filesystem
 [ \fB \-A\fP\fI device\fP ]
 [ \fB \-a\fP ]
 [ \fB \-c\fP ]
+.SH NOTE
+.B btrfs-show
+is deprecated. Please consider to switch to the btrfs utility.
 .SH DESCRIPTION
 .B btrfsctl
 is used to control the filesystem and the files and directories stored. It is the tool to 
create a new snapshot for the filesystem.


On Tuesday, 26 October, 2010, Chris Mason wrote:
> On Tue, Oct 26, 2010 at 07:32:14PM +0200, Goffredo Baroncelli wrote:
> > 
> > The package btrfs-tools needs a lot of care:
> > - the INSTALL file still reports that is not possible to remove a subvolume
> > - a lot of program are not documented (what is the meaning of btrfs-zero-log 
> > ?)
> > - "btrfs dev scan" and "btrfs -a" try to read CDROM and Floppy looking for a 
> > btrfs filesystem: only waste of time
> > - [...]
> > 
> > I think that is better to improve the btrfs-progs and not to update btrfsctl.
> 
> I'd agree, the btrfsctl command is more than a little awkward, and the
> btrfs command is pretty much better in every way.
> 
> -chris
> 
> --
> 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
> 


-- 
gpg key@ keyserver.linux.it: Goffredo Baroncelli (ghigo) <kreijack@inwind.it>
Key fingerprint = 4769 7E51 5293 D36C 814E  C054 BF04 F161 3DC5 0512

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 190 bytes --]