Awesome
<h1 align="center"> <div align="center"> <a href="https://fish-lsp.dev"> <image src="https://raw.githubusercontent.com/ndonfris/fish-lsp.dev/31d3d587ebd00f76ababcc98ed21b5109637e318/public/favicon-centered-bluee.svg" alt="fish-lsp" style="position: flex; text-align: center;" height="23rem"> fish-lsp </a> <div align="center"> <img src="https://img.shields.io/github/actions/workflow/status/ndonfris/fish-lsp/eslint.yml?branch=master&labelColor=%23181939" alt="GitHub Actions Workflow Status"> <img src="https://img.shields.io/github/license/ndonfris/fish-lsp?&labelColor=%23181939&color=b88af3" alt="License"> <img src="https://img.shields.io/github/created-at/ndonfris/fish-lsp?logo=%234e6cfa&label=created&labelColor=%23181939&color=%236198f5" alt="Github Created At"> </div> </div> </h1> <!-- A [Language Server Protocol (LSP)](https://lsif.dev/) tailored for the [fish shell](https://github.com/microsoft/vscode-languageserver-node/tree/main/server/src/common). -->Introducing the fish-lsp, a Language Server Protocol (LSP) implementation for the fish shell language.
<!-- The overall project goal is to produce [an editor agnostic developer environment](https://en.wikipedia.org/wiki/Language_Server_Protocol), while simultaneously --> <!-- introducing an extensive suite of intelligent text editing [features](#features). --> <!---->Why? 🐟
-
🦈 Efficiency: enhances the shell scripting experience with an extensive suite of intelligent text-editing features
-
🐡 Flexibility: allows for a highly customizable configuration
-
🐚 Guidance: friendly hints and documentation to comfortably explore command line tooling
-
🐬 Community: improved by a vibrant user base, with supportive and insightful feedback
-
🐙 Compatibility: integrates with a wide variety of tooling and language clients
-
🌊 Reliability: produces an editor agnostic developer environment, ensuring all fish user's have access to a consistent set of features
Features
Feature | Description | Status |
---|---|---|
Completion | Provides completions for commands, variables, and functions | ✅ |
Hover | Shows documentation for commands, variables, and functions. Has special handlers for --flag , commands , functions , variables | ✅ |
Signature Help | Shows the signature of a command or function | ✅ |
Goto Definition | Jumps to the definition of a command, variable, or function | ✅ |
Find References | Shows all references to a command, variable, or function | ✅ |
Rename | Rename within matching global && local scope | ✅ |
Document Symbols | Shows all commands, variables, and functions in a document | ✅ |
Workspace Symbols | Shows all commands, variables, and functions in a workspace | ✅ |
Document Formatting | Formats a document, full & selection | ✅ |
Document Highlight / Semantic Token | Highlights all references to a command, variable, or function. | ✅ |
Command Execution | Executes a server command from the client | ✅ |
Code Action | Shows all available code actions | ✖ |
Code Lens | Shows all available code lenses | ✖ |
Logger | Logs all server activity | ✅ |
Diagnostic | Shows all diagnostics | ✅ |
Folding Range | Toggle ranges to fold text | ✅ |
Telescope Integration | Integrates with the telescope.nvim plugin | ✅ |
CLI Interactivity | Provides a CLI for server interaction. Built by fish-lsp complete <option> | ✅ |
Client Tree | Shows the defined scope as a Tree | ✅ |
Indexing | Indexes all commands, variables, and functions | ✅ |
Installation
Recommended Dependencies:
yarn@1.22.22
,node@21.7.1
,fish@3.7.1
Building from source is the only currently recommended installation method, as we improve other methods of the installation process (Don't use releases or npm packages). Contributions to help enhance installation options are greatly appreciated!
-
Clone the repo
git clone https://github.com/ndonfris/fish-lsp # cd fish-lsp
-
Install the dependencies & run the setup handler scripts
yarn install
-
Optional: Check that the project successfully compiled & linked
fish-lsp --help # ./bin/fish-lsp --help
Setup
To properly configure fish-lsp, you need to define a client configuration after
installing the language server. Client's typically only need the keys command
,
args/arguments
, and filetypes
to start a language server.
Client Configuration (Required)
Theoretically, the language-server should generally be compatible with almost any text-editor or IDE you prefer using. Feel free to setup the project in any fish-lsp-client of your choice, or submit a PR for new configurations.
{
"fish-lsp": {
"command": "fish-lsp",
"filetypes": ["fish"],
"args": ["start"]
}
}
Neovim client using coc.nvim configuration, located inside coc-settings.json
"languageserver"
key
Server Configuration (Optional)
Specific functionality for the server can be set independently from the client. This allows for multiple
configurations, to be defined and chosen via specific startup requirements (i.e., using the bind
command
with the function edit_command_buffer
).
Environment variables
Generated by
fish-lsp env --create
# fish_lsp_enabled_handlers <ARRAY>
# enables the fish-lsp handlers (options: 'formatting', 'complete', 'hover', 'rename', 'definition', 'references', 'diagnostics', 'signatureHelp', 'codeAction', 'index')
set -gx fish_lsp_enabled_handlers
# fish_lsp_disabled_handlers <ARRAY>
# disables the fish-lsp handlers (options: 'formatting', 'complete', 'hover', 'rename', 'definition', 'references', 'diagnostics', 'signatureHelp', 'codeAction', 'index')
set -gx fish_lsp_disabled_handlers
# fish_lsp_commit_characters <ARRAY>
# array of the completion expansion characters. Single letter values only.
# Commit characters are used to select completion items, as shortcuts. (default: [])
set -gx fish_lsp_commit_characters
# fish_lsp_logfile <STRING>
# path to the logs.txt file (default: '')
# example locations could be: '~/path/to/fish-lsp/logs.txt' or '/tmp/fish_lsp_logs.txt'
set -gx fish_lsp_logfile
# fish_lsp_format_tabsize <NUMBER>
# amount of spaces in a tab character for the formatter provider (default: 4)
set -gx fish_lsp_format_tabsize
# fish_lsp_format_switch_case <BOOLEAN>
# keep case statements left aligned with switch block. (default: false)
set -gx fish_lsp_format_switch_case
# fish_lsp_all_indexed_paths <ARRAY>
# fish file paths/workspaces to include as workspaces (default: ['/usr/share/fish', "$HOME/.config/fish"])
set -gx fish_lsp_all_indexed_paths
# fish_lsp_modifiable_paths <ARRAY>
# fish file paths/workspaces that can be renamed by the user. (default: ["$HOME/.config/fish"])
set -gx fish_lsp_modifiable_paths
# fish_lsp_diagnostic_disable_error_codes <ARRAY>
# disable diagnostics for matching error codes (default: [])
# (options: 1001, 1002, 1003, 1004, 2001, 2002, 2003, 3001, 3002, 3003)
set -gx fish_lsp_diagnostic_disable_error_codes
# fish_lsp_max_background_files <NUMBER>
# maximum number of background files to read into buffer on startup (default: 1000)
set -gx fish_lsp_max_background_files
# fish_lsp_show_client_popups <BOOLEAN>
# show popup window notification in the connected client (default: true)
set -gx fish_lsp_show_client_popups
Command Flags
Both the flags --enable
and --disable
are provided on the fish-lsp start
subcommand. By default, all handlers will be enabled.
# displays what handlers are enabled. Removing the dump flag will run the server.
fish-lsp start --disable complete signature --dump
Further Server Configuration
Any flags will overwrite their corresponding environment variables, if both are
seen for the fish-lsp
process. For this reason, it is encouraged to wrap any
non-standard behavior of the fish-lsp
in functions or aliases.
Due to the vast possibilities this project aims to support in the fish shell, sharing useful configurations is highly encouraged.
How does it work?
If you're new to the concept of the Language Server Protocol (LSP), this section should be useful to help you grasp its core purpose and benefits.
📸 Check out this insightful video by TJ DeVries for an introduction to the subject.
The LSP is designed to create a uniform approach for supporting a programming language across various development tools, moving beyond the confines of specific Text-Editor/IDE ecosystems. This standardization enhances a language's appeal by allowing developers to maintain consistent tooling support without needing to switch developer environments.
The core of this system is the interaction between a 'language server', which provides language services, and a 'language client', which consumes these services. The protocol facilitates this interaction, ensuring that any language client can leverage a well-defined set of features provided by the server.
<details> <summary><b>Show</b> a diagram to <ins><i>visualize</i></ins> a hypothetical <code>fish-lsp</code> process</summary> </details> <!-- ## Challenges --> <!-- ![Static Badge](https://img.shields.io/badge/REQUIRED-8a2Be2?style=plastic) --> <!----> <!-- Since its inception, __fish-lsp__ has undergone substantial changes, requiring frequent refactoring --> <!-- and even the temporary exclusion of certain features to maintain compatibility and performance --> <!-- with the ever evolving [LSP standards](https://github.com/Microsoft/vscode-languageserver-node). These modifications have often led to extensive rewrites of --> <!-- significant sections throughout the project. As a result, some features are currently on hold until --> <!-- they can be seamlessly integrated into the updated framework. --> <!----> <!-- > [!NOTE] --> <!-- > __Your sponsorship and/or contributions are vital to continuing the development and refinement of [fish-lsp](https://fish-lsp.dev), --> <!-- > ensuring it remains a valuable tool for the community.__ -->Additional Resources
- Contributing - documentation describing how to contribute to the fish-lsp project.
- Roadmap - goals for future project releases.
- Wiki - further documentation and knowledge relevant to the project
- Discussions - interact with maintainers
- Site - website homepage
- Client Examples - testable language client configurations
- Sources - major influences for the project
Contributors
Special thanks to anyone who contributed to the project! Contributions of any kind are welcome!
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tbody> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/ndonfris"><img src="https://avatars.githubusercontent.com/u/49458459?v=4?s=50" width="50px;" alt="nick"/><br /><sub><b>nick</b></sub></a><br /><a href="https://github.com/ndonfris/fish-lsp/commits?author=ndonfris" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/mimikun"><img src="https://avatars.githubusercontent.com/u/13450321?v=4?s=50" width="50px;" alt="mimikun"/><br /><sub><b>mimikun</b></sub></a><br /><a href="https://github.com/ndonfris/fish-lsp/commits?author=mimikun" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/jpaju"><img src="https://avatars.githubusercontent.com/u/36770267?v=4?s=50" width="50px;" alt="Jaakko Paju"/><br /><sub><b>Jaakko Paju</b></sub></a><br /><a href="https://github.com/ndonfris/fish-lsp/commits?author=jpaju" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/shaleh"><img src="https://avatars.githubusercontent.com/u/1377996?v=4?s=50" width="50px;" alt="Sean Perry"/><br /><sub><b>Sean Perry</b></sub></a><br /><a href="https://github.com/ndonfris/fish-lsp/commits?author=shaleh" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://mastodon.online/@cova"><img src="https://avatars.githubusercontent.com/u/385249?v=4?s=50" width="50px;" alt="Fabio Coatti"/><br /><sub><b>Fabio Coatti</b></sub></a><br /><a href="https://github.com/ndonfris/fish-lsp/commits?author=cova-fe" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/PeterCardenas"><img src="https://avatars.githubusercontent.com/u/16930781?v=4?s=50" width="50px;" alt="Peter Cardenas"/><br /><sub><b>Peter Cardenas</b></sub></a><br /><a href="https://github.com/ndonfris/fish-lsp/commits?author=PeterCardenas" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/petertriho"><img src="https://avatars.githubusercontent.com/u/7420227?v=4?s=50" width="50px;" alt="Peter Tri Ho"/><br /><sub><b>Peter Tri Ho</b></sub></a><br /><a href="https://github.com/ndonfris/fish-lsp/commits?author=petertriho" title="Code">💻</a></td> </tr> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/bnwa"><img src="https://avatars.githubusercontent.com/u/74591246?v=4?s=50" width="50px;" alt="bnwa"/><br /><sub><b>bnwa</b></sub></a><br /><a href="https://github.com/ndonfris/fish-lsp/commits?author=bnwa" title="Code">💻</a></td> </tr> </tbody> </table> <!-- markdownlint-restore --> <!-- prettier-ignore-end --> <!-- ALL-CONTRIBUTORS-LIST:END --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <!-- markdownlint-restore --> <!-- prettier-ignore-end --> <!-- ALL-CONTRIBUTORS-LIST:END -->This project follows the all-contributors specification.