https://github.com/k8s-1/bashls
Bash language server (LSP) written in Rust
https://github.com/k8s-1/bashls
bash bash-lsp bash-script language-server language-server-protocol lsp lsp-server rust shellcheck shfmt tree-si
Last synced: 23 days ago
JSON representation
Bash language server (LSP) written in Rust
- Host: GitHub
- URL: https://github.com/k8s-1/bashls
- Owner: k8s-1
- License: mit
- Created: 2026-05-24T09:04:00.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-02T06:26:51.000Z (24 days ago)
- Last Synced: 2026-06-02T08:19:25.483Z (24 days ago)
- Topics: bash, bash-lsp, bash-script, language-server, language-server-protocol, lsp, lsp-server, rust, shellcheck, shfmt, tree-si
- Language: Rust
- Homepage:
- Size: 2.41 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# bashls
[](https://github.com/k8s-1/bashls/actions/workflows/ci.yml)
[](https://crates.io/crates/bashls)
A Bash language server (LSP) written in Rust. Provides IDE features — completions, hover, diagnostics, formatting, rename, and go-to-definition — for shell scripts in any LSP-compatible editor (Neovim, Helix, Zed, Emacs).
## Motivation
[bash-language-server](https://github.com/bash-lsp/bash-language-server) errors had pushed my logs past 1 GB. My editor was slowing down. I wanted something self-contained.
## Features
- Hover documentation
- Completions (variables, functions, executables, builtins, snippets)
- Jump to definition
- Find references
- Rename
- Document and workspace symbols
- Diagnostics via [shellcheck](https://github.com/koalaman/shellcheck)
- Formatting via [shfmt](https://github.com/mvdan/sh)
## Installation
Diagnostics and formatting require additional tools:
- [shellcheck](https://github.com/koalaman/shellcheck)
- [shfmt](https://github.com/mvdan/sh)
#### Binary
Download from [releases page](https://github.com/k8s-1/bashls/releases), extract, and place `bashls` somewhere on your `$PATH`.
#### Cargo
```
cargo install bashls
```
#### From source
```
git clone https://github.com/k8s-1/bashls
cd bashls
cargo build --release
```
## Editor support
bashls works with any editor that supports LSP.
### Neovim
```lua
vim.lsp.config('bashls', {
cmd = { 'bashls' },
filetypes = { 'sh' },
root_markers = { '.git' },
-- init_options = {
-- bashIde = { shellcheckPath = '/usr/bin/shellcheck' },
-- },
})
vim.lsp.enable('bashls')
```
### Helix
```toml
[[language]]
name = "bash"
language-servers = ["bashls"]
[language-server.bashls]
command = "bashls"
```
### Zed
```json
{
"lsp": {
"bash-language-server": {
"binary": {
"path": "bashls",
}
}
}
}
```
### Emacs
```elisp
(add-to-list 'eglot-server-programs
'(sh-mode . ("bashls")))
```
## Configuration
Settings can be provided as LSP initialization options (under `bashIde`) or as environment variables (e.g. `bashIde.shellcheckPath` → `SHELLCHECK_PATH`).
| Setting (`bashIde.*`) | Default | Description |
|---|---|---|
| `shellcheckPath` | `shellcheck` | Path to shellcheck binary. |
| `shellcheckArguments` | `[]` | Additional arguments passed to [shellcheck](https://github.com/koalaman/shellcheck). |
| `shfmt.path` | `shfmt` | Path to shfmt binary. |
| `shfmt.*` | | See [shfmt](https://github.com/mvdan/sh) for remaining options. |
| `globPattern` | `**/*@(.sh\|.inc\|.bash\|.command)` | Files the server treats as bash. |
| `backgroundAnalysisMaxFiles` | `500` | Max files to analyse in background for workspace-wide features. |
| `includeAllWorkspaceSymbols` | `false` | Return functions and variables from all workspace files in symbol search, not just open files. |
| `enableSourceErrorDiagnostics` | `false` | Show diagnostics when a `source`/`.` command cannot be resolved. |
## Limitations
- **No [explainshell](https://explainshell.com) integration.** Supporting this would require pulling in an HTTP/TLS stack (~50 crates); skipped intentionally to keep the dependency footprint small.
- **Linux and macOS only.** This is a bash language server — if you're on Windows, use WSL.
## Benchmarks
Measured against [bash-language-server](https://github.com/bash-lsp/bash-language-server) 5.6.0 using 50 `.sh` files from [oh-my-bash](https://github.com/ohmybash/oh-my-bash) as a corpus. Startup is measured cold (no prior Node.js activity); 1500 ms is a typical cold-start. See [examples/lsp_bench.rs](examples/lsp_bench.rs) for the full methodology and instructions to reproduce.
## License
This project is released under the [MIT License](LICENSE).