diff --git a/docs/reference/commandline/images.md b/docs/reference/commandline/images.md index 8490e95722..6e979937a6 100644 --- a/docs/reference/commandline/images.md +++ b/docs/reference/commandline/images.md @@ -123,7 +123,7 @@ The currently supported filters are: * dangling (boolean - true or false) * label (`label=` or `label==`) -##### Untagged images +##### Untagged images (dangling) $ docker images --filter "dangling=true" @@ -155,3 +155,27 @@ Ready for use by `docker rmi ...`, like: NOTE: Docker will warn you if any containers exist that are using these untagged images. +##### Labeled images + +The `label` filter matches images based on the presence of a `label` alone or a `label` and a +value. + +The following filter matches images with the `com.example.version` label regardless of its value. + + $ docker images --filter "label=com.example.version" + + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB + match-me-2 latest eeae25ada2aa About a minute ago 188.3 MB + +The following filter matches images with the `com.example.version` label with the `1.0` value. + + $ docker images --filter "label=com.example.version=1.0" + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + match-me latest eeae25ada2aa About a minute ago 188.3 MB + +In this example, with the `0.1` value, it returns an empty set because no matches were found. + + $ docker images --filter "label=com.example.version=0.1" + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + diff --git a/docs/reference/commandline/ps.md b/docs/reference/commandline/ps.md index 02df110e45..eae46368e4 100644 --- a/docs/reference/commandline/ps.md +++ b/docs/reference/commandline/ps.md @@ -51,7 +51,47 @@ The currently supported filters are: * exited (int - the code of exited containers. Only useful with `--all`) * status (created|restarting|running|paused|exited) -## Successfully exited containers + +#### Label + +The `label` filter matches containers based on the presence of a `label` alone or a `label` and a +value. + +The following filter matches containers with the `color` label regardless of its value. + + $ docker ps --filter "label=color" + 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. + + $ docker ps --filter "label=color=blue" + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani + +#### Name + +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. + + $ docker ps --filter "name=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: + + $ docker ps --filter "name=nostalgic" + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 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 + +The `exited` filter matches containers by exist status code. For example, to filter for containers +that have exited successfully: $ docker ps -a --filter 'exited=0' CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES @@ -59,7 +99,62 @@ The currently supported filters are: 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 -This shows all the containers that have exited with status of '0' +#### Status + +The `status` filter matches containers by status. You can filter using `created`, `restarting`, `running`, `paused` and `exited`. For example, to filter for `running` containers: + + $ docker ps --filter status=running + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 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: + + $ docker ps --filter status=paused + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley + +#### Ancestor + +The `ancestor` filter matches containers based on its image or a descendant of it. The filter supports the +following image representation: + +- image +- image:tag +- image:tag@digest +- short-id +- full-id + +If you don't specify a `tag`, the `latest` tag is used. For example, to filter for containers that use the +latest `ubuntu` image: + + $ docker ps --filter ancestor=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 + +Match containers based on the `ubuntu-c1` image which, in this case, is a child of `ubuntu`: + + $ 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: + + $ docker ps --filter ancestor=ubuntu:12.04.5 + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 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 +in it's layer stack. + + $ 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 + ## Formatting