1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
#!/usr/bin/env bash
#
# Compare commands listed by 'podman help' against those in 'man podman'.
# Recurse into subcommands as well.
#
# Because we read metadoc files in the `docs` directory, this script
# must run from the top level of a git checkout. FIXME: if necessary,
# it could instead run 'man podman-XX'; my thinking is that this
# script should run early in CI.
#
# override with, e.g., PODMAN=./bin/podman-remote
PODMAN=${PODMAN:-./bin/podman}
function die() {
echo "FATAL: $*" >&2
exit 1
}
# Run 'podman help' (possibly against a subcommand, e.g. 'podman help image')
# and return a list of each first word under 'Available Commands', that is,
# the command name but not its description.
function podman_commands() {
$PODMAN help "$@" |\
awk '/^Available Commands:/{ok=1;next}/^Flags:/{ok=0}ok { print $1 }' |\
grep .
}
# Read a list of subcommands from a command's metadoc
function podman_man() {
if [ "$@" = "podman" ]; then
# podman itself.
# This md file has a table of the form:
# | [podman-cmd(1)\[(podman-cmd.1.md) | Description ... |
# For all such, print the 'cmd' portion (the one in brackets).
sed -ne 's/^|\s\+\[podman-\([a-z]\+\)(1.*/\1/p' <docs/source/markdown/$1.1.md
# Special case: there is no podman-help man page, nor need for such.
echo "help"
# Auto-update differs from other commands as it's a single command, not
# a main and sub-command split by a dash.
echo "auto-update"
elif [ "$@" = "podman-image-trust" ]; then
# Special case: set and show aren't actually in a table in the man page
echo set
echo show
else
# podman subcommand.
# Each md file has a table of the form:
# | cmd | [podman-cmd(1)](podman-cmd.1.md) | Description ... |
# For all such we find, with 'podman- in the second column, print the
# first column (with whitespace trimmed)
awk -F\| '$3 ~ /podman-/ { gsub(" ","",$2); print $2 }' < docs/source/markdown/$1.1.md
fi
}
# The main thing. Compares help and man page; if we find subcommands, recurse.
rc=0
function compare_help_and_man() {
echo
echo "checking: podman $@"
# e.g. podman, podman-image, podman-volume
local basename=$(echo podman "$@" | sed -e 's/ /-/g')
podman_commands "$@" | sort > /tmp/${basename}_help.txt
podman_man $basename | sort > /tmp/${basename}_man.txt
diff -u /tmp/${basename}_help.txt /tmp/${basename}_man.txt || rc=1
# Now look for subcommands, e.g. container, image
for cmd in $(< /tmp/${basename}_help.txt); do
usage=$($PODMAN "$@" $cmd --help | grep -A1 '^Usage:' | tail -1)
# if string ends in '[command]', recurse into its subcommands
if expr "$usage" : '.*\[command\]$' >/dev/null; then
compare_help_and_man "$@" $cmd
fi
done
rm -f /tmp/${basename}_{help,man}.txt
}
compare_help_and_man
if [ $rc -ne 0 ]; then
cat <<EOF
**************************
** INTERPRETING RESULTS **
**************************************************************************
*
* The above results show differences between 'podman --help' and
* podman man pages.
*
* The 'checking:' header indicates the specific command (and possibly
* subcommand) being tested, e.g. podman --help vs docs/source/podman.1.md.
*
* A '-' indicates a subcommand present in 'podman --help' but not the
* corresponding man page.
*
* A '+' indicates a subcommand present in the man page but not --help.
*
**************************************************************************
EOF
fi
exit $rc
|
