Skip to content

Commit 04b0fb6

Browse files
author
moxiegirl
committed
Merge pull request moby#15822 from vdemeester/docs-update-filtering-ps-and-images
Update filtering chapters on ps/images references
2 parents 0634c65 + 61de442 commit 04b0fb6

File tree

2 files changed

+122
-3
lines changed

2 files changed

+122
-3
lines changed

‎docs/reference/commandline/images.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ The currently supported filters are:
123123
* dangling (boolean - true or false)
124124
* label (`label=<key>` or `label=<key>=<value>`)
125125

126-
##### Untagged images
126+
##### Untagged images (dangling)
127127

128128
$ docker images --filter "dangling=true"
129129

@@ -155,3 +155,27 @@ Ready for use by `docker rmi ...`, like:
155155
NOTE: Docker will warn you if any containers exist that are using these untagged images.
156156

157157

158+
##### Labeled images
159+
160+
The `label` filter matches images based on the presence of a `label` alone or a `label` and a
161+
value.
162+
163+
The following filter matches images with the `com.example.version` label regardless of its value.
164+
165+
$ docker images --filter "label=com.example.version"
166+
167+
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
168+
match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB
169+
match-me-2 latest eeae25ada2aa About a minute ago 188.3 MB
170+
171+
The following filter matches images with the `com.example.version` label with the `1.0` value.
172+
173+
$ docker images --filter "label=com.example.version=1.0"
174+
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
175+
match-me latest eeae25ada2aa About a minute ago 188.3 MB
176+
177+
In this example, with the `0.1` value, it returns an empty set because no matches were found.
178+
179+
$ docker images --filter "label=com.example.version=0.1"
180+
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
181+

‎docs/reference/commandline/ps.md‎

Lines changed: 97 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,15 +51,110 @@ The currently supported filters are:
5151
* exited (int - the code of exited containers. Only useful with `--all`)
5252
* status (created|restarting|running|paused|exited)
5353

54-
## Successfully exited containers
54+
55+
#### Label
56+
57+
The `label` filter matches containers based on the presence of a `label` alone or a `label` and a
58+
value.
59+
60+
The following filter matches containers with the `color` label regardless of its value.
61+
62+
$ docker ps --filter "label=color"
63+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
64+
673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley
65+
d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani
66+
67+
The following filter matches containers with the `color` label with the `blue` value.
68+
69+
$ docker ps --filter "label=color=blue"
70+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
71+
d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani
72+
73+
#### Name
74+
75+
The `name` filter matches on all or part of a container's name.
76+
77+
The following filter matches all containers with a name containing the `nostalgic_stallman` string.
78+
79+
$ docker ps --filter "name=nostalgic_stallman"
80+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
81+
9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman
82+
83+
You can also filter for a substring in a name as this shows:
84+
85+
$ docker ps --filter "name=nostalgic"
86+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
87+
715ebfcee040 busybox "top" 3 seconds ago Up 1 seconds i_am_nostalgic
88+
9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman
89+
673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley
90+
91+
#### Exited
92+
93+
The `exited` filter matches containers by exist status code. For example, to filter for containers
94+
that have exited successfully:
5595

5696
$ docker ps -a --filter 'exited=0'
5797
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
5898
ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey
5999
106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani
60100
48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds
61101

62-
This shows all the containers that have exited with status of '0'
102+
#### Status
103+
104+
The `status` filter matches containers by status. You can filter using `created`, `restarting`, `running`, `paused` and `exited`. For example, to filter for `running` containers:
105+
106+
$ docker ps --filter status=running
107+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
108+
715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic
109+
d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top
110+
9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman
111+
112+
To filter for `paused` containers:
113+
114+
$ docker ps --filter status=paused
115+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
116+
673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley
117+
118+
#### Ancestor
119+
120+
The `ancestor` filter matches containers based on its image or a descendant of it. The filter supports the
121+
following image representation:
122+
123+
- image
124+
- image:tag
125+
- image:tag@digest
126+
- short-id
127+
- full-id
128+
129+
If you don't specify a `tag`, the `latest` tag is used. For example, to filter for containers that use the
130+
latest `ubuntu` image:
131+
132+
$ docker ps --filter ancestor=ubuntu
133+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
134+
919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
135+
5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet
136+
82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose
137+
bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath
138+
139+
Match containers based on the `ubuntu-c1` image which, in this case, is a child of `ubuntu`:
140+
141+
$ docker ps --filter ancestor=ubuntu-c1
142+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
143+
919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace
144+
145+
Match containers based on the `ubuntu` version `12.04.5` image:
146+
147+
$ docker ps --filter ancestor=ubuntu:12.04.5
148+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
149+
82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose
150+
151+
The following matches containers based on the layer `d0e008c6cf02` or an image that have this layer
152+
in it's layer stack.
153+
154+
$ docker ps --filter ancestor=d0e008c6cf02
155+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
156+
82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose
157+
63158

64159
## Formatting
65160

0 commit comments

Comments
 (0)