Bug 1004506

Summary: Missing documentation for btrfs-zero-log
Product: [Fedora] Fedora Reporter: Brian Harrington <bharrington>
Component: btrfs-progsAssignee: Josef Bacik <josef>
Status: CLOSED ERRATA QA Contact: Fedora Extras Quality Assurance <extras-qa>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 19CC: esandeen, josef, kburres, mmahut
Target Milestone: ---   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: btrfs-progs-3.12-1.fc19 Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2013-12-09 02:01:35 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Brian Harrington 2013-09-04 19:21:30 UTC
Description of problem:
There's no documentation for multiple tools within btrfs-progs

[bharrington@leviathan ~]$ btrfs-zero-log --help
check_mounted(): Could not open --help
Could not check mount status: No such file or directory
[bharrington@leviathan ~]$ btrfs-zero-log -h
check_mounted(): Could not open -h
Could not check mount status: No such file or directory
[bharrington@leviathan ~]$ btrfs-zero-log /h
check_mounted(): Could not open /h
Could not check mount status: No such file or directory
[bharrington@leviathan ~]$ btrfs-zero-log /?
check_mounted(): Could not open /?
Could not check mount status: No such file or directory
[bharrington@leviathan ~]$ man btrfs-zero-log
No manual entry for btrfs-zero-log
[bharrington@leviathan ~]$ rpm -qif `which btrfs-zero-log`
Name        : btrfs-progs
Version     : 0.20.rc1.20130308git704a08c
Release     : 1.fc19
Architecture: x86_64
Install Date: Tue 27 Aug 2013 05:06:42 PM PDT
Group       : System Environment/Base
Size        : 2918122
License     : GPLv2
Signature   : RSA/SHA256, Fri 15 Mar 2013 03:27:07 AM PDT, Key ID 07477e65fb4b18e6
Source RPM  : btrfs-progs-0.20.rc1.20130308git704a08c-1.fc19.src.rpm
Build Date  : Fri 08 Mar 2013 08:10:09 PM PST
Build Host  : buildvm-25.phx2.fedoraproject.org
Relocations : (not relocatable)
Packager    : Fedora Project
Vendor      : Fedora Project
URL         : http://btrfs.wiki.kernel.org/index.php/Main_Page
Summary     : Userspace programs for btrfs
Description :
The btrfs-progs package provides all the userpsace programs needed to create,
check, modify and correct any inconsistencies in the btrfs filesystem.
[bharrington@leviathan ~]$ rpm -qd btrfs-progs
/usr/share/doc/btrfs-progs-0.20.rc1.20130308git704a08c/COPYING
/usr/share/doc/btrfs-progs-0.20.rc1.20130308git704a08c/INSTALL
/usr/share/man/man8/btrfs-image.8.gz
/usr/share/man/man8/btrfs-show.8.gz
/usr/share/man/man8/btrfs.8.gz
/usr/share/man/man8/btrfsck.8.gz
/usr/share/man/man8/btrfsctl.8.gz
/usr/share/man/man8/mkfs.btrfs.8.gz

Comment 1 Eric Sandeen 2013-09-18 15:52:46 UTC
A new git snapshot of btrfs-progs has been pushed to F19 testing.  If possible, please re-test these bugs & feel free to close or comment as appropriate.

Thanks,
-Eric

Comment 2 Brian Harrington 2013-09-23 19:23:47 UTC
This version is actually even worse as far as documentation goes:

[bharrington@leviathan Pictures]$ rpm -qd btrfs-progs/usr/share/doc/btrfs-progs-0.20.rc1.20130917git194aa4a/COPYING
/usr/share/man/man8/btrfs-image.8.gz
/usr/share/man/man8/btrfs.8.gz
/usr/share/man/man8/btrfsck.8.gz
/usr/share/man/man8/mkfs.btrfs.8.gz



[bharrington@leviathan Pictures]$ rpm -ql btrfs-progs | grep bin
/usr/sbin/btrfs
/usr/sbin/btrfs-convert
/usr/sbin/btrfs-debug-tree
/usr/sbin/btrfs-find-root
/usr/sbin/btrfs-image
/usr/sbin/btrfs-map-logical
/usr/sbin/btrfs-show-super
/usr/sbin/btrfs-zero-log
/usr/sbin/btrfsck
/usr/sbin/btrfstune
/usr/sbin/mkfs.btrfs

Comment 3 Eric Sandeen 2013-09-23 23:46:10 UTC
Would you like to write some docs & send them upstream?  That'd be an awesome collaborative-community-development thing to do.  :)

(Between the btrfs wiki & tool help output, at least a minimal man page could surely be cobbled together for review on the list and inclusion in the next release).

Comment 4 Eric Sandeen 2013-09-23 23:58:01 UTC
FWIW, although some of these tools don't take -h/--help/etc, most will print usage() when invoked w/ no options:

# btrfs-zero-log
usage: btrfs-zero-log dev

Sparse, granted, but it's something.

# btrfs-convert
usage: btrfs-convert [-d] [-i] [-n] [-r] device
	-d disable data checksum
	-i ignore xattrs and ACLs
	-n disable packing of small files
	-r roll back to ext2fs

# btrfs-find-root
Usage: find-roots [-o search_objectid] [ -g search_generation ] [ -l search_level ] <device>

# btrfs-image
usage: btrfs-image [options] source target
	-r      	restore metadump image
	-c value	compression level (0 ~ 9)
	-t value	number of threads (1 ~ 32)
	-o      	don't mess with the chunk tree when restoring
	-s      	sanitize file names, use once to just use garbage, use twice if you want crc collisions
	-w      	walk all trees instead of using extent tree, do this if your extent tree is broken

# btrfs-map-logical
usage: btrfs-map-logical [options] device
	-l Logical extent to map
	-c Copy of the extent to read (usually 1 or 2)
	-o Output file to hold the extent
	-b Number of bytes to read

etc...

Comment 7 Fedora Update System 2013-11-14 19:25:03 UTC
btrfs-progs-0.20.rc1.20131114git9f0c53f-1.fc19 has been submitted as an update for Fedora 19.
https://admin.fedoraproject.org/updates/btrfs-progs-0.20.rc1.20131114git9f0c53f-1.fc19

Comment 8 Eric Sandeen 2013-11-14 19:27:33 UTC
commit e7b0ec3665112143295028a60e2a14cb24df675a
Author: Wang Shilong <wangsl.fnst.com>
Date:   Wed Aug 14 12:29:16 2013 +0800

    Btrfs-progs: add missing man page information for btrfs-zero-log
    
    Signed-off-by: Wang Shilong <wangsl.fnst.com>
    Signed-off-by: Qu Wenruo <quwenruo.com>
    Signed-off-by: David Sterba <dsterba>
    Signed-off-by: Chris Mason <chris.mason>

Should be in the next release.

Comment 9 Fedora Update System 2013-11-15 20:37:07 UTC
Package btrfs-progs-0.20.rc1.20131114git9f0c53f-1.fc19:
* should fix your issue,
* was pushed to the Fedora 19 testing repository,
* should be available at your local mirror within two days.
Update it with:
# su -c 'yum update --enablerepo=updates-testing btrfs-progs-0.20.rc1.20131114git9f0c53f-1.fc19'
as soon as you are able to.
Please go to the following url:
https://admin.fedoraproject.org/updates/FEDORA-2013-21422/btrfs-progs-0.20.rc1.20131114git9f0c53f-1.fc19
then log in and leave karma (feedback).

Comment 10 Fedora Update System 2013-11-26 15:22:15 UTC
btrfs-progs-3.12-1.fc19 has been submitted as an update for Fedora 19.
https://admin.fedoraproject.org/updates/btrfs-progs-3.12-1.fc19

Comment 11 Fedora Update System 2013-12-09 02:01:35 UTC
btrfs-progs-3.12-1.fc19 has been pushed to the Fedora 19 stable repository.  If problems still persist, please make note of it in this bug report.