docs: improve formatting and highlighting of docker ps reference

this improves the formatting, and code-highlighting
of the `docker ps` reference page, and wraps sentences
to 80 chars

also adds single quotes around the formatting
example for labels.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2016-07-21 12:27:39 +02:00
Родитель bdf4d9c1cd
Коммит 07ef0a37f8
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 76698F39D527CE8C
1 изменённых файлов: 181 добавлений и 113 удалений

Просмотреть файл

@ -38,15 +38,24 @@ Options:
Running `docker ps --no-trunc` showing 2 linked containers. Running `docker ps --no-trunc` showing 2 linked containers.
$ docker ps ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps
4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp
d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db
`docker ps` will show only running containers by default. To see all containers: CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
`docker ps -a` 4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp
d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db
```
`docker ps` will group exposed ports into a single range if possible. E.g., a container that exposes TCP ports `100, 101, 102` will display `100-102/tcp` in the `PORTS` column. The `docker ps` command only shows running containers by default. To see all
containers, use the `-a` (or `--all`) flag:
```bash
$ docker ps -a
```
`docker ps` groups exposed ports into a single range if possible. E.g., a
container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in
the `PORTS` column.
## Filtering ## Filtering
@ -74,16 +83,22 @@ value.
The following filter matches containers with the `color` label regardless of its value. The following filter matches containers with the `color` label regardless of its value.
$ docker ps --filter "label=color" ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps --filter "label=color"
673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley
d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley
d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani
```
The following filter matches containers with the `color` label with the `blue` value. The following filter matches containers with the `color` label with the `blue` value.
$ docker ps --filter "label=color=blue" ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps --filter "label=color=blue"
d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani
```
#### Name #### Name
@ -91,49 +106,66 @@ The `name` filter matches on all or part of a container's name.
The following filter matches all containers with a name containing the `nostalgic_stallman` string. The following filter matches all containers with a name containing the `nostalgic_stallman` string.
$ docker ps --filter "name=nostalgic_stallman" ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps --filter "name=nostalgic_stallman"
9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman
```
You can also filter for a substring in a name as this shows: You can also filter for a substring in a name as this shows:
$ docker ps --filter "name=nostalgic" ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps --filter "name=nostalgic"
715ebfcee040 busybox "top" 3 seconds ago Up 1 seconds i_am_nostalgic
9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley 715ebfcee040 busybox "top" 3 seconds ago Up 1 seconds i_am_nostalgic
9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman
673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley
```
#### Exited #### Exited
The `exited` filter matches containers by exist status code. For example, to filter for containers The `exited` filter matches containers by exist status code. For example, to
that have exited successfully: filter for containers that have exited successfully:
$ docker ps -a --filter 'exited=0' ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps -a --filter 'exited=0'
ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey
106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey
106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani
48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds
```
#### Status #### Status
The `status` filter matches containers by status. You can filter using `created`, `restarting`, `running`, `paused`, `exited` and `dead`. For example, to filter for `running` containers: The `status` filter matches containers by status. You can filter using
`created`, `restarting`, `running`, `paused`, `exited` and `dead`. For example,
to filter for `running` containers:
$ docker ps --filter status=running ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps --filter status=running
715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic
d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman 715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic
d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top
9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman
```
To filter for `paused` containers: To filter for `paused` containers:
$ docker ps --filter status=paused ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps --filter status=paused
673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley
```
#### Ancestor #### Ancestor
The `ancestor` filter matches containers based on its image or a descendant of it. The filter supports the The `ancestor` filter matches containers based on its image or a descendant of
following image representation: it. The filter supports the following image representation:
- image - image
- image:tag - image:tag
@ -141,74 +173,99 @@ following image representation:
- short-id - short-id
- full-id - full-id
If you don't specify a `tag`, the `latest` tag is used. For example, to filter for containers that use the If you don't specify a `tag`, the `latest` tag is used. For example, to filter
latest `ubuntu` image: for containers that use the latest `ubuntu` image:
$ docker ps --filter ancestor=ubuntu ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps --filter ancestor=ubuntu
919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet
82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose
bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath
Match containers based on the `ubuntu-c1` image which, in this case, is a child of `ubuntu`: CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet
82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose
bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath
```
$ docker ps --filter ancestor=ubuntu-c1 Match containers based on the `ubuntu-c1` image which, in this case, is a child
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES of `ubuntu`:
919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
```bash
$ docker ps --filter ancestor=ubuntu-c1
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
```
Match containers based on the `ubuntu` version `12.04.5` image: Match containers based on the `ubuntu` version `12.04.5` image:
$ docker ps --filter ancestor=ubuntu:12.04.5 ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps --filter ancestor=ubuntu:12.04.5
82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose
The following matches containers based on the layer `d0e008c6cf02` or an image that have this layer CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
in it's layer stack. 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose
```
$ docker ps --filter ancestor=d0e008c6cf02 The following matches containers based on the layer `d0e008c6cf02` or an image
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES that have this layer in it's layer stack.
82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose
```bash
$ docker ps --filter ancestor=d0e008c6cf02
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose
```
#### Before #### Before
The `before` filter shows only containers created before the container with given id or name. For example, The `before` filter shows only containers created before the container with
having these containers created: given id or name. For example, having these containers created:
$ docker ps ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps
9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky
4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat 9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky
4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton
6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat
```
Filtering with `before` would give: Filtering with `before` would give:
$ docker ps -f before=9c3527ed70ce ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps -f before=9c3527ed70ce
4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton
6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton
6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat
```
#### Since #### Since
The `since` filter shows only containers created since the container with given id or name. For example, The `since` filter shows only containers created since the container with given
with the same containers as in `before` filter: id or name. For example, with the same containers as in `before` filter:
$ docker ps -f since=6e63f6ff38b0 ```bash
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES $ docker ps -f since=6e63f6ff38b0
9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky
4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky
4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton
```
#### Volume #### Volume
The `volume` filter shows only containers that mount a specific volume or have a volume mounted in a specific path: The `volume` filter shows only containers that mount a specific volume or have
a volume mounted in a specific path:
$ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" ```bash
CONTAINER ID MOUNTS $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}"
9c3527ed70ce remote-volume CONTAINER ID MOUNTS
9c3527ed70ce remote-volume
$ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}"
CONTAINER ID MOUNTS CONTAINER ID MOUNTS
9c3527ed70ce remote-volume 9c3527ed70ce remote-volume
```
#### Network #### Network
@ -223,6 +280,7 @@ $ docker run -d --net=net1 --name=test1 ubuntu top
$ docker run -d --net=net2 --name=test2 ubuntu top $ docker run -d --net=net2 --name=test2 ubuntu top
$ docker ps --filter network=net1 $ docker ps --filter network=net1
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1
``` ```
@ -233,51 +291,61 @@ the network id as a filter;
```bash ```bash
$ docker network inspect --format "{{.ID}}" net1 $ docker network inspect --format "{{.ID}}" net1
8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5
$ docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 $ docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1
``` ```
## Formatting ## Formatting
The formatting option (`--format`) will pretty-print container output using a Go template. The formatting option (`--format`) pretty-prints container output using a Go
template.
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description Placeholder | Description
---- | ---- --------------|----------------------------------------------------------------------------------------------------
`.ID` | Container ID `.ID` | Container ID
`.Image` | Image ID `.Image` | Image ID
`.Command` | Quoted command `.Command` | Quoted command
`.CreatedAt` | Time when the container was created. `.CreatedAt` | Time when the container was created.
`.RunningFor` | Elapsed time since the container was started. `.RunningFor` | Elapsed time since the container was started.
`.Ports` | Exposed ports. `.Ports` | Exposed ports.
`.Status` | Container status. `.Status` | Container status.
`.Size` | Container disk size. `.Size` | Container disk size.
`.Names` | Container names. `.Names` | Container names.
`.Labels` | All labels assigned to the container. `.Labels` | All labels assigned to the container.
`.Label` | Value of a specific label for this container. For example `{{.Label "com.docker.swarm.cpu"}}` `.Label` | Value of a specific label for this container. For example `'{{.Label "com.docker.swarm.cpu"}}'`
`.Mounts` | Names of the volumes mounted in this container. `.Mounts` | Names of the volumes mounted in this container.
When using the `--format` option, the `ps` command will either output the data exactly as the template When using the `--format` option, the `ps` command will either output the data
declares or, when using the `table` directive, will include column headers as well. exactly as the template declares or, when using the `table` directive, includes
column headers as well.
The following example uses a template without headers and outputs the `ID` and `Command` The following example uses a template without headers and outputs the `ID` and
entries separated by a colon for all running containers: `Command` entries separated by a colon for all running containers:
$ docker ps --format "{{.ID}}: {{.Command}}" ```bash
a87ecb4f327c: /bin/sh -c #(nop) MA $ docker ps --format "{{.ID}}: {{.Command}}"
01946d9d34d8: /bin/sh -c #(nop) MA
c1d3b0166030: /bin/sh -c yum -y up a87ecb4f327c: /bin/sh -c #(nop) MA
41d50ecd2f57: /bin/sh -c #(nop) MA 01946d9d34d8: /bin/sh -c #(nop) MA
c1d3b0166030: /bin/sh -c yum -y up
41d50ecd2f57: /bin/sh -c #(nop) MA
```
To list all running containers with their labels in a table format you can use: To list all running containers with their labels in a table format you can use:
$ docker ps --format "table {{.ID}}\t{{.Labels}}" ```bash
CONTAINER ID LABELS $ docker ps --format "table {{.ID}}\t{{.Labels}}"
a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd
01946d9d34d8 CONTAINER ID LABELS
c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6 a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd
41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd 01946d9d34d8
c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6
41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd
```