coc-vimls

coc-vimls

Vim script and Vim9 script language support for coc.nvim, powered by vimls-go.

Provides completion, diagnostics, hover, navigation, rename, formatting, semantic highlighting, inlay hints and code lenses through the language server.

Installation

Requires Node.js 22.15+ and coc.nvim 0.0.82 or newer.

:CocInstall coc-vimls

Open a Vim file. On first activation the extension queries the latest stable GitHub release, downloads the matching binary with coc.nvim's download API, verifies its SHA-256 checksum and caches it in the extension storage directory. Later starts reuse the cached executable, including when offline. The first installation and updates require access to GitHub. coc.nvim's HTTP proxy settings apply to release queries and downloads.

macOS, Linux, Windows and FreeBSD are supported where the release contains a binary matching the operating system and CPU architecture.

Remove any manually configured languageserver.vimls entry or competing Vim language-server extension to avoid running duplicate servers.

If installation or startup fails, vimls.doctor remains available with the last error and cache information. Fix the cause, then run vimls.restart to retry without reloading the extension.

Updating

:CocCommand vimls.update

Checks the latest GitHub release and installs it if needed, then restarts the language service. Failed downloads or checksum checks preserve the previous installation and running service. After a successful installation, only the current version and one previous version are retained in extension storage. If the new server fails to start, the extension restores the previous binary and restarts it. Use :CocCommand vimls.rollback to return to the previous installation manually.

When vimls.command is configured, the command explains that the custom executable must be updated manually. Clear that setting and reload the extension to return to managed release downloads.

The service appears as vimls in :CocList services; logs are available in the vimls output channel through :CocCommand vimls.openOutput or :CocCommand workspace.showOutput.

The extension checks for new releases once a week in the background and notifies you when an update is available. Set vimls.checkForUpdates to false to disable these checks; initial installation and vimls.update still work.

Using language features

These features use coc.nvim's built-in actions. Availability depends on the installed vimls-go version; the extension does not need separate commands for standard LSP features.

For an action name in the table, run :call CocActionAsync('actionName') or use your existing coc.nvim mapping.

Semantic highlighting and inlay hints use coc.nvim's semanticTokens.enable and inlayHint.enable settings. Their display depends on editor support and the current theme. Server-provided fixes depend on the diagnostic; the extension also contributes the two actions described below.

File creation, changes and deletion are synchronized through the server's LSP file-watcher registrations. Runtimepath changes are synchronized separately.

Code Actions

• Disable diagnostic <code>: A quickfix for the vimls diagnostic nearest the cursor on the current line. Adds its code to vim.diagnostic.disabled, preserving existing entries. If the current project overrides that list, the action is labeled in project and updates the project setting; otherwise it updates user settings. Suppression applies across files in that scope.
• Execute selected Vim script: Execute a nonempty selection using the editor or system Vim as described below.

Executing selections

Preserving the file context of Vim9 selections requires Vim 9.1.0359 or newer. This applies to the current Vim editor and to the external Vim selected by vimls.vimCommand when using Neovim or executing partial lines.

Legacy Vim script runs in the current editor. In Vim with Vim9 support, complete lines of Vim9 script are sourced directly from the current buffer, preserving its filename, relative imports and script-local state from previous execution. Closed folds do not expand the execution range, and folding is restored afterward. The extension never automatically executes code outside the selection.

In Neovim, Vim9 script runs in a separate system Vim process. File-backed selections use the original filename for relative imports and <sfile>, without reading or modifying the original file. Imports and variables needed by the snippet must be included in the selection. This also applies to partial-line Vim9 selections in Vim when a filename is available; they run as independent snippets to avoid executing the rest of the line. Partial-line snippets from unnamed buffers use a temporary script. vimls.vimCommand selects the external Vim executable.

Diagnostic rules

Run :CocCommand vimls.diagnostics to select a diagnostic from the current file, a disabled rule or an existing severity override. You can also enter a code. Choose user settings or the current project's .vim/coc-settings.json, then choose the action. The project option is available when coc.nvim has a workspace folder for its current root. The language server uses one set of settings for the workspace; this is not per-buffer suppression.

Enabling a rule removes it from that scope's disabled list. Severity changes do not re-enable disabled rules. Removing a project severity override restores the inherited user setting, if any. The quickfix disables the nearest diagnostic in one action, using project settings when the disabled list is overridden there and user settings otherwise.

Development

npm ci
mkdir -p .test-bin
go -C /path/to/vimls-go build -o "$PWD/.test-bin/vimls" ./cmd/vimls
npm run typecheck
npm run build
npm run test:nvim
npm run test:vim
npm pack --dry-run

Alternatively set VIMLS_TEST_BIN to a directory containing vimls. Tests load TypeScript source through coc-test and exercise a real server in both editors. Download tests use a local HTTP fixture and do not access GitHub. CI builds Vim 9.2.1015 from a pinned commit for both editor jobs, since the distribution Vim may lack support for file-relative imports in buffer selections. The suite covers installation recovery, rollback, configuration scope, selection execution and the registered completion, navigation, rename, formatting and CodeLens providers. Watcher tests inject file events into coc.nvim's registered watchers and verify real-server index updates; they do not require watchman or validate OS event delivery. CI pins the server source used for integration.

Tests open complete file fixtures and await requests or observable state changes. They avoid popup interaction, fixed startup sleeps and public release endpoints. The coc-test runner may still need network access to obtain coc.nvim on a clean machine; supply a local server as shown above.