Summary
Completions that are present on disk and visible in zi clist can still be unavailable to Zsh immediately after install/refresh.
This shows up most clearly with completions generated by atclone, such as the case reported in the organization discussion:
https://github.com/orgs/z-shell/discussions/334
User-visible behavior
A plugin/snippet installs or generates a completion file like _cscli.
zi clist shows the completion as installed
- the completion file exists in
${ZI[COMPLETIONS_DIR]}
- but completing
cscli <TAB> does nothing
zi compinit / a full compinit rebuild makes it start working
Example configuration
zi wait='1b' lucid for \
atinit='export PIPENV_SHELL_FANCY=true' \
OMZP::pipenv \
light-mode \
as="completion" id-as="cscli/completion" has="cscli" \
blockf \
atclone="cscli completion zsh > _cscli" \
atpull="%atclone" z-shell/null
Root cause
After completion mutations, Zi refreshes with compinit -C via .zi-compinit 1 1.
-C reuses the existing dump instead of rebuilding completion mappings, so newly added/generated completion files can remain absent from _comps even though they were symlinked correctly and appear in zi clist.
I verified this with a minimal repro:
- initialize completion system
- add a new
_bar completion file after the initial dump exists
- run the current refresh path (
.zi-compinit 1 1)
_comps[bar] is still missing
- run a full
.zi-compinit 1
_comps[bar] is registered
Suspected fix
Any path that changes installed/enabled/disabled completions should rebuild compinit state without -C.
Relevant call sites include:
zi.zsh
lib/zsh/install.zsh
lib/zsh/autoload.zsh
In practice, the stale refresh paths are the places currently calling .zi-compinit 1 1 immediately after completion install/remove/enable/disable/update flows.
Notes
This is separate from whether the completion file itself is valid. The failure mode here is that Zi's refresh path can leave new completions invisible until a full compinit rebuild happens.
Summary
Completions that are present on disk and visible in
zi clistcan still be unavailable to Zsh immediately after install/refresh.This shows up most clearly with completions generated by
atclone, such as the case reported in the organization discussion:https://github.com/orgs/z-shell/discussions/334
User-visible behavior
A plugin/snippet installs or generates a completion file like
_cscli.zi clistshows the completion as installed${ZI[COMPLETIONS_DIR]}cscli <TAB>does nothingzi compinit/ a full compinit rebuild makes it start workingExample configuration
Root cause
After completion mutations, Zi refreshes with
compinit -Cvia.zi-compinit 1 1.-Creuses the existing dump instead of rebuilding completion mappings, so newly added/generated completion files can remain absent from_compseven though they were symlinked correctly and appear inzi clist.I verified this with a minimal repro:
_barcompletion file after the initial dump exists.zi-compinit 1 1)_comps[bar]is still missing.zi-compinit 1_comps[bar]is registeredSuspected fix
Any path that changes installed/enabled/disabled completions should rebuild compinit state without
-C.Relevant call sites include:
zi.zshlib/zsh/install.zshlib/zsh/autoload.zshIn practice, the stale refresh paths are the places currently calling
.zi-compinit 1 1immediately after completion install/remove/enable/disable/update flows.Notes
This is separate from whether the completion file itself is valid. The failure mode here is that Zi's refresh path can leave new completions invisible until a full compinit rebuild happens.