>_EXECUTIVE SUMMARY
vim-zsh is the Vim / Neovim editor support for zshrs — the Rust rewrite of zsh, the first compiled Unix shell. It ships as a standard Vim runtime tree (ftdetect/, syntax/, indent/, ftplugin/, plugin/, doc/), so pathogen / vim-plug / native packages add it to runtimepath with no special handling.
Design principle: the syntax file is a standalone zshrs grammar, not a reskin of Vim's bundled zsh / perl syntax. It is generated (scripts/gen_syntax.sh) directly from the zshrs binary's own reflection tables (zshrs --dump-reflection) — .builtins, .extensions, and .special_vars — so it carries the complete shell surface and never drifts. The filetype is zshrs (not zsh), so Vim's bundled zsh highlighter is never clobbered. Regenerate after a zshrs upgrade.
~RUNTIME LAYOUT
Standard Vim runtime directories. Each file is loaded automatically when the plugin is on runtimepath; no entry point or sourcing call is required.
| File | Responsibility |
|---|---|
ftdetect/zshrs.vim | Sets filetype=zshrs for zsh files (*.zsh …), dotfiles (.zshrc …), and any file whose first line is a zsh / zshrs shebang (e.g. #!/usr/bin/env zsh). |
syntax/zshrs.vim | Standalone zshrs grammar (generated) — comments / shebang, numbers, sigil variables, strings / here-docs / command substitution, 137 builtins + 113 extensions + 245 special vars + keywords, linked to standard highlight groups. |
indent/zshrs.vim | Standalone indentexpr (GetZshrsIndent()) — indents after a line opening a block / paren / bracket or a do / then / in, dedents done / fi / esac / closing delimiters. |
ftplugin/zshrs.vim | Buffer-local options: commentstring=# %s, comments=:#, comment-continuation formatoptions, with a matching b:undo_ftplugin. |
plugin/zshrs.vim | Global wiring: ALE linter definition, vim-lsp server registration, coc snippet (commented), and the g:vim_zsh_no_ale / g:vim_zsh_no_lsp opt-outs, behind a load guard. |
doc/zshrs.txt | Vim help (:help vim-zsh) with tagged sections for install, detection, syntax, linting, LSP, and options. |
$SYNTAX COVERAGE
Token categories taken from the zshrs binary's own reflection tables (zshrs --dump-reflection). Builtins exclude the extension and keyword names so the zshrs extensions — the additions that don't exist in upstream zsh — get their own highlight group.
| Group | Tokens (sample) | Highlight link |
|---|---|---|
| Declarations (10) | declare export float integer let local readonly set shift typeset | StorageClass |
| Control flow (24) | if elif else fi for foreach while until do done case esac function select repeat return | Statement |
| Builtins (137) | bindkey cd echo print read setopt unsetopt zmodload zle zstyle autoload bg fg jobs | Function |
| Extensions (112) | async await barrier arch base64 fold — zshrs-specific | PreProc |
| Special variables (245) | PATH HOME PWD ZSH_VERSION RANDOM LINENO SECONDS HISTFILE | Identifier |
| Literals & vars | sigils ($name / ${...}), positional / punctuation specials ($1 $# $@ $? $! $$ $*), strings, here-docs, $(...) / backtick command substitution, numbers | String / Number / Identifier |
#TOOLING INTEGRATION
All three integrations degrade gracefully: each is guarded so the plugin loads cleanly whether or not ALE / vim-lsp / coc is installed. CLI flags verified against zshrs --help (v0.12.1).
| Integration | Mechanism |
|---|---|
| ALE | Registers a linter via ale#linter#Define running zshrs -n over the buffer (stdin); the handler parses zsh: <reason> / zsh: parse error near … stderr lines into error items. Skipped if ALE is absent or g:vim_zsh_no_ale is set. |
| vim-lsp | Registers a server (lsp#register_server) running zshrs --lsp, allowlisted for the zshrs and zsh filetypes. Skipped if vim-lsp is absent or g:vim_zsh_no_lsp is set. |
| coc.nvim | A ready-to-paste languageserver block for coc-settings.json using zshrs --lsp, documented in the plugin source and README. |
@COMPATIBILITY
| Target | Status |
|---|---|
| Vim 8+ | Filetype, syntax, indent, ftplugin, doc |
| Neovim | Same runtime files (no Lua required) |
| pathogen / vim-plug / native packages | Standard runtime layout — no plugin-manager-specific handling |
| ALE | zshrs -n linter |
| vim-lsp | zshrs --lsp server |
| coc.nvim | languageserver config provided |