Improve and fix bash completion for images

[albers]

Shortcomings of the current solution

Bash completion of images uses the vanilla output of docker images and filters it with awk.
This is error prone because users may customize the output of docker images by setting a go template in ~/.docker/config.json with the imagesFormat key.
And it is ugly.

There are several valid combinations of repository, tag and ID in Docker CLI. This diversity is not sufficiently covered yet, leading to issues like moby/moby#27791.

Furthermore, problems arise because completion of images is customizable through environment variables:

• The user may hide tags by setting DOCKER_COMPLETION_SHOW_TAGS=no.
• The user may choose the amount of image IDs shown in completion: DOCKER_COMPLETION_SHOW_IMAGE_IDS=none(default)|non-intermediate|all

These settings are not fine-grained enough, though.

• In cases where an exact image specification is required, e.g. docker history, we have to show tags even if the user opted to hide them.
• IDs are not legal in all image specifications.

Solution

• Use explicit formatting in docker images like in the completions of containers, networks, volumes... .
• Specify which of repository, tag and id are valid with arguments (--repo, --tag, --id) to one central completion function and let this function decide what to complete wrt environment settings.
• Create an override for cases where tags are required (--force-tag)

We now use the following combinations:
__docker_complete_images --force-tag --id
__docker_complete_images --repo
__docker_complete_images --repo --tag
__docker_complete_images --repo --tag --id

I prefer to leave the invocations as listed here instead of creating 4 helper functions because these would not increase readibility. The explicit list of legal choices very clearly expresses differences between related completetions, see images --filter (before|since)= and images --filter reference= for an example.

Fixes

• Fix bash completion of images when default tag does not exist moby/moby#27791 Fix bash completion of images when default tag does not exist
  For these cases, --repo is not used and --force-tags is applied. Only valid tags are completed.
• completion of image ls repo and image pull --all-tags repo failed for repository names containing a : (e.g. localhost:5000/some-repo)

Changes

Completion of image import now completes local files instead of nothing. The previous choice was made because URLs are also valid syntax. The result feels like a broken completion.

Some minor changes in style were applied in a separate commit in order to increase code consistency.

Testing

If you have bash completion installed and working, just source the updated completion script.
The main helper function can also be called directly to study the influence of the customizion via environment variables, e.g.

__docker_images --repo --tag --id
DOCKER_COMPLETION_SHOW_IMAGE_IDS=none __docker_images --repo --tag --id
DOCKER_COMPLETION_SHOW_IMAGE_IDS=non-intermediate __docker_images --repo --tag --id
DOCKER_COMPLETION_SHOW_TAGS=no __docker_images --force-tag

ping @mlaventure Fixes moby/moby#27791, PTAL

[codecov-io]

Codecov Report

Merging #717 into master will decrease coverage by 0.21%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #717      +/-   ##
==========================================
- Coverage   53.51%   53.29%   -0.22%     
==========================================
  Files         218      218              
  Lines       14565    14565              
==========================================
- Hits         7795     7763      -32     
- Misses       6289     6326      +37     
+ Partials      481      476       -5

[mdlinville]

This seems like it should be additive with --tag, like --tag --force or something like that.

[albers]

This won't work because it is not clear what should be forced. My intent is to use --repo, --tag and --id to express that a representation can be completed (if permitted by environment settings) and to use --force-repo, --force-tag and --force-id when a representation has to be added, regardless of environment settings. Of the latter, currently only --force-tag is used, so the other options from this set are not yet implemented.

[albers]

I also want to keep this function very simple. That's why it doesn't care about the order of the arguments. Thus, a --force is not deterministic. And I want the invocations to fit on one line, so I opted for the short names like --tag instead of something more exact like --try-tag or --allow-tag.
I think this simplicity is appropriate for this function because it is only used internally in the bash completion script.

[mdlinville]

nit: typo "appies" should be "applies"

[albers]

Oh yes, I'll change that. Thanks.

[vdemeester]

LGTM
cc @mlaventure

[mlaventure]

LGTM

[thaJeztah]

whoops forgot about this one LGTM, thanks!

[albers]

@thaJeztah Would you mind looking at #682? It's been hanging around even longer.