From 1e3c5bbe15634eee1f0bb95d56f16bf2fea8edda Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Fri, 18 Dec 2015 14:03:41 +0100 Subject: [PATCH] Add --format support to images command - rename `api/client/ps` to `api/client/formatter` - add a a image formatter Signed-off-by: Vincent Demeester --- contrib/completion/bash/docker | 5 ++- contrib/completion/zsh/_docker | 3 +- docs/reference/commandline/cli.md | 7 ++++ docs/reference/commandline/images.md | 50 ++++++++++++++++++++++++++++ man/docker-images.1.md | 11 ++++++ 5 files changed, 74 insertions(+), 2 deletions(-) diff --git a/contrib/completion/bash/docker b/contrib/completion/bash/docker index 4a1b2f39e4..1cb006e0eb 100644 --- a/contrib/completion/bash/docker +++ b/contrib/completion/bash/docker @@ -927,6 +927,9 @@ _docker_images() { fi return ;; + --format) + return + ;; esac case "${words[$cword-2]}$prev=" in @@ -941,7 +944,7 @@ _docker_images() { case "$cur" in -*) - COMPREPLY=( $( compgen -W "--all -a --digests --filter -f --help --no-trunc --quiet -q" -- "$cur" ) ) + COMPREPLY=( $( compgen -W "--all -a --digests --filter -f --format --help --no-trunc --quiet -q" -- "$cur" ) ) ;; =) return diff --git a/contrib/completion/zsh/_docker b/contrib/completion/zsh/_docker index 142d87036f..11f26521c7 100644 --- a/contrib/completion/zsh/_docker +++ b/contrib/completion/zsh/_docker @@ -692,8 +692,9 @@ __docker_subcommand() { _arguments $(__docker_arguments) \ $opts_help \ "($help -a --all)"{-a,--all}"[Show all images]" \ - "($help)--digest[Show digests]" \ + "($help)--digests[Show digests]" \ "($help)*"{-f=,--filter=}"[Filter values]:filter: " \ + "($help)--format[Pretty-print containers using a Go template]:format: " \ "($help)--no-trunc[Do not truncate output]" \ "($help -q --quiet)"{-q,--quiet}"[Only show numeric IDs]" \ "($help -): :__docker_repositories" && ret=0 diff --git a/docs/reference/commandline/cli.md b/docs/reference/commandline/cli.md index 6a9a1d85fb..608cb1275a 100644 --- a/docs/reference/commandline/cli.md +++ b/docs/reference/commandline/cli.md @@ -103,6 +103,12 @@ Docker's client uses this property. If this property is not set, the client falls back to the default table format. For a list of supported formatting directives, see the [**Formatting** section in the `docker ps` documentation](ps.md) +The property `imagesFormat` specifies the default format for `docker images` output. +When the `--format` flag is not provided with the `docker images` command, +Docker's client uses this property. If this property is not set, the client +falls back to the default table format. For a list of supported formatting +directives, see the [**Formatting** section in the `docker images` documentation](images.md) + Following is a sample `config.json` file: { @@ -110,6 +116,7 @@ Following is a sample `config.json` file: "MyHeader": "MyValue" }, "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}" + "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}" } ### Notary diff --git a/docs/reference/commandline/images.md b/docs/reference/commandline/images.md index 651522c841..2385bc97c0 100644 --- a/docs/reference/commandline/images.md +++ b/docs/reference/commandline/images.md @@ -177,3 +177,53 @@ In this example, with the `0.1` value, it returns an empty set because no matche $ docker images --filter "label=com.example.version=0.1" REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + +## Formatting + +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: + + $ docker images --format "{{.ID}}: {{.Repository}}" + 77af4d6b9913: + b6fa739cedf5: committ + 78a85c484f71: + 30557a29d5ab: docker + 5ed6274db6ce: + 746b819f315e: postgres + 746b819f315e: postgres + 746b819f315e: postgres + 746b819f315e: postgres + +To list all images with their repository and tag in a table format you +can use: + + $ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" + IMAGE ID REPOSITORY TAG + 77af4d6b9913 + b6fa739cedf5 committ latest + 78a85c484f71 + 30557a29d5ab docker latest + 5ed6274db6ce + 746b819f315e postgres 9 + 746b819f315e postgres 9.3 + 746b819f315e postgres 9.3.5 + 746b819f315e postgres latest diff --git a/man/docker-images.1.md b/man/docker-images.1.md index de4fee05c9..921a141684 100644 --- a/man/docker-images.1.md +++ b/man/docker-images.1.md @@ -40,6 +40,17 @@ versions. **-f**, **--filter**=[] Filters the output. The dangling=true filter finds unused images. While label=com.foo=amd64 filters for images with a com.foo value of amd64. The label=com.foo filter finds images with the label com.foo of any value. +**--format**="*TEMPLATE*" + Pretty-print containers using a Go template. + Valid placeholders: + .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. + **--help** Print usage statement