# Shell support

conda-completion supports bash, zsh, PowerShell, and fish.

## Supported shells

All supported shells are covered by automated tests for script
generation, CLI initialization, installation hooks, and shell detection.
Bug reports and contributions are welcome for each shell.

## Feature matrix

| Feature | bash | zsh | PowerShell | fish |
|---|---|---|---|---|
| Command completion | Yes | Yes | Yes | Yes |
| Flag completion | Yes | Yes | Yes | Yes |
| Flag value completion | Yes | Yes | Yes | Yes |
| Package name completion | Yes | Yes | Yes | Yes |
| Version completion (`=`) | Yes | Yes | Yes | Yes |
| Fuzzy matching | Yes | Yes | Yes | Yes |
| Descriptions | No | Yes | Yes | Yes |
| `install`/`uninstall` | Yes | Yes | Yes | Yes |
| Dynamic env names | Yes | Yes | Yes | Yes |
| Dynamic channels | Yes | Yes | Yes | Yes |
| Dynamic task names | Yes | Yes | Yes | Yes |

## Shell-specific behavior

Each shell has different completion mechanics. The generated scripts
handle these differences so completions work consistently across shells.

**Completion ordering.** conda-completion returns results in a specific
order: package names sorted by length (shortest first), versions sorted
newest-first. Without shell-specific handling, some shells re-sort
results alphabetically:

- **bash**: `compopt -o nosort` (bash 4.4+) prevents re-sorting
- **zsh**: `_describe -V` creates an unsorted completion group
- **fish**: `complete -k` keeps insertion order
- **PowerShell**: preserves order by default

**Equals sign in version specs.** Typing `conda install numpy=1.26`
requires the shell to treat `numpy=1.26` as a single token. Bash splits
on `=` by default via `COMP_WORDBREAKS`, so the generated bash script
removes `=` from that variable. Other shells do not split on `=`.

**PowerShell tokenization.** The generated PowerShell script reads
`$commandAst.CommandElements` instead of splitting the command string on
whitespace. This preserves quoted paths and arguments before passing
words to the Rust completer.

**Descriptions.** Zsh, fish, and PowerShell display descriptions
alongside completion candidates. Bash's COMPREPLY does not support
descriptions, so the Rust binary omits them for bash output.

## RC file locations

| Shell | RC file(s) |
|---|---|
| bash | `~/.bashrc`, `~/.bash_profile` |
| zsh | `~/.zshrc` |
| PowerShell (Windows) | `~/Documents/PowerShell/Microsoft.PowerShell_profile.ps1` |
| PowerShell (macOS/Linux) | `~/.config/powershell/Microsoft.PowerShell_profile.ps1` |
| fish | `~/.config/fish/completions/conda.fish` |

`conda completion install` writes a delimited block to the first existing
RC file (or creates the first one in the list if none exist).

## cmd.exe (Windows)

cmd.exe has no programmable completion API. Unlike bash, zsh, fish, and
PowerShell, there is no way to register a custom completer for a
command. cmd.exe's built-in TAB completion only cycles through file and
directory names.

Windows users who want conda tab completion should use PowerShell,
which is installed by default on all modern Windows versions.

## Future shell candidates

The following shells have programmable completion APIs and are
candidates for future support. Contributions are welcome.

**xonsh**
: A Python-powered shell with a `completes_for` decorator for
  registering custom completers. conda supports xonsh in `conda init`,
  and mamba supports it in `shell completion`.

**Nushell**
: A modern structured-data shell with an `extern` completion system.
  Growing in popularity, already supported by `argc-completions`.
  Nushell uses tab-separated output similar to fish, so the Rust
  binary's output format may need only minor adaptation.

**tcsh**
: A legacy C shell with a `complete` builtin for programmable
  completions. conda supports tcsh in `conda init`. Still ships as the
  default root shell on some BSDs, though usage is declining.

If you are interested in adding support for one of these shells, the
main work is writing a shell integration script and adding an output
format to the Rust binary if the shell's completion protocol differs
from the existing ones.

## Shell detection

When the shell argument is omitted, conda-completion detects the current
shell using this priority order:

1. `CONDA_COMPLETION_SHELL` environment variable (explicit override).
2. Process tree walking: walks parent processes via `ps` to find the
   nearest shell. This correctly detects shells like fish even when
   they are not the login shell (where `$SHELL` would still point to
   the login shell). Works on Linux, macOS, WSL, and Git Bash/MSYS2.
   Falls through silently on native Windows where `ps` is unavailable.
   PowerShell aliases such as `pwsh` are normalized to `powershell`.
3. `SHELL` environment variable (extracts the basename and normalizes
   supported aliases).
4. Platform default: `powershell` on Windows, `bash` otherwise.

The process tree approach is inspired by
[shellingham](https://github.com/sarugaku/shellingham) (ISC license).