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