Bug 1476280

Summary:	Differences between command -h and its manpage
Product:	Red Hat Enterprise Linux 7	Reporter:	Jakub Krysl <jkrysl>
Component:	device-mapper-persistent-data	Assignee:	Joe Thornber <thornber>
Status:	CLOSED ERRATA	QA Contact:	Jakub Krysl <jkrysl>
Severity:	unspecified	Docs Contact:
Priority:	unspecified
Version:	7.4	CC:	agk, heinzm, jkrysl, lvm-team, mcsontos, msnitzer, thornber
Target Milestone:	rc
Target Release:	---
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:	device-mapper-persistent-data-0.7.3-1.el7	Doc Type:	If docs needed, set a value
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2018-04-10 13:17:29 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:
Embargoed:

Description Jakub Krysl 2017-07-28 13:38:37 UTC

Description of problem:
Device-mapper-persistent-data provides few commands in /usr/sbin/ (rpm -ql device-mapper-persistent-data) and most of them have differences between its -h output and its manpage. So I decided to create a single bug and try to write the main differences command by command. There are already quite a few bugs about this issue, but each of them targets only single command and they don't cover this problem by far. SO I added them to each command her to provide a handy link.
Here are all the the differences command by command. If there is no info under the command, the manpage and -h goves the same options.

cache_check
 - manpage is missing option --clear-needs-check-flag

cache_dump
 - manpage is missing option -o <xml file>

cache_metadata_size
 - whole manpage is missing

cache_repair

cache_restore
 - manpage is missing option -q | --quiet
 - manpage is missing option --omit-clean-shutdown

cache_writeback
 - option --no-metadata-update is written as --skip-metadata-update in manpage
 - manpage is missing option --buffer-size-meg <size>
 - manpage is missing option --list-failed-blocks

era_check

era_dump
 - manpage lists invalid variant of option --repair as -r, which is not recognized and not listed in -h
 - manpage is missing option -o <xml file>

era_invalidate
 - manpage is missing option --metadata-snapshot
 - both manpage and -h are not listing option --written-since, which is only in examples
 - BZ1450196

era_restore
 - whole manpage is missing
 - BZ1450200

pdata_tools
 - no idea what this one should do, it only prints available commands list (which is not the same as rpm -ql) and has no -h option. Also no manpage.

thin_check

thin_delta
 - wrong number in second thin numeric identifier, is --thin1, --snap1 but should be --thin2, --snap2
 - BZ1253031

thin_dump
 - manpage is missing option -o <xml file>
 - -h is missing option --skip-mappings

thin_ls
 - manpage lists option --verbose, but it is unreconized
 - BZ1469183

thin_metadata_size

thin_repair

thin_restore

thin_rmap

thin_show_duplicates
 - can't compare because manpage is missing and command is urecognized
 - BZ1469178

thin_trim
 - can't compare because command is unrecognized (manpage exists)
 - BZ1471095

Version-Release number of selected component (if applicable):
0.7.0-0.1.rc6.el7

Comment 2 Jakub Krysl 2017-08-03 11:00:56 UTC

cache_metadata_size has option "--max-hint-width" which is not listed under -h

[root@storageqe-21 cache]# cache_metadata_size --max-hint-width 0 --nr-blocks 0
8192 sectors

Comment 3 Joe Thornber 2017-09-18 15:14:17 UTC

This commit fixes a lot of these issues.

https://github.com/jthornber/thin-provisioning-tools/commit/f7d79339e8da664d82f32e276a38744f050be9be

pdata_tools is the executable that all the other tools sym link to.

New release to follow this week.

Comment 6 Jakub Krysl 2017-09-22 13:03:35 UTC

Went through all of those in device-mapper-persistent-data-0.7.2-1.el7 and everything is fixed except for 1 thing:

era_invalidate option '--written-since' requires an argument, but this is not said in manpage as with the rest options requiring arguments (e.g. '-o {output file}' ). When given this option without argument, an error message appears.
Can you please modify manpage to something like '--written-since {era nr}'?

Comment 7 Joe Thornber 2017-10-05 11:40:06 UTC

Fix:

https://github.com/jthornber/thin-provisioning-tools/commit/8a0ee614343f945eeed06b7cff80a6a02bbf6dac

Comment 8 Jakub Krysl 2017-10-09 08:55:11 UTC

Fixed in device-mapper-persistent-data-0.7.3-1.el7.

Comment 11 errata-xmlrpc 2018-04-10 13:17:29 UTC

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHEA-2018:0776