Skip to content

Add completion troubleshooting guide #4821

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed

Add completion troubleshooting guide #4821

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6acc66f
Init
bebound Nov 29, 2024
2bb564a
Minor fix
bebound Nov 29, 2024
08a68f1
Minor fix
bebound Dec 2, 2024
4822727
Apply suggestions from code review
bebound Dec 16, 2024
dd4ed0a
Update docs-ref-conceptual/includes/linux-completion.md
bebound Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs-ref-conceptual/includes/cli-install-linux-apt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,3 +237,5 @@ If your proxy doesn't use basic auth, __remove__ the `[username]:[password]@` po
In order to get the Microsoft signing key and get the package from our repository, your proxy needs to allow HTTPS connections to the following address: `https://packages.microsoft.com.

[!INCLUDE[troubleshoot-wsl.md](troubleshoot-wsl.md)]

[!INCLUDE[linux-completion.md](linux-completion.md)]
2 changes: 2 additions & 0 deletions docs-ref-conceptual/includes/cli-install-linux-dnf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,3 +193,5 @@ allow HTTPS connections to the following address:
* `https://packages.microsoft.com`

[!INCLUDE[troubleshoot-wsl.md](troubleshoot-wsl.md)]

[!INCLUDE[linux-completion.md](linux-completion.md)]
4 changes: 4 additions & 0 deletions docs-ref-conceptual/includes/cli-install-linux-tdnf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,7 @@ sudo tdnf remove azure-cli
### Remove data

[!INCLUDE [remove-data-boilerplate.md](remove-data-boilerplate.md)]

## Troubleshooting

[!INCLUDE[linux-completion.md](linux-completion.md)]
20 changes: 20 additions & 0 deletions docs-ref-conceptual/includes/linux-completion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
author: bebound
ms.author: hanglei
ms.date: 11/29/2024
ms.topic: include
---
### Completion isn't working

For Bash users, the completion script is installed in `/etc/bash_completion.d/azure-cli`. If it is not automatically executed, add the following line to your `~/.bashrc` file, then save and reload your Bash profile:

```bash
source /etc/bash_completion.d/azure-cli
```

For Zsh users, add the following two lines in your `~/.zshrc` file, then save and reload your Zsh profile:

```zsh
autoload -U +X bashcompinit && bashcompinit
Copy link
Member

@jiasli jiasli Jan 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will this command automatically load /etc/bash_completion.d/azure-cli?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, bashcompinit only emulates the complete function in bash.

The function bashcompinit provides compatibility with bash’s programmable completion system. When run it will define the functions, compgen and complete which correspond to the bash builtins with the same names. It will then be possible to use completion specifications and functions written for bash.
--- https://zsh.sourceforge.io/Doc/Release/Completion-System.html

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the purpose and source of this autoload -U +X bashcompinit command?

Found some explanation on it:

Copy link
Contributor Author

@bebound bebound Feb 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Source of this command: https://stackoverflow.com/a/49277309/2251785

With the -U flag, alias expansion is suppressed when the function is loaded.

The flag +X attempts to load each name as an autoloaded function, but does not execute it. The exit status is zero (success) if the function was not previously defined and a definition for it was found. This does not replace any existing definition of the function. The exit status is nonzero (failure) if the function was already defined or when no definition was found. In the latter case the function remains undefined and marked for autoloading. If ksh-style autoloading is enabled, the function created will contain the contents of the file plus a call to the function itself appended to it, thus giving normal ksh autoloading behaviour on the first call to the function. If the -m flag is also given each name is treated as a pattern and all functions already marked for autoload that match the pattern are loaded.

The flags -z and -k mark the function to be autoloaded using the zsh or ksh style, as if the option KSH_AUTOLOAD were unset or were set, respectively.

https://man.archlinux.org/man/zshall.1.en#autoload

Copy link
Member

@jiasli jiasli Feb 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The AWS document https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-completion.html uses

autoload bashcompinit && bashcompinit
autoload -Uz compinit && compinit

Our document for MacOS https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-macos#completion-isnt-working also only uses

autoload bashcompinit && bashcompinit

Copy link
Contributor Author

@bebound bebound Feb 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the purpose and source of this autoload -U +X bashcompinit command?

Found some explanation on it:

After reading these docs. It seems -Uz is always the right option for autoload.

"-Uz"? Yes, that is "the right thing"[tm] almost always, so I won't discuss it here. See the manual for details. --- http://bewatermyfriend.org/p/2012/003/

For +X, it returns nonzero exit code if the function is defined. It saves some time if the .zshrc has multiple autoload bashcompinit.

Also, compinit is also needed for completion.

source /etc/bash_completion.d/azure-cli
```
2 changes: 1 addition & 1 deletion docs-ref-conceptual/install-azure-cli-macos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ If you encounter a problem when installing the CLI through Homebrew, here are so

### Completion isn't working

The Homebrew formula of Azure CLI installs a completion file named `az` in the Homebrew-managed completions directory (default location is `/usr/local/etc/bash_completion.d/`). To enable completion, follow Homebrew's instructions [here](https://docs.brew.sh/Shell-Completion).
The Homebrew formula of Azure CLI installs a completion file named `az` in the Homebrew-managed completions directory (default location is `$(brew --prefix)/etc/bash_completion.d/`). To enable completion, follow Homebrew's instructions [here](https://docs.brew.sh/Shell-Completion).

For Zsh, add the following two lines to the bottom of your `.zshrc` file, then save and reload your Zsh profile.

Expand Down