Filter args are inconsistent and poorly documented

[macdjord]

A number of Docker commands take --filter arguments, however the way these arguments work is radically inconsistent between the commands, and the documentation for them is insufficient in several ways. There are various tickets which discuss some of the issues, but I believe that the core issue is that the different filter arguments were implemented separately and grew organically individually over time; the only solution is to overhaul them all at once to provide a consistent interface using a shared codebase.

Problems include:

• image ls and image prune both take filter args, but accept different ones; similarly volume ls and volume prune
• The name= filter for ps accepts regexes. However, the documentation page doesn't actually explain this; instead it claims that the filter does substring matching.
  • Meanwhile, the reference= filter for image ls uses some sort of weird pattern-matching based on file-glob wildcards. The documentation for this is incomplete.
• The documentation page for volume prune says that it supports --filter, but doesn't explain what filters it supports
• image prune accepts the until filter, which matches images older than a given timestamp. image ls and ps also have an 'older than' filter, only its called 'before' and instead of taking a timestamp, it takes the name of another image or container whose creation time it used as the reference point.
• image prune supports negative filtering for labels. No other command or filter type supports negative filtering.
• None of the documentation for any of the commands specifies how multiple filters are combined. AFAICT, multiple filters of the same type get ORed, while filters of different types get ANDed... except that if you specify multiple 'label' filters, they must all match.

The whole system should be revamped as follows:

• image ls and image prune should support exactly the same filters with exactly the same semantics; similarly volume ls and volume prune
  • This simplifies documentation, since the 'filters' section on the doc pages for image prune and volume prune can simply link to the 'filters' section on the corresponding ls command
  • It also allows the ls commands to be used as a half-assed 'dry run' for the prune commands. (Half-assed because the ls commands' output will still include images/volumes that are in use.)
• ps, image ls, and volume ls will obviously support different sets of filter args - you can't search for an image by its run state, obviously - but where they share filters types, the filters should use the same names and have the same semantics
• All filters that involve a time should accept a timestamp. Also accepting container/image name to use as a comparative is nice but optional, but either all of them should support that or none of them should.
• All filters should be negatable.
• All filters should either be exact-match only or support a full regex - no wildcard glob-matching. Documentation should specify which one each filter type is.
• Documentation should be updated to specify the semantics of multiple filters.

Related issues:

• 3027

• 833

• 3654

• 1332

• 739

• 625

[ndeloof]

Agree. --filter is one of the worst part of the docker UX. Better documentation (at least) and better consistency would be a nice enhancement

[victor-timofei]

Agree, I would also want this to be documented either in the manpages or in the --help, or maybe both.

[maques1]

An additional "observation" on this inconsistent behavior:

docker volume ls --filter dangling=true --filter name="f464107006296e7623ed30aa1c4c66f0f7384e5398c59fae684be7e25b9d7d82"
DRIVER    VOLUME NAME
local     f464107006296e7623ed30aa1c4c66f0f7384e5398c59fae684be7e25b9d7d82

docker volume prune --filter dangling=true --filter name="f464107006296e7623ed30aa1c4c66f0f7384e5398c59fae684be7e25b9d7d82"
WARNING! This will remove all local volumes not used by at least one container.
Are you sure you want to continue? [y/N] y
Error response from daemon: Invalid filter 'dangling'

So "--filter" (even combined ones) works for volume ls, also volume prune accepts it and asks for confirmation, then bails out with the "Invalid filter" error, not even complaining for the "--filter" option, but the "filter" value (though it doesn't seem to accept any other filter value as well). The result is the same even if just one filter (name or dangling state) specified.