@@ -22,7 +22,7 @@ import (

 //

 // Usage: docker images [OPTIONS] [REPOSITORY]

 func (cli *DockerCli) CmdImages(args ...string) error {

-	cmd := Cli.Subcmd("images", []string{"[REPOSITORY]"}, "List images", true)

+	cmd := Cli.Subcmd("images", []string{"[REPOSITORY[:TAG]]"}, "List images", true)

 	quiet := cmd.Bool([]string{"q", "-quiet"}, false, "Only show numeric IDs")

 	all := cmd.Bool([]string{"a", "-all"}, false, "Show all images (default hides intermediate images)")

 	noTrunc := cmd.Bool([]string{"#notrunc", "-no-trunc"}, false, "Don't truncate output")

@@ -11,7 +11,7 @@ weight=1

 # images

-    Usage: docker images [OPTIONS] [REPOSITORY]

+    Usage: docker images [OPTIONS] [REPOSITORY[:TAG]]

     List images

@@ -52,6 +52,36 @@ uses up the `VIRTUAL SIZE` listed only once.

     postgres                  9.3.5               746b819f315e        4 days ago          213.4 MB

     postgres                  latest              746b819f315e        4 days ago          213.4 MB

+### Listing 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 this command :

+

+    $ docker images java

+    REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL 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:

+

+    $ docker images java:8

+    REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE

+    java                8                   308e519aac60        6 days ago          824.5 MB

+

+If nothing matches `REPOSITORY[:TAG]`, the list is empty.

+

+    $ docker images java:0

+    REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE

 ## Listing the full length image IDs

@@ -68,13 +68,29 @@ func (s *TagStore) Images(filterArgs, filter string, all bool) ([]*types.Image,

 	lookup := make(map[string]*types.Image)

 	s.Lock()

 	for repoName, repository := range s.Repositories {

+		filterTagName := ""

 		if filter != "" {

-			if match, _ := path.Match(filter, repoName); !match {

+			filterName := filter

+			// Test if the tag was in there, if yes, get the name

+			if strings.Contains(filterName, ":") {

+				filterWithTag := strings.Split(filter, ":")

+				filterName = filterWithTag[0]

+				filterTagName = filterWithTag[1]

+			}

+			if match, _ := path.Match(filterName, repoName); !match {

 				continue

 			}

+			if filterTagName != "" {

+				if _, ok := repository[filterTagName]; !ok {

+					continue

+				}

+			}

 		}

 		for ref, id := range repository {

 			imgRef := utils.ImageReference(repoName, ref)

+			if !strings.Contains(imgRef, filterTagName) {

+				continue

+			}

 			image, err := s.graph.Get(id)

 			if err != nil {

 				logrus.Warnf("couldn't load %s from %s: %s", id, imgRef, err)

@@ -18,6 +18,39 @@ func (s *DockerSuite) TestImagesEnsureImageIsListed(c *check.C) {

 	}

 }

+func (s *DockerSuite) TestImagesEnsureImageWithTagIsListed(c *check.C) {

+	_, err := buildImage("imagewithtag:v1",

+		`FROM scratch

+		MAINTAINER dockerio1`, true)

+	c.Assert(err, check.IsNil)

+

+	_, err = buildImage("imagewithtag:v2",

+		`FROM scratch

+		MAINTAINER dockerio1`, true)

+	c.Assert(err, check.IsNil)

+

+	out, _ := dockerCmd(c, "images", "imagewithtag:v1")

+

+	if !strings.Contains(out, "imagewithtag") || !strings.Contains(out, "v1") || strings.Contains(out, "v2") {

+		c.Fatal("images should've listed imagewithtag:v1 and not imagewithtag:v2")

+	}

+

+	out, _ = dockerCmd(c, "images", "imagewithtag")

+

+	if !strings.Contains(out, "imagewithtag") || !strings.Contains(out, "v1") || !strings.Contains(out, "v2") {

+		c.Fatal("images should've listed imagewithtag:v1 and imagewithtag:v2")

+	}

+}

+

+func (s *DockerSuite) TestImagesEnsureImageWithBadTagIsNotListed(c *check.C) {

+	out, _ := dockerCmd(c, "images", "busybox:nonexistent")

+

+	if strings.Contains(out, "busybox") {

+		c.Fatal("images should not have listed busybox")

+	}

+

+}

+

 func (s *DockerSuite) TestImagesOrderedByCreationDate(c *check.C) {

 	id1, err := buildImage("order:test_a",

 		`FROM scratch

@@ -12,7 +12,7 @@ docker-images - List images

 [**-f**|**--filter**[=*[]*]]

 [**--no-trunc**[=*false*]]

 [**-q**|**--quiet**[=*false*]]

-[REPOSITORY]

+[REPOSITORY[:TAG]]

 # DESCRIPTION

 This command lists the images stored in the local Docker repository.

@@ -61,6 +61,22 @@ The list will contain the image repository name, a tag for the image, and an

 image ID, when it was created and its virtual size. Columns: REPOSITORY, TAG,

 IMAGE ID, CREATED, and VIRTUAL SIZE.

+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.

+

+    docker images java

+

+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:

+

+    docker images java:8

+

 To get a verbose list of images which contains all the intermediate images

 used in builds use **-a**: