Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ndonfris/fish-lsp

LSP implementation for the fish shell langauge 🐠
https://github.com/ndonfris/fish-lsp

cli fish fish-shell language-server language-server-protocol lsp lsp-server neovim shell typescript vim vscode-language

Last synced: 19 days ago
JSON representation

LSP implementation for the fish shell langauge 🐠

Awesome Lists containing this project

README 

        


    


        

             fish-lsp

        

        


            GitHub Actions Workflow Status

            License

            Github Created At

            NPM Downloads

        


    





![demo.gif](https://github.com/ndonfris/fish-lsp.dev/blob/ndonfris-patch-1/new_output.gif?raw=true)



Introducing the [fish-lsp](https://fish-lsp.dev), a [Language Server Protocol (LSP)](https://lsif.dev/) implementation for the [fish shell language](https://fishshell.com).



## Quick Start



Please choose a [method to install](#installation) the language server and [configure a client](#client-configuration-required) to use `fish-lsp` in your editor.



A detailed explanation of how a language server connection works is described in the [how it works](#how-does-it-work) section.



## Why? 🐟



- 🦈 __Efficiency__: enhances the shell scripting experience with an extensive suite of intelligent text-editing [features](#features)



- 🐡 __Flexibility__: allows for a highly customizable [configuration](#server-configuration-optional)



- 🐚 __Guidance__: [friendly hints](https://github.com/ndonfris/fish-lsp/?tab=readme-ov-file#) and [documentation](#installation) to comfortably explore command line tooling



- 🐬 __Community__: improved by a [vibrant user base](#contributors), with [supportive and insightful feedback](https://github.com/ndonfris/fish-lsp/discussions)



- 🐙 __Compatibility__: integrates with a wide variety of [tooling and language clients](#client-configuration-required)



- 🌊 __Reliability__: produces an [editor agnostic developer environment](https://en.wikipedia.org/wiki/Language_Server_Protocol),

     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 | ✅  |

| __Inlay Hint__ | Shows Virtual Text/Inlay Hints | ✅  |

| __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 ` | ✅ |

| __Client Tree__ | Shows the defined scope as a Tree | ✅ |

| __Indexing__ | Indexes all commands, variables, and functions | ✅ |



## Installation



Some language clients might support downloading the fish-lsp directly from within the client, but for the most part, you'll typically be required to install the language server manually.



Below are a few methods to install the language server, and how to verify that it's working.



### Use a Package Manager



Stability across package managers can vary. Consider using another installation method if issues arise.



```bash

npm install -g fish-lsp



yarn global add fish-lsp



pnpm install -g fish-lsp



nix-shell -p fish-lsp



brew install fish-lsp

```



If you installed the language server using a __node__ based package manager (__i.e. npm/yarn/pnpm__), you can install the completions by running the following command:



```fish

fish-lsp complete > ~/.config/fish/completions/fish-lsp.fish

```



### Build from Source



Recommended Dependencies: `[email protected]` `[email protected]` `[email protected]`



```bash

git clone https://github.com/ndonfris/fish-lsp && cd fish-lsp

yarn install 

yarn dev # to watch for changes use `yarn dev:watch` 

```



Using the `yarn dev:watch` command will automatically rebuild the project when changes are detected. This allows easy testing of new features or bug fixes, if you're interested in contributing.



Building the project from source is the most portable method for installing the language server.



### Verifying Installation



After installation, verify that `fish-lsp` is working correctly:



```bash

fish-lsp --help

```



![fish-lsp --help](https://github.com/ndonfris/fish-lsp.dev/blob/master/public/help-msg-new.png?raw=true)



## Setup



To properly configure [fish-lsp](https://fish-lsp.dev), you need to define a client configuration after installing the language server.



Configuring a client should be relatively straightforward. Typically, you're only required to translate the shell command `fish-lsp start` for `fish` files, in the [client's configuration](#client-configuration-required). However, further configuration can be specified as a [server configuration](#server-configuration-optional).



Some clients may also allow specifying the server configuration directly in the client configuration.



### 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](https://github.com/ndonfris/fish-lsp/wiki/Client-Configurations) of your choice, or [submit a PR](https://github.com/ndonfris/fish-lsp-language-clients/pulls) for new configurations.



  neovim (v0.8)



  Full table of options available in the [neovim documentation](https://neovim.io/doc/user/lsp.html)



  ```lua

  vim.api.nvim_create_autocmd('FileType', {

    pattern = 'fish',

    callback = function()

      vim.lsp.start({

        name = 'fish-lsp',

        cmd = { 'fish-lsp', 'start' },

        cmd_env = { fish_lsp_show_client_popups = false },

      })

    end,

  })

  ```



  Alternatively, you can also see official documentation for [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#fish_lsp), or use your client of choice below.



  coc.nvim



  [Neovim](https://neovim.io) client using [coc.nvim](https://github.com/neoclide/coc.nvim) configuration, located inside [coc-settings.json](https://github.com/neoclide/coc.nvim/wiki/Language-servers#register-custom-language-servers) `"languageserver"` key



  ```json

  {

    "fish-lsp": {

      "command": "fish-lsp",

      "filetypes": ["fish"],

      "args": ["start"]

    }

  }

  ```



  YouCompleteMe



  [YouCompleteMe](https://github.com/ycm-core/YouCompleteMe) configuration for vim/neovim



  ```vim

  let g:ycm_language_server =

            \ [

            \   {

            \       'name': 'fish',

            \       'cmdline': [ 'fish-lsp', 'start' ],

            \       'filetypes': [ 'fish' ],

            \   }

            \ ]

  ```



  vim-lsp



  Configuration of [prabirshrestha/vim-lsp](https://github.com/prabirshrestha/vim-lsp) in your `init.vim` or `init.lua` file



  ```vim

  if executable('fish-lsp')

    au User lsp_setup call lsp#register_server({

        \ 'name': 'fish-lsp',

        \ 'cmd': {server_info->['fish-lsp', 'start']},

        \ 'allowlist': ['fish'],

        \ })

  endif

  ```



  helix



  In config file `~/.config/helix/languages.toml`



  ```toml

  [[language]]

  name = "fish"

  language-servers = [ "fish-lsp" ]

  

  [language-server.fish-lsp]

  command = "fish-lsp"

  args= ["start"]

  environment = { "fish_lsp_show_client_popups" = "false" }

  ```



  kakoune



  Configuration for [kakoune-lsp](https://github.com/kakoune-lsp/kakoune-lsp), located in `~/.config/kak-lsp/kak-lsp.toml`



  ```toml

  [language.fish]

  filetypes = ["fish"]

  command = "fish-lsp"

  args = ["start"]



  ```



  Or in your `~/.config/kak/lsp.kak` file



  ```kak

  hook -group lsp-filetype-fish global BufSetOption filetype=fish %{

      set-option buffer lsp_servers %{

          [fish-lsp]

          root_globs = [ "*.fish", "config.fish", ".git", ".hg" ]

          args = [ "start" ]

      }

  }

  ```



  kate



  Configuration for [kate](https://kate-editor.org/)



  ```json

  {

    "servers": {

      "fish": {

        "command": ["fish-lsp", "start"],

        "url": "https://github.com/ndonfris/fish-lsp",

        "highlightingModeRegex": "^fish$"

      }

    }

  }

  ```



  emacs



  Configuration using [eglot](https://github.com/joaotavora/eglot) (Built into Emacs 29+)



  ```elisp

  ;; Add to your init.el or .emacs

  (require 'eglot)



  (add-to-list 'eglot-server-programs

    '(fish-mode . ("fish-lsp" "start")))



  ;; Optional: auto-start eglot for fish files

  (add-hook 'fish-mode-hook 'eglot-ensure)

  ```



  or place in your `languages/fish.el` file



  ```elisp

  (use-package fish-mode)



  (with-eval-after-load 'eglot

    (add-to-list 'eglot-server-programs

                 '(fish-mode . ("fish-lsp" "start"))))

  ```



  



  Configuration using [lsp-mode](https://github.com/emacs-lsp/lsp-mode)



  ```elisp

  ;; Add to your init.el or .emacs

  (require 'lsp-mode)



  (lsp-register-client

   (make-lsp-client

    :new-connection (lsp-stdio-connection '("fish-lsp" "start"))

    :activation-fn (lsp-activate-on "fish")

    :server-id 'fish-lsp))



  ;; Optional: auto-start lsp for fish files

  (add-hook 'fish-mode-hook #'lsp)

  ```



  Full example configuration using [doom-emacs](https://github.com/doomemacs/doomemacs/tree/master) can be found in the [fish-lsp language clients repo](https://github.com/ndonfris/fish-lsp-language-clients/).



  vscode



  > To download the extension, visit the [fish-lsp extension on the VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=ndonfris.fish-lsp).

  >

  > VSCode configuration does not require a client configuration. The server will automatically start when a `.fish` file is opened.

  >

  > A server configuration can still be specified to control the server's behavior. ([see below](#server-configuration-optional))



### Server Configuration (Optional)



Specific functionality for the server can be set independently from the client. The server allows for both [environment variables](#environment-variables) and [command flags](#command-flags) to customize how specific server processes are started.



#### Environment variables



> Generated by `fish-lsp env --create`



```fish

# fish_lsp_enabled_handlers 

# enables the fish-lsp handlers (options: 'popups', 'formatting', 'complete', 'hover', 'rename', 'definition', 'references', 'diagnostics', 'signatureHelp', 'codeAction', 'inlayHint', 'highlight')

set -gx fish_lsp_enabled_handlers



# fish_lsp_disabled_handlers 

# disables the fish-lsp handlers (options: 'popups', 'formatting', 'complete', 'hover', 'rename', 'definition', 'references', 'diagnostics', 'signatureHelp', 'codeAction', 'inlayHint', 'highlight')

set -gx fish_lsp_disabled_handlers



# fish_lsp_commit_characters 

# 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 

# path to the logs.txt file (default: '')

# example locations could be: '~/path/to/fish-lsp/logs.txt' or '/tmp/fish_lsp.logs'

set -gx fish_lsp_logfile



# fish_lsp_all_indexed_paths 

# fish file paths/workspaces to include as workspaces (default: ["$HOME/.config/fish", '/usr/share/fish'])

set -gx fish_lsp_all_indexed_paths



# fish_lsp_modifiable_paths 

# 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 

# disable diagnostics for matching error codes (default: [])

# (options: 1001, 1002, 1003, 1004, 2001, 2002, 2003, 3001, 3002, 3003, 4001, 4002, 4003, 4004, 5001, 8001)

set -gx fish_lsp_diagnostic_disable_error_codes



# fish_lsp_max_background_files 

# 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 

# show popup window notification in the connected client (default: true)

# DISABLING THIS MIGHT BE REQUIRED FOR SOME CLIENTS THAT DO NOT SUPPORT POPUPS

set -gx fish_lsp_show_client_popups

```



If you're interested in disabling specific diagnostic messages, the [wiki](https://github.com/ndonfris/fish-lsp/wiki) includes a table of [error codes](https://github.com/ndonfris/fish-lsp/wiki/Diagnostic-Error-Codes) that should be helpful. Diagnostics are a newer feature so [PRs](https://github.com/ndonfris/fish-lsp/blob/master/docs/CONTRIBUTING.md#getting-started-rocket) are welcome to improve their support.



Alternatively, you can now __use comments__ to disable diagnostics.



```fish

# @fish-lsp-disable-next-line 

alias ls='ls -G' # all diagnostics have been disabled for this line



# @fish-lsp-disable 2001

alias ll='ls -l' # only the diagnostic 2001 has been disabled for this line



# @fish-lsp-enable

## all diagnostics are re-enabled till the next @fish-lsp-disable for this file



# @fish-lsp-disable 2001 2002

## now both diagnostics 2001 and 2002 have been disabled for the rest of this file

alias la='ls -la'

```



#### Command Flags



Both the flags `--enable` and `--disable` are provided on the `fish-lsp start` subcommand. __By default, all handlers will be enabled__.



```fish

# 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](#command-flags) will overwrite their corresponding [environment variables](#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](https://fishshell.com/docs/current/language.html#functions) or [aliases](https://fishshell.com/docs/current/language.html#defining-aliases).



  Example edit_command_buffer wrapper to conditionally disable specific fish-lsp features



  > ```fish

  > function edit_command_buffer_wrapper --description 'edit command buffer with custom server configurations'

  >   # place any CUSTOM server configurations here

  >   set -lx fish_lsp_diagnostic_disable_error_codes 1001 1002 1003 1004 2001 2002 2003 3001 3002 3003 

  >   set -lx fish_lsp_show_client_popups false

  > 

  >   # open the command buffer with the custom server configuration, without

  >   # overwriting the default server settings

  >   edit_command_buffer

  > end

  > bind \ee edit_command_buffer_wrapper

  > # now pressing alt+e in an interactive command prompt will open fish-lsp with the

  > # options set above, but opening the `$EDITOR` normally will still behave as expected

  > ```

  >

  > This allows normal editing of fish files to keep their default behaviour, while disabling unwanted server features for _"interactive"_ buffers.



Due to the vast possibilities this project aims to support in the fish shell, [sharing useful configurations is highly encouraged](https://github.com/ndonfris/fish-lsp/discussions).



## How does it work?



If you're new to the concept of the [Language Server Protocol (LSP)](https://lsif.dev), this section should be useful to help you grasp its core purpose and benefits.



> 📸 Check out [this insightful video](https://youtu.be/LaS32vctfOY?si=MISP8tL_HU06-_z-) 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_.



Show a diagram to visualize a hypothetical fish-lsp process



![graph](https://github.com/ndonfris/fish-lsp.dev/blob/master/public/mermaid-diagram.png?raw=true)



## Additional Resources



- [Contributing](./docs/CONTRIBUTING.md) - documentation describing how to contribute to the fish-lsp project.

- [Roadmap](./docs/ROADMAP.md) - goals for future project releases.

- [Wiki](https://github.com/ndonfris/fish-lsp/wiki) - further documentation and knowledge relevant to the project

- [Discussions](https://github.com/ndonfris/fish-lsp/discussions) - interact with maintainers

- [Site](https://fish-lsp.dev/) - website homepage

- [Client Examples](https://github.com/ndonfris/fish-lsp/wiki/Client-Configurations) - testable language client configurations

- [Sources](https://github.com/ndonfris/fish-lsp/wiki/Sources) - major influences for the project



## Contributors



Special thanks to anyone who contributed to the project!

Contributions of any kind are welcome!



  

    

      nick
nick
💻

      mimikun
mimikun
💻

      Jaakko Paju
Jaakko Paju
💻

      Sean Perry
Sean Perry
💻

      Fabio Coatti
Fabio Coatti
💻

      Peter Cardenas
Peter Cardenas
💻

      Peter Tri Ho
Peter Tri Ho
💻

    

    

      bnwa
bnwa
💻

      Branch Vincent
Branch Vincent
💻

      Jaeseok Lee
Jaeseok Lee
💻

      ClanEver
ClanEver
💻

    

  



This project follows the [all-contributors](https://allcontributors.org) specification.



## License



[MIT](https://github.com/ndonfris/fish-lsp/blob/master/LICENSE.md)