Filter args are inconsistent and poorly documented
Nobody has claimed this yet.
- 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 lsandimage pruneboth take filter args, but accept different ones; similarlyvolume lsandvolume prune- The
name=filter forpsaccepts regexes. However, the documentation page doesn't actually explain this; instead it claims that the filter does substring matching.- Meanwhile, the
reference=filter forimage lsuses some sort of weird pattern-matching based on file-glob wildcards. The documentation for this is incomplete.
- Meanwhile, the
- The documentation page for
volume prunesays that it supports--filter, but doesn't explain what filters it supports image pruneaccepts theuntilfilter, which matches images older than a given timestamp.image lsandpsalso 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 prunesupports 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 lsandimage pruneshould support exactly the same filters with exactly the same semantics; similarlyvolume lsandvolume prune- This simplifies documentation, since the 'filters' section on the doc pages for
image pruneandvolume prunecan simply link to the 'filters' section on the correspondinglscommand - It also allows the
lscommands to be used as a half-assed 'dry run' for theprunecommands. (Half-assed because thelscommands' output will still include images/volumes that are in use.)
- This simplifies documentation, since the 'filters' section on the doc pages for
ps,image ls, andvolume lswill 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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