Please add documentation for docker and docker compose shell completions

benatshippabo commented 1 year ago

Problem description

Please add documentation for docker and docker compose shell completions. Currently, searching for completions only brings up the deprecated docker app completions.

There is an ongoing issue about the completion command being implemented, but not being available for users.

Are we supposed to curl from cli/contrib/completion/zsh/ for docker cli and compose/contrib/completion/zsh/ even though it's only for docker compose v1?

Are we supposed to use the docker completion and docker compose completion commands even though they aren't exposed?

I believe not having any documentation or guidance is confusing many users

Problem location

I saw a problem at the following URL: https://docs.docker.com/engine/reference/commandline/app_completion/
I couldn't find the information I wanted. I expected to find it near the following URL
- https://docs.docker.com/compose/reference/
- https://docs.docker.com/engine/reference/commandline/docker/
Other: please offer some guidance to the end user on the proper method to obtain shell completions for bash, zsh, fish, etc

Project version(s) affected

Docker version 20.10.21, build baeda1f Docker Compose version v2.13.0

Suggestions for a fix

Please offer some guidance to the end user on the proper method to obtain shell completions for bash, zsh, fish, etc

Many commands such as kubectl and helm offer very clear guidance on generating, obtaining, and configuring shell completions in their documentation

powerman commented 1 year ago

To me docker completion zsh > ~/.zsh/completions/_docker (using 23.0.1) does the trick.

layoaster commented 1 year ago

@powerman that completions work for the parent command (docker) but we are still without completions for the compose plugin

powerman commented 1 year ago

@powerman that completions work for the parent command (docker) but we are still without completions for the compose plugin

Not sure what you mean. Issue you referenced is closed as completed 6 months ago, as of today completion for the compose plugin works - at least using workaround in my previous comment.

layoaster commented 1 year ago

@powerman pressing TAB after this command docker compose does not produce any completions/suggestions.

I have ubuntu with zsh and omzh.
I previously created completions for docker with docker completion zsh > .oh-my-zsh/completions/_docker
the completion command for compose is not available docker compose completion
Docker version 23.0.2
Docker Compose version v2.17.2

powerman commented 1 year ago

Well, for me it works, so you probably doing something wrong. Maybe you need to run that command once again to update completions or reload zsh.

# lsb_release -d
Description:    Ubuntu 22.04.2 LTS
# docker version -f '{{.Client.Version}}'
23.0.1
# docker compose version
Docker Compose version v2.16.0
# docker compose <Tab>
 -- completions --
build    -- Build or rebuild services
config   -- Parse, resolve and render compose file in canonical format
cp       -- Copy files/folders between a service container and the local filesystem
create   -- Creates containers for a service.
down     -- Stop and remove containers, networks
events   -- Receive real time events from containers.
exec     -- Execute a command in a running container.
images   -- List images used by the created containers
kill     -- Force stop service containers.
logs     -- View output from containers
ls       -- List running compose projects
pause    -- Pause services
port     -- Print the public port for a port binding.
ps       -- List containers
pull     -- Pull service images
push     -- Push service images
restart  -- Restart service containers
rm       -- Removes stopped service containers
run      -- Run a one-off command on a service.
start    -- Start services
stop     -- Stop services
top      -- Display the running processes
unpause  -- Unpause services
up       -- Create and start containers
version  -- Show the Docker Compose version information

layoaster commented 1 year ago

this is weird, still not working

I downgraded to match your versions (except Ubuntu) @powerman

# lsb_release -d
Description:    Ubuntu 22.10
# docker version -f '{{.Client.Version}}'
23.0.1
# docker compose version
Docker Compose version v2.16.0

Regenerated completions to with docker completion zsh > ~/.zsh/completions/_docker.
removed rm .zcompdump* which usually messes with completions
Reloaded but docker compose <Tab> still doesn't work

powerman commented 1 year ago

I don't think this is the right place to debug your issue, because it looks like it's related mostly to your zsh setup than to docker completions. If you like to you can try my zsh setup: https://github.com/powerman/flazsh.

docker-robot[bot] commented 1 year ago

There hasn't been any activity on this issue for a long time. If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment. If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

benatshippabo commented 1 year ago

/remove-lifecycle stale

jbigler commented 1 year ago

I was having a similar issue with my docker compose completion with zsh on Arch Linux. The problem was being caused by the docker completion file being installed by the package manager. When I replaced /usr/share/zsh/site-functions/_docker with the output of the docker completion zsh command everything started working. So for me it is an issue I will take up with the Arch Linux packager.

layoaster commented 1 year ago

@jbigler This was definitely my issue's root cause except that in Ubuntu/Debian these outdated completions are installed in /usr/share/zsh/vendor-completions/_docker.

Seem like cli/contrib/completion/zsh/ must be updated or package builders omit it.

jbigler commented 1 year ago

I believe it is also an issue of documentation, as you mention in the main issue. I can't find official documentation for the docker completion <shell> command, so package maintainers might not know about it. I think if @powerman hadn't mentioned it then I wouldn't have known about it. It also doesn't show up as a command in docker help, though docker completion help does show the supported shells.

benatshippabo commented 1 year ago

I believe it is also an issue of documentation, as you mention in the main issue. I can't find official documentation for the docker completion <shell> command, so package maintainers might not know about it. I think if @powerman hadn't mentioned it then I wouldn't have known about it. It also doesn't show up as a command in docker help, though docker completion help does show the supported shells.

💯 totally agree that the completion command should be documented

FeryET commented 11 months ago

I was having a similar issue with my docker compose completion with zsh on Arch Linux. The problem was being caused by the docker completion file being installed by the package manager. When I replaced /usr/share/zsh/site-functions/_docker with the output of the docker completion zsh command everything started working. So for me it is an issue I will take up with the Arch Linux packager. @jbigler This was definitely my issue's root cause except that in Ubuntu/Debian these outdated completions are installed in /usr/share/zsh/vendor-completions/_docker.

Seem like cli/contrib/completion/zsh/ must be updated or package builders omit it.

I removed /usr/share/zsh/vendor-completions/_docker and used the completions installed in my oh-my-zsh plugins dir by using zsh-completions and now its working. Thanks!

Btw I'm using docker-rootless so it will probably not cause any problems since I won't use docker as a root user.

docker-robot[bot] commented 8 months ago

There hasn't been any activity on this issue for a long time. If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment. If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

benatshippabo commented 8 months ago

/remove-lifecycle stale

benatshippabo commented 8 months ago

There is now documentation in the mac installation faq page, but none exists for linux users.

The methods in this thread definitely work properly, someone just needs to create a pull request to document it

docker-robot[bot] commented 4 months ago

There hasn't been any activity on this issue for a long time. If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment. If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

benatshippabo commented 4 months ago

/remove-lifecycle stale

Farid-NL commented 2 months ago

I think it's important to notice a caveat of using the completions generated by the docker completion <shell> command.

Some context completions won't be shown properly.

Using completions generated by the completion command (Show files and directories)

docker rmi <tab>

app/
node_modules/
docker-compose.yml
...

Using completions provided by the vendor-completions (Shows images ids and names)

docker rmi <tab> 

5675b83f2460  -- latest          in dpage/pgadmin4
8e4fc9e18489  -- latest          in postgres
dpage/pgadmin4
postgres

The completions provided by vendor-completions have some logic to complete images, containers, sevices, networks, etc.

docker / docs