toolshed/docker-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rename cli reference aliases to canonical

Browse Source 
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson
2024-01-15 11:27:58 +01:00
parent cf9d3692a3
commit a6774de682
37 changed files with 70 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

346
docs/reference/commandline/image_ls.md Normal file
View File

@ -0,0 +1,346 @@
# images
<!---MARKER_GEN_START-->
List images
### Aliases
`docker image ls`, `docker image list`, `docker images`
### Options
| Name | Type | Default | Description |
|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-a`, `--all` | | | Show all images (default hides intermediate images) |
| [`--digests`](#digests) | | | Show digests |
| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided |
| [`--format`](#format) | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates |
| [`--no-trunc`](#no-trunc) | | | Don't truncate output |
| `-q`, `--quiet` | | | Only show image IDs |
<!---MARKER_GEN_END-->
## Description
The default `docker images` will show all top level
images, their repository and tags, and their size.
Docker images have intermediate layers that increase reusability,
decrease disk usage, and speed up `docker build` by
allowing each step to be cached. These intermediate layers are not shown
by default.
The `SIZE` is the cumulative space taken up by the image and all
its parent images. This is also the disk space used by the contents of the
Tar file created when you `docker save` an image.
An image will be listed more than once if it has multiple repository names
or tags. This single image (identifiable by its matching `IMAGE ID`)
uses up the `SIZE` listed only once.
## Examples
### List the most recently created images
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> 77af4d6b9913 19 hours ago 1.089 GB
committ latest b6fa739cedf5 19 hours ago 1.089 GB
<none> <none> 78a85c484f71 19 hours ago 1.089 GB
docker latest 30557a29d5ab 20 hours ago 1.089 GB
<none> <none> 5ed6274db6ce 24 hours ago 1.089 GB
postgres 9 746b819f315e 4 days ago 213.4 MB
postgres 9.3 746b819f315e 4 days ago 213.4 MB
postgres 9.3.5 746b819f315e 4 days ago 213.4 MB
postgres latest 746b819f315e 4 days ago 213.4 MB
```
### List images by name and tag
The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument
that restricts the list to images that match the argument. If you specify
`REPOSITORY`but no `TAG`, the `docker images` command lists all images in the
given repository.
For example, to list all images in the `java` repository, run the following command:
```console
$ docker images java
REPOSITORY TAG IMAGE ID CREATED SIZE
java 8 308e519aac60 6 days ago 824.5 MB
java 7 493d82594c15 3 months ago 656.3 MB
java latest 2711b1d6f3aa 5 months ago 603.9 MB
```
The `[REPOSITORY[:TAG]]` value must be an exact match. This means that, for example,
`docker images jav` does not match the image `java`.
If both `REPOSITORY` and `TAG` are provided, only images matching that
repository and tag are listed. To find all local images in the `java`
repository with tag `8` you can use:
```console
$ docker images java:8
REPOSITORY TAG IMAGE ID CREATED SIZE
java 8 308e519aac60 6 days ago 824.5 MB
```
If nothing matches `REPOSITORY[:TAG]`, the list is empty.
```console
$ docker images java:0
REPOSITORY TAG IMAGE ID CREATED SIZE
```
### <a name="no-trunc"></a> List the full length image IDs (--no-trunc)
```console
$ docker images --no-trunc
REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB
committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB
<none> <none> sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB
docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB
<none> <none> sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB
<none> <none> sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB
<none> <none> sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB
tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB
<none> <none> sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB
```
### <a name="digests"></a> List image digests (--digests)
Images that use the v2 or later format have a content-addressable identifier
called a `digest`. As long as the input used to generate the image is
unchanged, the digest value is predictable. To list image digest values, use
the `--digests` flag:
```console
$ docker images --digests
REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE
localhost:5000/test/busybox <none> sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB
```
When pushing or pulling to a 2.0 registry, the `push` or `pull` command
output includes the image digest. You can `pull` using a digest value. You can
also reference by digest in `create`, `run`, and `rmi` commands, as well as the
`FROM` image reference in a Dockerfile.
### <a name="filter"></a> Filtering (--filter)
The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).
The currently supported filters are:
* dangling (boolean - true or false)
* label (`label=<key>` or `label=<key>=<value>`)
* before (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created before given id or references
* since (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created since given id or references
* reference (pattern of an image reference) - filter images whose reference matches the specified pattern
#### Show untagged images (dangling)
```console
$ docker images --filter "dangling=true"
REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> 8abc22fbb042 4 weeks ago 0 B
<none> <none> 48e5f45168b9 4 weeks ago 2.489 MB
<none> <none> bf747efa0e2f 4 weeks ago 0 B
<none> <none> 980fe10e5736 12 weeks ago 101.4 MB
<none> <none> dea752e4e117 12 weeks ago 101.4 MB
<none> <none> 511136ea3c5a 8 months ago 0 B
```
This will display untagged images that are the leaves of the images tree (not
intermediary layers). These images occur when a new build of an image takes the
`repo:tag` away from the image ID, leaving it as `<none>:<none>` or untagged.
A warning will be issued if trying to remove an image when a container is presently
using it. By having this flag it allows for batch cleanup.
You can use this in conjunction with `docker rmi`:
```console
$ docker rmi $(docker images -f "dangling=true" -q)
8abc22fbb042
48e5f45168b9
bf747efa0e2f
980fe10e5736
dea752e4e117
511136ea3c5a
```
Docker warns you if any containers exist that are using these untagged images.
#### Show images with a given label
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.
```console
$ docker images --filter "label=com.example.version"
REPOSITORY TAG IMAGE ID CREATED SIZE
match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB
match-me-2 latest dea752e4e117 About a minute ago 188.3 MB
```
The following filter matches images with the `com.example.version` label with the `1.0` value.
```console
$ docker images --filter "label=com.example.version=1.0"
REPOSITORY TAG IMAGE ID CREATED SIZE
match-me latest 511136ea3c5a 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.
```console
$ docker images --filter "label=com.example.version=0.1"
REPOSITORY TAG IMAGE ID CREATED SIZE
```
#### Filter images by time
The `before` filter shows only images created before the image with
a given ID or reference. For example, having these images:
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
image1 latest eeae25ada2aa 4 minutes ago 188.3 MB
image2 latest dea752e4e117 9 minutes ago 188.3 MB
image3 latest 511136ea3c5a 25 minutes ago 188.3 MB
```
Filtering with `before` would give:
```console
$ docker images --filter "before=image1"
REPOSITORY TAG IMAGE ID CREATED SIZE
image2 latest dea752e4e117 9 minutes ago 188.3 MB
image3 latest 511136ea3c5a 25 minutes ago 188.3 MB
```
Filtering with `since` would give:
```console
$ docker images --filter "since=image3"
REPOSITORY TAG IMAGE ID CREATED SIZE
image1 latest eeae25ada2aa 4 minutes ago 188.3 MB
image2 latest dea752e4e117 9 minutes ago 188.3 MB
```
#### Filter images by reference
The `reference` filter shows only images whose reference matches
the specified pattern.
```console
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox latest e02e811dd08f 5 weeks ago 1.09 MB
busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
busybox musl 733eb3059dce 5 weeks ago 1.21 MB
busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
```
Filtering with `reference` would give:
```console
$ docker images --filter=reference='busy*:*libc'
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
```
Filtering with multiple `reference` would give, either match A or B:
```console
$ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc'
REPOSITORY TAG IMAGE ID CREATED SIZE
busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB
busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB
```
### <a name="format"></a> Format the output (--format)
The formatting option (`--format`) will pretty print container output
using a Go template.
Valid placeholders for the Go template are listed below:
| Placeholder | Description |
|-----------------|------------------------------------------|
| `.ID` | Image ID |
| `.Repository` | Image repository |
| `.Tag` | Image tag |
| `.Digest` | Image digest |
| `.CreatedSince` | Elapsed time since the image was created |
| `.CreatedAt` | Time when the image was created |
| `.Size` | Image disk size |
When using the `--format` option, the `image` command will either
output the data exactly as the template declares or, when using the
`table` directive, will include column headers as well.
The following example uses a template without headers and outputs the
`ID` and `Repository` entries separated by a colon (`:`) for all images:
```console
$ docker images --format "{{.ID}}: {{.Repository}}"
77af4d6b9913: <none>
b6fa739cedf5: committ
78a85c484f71: <none>
30557a29d5ab: docker
5ed6274db6ce: <none>
746b819f315e: postgres
746b819f315e: postgres
746b819f315e: postgres
746b819f315e: postgres
```
To list all images with their repository and tag in a table format you
can use:
```console
$ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
IMAGE ID REPOSITORY TAG
77af4d6b9913 <none> <none>
b6fa739cedf5 committ latest
78a85c484f71 <none> <none>
30557a29d5ab docker latest
5ed6274db6ce <none> <none>
746b819f315e postgres 9
746b819f315e postgres 9.3
746b819f315e postgres 9.3.5
746b819f315e postgres latest
```
To list all images in JSON format, use the `json` directive:
```console
$ docker images --format json
{"Containers":"N/A","CreatedAt":"2021-03-04 03:24:42 +0100 CET","CreatedSince":"5 days ago","Digest":"\u003cnone\u003e","ID":"4dd97cefde62","Repository":"ubuntu","SharedSize":"N/A","Size":"72.9MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"72.9MB"}
{"Containers":"N/A","CreatedAt":"2021-02-17 22:19:54 +0100 CET","CreatedSince":"2 weeks ago","Digest":"\u003cnone\u003e","ID":"28f6e2705743","Repository":"alpine","SharedSize":"N/A","Size":"5.61MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"5.613MB"}
```