diff --git a/content/config/completion.md b/content/config/completion.md new file mode 100644 index 0000000000..90ab810054 --- /dev/null +++ b/content/config/completion.md @@ -0,0 +1,104 @@ +--- +title: CLI completion +description: Set up your shell to get autocomplete for Docker commands and flags +keywords: cli, shell, fish, bash, zsh, completion, options +--- + +You can generate a shell completion script for the Docker CLI using the `docker +completion` command. The completion script gives you word completion for +commands, flags, and Docker objects (such as container and volume names) when +you hit `` as you type into your terminal. + +You can generate completion scripts for the following shells: + +- [Bash](#bash) +- [Zsh](#zsh) +- [fish](#fish) + +## Bash + +To get Docker CLI completion with Bash, you first need to install the +`bash-completion` package which contains a number of Bash functions for shell +completion. + +```bash +# Install using APT: +sudo apt install bash-completion + +# Install using Homebrew (Bash version 4 or later): +brew install bash-completion@2 +# Homebrew install for older versions of Bash: +brew install bash-completion + +# With pacman: +sudo pacman -S bash-completion +``` + +After installing `bash-completion`, source the script in your shell +configuration file (in this example, `.bashrc`): + +```bash +# On Linux: +cat <> ~/.bashrc +if [ -f /etc/bash_completion ]; then + . /etc/bash_completion +fi +EOT + +# On macOS / with Homebrew: +cat <> ~/.bash_profile +[[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && . "$(brew --prefix)/etc/profile.d/bash_completion.sh" +EOT +``` + +And reload your shell configuration: + +```console +$ source ~/.bashrc +``` + +Now you can generate the Bash completion script using the `docker completion` command: + +```console +$ mkdir -p ~/.local/share/bash-completion/completions +$ docker completion bash > ~/.local/share/bash-completion/completions/docker +``` + +## Zsh + +The Zsh [completion system](http://zsh.sourceforge.net/Doc/Release/Completion-System.html) +takes care of things as long as the completion can be sourced using `FPATH`. + +If you use Oh My Zsh, you can install completions without modifying `~/.zshrc` +by storing the completion script in the `~/.oh-my-zsh/completions` directory. + +```console +$ mkdir -p ~/.oh-my-zsh/completions +$ docker completion zsh > ~/.oh-my-zsh/completions/_docker +``` + +If you're not using Oh My Zsh, store the completion script in a directory of +your choice and add the directory to `FPATH` in your `.zshrc`. + +```console +$ mkdir -p ~/.docker/completions +$ docker completion zsh > ~/.docker/completions/_docker +``` + +```console +$ cat <> ~/.zshrc +fpath=(~/.docker/completions \\$fpath) +autoload -Uz compinit +compinit +EOT +``` + +## Fish + +fish shell supports a [completion system](https://fishshell.com/docs/current/#tab-completion) natively. +To activate completion for Docker commands, copy or symlink the completion script to your fish shell `completions/` directory: + +```console +$ mkdir -p ~/.config/fish/completions +$ docker completion fish > ~/.config/fish/completions/docker.fish +``` diff --git a/content/desktop/faqs/macfaqs.md b/content/desktop/faqs/macfaqs.md index 71149e7360..e09d7ede7c 100644 --- a/content/desktop/faqs/macfaqs.md +++ b/content/desktop/faqs/macfaqs.md @@ -220,70 +220,3 @@ To learn more about how to install a CA root certificate for the registry and how to set the client TLS certificate for verification, see [Verify repository client with certificates](../../engine/security/certificates.md) in the Docker Engine topics. - -### How do I install shell completion? - -Docker Desktop comes with scripts to enable completion for the `docker` and `docker compose` commands. The completion scripts may be -found inside `Docker.app`, in the `Contents/Resources/etc/` directory and can be -installed both in Bash and Zsh. - -#### Bash - -Bash has [built-in support for -completion](https://www.debian-administration.org/article/316/An_introduction_to_bash_completion_part_1) To activate completion for Docker commands, these files need to be -copied or symlinked to your `bash_completion.d/` directory. For example, if you -installed bash via [Homebrew](https://brew.sh): - -```bash -etc=/Applications/Docker.app/Contents/Resources/etc -ln -s $etc/docker.bash-completion $(brew --prefix)/etc/bash_completion.d/docker -ln -s $etc/docker-compose.bash-completion $(brew --prefix)/etc/bash_completion.d/docker-compose -``` - -Add the following to your `~/.bash_profile`: - -```bash -[ -f /usr/local/etc/bash_completion ] && . /usr/local/etc/bash_completion -``` - -OR - -```bash -if [ -f $(brew --prefix)/etc/bash_completion ]; then -. $(brew --prefix)/etc/bash_completion -fi -``` - -#### Zsh - -In Zsh, the [completion -system](http://zsh.sourceforge.net/Doc/Release/Completion-System.html) -takes care of things. To activate completion for Docker commands, -these files need to be copied or symlinked to your Zsh `site-functions/` -directory. For example, if you installed Zsh via [Homebrew](https://brew.sh): - -```bash -etc=/Applications/Docker.app/Contents/Resources/etc -ln -s $etc/docker.zsh-completion /usr/local/share/zsh/site-functions/_docker -ln -s $etc/docker-compose.zsh-completion /usr/local/share/zsh/site-functions/_docker-compose -``` - -#### Fish-Shell - -Fish-shell also supports tab completion [completion -system](https://fishshell.com/docs/current/#tab-completion). To activate completion for Docker commands, -these files need to be copied or symlinked to your Fish-shell `completions/` -directory. - -Create the `completions` directory: - -```console -$ mkdir -p ~/.config/fish/completions -``` - -Now add fish completions from docker. - -```console -$ ln -shi /Applications/Docker.app/Contents/Resources/etc/docker.fish-completion ~/.config/fish/completions/docker.fish -$ ln -shi /Applications/Docker.app/Contents/Resources/etc/docker-compose.fish-completion ~/.config/fish/completions/docker-compose.fish -``` diff --git a/data/toc.yaml b/data/toc.yaml index 112e0a2c73..398fe2def4 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1579,6 +1579,8 @@ Manuals: section: - path: /engine/reference/commandline/cli/ title: Use the Docker CLI + - path: /config/completion/ + title: Completion - path: /config/filter/ title: Filter commands - path: /config/formatting/