docker / docker/cli

Filter args are inconsistent and poorly documented

Open
#3,696 3 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area/ux kind/docs kind/enhancement
Dominant language
Go
Stars
6.1k
Forks
2.2k
Avg merge
1d 15h
Merged PRs (30d)
43

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the Docker CLI implementations and documentation for ps, image ls, image prune, volume ls, and volume prune, along with related issues #3027, #833, #3654, #1332, #739, and #625. Map their current filter names, matching rules, negation behavior, and combination semantics before deciding how a shared implementation and consistent documentation could be evaluated.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, go
Domain
cli, documentation
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.