From 281def2647142acd1a901332391bd25f96169286 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 10 Mar 2020 14:03:50 -0600 Subject: man pages: fix inconsistencies I wrote a script to cross-reference podman --help against man pages. It found a bunch of inconsistencies fix them: * options missing from man pages * options misspelled or misformatted in man pages (usually misplaced asterisks or missing dashes, but see --dns-opt) * one spurious comma in the actual source file --help This is a fix in which I iterate over 'podman CMD --help' and check for presence in man pages. The other way around (look for flags in man pages, check podman CMD --help) is probably impossible: there are too many special cases Signed-off-by: Ed Santiago --- cmd/podman/pod_top.go | 2 +- docs/source/markdown/podman-build.1.md | 18 +++++++++++++++++- docs/source/markdown/podman-container-checkpoint.1.md | 2 +- docs/source/markdown/podman-container-cleanup.1.md | 2 +- docs/source/markdown/podman-container-prune.1.md | 5 +++++ docs/source/markdown/podman-container-restore.1.md | 4 ++-- docs/source/markdown/podman-create.1.md | 10 +++++----- docs/source/markdown/podman-image-prune.1.md | 8 ++++++++ docs/source/markdown/podman-images.1.md | 2 +- docs/source/markdown/podman-kill.1.md | 2 +- docs/source/markdown/podman-logs.1.md | 4 ++++ docs/source/markdown/podman-mount.1.md | 2 +- docs/source/markdown/podman-network-create.1.md | 2 +- docs/source/markdown/podman-pod-create.1.md | 6 +++++- docs/source/markdown/podman-pod-prune.1.md | 2 +- docs/source/markdown/podman-pod-ps.1.md | 6 +++++- docs/source/markdown/podman-pod-stop.1.md | 2 +- docs/source/markdown/podman-restart.1.md | 2 +- docs/source/markdown/podman-rmi.1.md | 2 +- docs/source/markdown/podman-run.1.md | 12 ++++++++---- docs/source/markdown/podman-volume-create.1.md | 2 +- docs/source/markdown/podman-volume-inspect.1.md | 2 +- docs/source/markdown/podman-volume-ls.1.md | 2 +- 23 files changed, 73 insertions(+), 28 deletions(-) diff --git a/cmd/podman/pod_top.go b/cmd/podman/pod_top.go index fcd9c4f3c..734472817 100644 --- a/cmd/podman/pod_top.go +++ b/cmd/podman/pod_top.go @@ -42,7 +42,7 @@ func init() { podTopCommand.SetHelpTemplate(HelpTemplate()) podTopCommand.SetUsageTemplate(UsageTemplate()) flags := podTopCommand.Flags() - flags.BoolVarP(&podTopCommand.Latest, "latest,", "l", false, "Act on the latest pod podman is aware of") + flags.BoolVarP(&podTopCommand.Latest, "latest", "l", false, "Act on the latest pod podman is aware of") flags.BoolVar(&podTopCommand.ListDescriptors, "list-descriptors", false, "") markFlagHidden(flags, "list-descriptors") } diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index e08eebc24..dc38caac0 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -37,6 +37,10 @@ Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can b Note: this information is not present in Docker image formats, so it is discarded when writing images in Docker formats. +**--arch**=*arch* + +Set the ARCH of the image to the provided value instead of the architecture of the host. + **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. @@ -187,7 +191,7 @@ Note: if the user only has access rights via a group, accessing the device from inside a rootless container will fail. The **crun**(1) runtime offers a workaround for this by adding the option **--annotation run.oci.keep_original_groups=1**. -**--disable-compression, -D** +**--disable-compression**, **-D** Don't compress filesystem layers when building the image unless it is required by the location where the image is being written. This is the default setting, @@ -248,6 +252,10 @@ environment variable. `export BUILDAH_FORMAT=docker` Print usage statement +**--http-proxy** + +Pass through HTTP Proxy environment variables. + **--iidfile**=*ImageIDfile* Write the image ID to the file. @@ -340,6 +348,10 @@ another process. Do not use existing cached images for the container build. Build from the start with a new set of cached layers. +**--os**=*string* + +Set the OS to the provided value instead of the current operating system of the host. + **--pid**=*pid* Sets the configuration for PID namespaces when handling `RUN` instructions. @@ -429,6 +441,10 @@ Size of `/dev/shm`. The format is ``. `number` must be greater tha Unit is optional and can be `b` (bytes), `k` (kilobytes), `m`(megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. +**--sign-by**=*fingerprint* + +Sign the image using a GPG key with the specified FINGERPRINT. + **--squash** Squash all of the image's new layers into a single new layer; any preexisting layers diff --git a/docs/source/markdown/podman-container-checkpoint.1.md b/docs/source/markdown/podman-container-checkpoint.1.md index 034d338bb..1bac477c8 100644 --- a/docs/source/markdown/podman-container-checkpoint.1.md +++ b/docs/source/markdown/podman-container-checkpoint.1.md @@ -38,7 +38,7 @@ image contains established TCP connections, this options is required during restore. Defaults to not checkpointing containers with established TCP connections. -**--export, -e** +**--export**, **-e** Export the checkpoint to a tar.gz file. The exported checkpoint can be used to import the container on another system and thus enabling container live diff --git a/docs/source/markdown/podman-container-cleanup.1.md b/docs/source/markdown/podman-container-cleanup.1.md index 86e6b4316..66a6cff62 100644 --- a/docs/source/markdown/podman-container-cleanup.1.md +++ b/docs/source/markdown/podman-container-cleanup.1.md @@ -12,7 +12,7 @@ Sometimes container's mount points and network stacks can remain if the podman c ## OPTIONS -**--all**, **a** +**--all**, **-a** Cleanup all containers. diff --git a/docs/source/markdown/podman-container-prune.1.md b/docs/source/markdown/podman-container-prune.1.md index eaecee304..8c05eeafe 100644 --- a/docs/source/markdown/podman-container-prune.1.md +++ b/docs/source/markdown/podman-container-prune.1.md @@ -11,7 +11,12 @@ podman-container-prune - Remove all stopped containers from local storage ## OPTIONS +**--filter**=*filters* + +Provide filter values. + **--force**, **-f** + Do not provide an interactive prompt for container removal. **-h**, **--help** diff --git a/docs/source/markdown/podman-container-restore.1.md b/docs/source/markdown/podman-container-restore.1.md index d71daf4af..a7b0f199b 100644 --- a/docs/source/markdown/podman-container-restore.1.md +++ b/docs/source/markdown/podman-container-restore.1.md @@ -42,13 +42,13 @@ If the checkpoint image does not contain established TCP connections this option is ignored. Defaults to not restoring containers with established TCP connections. -**--import, -i** +**--import**, **-i** Import a checkpoint tar.gz file, which was exported by Podman. This can be used to import a checkpointed container from another host. Do not specify a *container* argument when using this option. -**--name, -n** +**--name**, **-n** This is only available in combination with **--import, -i**. If a container is restored from a checkpoint tar.gz file it is possible to rename it with **--name, -n**. This diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 23106fe76..af66d7911 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -251,9 +251,9 @@ is the case the **--dns** flags is necessary for every run. The special value **none** can be specified to disable creation of **/etc/resolv.conf** in the container by Podman. The **/etc/resolv.conf** file in the image will be used without changes. -**--dns-option**=*option* +**--dns-opt**=*option* -Set custom DNS options. Invalid if using **--dns-option** and **--network** that is set to 'none' or 'container:'. +Set custom DNS options. Invalid if using **--dns-opt** and **--network** that is set to 'none' or 'container:'. **--dns-search**=*domain* @@ -334,7 +334,7 @@ The initialization time needed for a container to bootstrap. The value can be ex The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the value can be expressed in a time format such as `1m22s`. The default value is `30s`. -**--hostname**=*name* +**-h**, **--hostname**=*name* Container host name @@ -381,7 +381,7 @@ Run an init inside the container that forwards signals and reaps processes. Path to the container-init binary. -**--interactive**, **i**=*true|false* +**--interactive**, **-i**=*true|false* Keep STDIN open even if not attached. The default is *false*. @@ -548,7 +548,7 @@ This works for both background and foreground containers. **--network**, **--net**="*bridge*" -Set the Network mode for the container. Invalid if using **--dns**, **--dns-option**, or **--dns-search** with **--network** that is set to 'none' or 'container:'. +Set the Network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** that is set to 'none' or 'container:'. Valid values are: diff --git a/docs/source/markdown/podman-image-prune.1.md b/docs/source/markdown/podman-image-prune.1.md index 0155ebcd1..c76e9bd3f 100644 --- a/docs/source/markdown/podman-image-prune.1.md +++ b/docs/source/markdown/podman-image-prune.1.md @@ -16,6 +16,14 @@ does not have any containers based on it. Remove dangling images and images that have no associated containers. +**--filter**=*filters* + +Provide filter values. + +**--force**, **-f** + +Do not provide an interactive prompt for container removal. + **--help**, **-h** Print usage statement diff --git a/docs/source/markdown/podman-images.1.md b/docs/source/markdown/podman-images.1.md index 09778e3c2..379f7573e 100644 --- a/docs/source/markdown/podman-images.1.md +++ b/docs/source/markdown/podman-images.1.md @@ -72,7 +72,7 @@ Display the history of image names. If an image gets re-tagged or untagged, the Omit the table headings from the listing of images. -**--no-trunc**, **--notruncate** +**--no-trunc** Do not truncate output. diff --git a/docs/source/markdown/podman-kill.1.md b/docs/source/markdown/podman-kill.1.md index 617d25b85..010c04edc 100644 --- a/docs/source/markdown/podman-kill.1.md +++ b/docs/source/markdown/podman-kill.1.md @@ -23,7 +23,7 @@ to run containers such as CRI-O, the last started container could be from either The latest option is not supported on the remote client. -**--signal**, **s** +**--signal**, **-s** Signal to send to the container. For more information on Linux signals, refer to *man signal(7)*. diff --git a/docs/source/markdown/podman-logs.1.md b/docs/source/markdown/podman-logs.1.md index 66308c2b5..bcfc0bae8 100644 --- a/docs/source/markdown/podman-logs.1.md +++ b/docs/source/markdown/podman-logs.1.md @@ -30,6 +30,10 @@ to run containers such as CRI-O, the last started container could be from either The latest option is not supported on the remote client. +**-n**, **--names** + +Output the container name in the log + **--since**=*TIMESTAMP* Show logs since TIMESTAMP. The --since option can be Unix timestamps, date formatted timestamps, or Go duration diff --git a/docs/source/markdown/podman-mount.1.md b/docs/source/markdown/podman-mount.1.md index 8f4deeca6..c7bfedb48 100644 --- a/docs/source/markdown/podman-mount.1.md +++ b/docs/source/markdown/podman-mount.1.md @@ -21,7 +21,7 @@ returned. ## OPTIONS -**--all**, **a** +**--all**, **-a** Mount all containers. diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index 2eca93adb..cbdfee4d0 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -22,7 +22,7 @@ Upon completion of creating the network, Podman will display the path to the new Disables the DNS plugin for this network which if enabled, can perform container to container name resolution. -**-d**, , **--driver** +**-d**, **--driver** Driver to manage the network (default "bridge"). Currently on `bridge` is supported. diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md index dba31f681..489c9b32e 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md @@ -39,6 +39,10 @@ Set custom DNS search domains in the /etc/resolv.conf file that will be shared b Print usage statement. +**--hostname**=name + +Set a hostname to the pod + **--infra**=**true**|**false** Create an infra container and associate it with the pod. An infra container is a lightweight container used to coordinate the shared kernel namespace of a pod. Default: true. @@ -79,7 +83,7 @@ Set network mode for the pod. Supported values are *bridge* (the default), *host Disable creation of /etc/hosts for the pod. -**--podidfile**=*podid* +**--pod-id-file**=*path* Write the pod ID to the file. diff --git a/docs/source/markdown/podman-pod-prune.1.md b/docs/source/markdown/podman-pod-prune.1.md index 478f563c3..5b74adade 100644 --- a/docs/source/markdown/podman-pod-prune.1.md +++ b/docs/source/markdown/podman-pod-prune.1.md @@ -11,7 +11,7 @@ podman-pod-prune - Remove all stopped pods and their containers ## OPTIONS -**--force** **-f** +**--force**, **-f** Force removal of all running pods and their containers. The default is false. ## EXAMPLES diff --git a/docs/source/markdown/podman-pod-ps.1.md b/docs/source/markdown/podman-pod-ps.1.md index 887682f19..035c20c7f 100644 --- a/docs/source/markdown/podman-pod-ps.1.md +++ b/docs/source/markdown/podman-pod-ps.1.md @@ -38,7 +38,7 @@ Includes the container IDs in the container info field Includes the container statuses in the container info field -**--latest**,**-l** +**--latest**, **-l** Show the latest pod created (all states) @@ -48,6 +48,10 @@ The latest option is not supported on the remote client. Display the extended information +**--ns** + +Display namespace information of the pod + **--quiet**, **-q** Print the numeric IDs of the pods only diff --git a/docs/source/markdown/podman-pod-stop.1.md b/docs/source/markdown/podman-pod-stop.1.md index 73c347cec..42d2a2d3f 100644 --- a/docs/source/markdown/podman-pod-stop.1.md +++ b/docs/source/markdown/podman-pod-stop.1.md @@ -27,7 +27,7 @@ Instead of providing the pod name or ID, stop the last created pod. The latest option is not supported on the remote client. -**--timeout**, **--time**, **-t**=*time* +**--timeout**, **-t**=*time* Timeout to wait before forcibly stopping the containers in the pod. diff --git a/docs/source/markdown/podman-restart.1.md b/docs/source/markdown/podman-restart.1.md index 08fa29244..6507530e1 100644 --- a/docs/source/markdown/podman-restart.1.md +++ b/docs/source/markdown/podman-restart.1.md @@ -26,7 +26,7 @@ The latest option is not supported on the remote client. **--running** Restart all containers that are already in the *running* state. -**--timeout**=*time* +**-t**, **--time**, **--timeout**=*time* Timeout to wait before forcibly stopping the container. diff --git a/docs/source/markdown/podman-rmi.1.md b/docs/source/markdown/podman-rmi.1.md index 78ef2b157..2e093e9c8 100644 --- a/docs/source/markdown/podman-rmi.1.md +++ b/docs/source/markdown/podman-rmi.1.md @@ -13,7 +13,7 @@ Removes one or more locally stored images. ## OPTIONS -**-all**, **-a** +**--all**, **-a** Remove all images in the local storage. diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index f595e77e4..3225654b6 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -225,6 +225,10 @@ Note: if the user only has access rights via a group, accessing the device from inside a rootless container will fail. The **crun**(1) runtime offers a workaround for this by adding the option **--annotation run.oci.keep_original_groups=1**. +**--device-cgroup-rule**=rule + +Add a rule to the cgroup allowed devices list + **--device-read-bps**=_path_:_rate_ Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**). @@ -253,9 +257,9 @@ is the case the **--dns** flags is necessary for every run. The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman. The _/etc/resolv.conf_ file in the image will be used without changes. -**--dns-option**=*option* +**--dns-opt**=*option* -Set custom DNS options. Invalid if using **--dns-option** with **--network** that is set to **none** or **container:**_id_. +Set custom DNS options. Invalid if using **--dns-opt** with **--network** that is set to **none** or **container:**_id_. **--dns-search**=*domain* @@ -342,7 +346,7 @@ value can be expressed in a time format such as **1m22s**. The default value is Print usage statement -**--hostname**=*name* +**-h**, **--hostname**=*name* Container host name @@ -547,7 +551,7 @@ This works for both background and foreground containers. **--network**, **--net**=*mode* -Set the network mode for the container. Invalid if using **--dns**, **--dns-option**, or **--dns-search** with **--network** that is set to **none** or **container:**_id_. +Set the network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** that is set to **none** or **container:**_id_. Valid _mode_ values are: diff --git a/docs/source/markdown/podman-volume-create.1.md b/docs/source/markdown/podman-volume-create.1.md index b354f396f..5672a80a5 100644 --- a/docs/source/markdown/podman-volume-create.1.md +++ b/docs/source/markdown/podman-volume-create.1.md @@ -23,7 +23,7 @@ Specify the volume driver name (default local). Print usage statement -**-l**, **-label**=*label* +**-l**, **--label**=*label* Set metadata for a volume (e.g., --label mykey=value). diff --git a/docs/source/markdown/podman-volume-inspect.1.md b/docs/source/markdown/podman-volume-inspect.1.md index ac5b6c977..b889383b1 100644 --- a/docs/source/markdown/podman-volume-inspect.1.md +++ b/docs/source/markdown/podman-volume-inspect.1.md @@ -20,7 +20,7 @@ Volumes can be queried individually by providing their full name or a unique par Inspect all volumes. -**--format**=*format* +**-f**, **--format**=*format* Format volume output using Go template diff --git a/docs/source/markdown/podman-volume-ls.1.md b/docs/source/markdown/podman-volume-ls.1.md index d431c7c6e..a4fb925f8 100644 --- a/docs/source/markdown/podman-volume-ls.1.md +++ b/docs/source/markdown/podman-volume-ls.1.md @@ -14,7 +14,7 @@ flag. Use the **--quiet** flag to print only the volume names. ## OPTIONS -**--filter**=*filter* +**-f**, **--filter**=*filter* Filter volume output. -- cgit v1.2.3-54-g00ecf