Re-implement --before and --since as options for --filter

* This commit will mark --before and --since as deprecated, but leave their behavior
  unchanged until they are removed, then re-implement them as options for --filter.

* And update the related docs.

* Update the integration tests.

Fixes issue #17716

Signed-off-by: Wen Cheng Ma <wenchma@cn.ibm.com>

api/client/ps.go

@@ -28,10 +28,10 @@ func (cli *DockerCli) CmdPs(args ...string) error {
 		size     = cmd.Bool([]string{"s", "-size"}, false, "Display total file sizes")
 		all      = cmd.Bool([]string{"a", "-all"}, false, "Show all containers (default shows just running)")
 		noTrunc  = cmd.Bool([]string{"-no-trunc"}, false, "Don't truncate output")
-		nLatest  = cmd.Bool([]string{"l", "-latest"}, false, "Show the latest created container, include non-running")
-		since    = cmd.String([]string{"-since"}, "", "Show created since Id or Name, include non-running")
-		before   = cmd.String([]string{"-before"}, "", "Show only container created before Id or Name")
-		last     = cmd.Int([]string{"n"}, -1, "Show n last created containers, include non-running")
+		nLatest  = cmd.Bool([]string{"l", "-latest"}, false, "Show the latest created container (includes all states)")
+		since    = cmd.String([]string{"#-since"}, "", "Show containers created since Id or Name (includes all states)")
+		before   = cmd.String([]string{"#-before"}, "", "Only show containers created before Id or Name")
+		last     = cmd.Int([]string{"n"}, -1, "Show n last created containers (includes all states)")
 		format   = cmd.String([]string{"-format"}, "", "Pretty-print containers using a Go template")
 		flFilter = opts.NewListOpts(nil)
 	)

daemon/list.go

@@ -71,10 +71,12 @@ type listContext struct {
 	filters filters.Args
 	// exitAllowed is a list of exit codes allowed to filter with
 	exitAllowed []int
-	// beforeContainer is a filter to ignore containers that appear before the one given
-	beforeContainer *Container
-	// sinceContainer is a filter to stop the filtering when the iterator arrive to the given container
-	sinceContainer *Container
+	// beforeFilter is a filter to ignore containers that appear before the one given
+	// this is used for --filter=before= and --before=, the latter is deprecated.
+	beforeFilter *Container
+	// sinceFilter is a filter to stop the filtering when the iterator arrive to the given container
+	// this is used for --filter=since= and --since=, the latter is deprecated.
+	sinceFilter *Container
 	// ContainersConfig is the filters set by the user
 	*ContainersConfig
 }
@@ -155,6 +157,25 @@ func (daemon *Daemon) foldFilter(config *ContainersConfig) (*listContext, error)
 		}
 	}
 
+	var beforeContFilter, sinceContFilter *Container
+	if i, ok := psFilters["before"]; ok {
+		for _, value := range i {
+			beforeContFilter, err = daemon.Get(value)
+			if err != nil {
+				return nil, err
+			}
+		}
+	}
+
+	if i, ok := psFilters["since"]; ok {
+		for _, value := range i {
+			sinceContFilter, err = daemon.Get(value)
+			if err != nil {
+				return nil, err
+			}
+		}
+	}
+
 	imagesFilter := map[string]bool{}
 	var ancestorFilter bool
 	if ancestors, ok := psFilters["ancestor"]; ok {
@@ -183,16 +204,15 @@ func (daemon *Daemon) foldFilter(config *ContainersConfig) (*listContext, error)
 		return nil
 	}, 1)
 
-	var beforeCont, sinceCont *Container
 	if config.Before != "" {
-		beforeCont, err = daemon.Get(config.Before)
+		beforeContFilter, err = daemon.Get(config.Before)
 		if err != nil {
 			return nil, err
 		}
 	}
 
 	if config.Since != "" {
-		sinceCont, err = daemon.Get(config.Since)
+		sinceContFilter, err = daemon.Get(config.Since)
 		if err != nil {
 			return nil, err
 		}
@@ -204,8 +224,8 @@ func (daemon *Daemon) foldFilter(config *ContainersConfig) (*listContext, error)
 		names:            names,
 		images:           imagesFilter,
 		exitAllowed:      filtExited,
-		beforeContainer:  beforeCont,
-		sinceContainer:   sinceCont,
+		beforeFilter:     beforeContFilter,
+		sinceFilter:      sinceContFilter,
 		ContainersConfig: config,
 	}, nil
 }
@@ -214,7 +234,7 @@ func (daemon *Daemon) foldFilter(config *ContainersConfig) (*listContext, error)
 // It also decides if the iteration should be stopped or not.
 func includeContainerInList(container *Container, ctx *listContext) iterationAction {
 	// Do not include container if it's stopped and we're not filters
-	if !container.Running && !ctx.All && ctx.Limit <= 0 && ctx.beforeContainer == nil && ctx.sinceContainer == nil {
+	if !container.Running && !ctx.All && ctx.Limit <= 0 && ctx.beforeFilter == nil && ctx.sinceFilter == nil {
 		return excludeContainer
 	}
 
@@ -240,25 +260,25 @@ func includeContainerInList(container *Container, ctx *listContext) iterationAct
 
 	// Do not include container if it's in the list before the filter container.
 	// Set the filter container to nil to include the rest of containers after this one.
-	if ctx.beforeContainer != nil {
-		if container.ID == ctx.beforeContainer.ID {
-			ctx.beforeContainer = nil
+	if ctx.beforeFilter != nil {
+		if container.ID == ctx.beforeFilter.ID {
+			ctx.beforeFilter = nil
 		}
 		return excludeContainer
 	}
 
-	// Stop iteration when the index is over the limit
-	if ctx.Limit > 0 && ctx.idx == ctx.Limit {
-		return stopIteration
-	}
-
 	// Stop interation when the container arrives to the filter container
-	if ctx.sinceContainer != nil {
-		if container.ID == ctx.sinceContainer.ID {
+	if ctx.sinceFilter != nil {
+		if container.ID == ctx.sinceFilter.ID {
 			return stopIteration
 		}
 	}
 
+	// Stop iteration when the index is over the limit
+	if ctx.Limit > 0 && ctx.idx == ctx.Limit {
+		return stopIteration
+	}
+
 	// Do not include container if its exit code is not in the filter
 	if len(ctx.exitAllowed) > 0 {
 		shouldSkip := true

docs/misc/deprecated.md

@@ -12,6 +12,15 @@ parent = "mn_use_docker"
 
 The following list of features are deprecated.
 
+### Docker ps 'before' and 'since' options
+
+**Deprecated In Release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**
+
+**Target For Removal In Release: v1.12**
+
+The `docker ps --before` and `docker ps --since` options are deprecated.
+Use `docker ps --filter=before=...` and `docker ps --filter=since=...` instead.
+
 ### Command line short variant options
 **Deprecated In Release: v1.9**
 

docs/reference/commandline/ps.md

@@ -15,16 +15,14 @@ parent = "smn_cli"
     List containers
 
       -a, --all=false       Show all containers (default shows just running)
-      --before=""           Show only container created before Id or Name
       -f, --filter=[]       Filter output based on conditions provided
       --format=[]           Pretty-print containers using a Go template
       --help=false          Print usage
-      -l, --latest=false    Show the latest created container, include non-running
-      -n=-1                 Show n last created containers, include non-running
+      -l, --latest=false    Show the latest created container (includes all states)
+      -n=-1                 Show n last created containers (includes all states)
       --no-trunc=false      Don't truncate output
       -q, --quiet=false     Only display numeric IDs
       -s, --size=false      Display total file sizes
-      --since=""            Show created since Id or Name, include non-running
 
 Running `docker ps --no-trunc` showing 2 linked containers.
 

integration-cli/docker_cli_ps_test.go

@@ -58,52 +58,53 @@ func (s *DockerSuite) TestPsListContainersBase(c *check.C) {
 	out, _ = dockerCmd(c, "ps", "-n=2")
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("LIMIT: Container list is not in the correct order: \n%s", out))
 
-	// since
-	out, _ = dockerCmd(c, "ps", "--since", firstID, "-a")
+	// filter since
+	out, _ = dockerCmd(c, "ps", "-f", "since="+firstID, "-a")
 	expected = []string{fourthID, thirdID, secondID}
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("SINCE & ALL: Container list is not in the correct order: \n%s", out))
 
-	out, _ = dockerCmd(c, "ps", "--since", firstID)
+	out, _ = dockerCmd(c, "ps", "-f", "since="+firstID)
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("SINCE: Container list is not in the correct order: \n%s", out))
 
-	// before
-	out, _ = dockerCmd(c, "ps", "--before", thirdID, "-a")
+	// filter before
+	out, _ = dockerCmd(c, "ps", "-f", "before="+thirdID, "-a")
 	expected = []string{secondID, firstID}
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("BEFORE & ALL: Container list is not in the correct order: \n%s", out))
 
-	out, _ = dockerCmd(c, "ps", "--before", thirdID)
+	out, _ = dockerCmd(c, "ps", "-f", "before="+thirdID)
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("BEFORE: Container list is not in the correct order: \n%s", out))
 
-	// since & before
-	out, _ = dockerCmd(c, "ps", "--since", firstID, "--before", fourthID, "-a")
+	// filter since & before
+	out, _ = dockerCmd(c, "ps", "-f", "since="+firstID, "-f", "before="+fourthID, "-a")
 	expected = []string{thirdID, secondID}
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("SINCE, BEFORE & ALL: Container list is not in the correct order: \n%s", out))
 
-	out, _ = dockerCmd(c, "ps", "--since", firstID, "--before", fourthID)
+	out, _ = dockerCmd(c, "ps", "-f", "since="+firstID, "-f", "before="+fourthID)
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("SINCE, BEFORE: Container list is not in the correct order: \n%s", out))
 
-	// since & limit
-	out, _ = dockerCmd(c, "ps", "--since", firstID, "-n=2", "-a")
+	// filter since & limit
+	out, _ = dockerCmd(c, "ps", "-f", "since="+firstID, "-n=2", "-a")
 	expected = []string{fourthID, thirdID}
 
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("SINCE, LIMIT & ALL: Container list is not in the correct order: \n%s", out))
 
-	out, _ = dockerCmd(c, "ps", "--since", firstID, "-n=2")
+	out, _ = dockerCmd(c, "ps", "-f", "since="+firstID, "-n=2")
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("SINCE, LIMIT: Container list is not in the correct order: \n%s", out))
 
-	// before & limit
-	out, _ = dockerCmd(c, "ps", "--before", fourthID, "-n=1", "-a")
+	// filter before & limit
+	out, _ = dockerCmd(c, "ps", "-f", "before="+fourthID, "-n=1", "-a")
 	expected = []string{thirdID}
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("BEFORE, LIMIT & ALL: Container list is not in the correct order: \n%s", out))
 
-	out, _ = dockerCmd(c, "ps", "--before", fourthID, "-n=1")
+	out, _ = dockerCmd(c, "ps", "-f", "before="+fourthID, "-n=1")
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("BEFORE, LIMIT: Container list is not in the correct order: \n%s", out))
 
-	out, _ = dockerCmd(c, "ps", "--since", firstID, "--before", fourthID, "-n=1", "-a")
+	// filter since & filter before & limit
+	out, _ = dockerCmd(c, "ps", "-f", "since="+firstID, "-f", "before="+fourthID, "-n=1", "-a")
 	expected = []string{thirdID}
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("SINCE, BEFORE, LIMIT & ALL: Container list is not in the correct order: \n%s", out))
 
-	out, _ = dockerCmd(c, "ps", "--since", firstID, "--before", fourthID, "-n=1")
+	out, _ = dockerCmd(c, "ps", "-f", "since="+firstID, "-f", "before="+fourthID, "-n=1")
 	c.Assert(assertContainerList(out, expected), checker.Equals, true, check.Commentf("SINCE, BEFORE, LIMIT: Container list is not in the correct order: \n%s", out))
 
 }

man/docker-ps.1.md

@@ -7,7 +7,6 @@ docker-ps - List containers
 # SYNOPSIS
 **docker ps**
 [**-a**|**--all**[=*false*]]
-[**--before**[=*BEFORE*]]
 [**-f**|**--filter**[=*[]*]]
 [**--format**=*"TEMPLATE"*]
 [**--help**]
@@ -16,7 +15,6 @@ docker-ps - List containers
 [**--no-trunc**[=*false*]]
 [**-q**|**--quiet**[=*false*]]
 [**-s**|**--size**[=*false*]]
-[**--since**[=*SINCE*]]
 
 # DESCRIPTION
 
@@ -27,9 +25,6 @@ the running containers.
 **-a**, **--all**=*true*|*false*
    Show all containers. Only running containers are shown by default. The default is *false*.
 
-**--before**=""
-   Show only containers created before Id or Name, including non-running containers.
-
 **-f**, **--filter**=[]
    Provide filter values. Valid filters:
                           exited=<int> - containers with exit code of <int>
@@ -37,6 +32,8 @@ the running containers.
                           status=(created|restarting|running|paused|exited)
                           name=<string> - container's name
                           id=<ID> - container's ID
+                          before=(<container-name>|<container-id>)
+                          since=(<container-name>|<container-id>)
                           ancestor=(<image-name>[:tag]|<image-id>|<image@digest>) - filters containers that were
                           created from the given image or a descendant.
 
@@ -58,10 +55,10 @@ the running containers.
   Print usage statement
 
 **-l**, **--latest**=*true*|*false*
-   Show only the latest created container, include non-running ones. The default is *false*.
+   Show only the latest created container (includes all states). The default is *false*.
 
 **-n**=*-1*
-   Show n last created containers, include non-running ones.
+   Show n last created containers (includes all states).
 
 **--no-trunc**=*true*|*false*
    Don't truncate output. The default is *false*.
@@ -72,9 +69,6 @@ the running containers.
 **-s**, **--size**=*true*|*false*
    Display total file sizes. The default is *false*.
 
-**--since**=""
-   Show only containers created since Id or Name, include non-running ones.
-
 # EXAMPLES
 # Display all containers, including non-running