Troubleshooting

What to check when nothing completes.

Nothing happens when I press Tab

The completions are loaded when the shell starts. Open a new shell, or reload the current one:

exec "$SHELL"

Note the absence of -l. Under bash the completions are loaded from ~/.bashrc, and a login bash reads ~/.bash_profile, ~/.bash_login, or ~/.profile instead, never falling back to ~/.bashrc. On macOS none of those exist by default and the terminal opens login shells, so completions installed for bash are absent from every new window until the first of those files sources ~/.bashrc. Only the first one bash finds is read, so a ~/.profile that sources ~/.bashrc does nothing under a ~/.bash_profile that does not. Create ~/.bash_profile, or add to the one you have:

[ -r ~/.bashrc ] && . ~/.bashrc

If that does not help, confirm the file is where the installer put it:

curl -fsSL https://m.canouil.dev/quarto-completions/install.sh | bash -s -- --dry-run

--dry-run prints every path the installer would touch, without touching any of them.

zsh completes filenames instead of commands

zsh only loads a completion function once compinit has run, and only from a directory that was on fpath at that point. Where the file lands in ~/.zfunc, the managed block is appended to ~/.zshrc, so it runs after any compinit you call yourself, and it calls compinit -i of its own to pick up what it has just added. Under Oh My Zsh and under Homebrew there is no managed block, because the directory the file goes to is already on fpath.

Under Oh My Zsh the file goes to $ZSH_CUSTOM/completions, which Oh My Zsh puts on fpath before running compinit. Confirm the file is where that expects:

ls ~/.oh-my-zsh/custom/completions/_quarto

Otherwise, check that the block is still the last word on the subject. If something later in ~/.zshrc calls compinit -C, or replaces fpath outright, it undoes the block. Move the block below it, or delete the block and put this above your own compinit:

fpath=("$HOME/.zfunc" $fpath)

Then remove the stale completion cache and start a new shell:

rm -f ~/.zcompdump*
exec zsh -l

bash offers every file, not just documents

Filtering to .qmd, .ipynb, .md, .Rmd, and .markdown needs the extglob shell option. The script enables it around the one call that needs it, so this should not happen. It will, however, fall back to offering every file if compgen is not available, which is the case in a shell built without programmable completion.

Check that programmable completion is present:

complete -p quarto

An error there means bash was started with --norc or without bash-completion, and the script was never sourced.

The completions are out of date

They are generated from a released Quarto, so a flag added after that release is not there yet. The installer checks this each time it runs, comparing the quarto on your PATH against the completions it is about to install: it says so when they disagree by major or minor version, adding --channel pre-release to the message when your Quarto is newer than a release install. Nothing checks again after that, so an upgrade of Quarto is not noticed on its own: re-run the installer after upgrading, the same way you first installed.

If your Quarto is behind the current release, the mismatch is not a reason to live with stale completions: every Quarto minor from 1.9 onwards has its own channel, generated from that line’s newest patch. With no --channel given, the installer already matches your Quarto’s own minor when it is published, so the fix is usually to re-run the installer with nothing more than that; see Channels. To check an install done earlier, or without running the installer again, ask where the file is:

curl -fsSL https://m.canouil.dev/quarto-completions/install.sh | bash -s -- --dry-run

Then read the version out of the path it reported:

grep -m1 Quarto <path>

The piped form cannot take arguments in PowerShell, so save the script first, then pass -DryRun when you run it:

irm https://m.canouil.dev/quarto-completions/install.ps1 -OutFile install.ps1
./install.ps1 -DryRun

Then read the version out of the path it reported:

Select-String -Pattern Quarto -Path <path> | Select-Object -First 1

Every script carries that line in its header. The path is worth asking for rather than assuming: where the file goes depends on what else the machine has installed, so it differs between shells and between machines. If you run a Quarto pre-release, install the matching channel:

curl -fsSL https://m.canouil.dev/quarto-completions/install.sh | bash -s -- --channel pre-release

$env:QUARTO_COMPLETIONS_CHANNEL = 'pre-release'
powershell -ExecutionPolicy ByPass -c "irm https://m.canouil.dev/quarto-completions/install.ps1 | iex"
Remove-Item Env:\QUARTO_COMPLETIONS_CHANNEL

If the quarto on PATH reports version 99.9.9, which is what a source build reports, the installer picks the dev channel on its own, with no option or environment variable needed. That channel also completes the commands Quarto hides from quarto --help, such as dev-call; see Channels.

Tab still shows the old commands after installing

This is about the macOS and Linux installer, which maintains one shell per run, the one $SHELL names. Running it from a bash terminal maintains bash and leaves zsh exactly as it was, so a shell you did not install for keeps whatever it had, however old. The Windows installer has no equivalent situation, since PowerShell is the only shell it serves.

An install reports this when it finds it, naming the other shell’s file and its version, so start by reading what the last run said. To check without installing anything, ask each shell in turn:

curl -fsSL https://m.canouil.dev/quarto-completions/install.sh | bash -s -- --shell zsh --dry-run

Then read the header of every path it reports:

grep -m1 Quarto <path>

Each script names the Quarto version and the channel it came from. A shell showing an older command set is a shell whose file says an older version, or says release where you expected dev. Install for it by name:

curl -fsSL https://m.canouil.dev/quarto-completions/install.sh | bash -s -- --shell zsh

Hidden commands such as inspect and dev-call are on the dev channel only, so a release file lacking them is correct rather than stale; see Channels.

Extension formats are missing from `--to`

Only Quarto’s built-in formats are completed. A format contributed by an installed extension would have to be read from disk on every keystroke, which is the cost these completions exist to avoid.

No completions published for that channel

The published channels are release, pre-release, dev, and every Quarto minor from 1.9 onwards. Naming anything else, --channel 1.0 on an older Quarto for instance, stops the installer:

error: no completions published for channel '1.0'
(https://m.canouil.dev/quarto-completions/completions/1.0/manifest.json);
published channels are release, pre-release, dev, and Quarto minors from 1.9 onwards

A channel you name is never quietly swapped for another one, on --dry-run or on a real run. Leave --channel off instead, and the installer matches your Quarto’s own minor when that is published, falling back to release and saying so when it is not. The completions are then generated from a newer Quarto than yours, which it also tells you; see The completions are out of date.

Checksum mismatch

The installer verifies each file against manifest.json before writing it, and stops if they disagree. That normally means the download was truncated. Run it again.

On Windows PowerShell 5.1, a connection error rather than a mismatch usually means TLS 1.2 was not negotiated. The installer enables it, so this should only appear on a Windows build old enough to lack it entirely.

If it keeps failing, report it with the two hashes the error printed: https://github.com/mcanouil/quarto-completions/issues.

The managed block has no closing line

The installer keeps everything it adds to your shell configuration between two markers:

# >>> quarto completions >>>
# <<< quarto completions <<<

A hand edit, a merge conflict, or a half-written file can leave the opening marker with no matching closing one. The installer removes the block by cutting from one marker to the other, so on a file in that state it would take every line you keep below the opening marker with it. It stops instead, and changes nothing, on install, on uninstall, and on --dry-run alike.

Open the file it named, ~/.bashrc or ~/.zshrc on macOS and Linux, and your PowerShell profile on Windows, then either add the closing line back below the block or delete the block outright, markers included. Re-run the installer afterwards; it writes a fresh block of its own.

Removing everything

curl -fsSL https://m.canouil.dev/quarto-completions/install.sh | bash -s -- --uninstall

That deletes the completion file and the managed block from your shell’s configuration, and leaves the rest of your configuration untouched. One run covers one shell, the one detected from $SHELL; if you installed for several, repeat with --shell bash|zsh|fish.