diff --git a/contrib/completion/bash/docker b/contrib/completion/bash/docker index f26ff802..0bea86cb 100644 --- a/contrib/completion/bash/docker +++ b/contrib/completion/bash/docker @@ -1907,15 +1907,29 @@ _docker_save() { } _docker_search() { + local key=$(__docker_map_key_of_current_option '--filter|-f') + case "$key" in + is-automated) + COMPREPLY=( $( compgen -W "false true" -- "${cur##*=}" ) ) + return + ;; + is-official) + COMPREPLY=( $( compgen -W "false true" -- "${cur##*=}" ) ) + return + ;; + esac + case "$prev" in - --stars|-s) + --filter|-f) + COMPREPLY=( $( compgen -S = -W "is-automated is-official stars" -- "$cur" ) ) + __docker_nospace return ;; esac case "$cur" in -*) - COMPREPLY=( $( compgen -W "--automated --help --no-trunc --stars -s" -- "$cur" ) ) + COMPREPLY=( $( compgen -W "--filter --help --no-trunc" -- "$cur" ) ) ;; esac } diff --git a/contrib/completion/zsh/_docker b/contrib/completion/zsh/_docker index 5862768f..3e0f26d5 100644 --- a/contrib/completion/zsh/_docker +++ b/contrib/completion/zsh/_docker @@ -311,6 +311,30 @@ __docker_complete_ps_filters() { return ret } +__docker_complete_search_filters() { + [[ $PREFIX = -* ]] && return 1 + integer ret=1 + declare -a boolean_opts opts + + boolean_opts=('true' 'false') + opts=('is-automated' 'is-official' 'stars') + + if compset -P '*='; then + case "${${words[-1]%=*}#*=}" in + (is-automated|is-official) + _describe -t boolean-filter-opts "filter options" boolean_opts && ret=0 + ;; + *) + _message 'value' && ret=0 + ;; + esac + else + _describe -t filter-opts "filter options" opts -qS "=" && ret=0 + fi + + return ret +} + __docker_network_complete_ls_filters() { [[ $PREFIX = -* ]] && return 1 integer ret=1 @@ -1126,10 +1150,15 @@ __docker_subcommand() { (search) _arguments $(__docker_arguments) \ $opts_help \ - "($help)--automated[Only show automated builds]" \ + "($help)*"{-f=,--filter=}"[Filter values]:filter:->filter-options" \ "($help)--no-trunc[Do not truncate output]" \ - "($help -s --stars)"{-s=,--stars=}"[Only display with at least X stars]:stars:(0 10 100 1000)" \ "($help -):term: " && ret=0 + + case $state in + (filter-options) + __docker_complete_search_filters && ret=0 + ;; + esac ;; (start) _arguments $(__docker_arguments) \ diff --git a/docs/deprecated.md b/docs/deprecated.md index df871184..d80f24e7 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -58,6 +58,15 @@ defining it at container creation (`POST /containers/create`). The `docker ps --before` and `docker ps --since` options are deprecated. Use `docker ps --filter=before=...` and `docker ps --filter=since=...` instead. +### Docker search 'automated' and 'stars' options + +**Deprecated in Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)** + +**Removed In Release: v1.14** + +The `docker search --automated` and `docker search --stars` options are deprecated. +Use `docker search --filter=is-automated=...` and `docker search --filter=stars=...` instead. + ### Command line short variant options **Deprecated In Release: v1.9** diff --git a/docs/reference/commandline/search.md b/docs/reference/commandline/search.md index 893895e2..8bca98f0 100644 --- a/docs/reference/commandline/search.md +++ b/docs/reference/commandline/search.md @@ -14,10 +14,12 @@ parent = "smn_cli" Search the Docker Hub for images - --automated Only show automated builds + --filter=[] Filter output based on these conditions: + - is-automated=(true|false) + - is-official=(true|false) + - stars= - image has at least 'number' stars --help Print usage --no-trunc Don't truncate output - -s, --stars=0 Only displays with at least x stars Search [Docker Hub](https://hub.docker.com) for images @@ -61,29 +63,6 @@ This example displays images with a name containing 'busybox': scottabernethy/busybox 0 [OK] marclop/busybox-solr -### Search images by name and number of stars (-s, --stars) - -This example displays images with a name containing 'busybox' and at -least 3 stars: - - $ docker search --stars=3 busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - busybox Busybox base image. 325 [OK] - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] - - -### Search automated images (--automated) - -This example displays images with a name containing 'busybox', at -least 3 stars and are automated builds: - - $ docker search --stars=3 --automated busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] - - ### Display non-truncated description (--no-trunc) This example displays images with a name containing 'busybox', @@ -95,3 +74,48 @@ at least 3 stars and the description isn't truncated in the output: progrium/busybox 50 [OK] radial/busyboxplus Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors. 8 [OK] +## Filtering + +The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more +than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`) + +The currently supported filters are: + +* stars (int - number of stars the image has) +* is-automated (true|false) - is the image automated or not +* is-official (true|false) - is the image official or not + + +### stars + +This example displays images with a name containing 'busybox' and at +least 3 stars: + + $ docker search --filter stars=3 busybox + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + busybox Busybox base image. 325 [OK] + progrium/busybox 50 [OK] + radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] + + +### is-automated + +This example displays images with a name containing 'busybox' +and are automated builds: + + $ docker search --filter is-automated busybox + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + progrium/busybox 50 [OK] + radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] + +### is-official + +This example displays images with a name containing 'busybox', at least +3 stars and are official builds: + + $ docker search --filter "is-automated=true" --filter "stars=3" busybox + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + progrium/busybox 50 [OK] + radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] + + diff --git a/man/docker-search.1.md b/man/docker-search.1.md index a95c0237..c1728f54 100644 --- a/man/docker-search.1.md +++ b/man/docker-search.1.md @@ -6,10 +6,9 @@ docker-search - Search the Docker Hub for images # SYNOPSIS **docker search** -[**--automated**] +[**-f**|**--filter**[=*[]*]] [**--help**] [**--no-trunc**] -[**-s**|**--stars**[=*0*]] TERM # DESCRIPTION @@ -21,8 +20,12 @@ of stars awarded, whether the image is official, and whether it is automated. *Note* - Search queries will only return up to 25 results # OPTIONS -**--automated**=*true*|*false* - Only show automated builds. The default is *false*. + +**-f**, **--filter**=[] + Filter output based on these conditions: + - stars= + - is-automated=(true|false) + - is-official=(true|false) **--help** Print usage statement @@ -30,9 +33,6 @@ of stars awarded, whether the image is official, and whether it is automated. **--no-trunc**=*true*|*false* Don't truncate output. The default is *false*. -**-s**, **--stars**=*X* - Only displays with at least X stars. The default is zero. - # EXAMPLES ## Search Docker Hub for ranked images @@ -40,7 +40,7 @@ of stars awarded, whether the image is official, and whether it is automated. Search a registry for the term 'fedora' and only display those images ranked 3 or higher: - $ docker search -s 3 fedora + $ docker search --filter=stars=3 fedora NAME DESCRIPTION STARS OFFICIAL AUTOMATED mattdm/fedora A basic Fedora image corresponding roughly... 50 fedora (Semi) Official Fedora base image. 38 @@ -52,7 +52,7 @@ ranked 3 or higher: Search Docker Hub for the term 'fedora' and only display automated images ranked 1 or higher: - $ docker search --automated -s 1 fedora + $ docker search --filter=is-automated=true --filter=stars=1 fedora NAME DESCRIPTION STARS OFFICIAL AUTOMATED goldmann/wildfly A WildFly application server running on a ... 3 [OK] tutum/fedora-20 Fedora 20 image with SSH access. For the r... 1 [OK] @@ -62,4 +62,5 @@ April 2014, Originally compiled by William Henry (whenry at redhat dot com) based on docker.com source material and internal work. June 2014, updated by Sven Dowideit April 2015, updated by Mary Anthony for v2 +April 2016, updated by Vincent Demeester