diff options
26 files changed, 162 insertions, 77 deletions
diff --git a/cmd/podman/healthcheck/run.go b/cmd/podman/healthcheck/run.go index 5612910cb..17ddf17b6 100644 --- a/cmd/podman/healthcheck/run.go +++ b/cmd/podman/healthcheck/run.go @@ -12,12 +12,13 @@ import ( var ( healthcheckRunDescription = "run the health check of a container" healthcheckrunCommand = &cobra.Command{ - Use: "run [flags] CONTAINER", - Short: "run the health check of a container", - Long: healthcheckRunDescription, - Example: `podman healthcheck run mywebapp`, - RunE: run, - Args: cobra.ExactArgs(1), + Use: "run CONTAINER", + Short: "run the health check of a container", + Long: healthcheckRunDescription, + Example: `podman healthcheck run mywebapp`, + RunE: run, + Args: cobra.ExactArgs(1), + DisableFlagsInUseLine: true, } ) diff --git a/cmd/podman/images/tag.go b/cmd/podman/images/tag.go index dae3416c4..859489552 100644 --- a/cmd/podman/images/tag.go +++ b/cmd/podman/images/tag.go @@ -9,22 +9,24 @@ import ( var ( tagDescription = "Adds one or more additional names to locally-stored image." tagCommand = &cobra.Command{ - Use: "tag [flags] IMAGE TARGET_NAME [TARGET_NAME...]", - Short: "Add an additional name to a local image", - Long: tagDescription, - RunE: tag, - Args: cobra.MinimumNArgs(2), + Use: "tag IMAGE TARGET_NAME [TARGET_NAME...]", + Short: "Add an additional name to a local image", + Long: tagDescription, + RunE: tag, + Args: cobra.MinimumNArgs(2), + DisableFlagsInUseLine: true, Example: `podman tag 0e3bbc2 fedora:latest podman tag imageID:latest myNewImage:newTag podman tag httpd myregistryhost:5000/fedora/httpd:v2`, } imageTagCommand = &cobra.Command{ - Args: tagCommand.Args, - Use: tagCommand.Use, - Short: tagCommand.Short, - Long: tagCommand.Long, - RunE: tagCommand.RunE, + Args: tagCommand.Args, + DisableFlagsInUseLine: true, + Use: tagCommand.Use, + Short: tagCommand.Short, + Long: tagCommand.Long, + RunE: tagCommand.RunE, Example: `podman image tag 0e3bbc2 fedora:latest podman image tag imageID:latest myNewImage:newTag podman image tag httpd myregistryhost:5000/fedora/httpd:v2`, diff --git a/cmd/podman/images/untag.go b/cmd/podman/images/untag.go index 266a3f115..5d1274895 100644 --- a/cmd/podman/images/untag.go +++ b/cmd/podman/images/untag.go @@ -8,22 +8,24 @@ import ( var ( untagCommand = &cobra.Command{ - Use: "untag [flags] IMAGE [NAME...]", - Short: "Remove a name from a local image", - Long: "Removes one or more names from a locally-stored image.", - RunE: untag, - Args: cobra.MinimumNArgs(1), + Use: "untag IMAGE [NAME...]", + Short: "Remove a name from a local image", + Long: "Removes one or more names from a locally-stored image.", + RunE: untag, + Args: cobra.MinimumNArgs(1), + DisableFlagsInUseLine: true, Example: `podman untag 0e3bbc2 podman untag imageID:latest otherImageName:latest podman untag httpd myregistryhost:5000/fedora/httpd:v2`, } imageUntagCommand = &cobra.Command{ - Args: untagCommand.Args, - Use: untagCommand.Use, - Short: untagCommand.Short, - Long: untagCommand.Long, - RunE: untagCommand.RunE, + Args: untagCommand.Args, + DisableFlagsInUseLine: true, + Use: untagCommand.Use, + Short: untagCommand.Short, + Long: untagCommand.Long, + RunE: untagCommand.RunE, Example: `podman image untag 0e3bbc2 podman image untag imageID:latest otherImageName:latest podman image untag httpd myregistryhost:5000/fedora/httpd:v2`, diff --git a/cmd/podman/manifest/inspect.go b/cmd/podman/manifest/inspect.go index 5112aa5b2..861f4be4f 100644 --- a/cmd/podman/manifest/inspect.go +++ b/cmd/podman/manifest/inspect.go @@ -12,12 +12,13 @@ import ( var ( inspectCmd = &cobra.Command{ - Use: "inspect [flags] IMAGE", - Short: "Display the contents of a manifest list or image index", - Long: "Display the contents of a manifest list or image index.", - RunE: inspect, - Example: "podman manifest inspect localhost/list", - Args: cobra.ExactArgs(1), + Use: "inspect IMAGE", + Short: "Display the contents of a manifest list or image index", + Long: "Display the contents of a manifest list or image index.", + RunE: inspect, + Example: "podman manifest inspect localhost/list", + Args: cobra.ExactArgs(1), + DisableFlagsInUseLine: true, } ) diff --git a/cmd/podman/manifest/remove.go b/cmd/podman/manifest/remove.go index 4d345efc0..815a3f0a8 100644 --- a/cmd/podman/manifest/remove.go +++ b/cmd/podman/manifest/remove.go @@ -12,12 +12,13 @@ import ( var ( removeCmd = &cobra.Command{ - Use: "remove [flags] LIST IMAGE", - Short: "Remove an entry from a manifest list or image index", - Long: "Removes an image from a manifest list or image index.", - RunE: remove, - Example: `podman manifest remove mylist:v1.11 sha256:15352d97781ffdf357bf3459c037be3efac4133dc9070c2dce7eca7c05c3e736`, - Args: cobra.ExactArgs(2), + Use: "remove LIST IMAGE", + Short: "Remove an entry from a manifest list or image index", + Long: "Removes an image from a manifest list or image index.", + RunE: remove, + Example: `podman manifest remove mylist:v1.11 sha256:15352d97781ffdf357bf3459c037be3efac4133dc9070c2dce7eca7c05c3e736`, + Args: cobra.ExactArgs(2), + DisableFlagsInUseLine: true, } ) diff --git a/cmd/podman/system/renumber.go b/cmd/podman/system/renumber.go index b90640de3..39cd15dd7 100644 --- a/cmd/podman/system/renumber.go +++ b/cmd/podman/system/renumber.go @@ -22,11 +22,12 @@ var ( ` renumberCommand = &cobra.Command{ - Use: "renumber", - Args: validate.NoArgs, - Short: "Migrate lock numbers", - Long: renumberDescription, - Run: renumber, + Use: "renumber", + Args: validate.NoArgs, + DisableFlagsInUseLine: true, + Short: "Migrate lock numbers", + Long: renumberDescription, + Run: renumber, } ) diff --git a/cmd/podman/system/unshare.go b/cmd/podman/system/unshare.go index e5d41e06d..109bab9ed 100644 --- a/cmd/podman/system/unshare.go +++ b/cmd/podman/system/unshare.go @@ -13,10 +13,11 @@ import ( var ( unshareDescription = "Runs a command in a modified user namespace." unshareCommand = &cobra.Command{ - Use: "unshare [flags] [COMMAND [ARG ...]]", - Short: "Run a command in a modified user namespace", - Long: unshareDescription, - RunE: unshare, + Use: "unshare [COMMAND [ARG ...]]", + DisableFlagsInUseLine: true, + Short: "Run a command in a modified user namespace", + Long: unshareDescription, + RunE: unshare, Example: `podman unshare id podman unshare cat /proc/self/uid_map, podman unshare podman-script.sh`, diff --git a/docs/source/markdown/podman-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md index 90e581e42..f37280cda 100644 --- a/docs/source/markdown/podman-auto-update.1.md +++ b/docs/source/markdown/podman-auto-update.1.md @@ -4,7 +4,7 @@ podman-auto-update - Auto update containers according to their auto-update policy ## SYNOPSIS -**podman auto-update** +**podman auto-update** [*options*] ## DESCRIPTION `podman auto-update` looks up containers with a specified "io.containers.autoupdate" label (i.e., the auto-update policy). diff --git a/docs/source/markdown/podman-container-exists.1.md b/docs/source/markdown/podman-container-exists.1.md index 3b4ca33e4..d24df2fc8 100644 --- a/docs/source/markdown/podman-container-exists.1.md +++ b/docs/source/markdown/podman-container-exists.1.md @@ -4,7 +4,7 @@ podman-container-exists - Check if a container exists in local storage ## SYNOPSIS -**podman container exists** [*options*] *container* +**podman container exists** *container* ## DESCRIPTION **podman container exists** checks if a container exists in local storage. The **ID** or **Name** diff --git a/docs/source/markdown/podman-healthcheck-run.1.md b/docs/source/markdown/podman-healthcheck-run.1.md index 21f2d9b20..546d847eb 100644 --- a/docs/source/markdown/podman-healthcheck-run.1.md +++ b/docs/source/markdown/podman-healthcheck-run.1.md @@ -4,7 +4,7 @@ podman\-healthcheck\-run - Run a container healthcheck ## SYNOPSIS -**podman healthcheck run** [*options*] *container* +**podman healthcheck run** *container* ## DESCRIPTION diff --git a/docs/source/markdown/podman-image-exists.1.md b/docs/source/markdown/podman-image-exists.1.md index 3b7127b64..59f2145cc 100644 --- a/docs/source/markdown/podman-image-exists.1.md +++ b/docs/source/markdown/podman-image-exists.1.md @@ -4,7 +4,7 @@ podman-image-exists - Check if an image exists in local storage ## SYNOPSIS -**podman image exists** [*options*] *image* +**podman image exists** *image* ## DESCRIPTION **podman image exists** checks if an image exists in local storage. The **ID** or **Name** diff --git a/docs/source/markdown/podman-manifest-add.1.md b/docs/source/markdown/podman-manifest-add.1.md index 82f2071b9..44815def5 100644 --- a/docs/source/markdown/podman-manifest-add.1.md +++ b/docs/source/markdown/podman-manifest-add.1.md @@ -4,7 +4,7 @@ podman\-manifest\-add - Add an image to a manifest list or image index ## SYNOPSIS -**podman manifest add** *listnameorindexname* *imagename* +**podman manifest add** [*options*] *listnameorindexname* *imagename* ## DESCRIPTION diff --git a/docs/source/markdown/podman-manifest-annotate.1.md b/docs/source/markdown/podman-manifest-annotate.1.md index 4450de7fd..25ad4642e 100644 --- a/docs/source/markdown/podman-manifest-annotate.1.md +++ b/docs/source/markdown/podman-manifest-annotate.1.md @@ -4,7 +4,7 @@ podman\-manifest\-annotate - Add or update information about an entry in a manifest list or image index ## SYNOPSIS -**podman manifest annotate** [options...] *listnameorindexname* *imagemanifestdigest* +**podman manifest annotate** [*options*] *listnameorindexname* *imagemanifestdigest* ## DESCRIPTION diff --git a/docs/source/markdown/podman-manifest-push.1.md b/docs/source/markdown/podman-manifest-push.1.md index ab3287a7c..33b2a24c5 100644 --- a/docs/source/markdown/podman-manifest-push.1.md +++ b/docs/source/markdown/podman-manifest-push.1.md @@ -4,7 +4,7 @@ podman\-manifest\-push - Push a manifest list or image index to a registry ## SYNOPSIS -**podman manifest push** [options...] *listnameorindexname* *transport:details* +**podman manifest push** [*options*] *listnameorindexname* *transport:details* ## DESCRIPTION Pushes a manifest list or image index to a registry. diff --git a/docs/source/markdown/podman-mount.1.md b/docs/source/markdown/podman-mount.1.md index c7bfedb48..eaed1051e 100644 --- a/docs/source/markdown/podman-mount.1.md +++ b/docs/source/markdown/podman-mount.1.md @@ -4,9 +4,9 @@ podman\-mount - Mount a working container's root filesystem ## SYNOPSIS -**podman mount** [*container* ...] +**podman mount** [*options*] [*container* ...] -**podman container mount** [*container* ...] +**podman container mount** [*options*] [*container* ...] ## DESCRIPTION Mounts the specified containers' root file system in a location which can be diff --git a/docs/source/markdown/podman-network-inspect.1.md b/docs/source/markdown/podman-network-inspect.1.md index 86fa2552e..c75c6788a 100644 --- a/docs/source/markdown/podman-network-inspect.1.md +++ b/docs/source/markdown/podman-network-inspect.1.md @@ -4,7 +4,7 @@ podman\-network\-inspect - Displays the raw CNI network configuration for one or more networks ## SYNOPSIS -**podman network inspect** [*network* ...] +**podman network inspect** [*options*] [*network* ...] ## DESCRIPTION Display the raw (JSON format) network configuration. This command is not available for rootless users. diff --git a/docs/source/markdown/podman-network-rm.1.md b/docs/source/markdown/podman-network-rm.1.md index c71f0d8fd..9ce4d1cd8 100644 --- a/docs/source/markdown/podman-network-rm.1.md +++ b/docs/source/markdown/podman-network-rm.1.md @@ -4,7 +4,7 @@ podman\-network\-rm - Remove one or more CNI networks ## SYNOPSIS -**podman network rm** [*network...*] +**podman network rm** [*options*] [*network...*] ## DESCRIPTION Delete one or more Podman networks. diff --git a/docs/source/markdown/podman-pod-prune.1.md b/docs/source/markdown/podman-pod-prune.1.md index 5b74adade..5b4c4661c 100644 --- a/docs/source/markdown/podman-pod-prune.1.md +++ b/docs/source/markdown/podman-pod-prune.1.md @@ -4,7 +4,7 @@ podman-pod-prune - Remove all stopped pods and their containers ## SYNOPSIS -**podman pod prune** +**podman pod prune** [*options*] ## DESCRIPTION **podman pod prune** removes all stopped pods and their containers from local storage. diff --git a/docs/source/markdown/podman-rmi.1.md b/docs/source/markdown/podman-rmi.1.md index 2e093e9c8..58280e831 100644 --- a/docs/source/markdown/podman-rmi.1.md +++ b/docs/source/markdown/podman-rmi.1.md @@ -4,9 +4,9 @@ podman\-rmi - Removes one or more locally stored images ## SYNOPSIS -**podman rmi** *image* [...] +**podman rmi** [*options*] *image* [...] -**podman image rm** *image* [...] +**podman image rm** [*options*] *image* [...] ## DESCRIPTION Removes one or more locally stored images. diff --git a/docs/source/markdown/podman-system-migrate.1.md b/docs/source/markdown/podman-system-migrate.1.md index 28db56dee..baabfd14b 100644 --- a/docs/source/markdown/podman-system-migrate.1.md +++ b/docs/source/markdown/podman-system-migrate.1.md @@ -4,7 +4,7 @@ podman\-system\-migrate - Migrate existing containers to a new podman version ## SYNOPSIS -**podman system migrate** +**podman system migrate** [*options*] ## DESCRIPTION **podman system migrate** migrates containers to the latest podman version. diff --git a/docs/source/markdown/podman-system-reset.1.md b/docs/source/markdown/podman-system-reset.1.md index 432f275f4..f290e26d5 100644 --- a/docs/source/markdown/podman-system-reset.1.md +++ b/docs/source/markdown/podman-system-reset.1.md @@ -4,7 +4,7 @@ podman\-system\-reset - Reset storage back to initial state ## SYNOPSIS -**podman system reset** +**podman system reset** [*options*] ## DESCRIPTION **podman system reset** removes all pods, containers, images and volumes. diff --git a/docs/source/markdown/podman-umount.1.md b/docs/source/markdown/podman-umount.1.md index 100c47b32..31a213f28 100644 --- a/docs/source/markdown/podman-umount.1.md +++ b/docs/source/markdown/podman-umount.1.md @@ -4,13 +4,13 @@ podman\-umount - Unmount a working container's root filesystem ## SYNOPSIS -**podman umount** *container* [...] +**podman umount** [*options*] *container* [...] -**podman container umount** *container* [...] +**podman container umount** [*options*] *container* [...] -**podman container unmount** *container* [...] +**podman container unmount** [*options*] *container* [...] -**podman unmount** *container* [...] +**podman unmount** [*options*] *container* [...] ## DESCRIPTION Unmounts the specified containers' root file system, if no other processes diff --git a/docs/source/markdown/podman-unshare.1.md b/docs/source/markdown/podman-unshare.1.md index f2eb02814..239213981 100644 --- a/docs/source/markdown/podman-unshare.1.md +++ b/docs/source/markdown/podman-unshare.1.md @@ -4,7 +4,7 @@ podman\-unshare - Run a command inside of a modified user namespace ## SYNOPSIS -**podman unshare** [*options*] [*--*] [*command*] +**podman unshare** [*--*] [*command*] ## DESCRIPTION Launches a process (by default, *$SHELL*) in a new user namespace. The user diff --git a/docs/source/markdown/podman-untag.1.md b/docs/source/markdown/podman-untag.1.md index c83a0544c..d6ed7f3ea 100644 --- a/docs/source/markdown/podman-untag.1.md +++ b/docs/source/markdown/podman-untag.1.md @@ -4,9 +4,9 @@ podman\-untag - Removes one or more names from a locally-stored image ## SYNOPSIS -**podman untag** [*options*] *image* [*name*[:*tag*]...] +**podman untag** *image* [*name*[:*tag*]...] -**podman image untag** [*options*] *image* [*name*[:*tag*]...] +**podman image untag** *image* [*name*[:*tag*]...] ## DESCRIPTION Remove one or more names from an image in the local storage. The image can be referred to by ID or reference. If a no name is specified, all names are removed the image. If a specified name is a short name and does not include a registry `localhost/` will be prefixed (e.g., `fedora` -> `localhost/fedora`). If a specified name does not include a tag `:latest` will be appended (e.g., `localhost/fedora` -> `localhost/fedora:latest`). diff --git a/hack/man-page-checker b/hack/man-page-checker index 17d85d65d..d2cc6c6e1 100755 --- a/hack/man-page-checker +++ b/hack/man-page-checker @@ -3,6 +3,14 @@ # man-page-checker - validate and cross-reference man page names # +verbose= +for i; do + case "$i" in + -v|--verbose) verbose=verbose ;; + esac +done + + die() { echo "$(basename $0): $*" >&2 exit 1 @@ -65,6 +73,61 @@ for md in $(ls -1 *-*.1.md | grep -v remote);do fi done +# Helper function: compares man page synopsis vs --help usage message +function compare_usage() { + local cmd="$1" + local from_man="$2" + + # Sometimes in CI we run before podman gets built. + test -x ../../../bin/podman || return + + # Run 'cmd --help', grab the line immediately after 'Usage:' + local help_output=$(../../../bin/$cmd --help) + local from_help=$(echo "$help_output" | grep -A1 '^Usage:' | tail -1) + + # strip off command name from both + from_man=$(sed -e "s/\*\*$cmd\*\*[[:space:]]*//" <<<"$from_man") + from_help=$(sed -e "s/^[[:space:]]*$cmd[[:space:]]*//" <<<"$from_help") + + # man page lists 'foo [*options*]', help msg shows 'foo [flags]'. + # Make sure if one has it, the other does too. + if expr "$from_man" : "\[\*options\*\]" >/dev/null; then + if expr "$from_help" : "\[flags\]" >/dev/null; then + : + else + echo "WARNING: $cmd: man page shows '[*options*]', help does not show [flags]" + rc=1 + fi + elif expr "$from_help" : "\[flags\]" >/dev/null; then + echo "WARNING: $cmd: --help shows [flags], man page does not show [*options*]" + rc=1 + fi + + # Strip off options and flags; start comparing arguments + from_man=$(sed -e 's/^\[\*options\*\][[:space:]]*//' <<<"$from_man") + from_help=$(sed -e 's/^\[flags\][[:space:]]*//' <<<"$from_help") + + # Args in man page are '*foo*', in --help are 'FOO'. Convert all to + # UPCASE simply because it stands out better to the eye. + from_man=$(sed -e 's/\*\([a-z-]\+\)\*/\U\1/g' <<<"$from_man") + + # FIXME: one of the common patterns is for --help to show 'POD [POD...]' + # but man page show 'pod ...'. This conversion may help one day, but + # not yet: there are too many inconsistencies such as '[pod ...]' + # (brackets) and 'pod...' (no space between). +# from_help=$(sed -e 's/\([A-Z]\+\)[[:space:]]\+\[\1[[:space:]]*\.\.\.\]/\1 .../' <<<"$from_help") + + # Compare man-page and --help usage strings. For now, do so only + # when run with --verbose. + if [[ "$from_man" != "$from_help" ]]; then + if [ -n "$verbose" ]; then + printf "%-25s man='%s' help='%s'\n" "$cmd:" "$from_man" "$from_help" + # Yeah, we're not going to enable this as a blocker any time soon. + # rc=1 + fi + fi +} + # Pass 3: compare synopses. # # Make sure the SYNOPSIS line in podman-foo.1.md reads '**podman foo** ...' @@ -87,9 +150,7 @@ for md in *.1.md;do cmd=$(echo "$synopsis" | sed -e 's/\(.*\)\*\*.*/\1/' | tr -d \*) md_nodash=$(basename "$md" .1.md | tr '-' ' ') if [[ $md_nodash = 'podman auto update' ]]; then - # podman-auto-update.1.md is special cased as it's structure differs - # from that of other man pages where main and sub-commands split by - # dashes. + # special case: the command is "auto-update", with a hyphen md_nodash='podman auto-update' fi if [ "$cmd" != "$md_nodash" -a "$cmd" != "podman-remote" ]; then @@ -111,8 +172,9 @@ for md in *.1.md;do # (for debugging, and getting a sense of standard conventions) #printf " %-32s ------ '%s'\n" $md "$synopsis" - # FIXME: some day: run ./bin/podman "args", extract Usage, - # strip off [flags] and [options], then compare arguments + # If bin/podman is available, run "cmd --help" and compare Usage + # messages. This is complicated, so do it in a helper function. + compare_usage "$md_nodash" "$synopsis" done diff --git a/test/system/015-help.bats b/test/system/015-help.bats index 14af8e1a4..3d05b44fe 100644 --- a/test/system/015-help.bats +++ b/test/system/015-help.bats @@ -34,13 +34,16 @@ function check_help() { dprint "$command_string --help" run_podman "$@" $cmd --help + local full_help="$output" # The line immediately after 'Usage:' gives us a 1-line synopsis - usage=$(echo "$output" | grep -A1 '^Usage:' | tail -1) + usage=$(echo "$full_help" | grep -A1 '^Usage:' | tail -1) [ -n "$usage" ] || die "podman $cmd: no Usage message found" # e.g. 'podman ps' should not show 'podman container ps' in usage - is "$usage" " $command_string .*" "Usage string matches command" + # Trailing space in usage handles 'podman system renumber' which + # has no ' [flags]' + is "$usage " " $command_string .*" "Usage string matches command" # If usage ends in '[command]', recurse into subcommands if expr "$usage" : '.*\[command\]$' >/dev/null; then @@ -59,6 +62,17 @@ function check_help() { die "'flags' must precede arguments in usage: $usage" fi + # Cross-check: if usage includes '[flags]', there must be a + # longer 'Flags:' section in the full --help output; vice-versa, + # if 'Flags:' is in full output, usage line must have '[flags]'. + if expr "$usage" : '.*\[flag' >/dev/null; then + if ! expr "$full_help" : ".*Flags:" >/dev/null; then + die "$command_string: Usage includes '[flags]' but has no 'Flags:' subsection" + fi + elif expr "$full_help" : ".*Flags:" >/dev/null; then + die "$command_string: --help has 'Flags:' section but no '[flags]' in synopsis" + fi + # If usage lists no arguments (strings in ALL CAPS), confirm # by running with 'invalid-arg' and expecting failure. if ! expr "$usage" : '.*[A-Z]' >/dev/null; then |