opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-05-20 08:36:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Follow man-pages(7) suggestions for SYNOPSIS

Browse Source 
man-pages(7) has [1]:

> For commands, this shows the syntax of the command and its arguments
> (including options); boldface is used for as-is text and italics are
> used to indicate replaceable arguments. Brackets ([]) surround
> optional arguments, vertical bars (|) separate choices, and ellipses
> (...) can be repeated.

I've adjusted our SYNOPSIS entries to match that formatting, and
generally tried to make them more consistent with the precedent set by
the man-pages project.  Outside of the SYNOPSIS entry, I prefer using
backticks for literals, although in some places I've left the **
bolding to keep things visually similar to a nearby SYNOPSIS entry.

[1]: http://man7.org/linux/man-pages/man7/man-pages.7.html

Signed-off-by: W. Trevor King <wking@tremily.us>

Closes: #1027
Approved by: rhatdan
This commit is contained in:
W. Trevor King
2018-06-29 10:53:33 -07:00
committed by Atomic Bot
parent 6d8fac87ed
commit f2462ca59e
43 changed files with 111 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/podman-attach.1.md
View File

@ -4,7 +4,7 @@
podman\-attach - Attach to a running container
## SYNOPSIS
**podman attach [OPTIONS] CONTAINER**
**podman attach** [*options*] *container*
## DESCRIPTION
The attach command allows you to attach to a running container using the container's ID

2
docs/podman-build.1.md
View File

@ -4,7 +4,7 @@
podman\-build - Build a container image using a Dockerfile.
## SYNOPSIS
**podman** **build** [*options* [...]] **context**
**podman build** [*options*] *context*
## DESCRIPTION
**podman build** Builds an image using instructions from one or more Dockerfiles and a specified build context directory.

14
docs/podman-commit.1.md
View File

@ -4,18 +4,18 @@
podman\-commit - Create new image based on the changed container
## SYNOPSIS
**podman commit** [*options* [...]] CONTAINER IMAGE
**podman commit** [*options*] *container* *image*
## DESCRIPTION
**podman commit** creates an image based on a changed container. The author of the
image can be set using the **--author** flag. Various image instructions can be
configured with the **--change** flag and a commit message can be set using the
**--message** flag. The container and its processes are paused while the image is
`podman commit` creates an image based on a changed container. The author of the
image can be set using the `--author` flag. Various image instructions can be
configured with the `--change` flag and a commit message can be set using the
`--message` flag. The container and its processes are paused while the image is
committed. This minimizes the likelihood of data corruption when creating the new
image. If this is not desired, the **--pause** flag can be set to false. When the commit
image. If this is not desired, the `--pause` flag can be set to false. When the commit
is complete, podman will print out the ID of the new image.
If *imageName* does not begin with a registry name component, *localhost* will be added to the name.
If *image* does not begin with a registry name component, `localhost` will be added to the name.
## OPTIONS

2
docs/podman-container-cleanup.1.md
View File

@ -4,7 +4,7 @@
podman\-container\-cleanup - Cleanup Container storage and networks
## SYNOPSIS
**podman container cleanup [OPTIONS] CONTAINER**
**podman container cleanup** [*options*] *container*
## DESCRIPTION
`podman container cleanup` cleans up exited containers by removing all mountpoints and network configuration from the host. The container name or ID can be used. The cleanup command does not remove the containers. Running containers will not be cleaned up.

2
docs/podman-container.1.md
View File

@ -4,7 +4,7 @@
podman\-container - Manage containers
## SYNOPSIS
**podman container SUBCOMMAND [OPTIONS]
**podman container** *subcommand*
## DESCRIPTION
The container command allows you to manage containers

4
docs/podman-create.1.md
View File

@ -4,14 +4,14 @@
podman\-create - Create a new container
## SYNOPSIS
**podman create** [*options* [...]] IMAGE [COMMAND] [ARG...]
**podman create** [*options*] *image* [*command* [*arg* ...]]
## DESCRIPTION
Creates a writable container layer over the specified image and prepares it for
running the specified command. The container ID is then printed to STDOUT. This
is similar to **podman run -d** except the container is never started. You can
then use the **podman start <container_id>** command to start the container at
then use the **podman start** *container* command to start the container at
any point.
The initial status of the container created with **podman create** is 'created'.

2
docs/podman-diff.1.md
View File

@ -4,7 +4,7 @@
podman\-diff - Inspect changes on a container or image's filesystem
## SYNOPSIS
**podman** **diff** [*options* [...]] NAME
**podman diff** [*options*] *name*
## DESCRIPTION
Displays changes on a container or image's filesystem. The container or image will be compared to its parent layer

5
docs/podman-exec.1.md
View File

@ -4,10 +4,7 @@
podman\-exec - Execute a command in a running container
## SYNOPSIS
**podman exec**
**CONTAINER**
[COMMAND] [ARG...]
[**--help**|**-h**]
**podman exec** *container* [*options*] [*command* [*arg* ...]]
## DESCRIPTION
**podman exec** executes a command in a running container.

11
docs/podman-export.1.md
View File

@ -4,15 +4,12 @@
podman export - Export container's filesystem contents as a tar archive
## SYNOPSIS
**podman export**
**CONTAINER**
[**--output**|**-o**]
[**--help**|**-h**]
**podman export** [*options*] *container*
## DESCRIPTION
**podman export** exports the filesystem of a container and saves it as a tarball
on the local machine. **podman export** writes to STDOUT by default and can be
redirected to a file using the **output flag**.
redirected to a file using the `--output` flag.
Note: `:` is a restricted character and cannot be part of the file name.
**podman [GLOBAL OPTIONS]**
@ -27,6 +24,10 @@ Note: `:` is a restricted character and cannot be part of the file name.
Write to a file, default is STDOUT
**--help**, **-h**
Print usage statement
## EXAMPLES
```

17
docs/podman-history.1.md
View File

@ -4,13 +4,7 @@
podman\-history - Shows the history of an image
## SYNOPSIS
**podman history**
**IMAGE[:TAG|DIGEST]**
[**--human**|**-H**]
[**--no-trunc**]
[**--quiet**|**-q**]
[**--format**]
[**--help**|**-h**]
**podman history** [*options*] *image*[:*tag*|@*digest*]
## DESCRIPTION
**podman history** displays the history of an image by printing out information
@ -31,12 +25,6 @@ Valid placeholders for the Go template are listed below:
| .Size | Size of layer on disk |
| .Comment | Comment for the layer |
**podman [GLOBAL OPTIONS]**
**podman history [GLOBAL OPTIONS]**
**podman history [OPTIONS] IMAGE[:TAG|DIGEST]**
## OPTIONS
**--human, -H**
@ -55,6 +43,9 @@ Print the numeric IDs only
Alter the output for a format like 'json' or a Go template.
**--help**, **-h**
Print usage statement
## EXAMPLES

2
docs/podman-image.1.md
View File

@ -4,7 +4,7 @@
podman\-image - Manage images
## SYNOPSIS
**podman image SUBCOMMAND [OPTIONS]
**podman image** *subcommand*
## DESCRIPTION
The image command allows you to manage images

2
docs/podman-images.1.md
View File

@ -4,7 +4,7 @@
podman\-images - List images in local storage
## SYNOPSIS
**podman** **images** [*options* [...]]
**podman** **images** [*options*]
## DESCRIPTION
Displays locally stored images, their names, and their IDs.

21
docs/podman-import.1.md
View File

@ -4,12 +4,7 @@
podman\-import - Import a tarball and save it as a filesystem image
## SYNOPSIS
**podman import**
**TARBALL**
[**--change**|**-c**]
[**--message**|**-m**]
[**--help**|**-h**]
[**-verbose**]
**podman import** [*options*] *path*
## DESCRIPTION
**podman import** imports a tarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz)
@ -18,12 +13,6 @@ Various image instructions can be configured with the **--change** flag and
a commit message can be set using the **--message** flag.
Note: `:` is a restricted character and cannot be part of the file name.
**podman [GLOBAL OPTIONS]**
**podman import [GLOBAL OPTIONS]**
**podman import [OPTIONS] CONTAINER**
## OPTIONS
**--change, -c**
@ -40,6 +29,14 @@ Set commit message for imported image
Shows progress on the import
**-verbose**
Print additional debugging information
**--help**, **-h**
Print usage statement
## EXAMPLES
```

2
docs/podman-info.1.md
View File

@ -5,7 +5,7 @@ podman\-info - Display system information
## SYNOPSIS
**podman** **info** [*options* [...]]
**podman info** [*options*]
## DESCRIPTION

2
docs/podman-inspect.1.md
View File

@ -4,7 +4,7 @@
podman\-inspect - Display a container or image's configuration
## SYNOPSIS
**podman** **inspect** [*options* [...]] name [...]
**podman inspect** [*options*] *name* ...
## DESCRIPTION
This displays the low-level information on containers and images identified by name or ID. By default, this will render

2
docs/podman-kill.1.md
View File

@ -4,7 +4,7 @@
podman\-kill - Kills one or more containers with a signal
## SYNOPSIS
**podman kill [OPTIONS] CONTAINER [...]**
**podman kill** [*options*] *container* ...
## DESCRIPTION
The main process inside each container specified will be sent SIGKILL, or any signal specified with option --signal.

10
docs/podman-load.1.md
View File

@ -4,11 +4,7 @@
podman\-load - Load an image from docker archive
## SYNOPSIS
**podman load**
**NAME[:TAG|@DIGEST]**
[**--input**|**-i**]
[**--quiet**|**-q**]
[**--help**|**-h**]
**podman load** *name*[:*tag*|@*digest*]
## DESCRIPTION
**podman load** copies an image from either **docker-archive** or **oci-archive** stored
@ -38,6 +34,10 @@ Pathname of a signature policy file to use. It is not recommended that this
option be used, as the default behavior of using the system-wide default policy
(frequently */etc/containers/policy.json*) is most often preferred
**--help**, **-h**
Print usage statement
## EXAMPLES
```

11
docs/podman-login.1.md
View File

@ -4,12 +4,7 @@
podman\-login - Login to a container registry
## SYNOPSIS
**podman login**
[**--help**|**-h**]
[**--authfile**]
[**--user**|**-u**]
[**--password**|**-p**]
**REGISTRY**
**podman login** [*options*] *registry*
## DESCRIPTION
**podman login** logs into a specified registry server with the correct username
@ -47,6 +42,10 @@ Default certificates directory is _/etc/containers/certs.d_.
Require HTTPS and verify certificates when contacting registries (default: true)
**--help**, **-h**
Print usage statement
## EXAMPLES
```

10
docs/podman-logout.1.md
View File

@ -4,11 +4,7 @@
podman\-logout - Logout of a container registry
## SYNOPSIS
**podman logout**
[**--help**|**-h**]
[**--authfile**]
[**--all**|**-a**]
**REGISTRY**
**podman logout** [*options*] *registry*
## DESCRIPTION
**podman logout** logs out of a specified registry server by deleting the cached credentials
@ -32,6 +28,10 @@ Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth
Remove the cached credentials for all registries in the auth file
**--help**, **-h**
Print usage statement
## EXAMPLES
```

2
docs/podman-logs.1.md
View File

@ -4,7 +4,7 @@
podman\-logs - Fetch the logs of a container
## SYNOPSIS
**podman** **logs** [*options* [...]] container
**podman** **logs** [*options*] *container*
## DESCRIPTION
The podman logs command batch-retrieves whatever logs are present for a container at the time of execution.

4
docs/podman-mount.1.md
View File

@ -4,9 +4,7 @@
podman\-mount - Mount the specifed working containers' root filesystem
## SYNOPSIS
**podman** **mount**
**podman** **mount** **containerID [...]**
**podman** **mount** [*container* ...]
## DESCRIPTION
Mounts the specified containers' root file system in a location which can be

2
docs/podman-pause.1.md
View File

@ -4,7 +4,7 @@
podman\-pause - Pause one or more containers
## SYNOPSIS
**podman pause [OPTIONS] CONTAINER [...]**
**podman pause** [*options*] *container* ...
## DESCRIPTION
Pauses all the processes in one or more containers. You may use container IDs or names as input.

4
docs/podman-port.1.md
View File

@ -4,10 +4,10 @@
podman\-port - List port mappings for a container
## SYNOPSIS
**podman port [OPTIONS] CONTAINER [PRIVATE_PORT[/PROTO]]**
**podman port** [*options*] *container* [*private-port*[/*proto*]]
## DESCRIPTION
List port mappings for the CONTAINER, or lookup the public-facing port that is NAT-ed to the PRIVATE_PORT
List port mappings for the *container* or lookup the public-facing port that is NAT-ed to the *private-port*.
## OPTIONS

17
docs/podman-ps.1.md
View File

@ -4,12 +4,7 @@
podman\-ps - Prints out information about containers
## SYNOPSIS
**podman ps**
[**--all**|**-a**]
[**--no-trunc**]
[**--quiet**|**-q**]
[**--format**]
[**--help**|**-h**]
**podman ps** [*options*]
## DESCRIPTION
**podman ps** lists the running containers on the system. Use the **--all** flag to view
@ -23,12 +18,6 @@ all the containers information. By default it lists:
* port mappings the container is using
* alternative names for the container
**podman [GLOBAL OPTIONS]**
**podman ps [GLOBAL OPTIONS]**
**podman ps [OPTIONS]**
## OPTIONS
**--all, -a**
@ -103,6 +92,10 @@ Valid filters are listed below:
| since | [ID] or [Name] Containers created since this container |
| volume | [VolumeName] or [MountpointDestination] Volume mounted in container |
**--help**, **-h**
Print usage statement
## EXAMPLES
```

16
docs/podman-pull.1.md
View File

@ -4,9 +4,7 @@
podman\-pull - Pull an image from a registry
## SYNOPSIS
**podman pull**
**NAME[:TAG|@DIGEST]**
[**--help**|**-h**]
**podman pull** [*options*] *name*[:*tag*|@*digest*]
## DESCRIPTION
Copies an image from a registry onto the local machine. **podman pull** pulls an
@ -14,7 +12,7 @@ image from Docker Hub if a registry is not specified in the command line argumen
If an image tag is not specified, **podman pull** defaults to the image with the
**latest** tag (if it exists) and pulls it. After the image is pulled, podman will
print the full image ID. **podman pull** can also pull an image
using its digest **podman pull [image]@[digest]**. **podman pull** can be used to pull
using its digest **podman pull** *image*@*digest*. **podman pull** can be used to pull
images from archives and local storage using different transports.
## imageID
@ -45,12 +43,6 @@ Image stored in local container/storage
**ostree:**_image_[**@**_/absolute/repo/path_]
An image in local OSTree repository. _/absolute/repo/path_ defaults to _/ostree/repo_.
**podman [GLOBAL OPTIONS]**
**podman pull [GLOBAL OPTIONS]**
**podman pull NAME[:TAG|@DIGEST]**
## OPTIONS
**--authfile**
@ -85,6 +77,10 @@ Require HTTPS and verify certificates when contacting registries (default: true)
then tls verification will be used, If set to false then tls verification will not be used. If not specified
tls verification will be used unless the target registry is listed as an insecure registry in registries.conf.
**--help**, **-h**
Print usage statement
## EXAMPLES
```

2
docs/podman-push.1.md
View File

@ -4,7 +4,7 @@
podman\-push - Push an image from local storage to elsewhere
## SYNOPSIS
**podman** **push** [*options* [...]] **imageID** [**destination**]
**podman push** [*options*] **image** [**destination**]
## DESCRIPTION
Pushes an image from local storage to a specified destination.

2
docs/podman-restart.1.md
View File

@ -4,7 +4,7 @@
podman\-restart - Restart a container
## SYNOPSIS
**podman attach [OPTIONS] CONTAINER [CONTAINER...]**
**podman attach** [*options*] *container* ...
## DESCRIPTION
The restart command allows containers to be restarted using their ID or name.

4
docs/podman-rm.1.md
View File

@ -4,10 +4,10 @@
podman\-rm - Remove one or more containers
## SYNOPSIS
**podman** **rm** [*options* [...]] container
**podman rm** [*options*] *container*
## DESCRIPTION
podman rm will remove one or more containers from the host. The container name or ID can be used. This does not remove images. Running containers will not be removed without the -f option
**podman rm** will remove one or more containers from the host. The container name or ID can be used. This does not remove images. Running containers will not be removed without the `-f` option
## OPTIONS

2
docs/podman-rmi.1.md
View File

@ -4,7 +4,7 @@
podman\-rmi - Removes one or more images
## SYNOPSIS
**podman** **rmi** **imageID [...]**
**podman rmi** *image* ...
## DESCRIPTION
Removes one or more locally stored images.

2
docs/podman-run.1.md
View File

@ -4,7 +4,7 @@
podman\-run - Run a command in a new container
## SYNOPSIS
**podman run** [*options* [...]] IMAGE [COMMAND] [ARG...]
**podman run** [*options*] *image* [*command* [*arg* ...]]
## DESCRIPTION

11
docs/podman-save.1.md
View File

@ -4,12 +4,7 @@
podman\-save - Save an image to docker-archive or oci-archive
## SYNOPSIS
**podman save**
**NAME[:TAG]**
[**--quiet**|**-q**]
[**--format**]
[**--output**|**-o**]
[**--help**|**-h**]
**podman save** [*options*] *name*[:*tag*]
## DESCRIPTION
**podman save** saves an image to either **docker-archive**, **oci-archive**, **oci-dir** (directory
@ -48,6 +43,10 @@ Save image to **oci-archive**, **oci-dir** (directory with oci manifest type), o
Suppress the output
**--help**, **-h**
Print usage statement
## EXAMPLES
```

13
docs/podman-search.1.md
View File

@ -4,14 +4,7 @@
podman\-search - Search a registry for an image
## SYNOPSIS
**podman search**
**TERM**
[**--filter**|**-f**]
[**--format**]
[**--limit**]
[**--no-trunc**]
[**--registry**]
[**--help**|**-h**]
**podman search** [*options*] *term*
## DESCRIPTION
**podman search** searches a registry or a list of registries for a matching image.
@ -78,6 +71,10 @@ then tls verification will be used. If set to false then tls verification will n
default registries will be searched through (in /etc/containers/registries.conf), and tls will be skipped if a default
registry is listed in the insecure registries.
**--help**, **-h**
Print usage statement
## EXAMPLES
```

2
docs/podman-start.1.md
View File

@ -4,7 +4,7 @@
podman\-start - Start one or more containers
## SYNOPSIS
**podman start [OPTIONS] CONTAINER [...]**
**podman start** [*options*] *container* ...
## DESCRIPTION
Start one or more containers. You may use container IDs or names as input. The *attach* and *interactive*

2
docs/podman-stats.1.md
View File

@ -4,7 +4,7 @@
podman\-stats - Display a live stream of 1 or more containers' resource usage statistics
## SYNOPSIS
**podman** **stats** [*options* [...]] [container]
**podman stats** [*options*] [*container*]
## DESCRIPTION
Display a live stream of one or more containers' resource usage statistics

2
docs/podman-stop.1.md
View File

@ -4,7 +4,7 @@
podman\-stop - Stop one or more containers
## SYNOPSIS
**podman stop [OPTIONS] CONTAINER [...]**
**podman stop** [*options*] *container* ...
## DESCRIPTION
Stops one or more containers. You may use container IDs or names as input. The **--timeout** switch

11
docs/podman-tag.1.md
View File

@ -4,14 +4,19 @@
podman\-tag - Add an additional name to a local image
## SYNOPSIS
**podman [GLOBAL OPTIONS] tag IMAGE[:TAG] TARGET_NAME[:TAG]**
**podman tag** *image*[:*tag*] *target-name*[:*tag*]
[**--help**|**-h**]
## DESCRIPTION
Assigns a new alias to an image. An alias refers to the entire image name, including the optional
**TAG** after the ':' If you do not provide a :TAG, podman will assume a :TAG of "latest" for both
the IMAGE and the TARGET_NAME.
*tag* after the `:`. If you do not provide *tag*, podman will default to `latest` for both
the *image* and the *target-name*.
## OPTIONS
**--help**, **-h**
Print usage statement
## EXAMPLES

7
docs/podman-top.1.md
View File

@ -4,13 +4,10 @@
podman\-top - Display the running processes of a container
## SYNOPSIS
**podman top**
[**--help**|**-h**]
**podman top** [*options*] *container* [*ps-options*]
## DESCRIPTION
Display the running process of the container. ps-OPTION can be any of the options you would pass to a Linux ps command
**podman [GLOBAL OPTIONS] top [OPTIONS]**
Display the running process of the container. *ps-options* can be any of the options you would pass to `ps(1)`.
## OPTIONS

2
docs/podman-umount.1.md
View File

@ -4,7 +4,7 @@
podman\-umount - Unmount the specified working containers' root file system.
## SYNOPSIS
**podman** **umount** **containerID [...]**
**podman umount** *container* ...
## DESCRIPTION
Unmounts the specified containers' root file system.

2
docs/podman-unpause.1.md
View File

@ -4,7 +4,7 @@
podman\-unpause - Unpause one or more containers
## SYNOPSIS
**podman unpause [OPTIONS] CONTAINER [...]**
**podman unpause** [*options*] *container* ...
## DESCRIPTION
Unpauses the processes in one or more containers. You may use container IDs or names as input.

8
docs/podman-varlink.1.md
View File

@ -4,16 +4,12 @@
podman\-varlink - Runs the varlink backend interface
## SYNOPSIS
**podman varlink** [OPTIONS]
[**--help**|**-h**]
VARLINK_URI
**podman varlink** [*options*] *uri*
## DESCRIPTION
Starts the varlink service that allows varlink clients to interact with podman. This should generally be done
Starts the varlink service listening on *uri* that allows varlink clients to interact with podman. This should generally be done
with systemd. See _Configuration_ below.
**podman [GLOBAL OPTIONS] [OPTIONS] varlink VARLINK_URI**
## GLOBAL OPTIONS
**--help, -h**

9
docs/podman-version.1.md
View File

@ -4,16 +4,17 @@
podman\-version - Display the PODMAN Version Information
## SYNOPSIS
**podman version**
[**--help**|**-h**]
**podman version** [*options*]
## DESCRIPTION
Shows the the following information: Version, Go Version, Git Commit, Build Time,
OS, and Architecture.
**podman [GLOBAL OPTIONS]**
## OPTIONS
**podman version**
**--help**, **-h**
Print usage statement
## SEE ALSO
podman(1), crio(8)

7
docs/podman-wait.1.md
View File

@ -4,17 +4,14 @@
podman\-wait - Waits on one or more containers to stop and prints exit code
## SYNOPSIS
**podman wait**
[**--help**|**-h**]
**podman wait** [*options*] *container*
## DESCRIPTION
Waits on one or more containers to stop. The container can be referred to by its
name or ID. In the case of multiple containers, podman will wait on each consecutively.
After the container stops, the container's return code is printed.
**podman [GLOBAL OPTIONS] wait **
## GLOBAL OPTIONS
## OPTIONS
**--help, -h**

2
docs/podman.1.md
View File

@ -4,7 +4,7 @@
podman - Simple management tool for containers and images
## SYNOPSIS
**podman** [*options*] COMMAND
**podman** [*options*] *command*
# DESCRIPTION
podman is a simple client only tool to help with debugging issues when daemons