image/list: Add --tree flag

[vvoland]

• needs: c8d: Multi-platform image list moby/moby#47526
• needs: vendor: github.com/docker/docker master (f3cf9359bdf6) #5330
• needs: api/image/list: Add container-count parameter moby/moby#47501
• relates to UX: improve / design UX for multi-arch images moby/moby#44582

Add --tree flag to docker image list

Update:
Added some spacing around images:

- Description for the changelog

- containerd image store: `docker image ls` now supports `--tree` flag that shows a multiplatform-aware image list. This is experimental and may change at any time without any backwards compatibility.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 1.49254% with 198 lines in your changes missing coverage. Please review.

Project coverage is 60.94%. Comparing base (bbce5a0) to head (a9b78da).
Report is 29 commits behind head on master.

Additional details and impacted files

@@ Coverage Diff @@## master #4982 +/- ##
==========================================
- Coverage 61.51% 60.94% -0.57% 
==========================================
Files 303 304 +1 Lines 21130 21331 +201 ==========================================
+ Hits 12998 13001 +3 - Misses 7203 7400 +197 - Partials 929 930 +1 

[vvoland]

Needs: moby/moby#47501

[thaJeztah]

I think we have the per-image list of containers now, correct? In that case; do we still need that PR? I was always a slight bit on the fence on that one, as only a number of containers didn't provide a ton of useful information.

[vvoland]

We have, but it's only filled if the ContainerCount option is set (we can still change that though).

[vvoland]

Should I remove the Usage column for now?

[vvoland]

Combined multiple images with the same target under one entry:

tree.mp4

cc @jalonsogo

[Benehiko]

LGTM 👍

[thaJeztah]

OK; one more thing I noticed (but maybe something to also fix on the daemon side not sure?) is the order in which variants are shown;

Output with only arm64;

docker image ls --tree
Image ID Disk usage Content size Used
alpine:latest 0a4eaa0eecf5 13.6MB 4.09MB
├─ linux/arm64/v8 24ba417e25e7 13.6MB 4.09MB
├─ linux/amd64 eddacbc7e24b 0B 0B
├─ linux/arm/v6 5c7e326e3c8a 0B 0B
├─ linux/arm/v7 fda9b1b812b2 0B 0B
├─ linux/386 fa66aa594ffa 0B 0B
├─ linux/ppc64le a01843eb870e 0B 0B
├─ linux/riscv64 e99a4d9aa9f9 0B 0B
└─ linux/s390x 14da06d3a895 0B 0B

Pull s390x;

docker image pull --platform=linux/s390x alpine

New output;

docker image ls --tree
Image ID Disk usage Content size Used
alpine:latest 0a4eaa0eecf5 25.5MB 7.55MB
├─ linux/s390x 14da06d3a895 11.9MB 3.46MB
├─ linux/arm64/v8 24ba417e25e7 13.6MB 4.09MB
├─ linux/amd64 eddacbc7e24b 0B 0B
├─ linux/arm/v6 5c7e326e3c8a 0B 0B
├─ linux/arm/v7 fda9b1b812b2 0B 0B
├─ linux/386 fa66aa594ffa 0B 0B
├─ linux/ppc64le a01843eb870e 0B 0B
└─ linux/riscv64 e99a4d9aa9f9 0B 0B

I wondered where the sort-order is based on; perhaps sorting is happening on "Created" date, but it looks like we omit that in the new view;

docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
docker-dev latest e1ca8a3ea183 6 hours ago 2.2GB
localhost:5001/owner/name latest 0fea7086b9c0 8 hours ago 17.2MB
docker-cli-dev latest 88c125e27aee 3 days ago 749MB
golang 1.22 2bd56f00ff47 8 days ago 1.21GB
moby/buildkit buildx-stable-1 0a5641c72659 3 weeks ago 298MB
docker dind a69069397655 3 weeks ago 491MB
alpine latest 0a4eaa0eecf5 3 weeks ago 25.7MB
registry 3.0.0-beta.1 efb271da5cd0 5 weeks ago 61.8MB
nginx alpine 208b70eefac1 7 weeks ago 68.4MB
registry 2 12120425f07d 10 months ago 36.1MB
docker 20.10-cli 2967f0819c84 15 months ago 209MB
registry 2.7 169211e20e2f 2 years ago 35.4MB
registry 2.6 c4bdca23bab1 4 years ago 38.5MB

Maybe we should

• have the variants sorted by the first column
• the overall list of images could still be (as default) sorted by created date
• ☝️ that order can sometimes be relevant (e.g. cut the last X images)
• ☝️ BUT also admitted that "created" date may be different with containerd (IIRC it uses the "local" date the image was added, not when the image was built not sure?)
• ☝️ Even if it shows the "created" date ("built" date); reproducible builds make that ... less useful (1-1-1970 or something along those lines 😂)

Final thought; some what related to moby/moby#48264 (comment) - wondering if we should have --all (or some equivalent) to control whether "non available" variants should be shown / hidden.

• It's good to have the option to show all variants of the image (including those "not present")
• At the same time, it makes the list really long, and sometimes you may only want to see "what's present"
• ☝️ for that we'd have to decide on a default

[vvoland]

Variants are sorted by the "availability" so that present variants are always on top.
Added sorting the top level images by the created (like the regular list does). Not showing it though for now.
I think we can revisit sorting and all to show the unavailable platform in a follow-up.

[vvoland]

Also, wondering if we need an additional warning like:

[thaJeztah]

I forgot now; did we also add the list of container-id's that used it somewhere? (Maybe not to be printed by default for sure)

[vvoland]

Yes, the ImageData has a list of containers. It's only available in the manifest summary though.
Also, see: #4982 (comment)

[krissetto]

i agree with @laurazard that maybe some things could be refactored, but looks like a good start to me :)

One design consideration though: I tend to think that some whitespace could go a long way in making the output easier to parse (since this is for humans more than for machines, right?). For example when using the command a couple times i find it hard to visually parse the beginning of the output from the command that the user typed, and also to read the column titles from the image names listed since they're all back to back (and title+first image name are both bold).

Maybe to separate column titles from the column contents they could:

• have some whitespace around them, separating them from contents and the command the user typed;
• be a different color;
• have a line under them like an old school table;

Just throwing some thoughts out there. WDYT here @jalonsogo? Maybe some discussions have already been made around this, if so feel free to ignore this comment :)

Given the experimental nature, we can definitely iterate on these things. It'd also be nice to consolidate our design and usage of columns/tables etc amongst all our other commands as well

This command has nice (imho) whitespace in it's output, for example

[vvoland]

Initially there was a newline between header and the first item, but removed it after a small discussion here: #4982 (comment)

Regarding the newline before the command content.. I think it might work:

[vvoland]

Removed the Used column for now, as it won't be populated correctly without moby/moby#47501

EDIT: Also an alternative PR that allows the Used column to work: moby/moby#48345
EDIT2: moby/moby#48345 got merged so restored the Used column

[jalonsogo]

In the CLI design guidelines, I recommend using capitalization+bold for the headers.
Also, in my designs, I use them in combination with colors:

• Bright White \u001b[37m;1m for the primary chunks of information
• Write-default \u001b[37m for the secondary chucks of information

[vvoland]

Restored the new-line and capitalized column headers: