{"id":16607664,"url":"https://github.com/coder3101/protols","last_synced_at":"2026-05-23T12:01:55.184Z","repository":{"id":243604756,"uuid":"812879930","full_name":"coder3101/protols","owner":"coder3101","description":"Language Server for protocol buffers","archived":false,"fork":false,"pushed_at":"2025-03-31T15:56:54.000Z","size":5166,"stargazers_count":99,"open_issues_count":1,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-12T13:49:17.038Z","etag":null,"topics":["lsp-server","proto3","protobuf"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coder3101.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["coder3101"]}},"created_at":"2024-06-10T04:41:37.000Z","updated_at":"2025-04-06T13:46:33.000Z","dependencies_parsed_at":"2024-06-10T05:47:51.639Z","dependency_job_id":"b60e087f-b823-4711-b69d-0f67a3cc7d22","html_url":"https://github.com/coder3101/protols","commit_stats":null,"previous_names":["coder3101/protols"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder3101%2Fprotols","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder3101%2Fprotols/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder3101%2Fprotols/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coder3101%2Fprotols/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coder3101","download_url":"https://codeload.github.com/coder3101/protols/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248642510,"owners_count":21138351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lsp-server","proto3","protobuf"],"created_at":"2024-10-12T01:23:29.705Z","updated_at":"2026-05-23T12:01:55.177Z","avatar_url":"https://github.com/coder3101.png","language":"Rust","funding_links":["https://github.com/sponsors/coder3101"],"categories":[],"sub_categories":[],"readme":"# Protols - Protobuf Language Server\n\n[![Crates.io](https://img.shields.io/crates/v/protols.svg)](https://crates.io/crates/protols)  \n[![Build and Test](https://github.com/coder3101/protols/actions/workflows/ci.yml/badge.svg)](https://github.com/coder3101/protols/actions/workflows/ci.yml)\n\n**Protols** is an open-source, feature-rich [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) for **Protocol Buffers (proto)** files. Powered by the efficient [tree-sitter](https://tree-sitter.github.io/tree-sitter/) parser, Protols offers intelligent code assistance for protobuf development, including features like auto-completion, diagnostics, formatting, and more.\n\n## ✨ Features\n\n- ✅ **Code Completion**: Auto-complete messages, enums, and keywords in your `.proto` files.\n- ✅ **Diagnostics**: Syntax errors, import error with tree-sitter and advanced diagnostics from `protoc`.\n- ✅ **Workspace Symbols**: Search and view all symbols across workspaces.\n- ✅ **Document Symbols**: Navigate and view all symbols, including nested messages and enums.\n- ✅ **Code Formatting**: Format `.proto` files using `clang-format` for a consistent style.\n- ✅ **Go to Definition**: Jump to the definition of symbols like messages or enums and imports.\n- ✅ **Hover Information**: Get detailed information and documentation on hover.\n- ✅ **Rename Symbols**: Rename protobuf symbols and propagate changes across the codebase.\n- ✅ **Find References**: Find where messages, enums, and fields are used throughout the codebase.\n\n---\n\n## Table of Contents\n\n- [Installation](#-installation)\n  - [For Neovim](#for-neovim)\n    - [Setting Include Paths in Neovim](#setting-include-paths-in-neovim)\n  - [Command Line Options](#command-line-options)\n    - [Examples](#examples)\n  - [For Visual Studio Code](#for-visual-studio-code)\n- [Configuration](#%EF%B8%8Fconfiguration)\n  - [Sample `protols.toml`](#sample-protolstoml)\n  - [Configuration Sections](#configuration-sections)\n    - [Basic Configuration](#basic-configuration)\n    - [Path Configuration](#path-configuration)\n    - [Rename Configuration](#rename-configuration)\n- [Usage](#-usage)\n  - [Code Completion](#code-completion)\n  - [Diagnostics](#diagnostics)\n  - [Code Formatting](#code-formatting)\n  - [Workspace Symbols](#workspace-symbols)\n  - [Document Symbols](#document-symbols)\n  - [Go to Definition](#go-to-definition)\n  - [Hover Information](#hover-information)\n  - [Rename Symbols](#rename-symbols)\n  - [Find References](#find-references)\n- [Protocol Buffers Well-Known Types](#protocol-buffers-well-known-types)\n- [Packaging](#-packaging)\n- [Contributing](#-contributing)\n  - [Setting Up Locally](#setting-up-locally)\n    - [Option 1: Using Dev Containers (Easiest)](#option-1-using-dev-containers-easiest)\n    - [Option 2: Manual Setup](#option-2-manual-setup)\n  - [Debugging](#-debugging)\n- [License](#-license)\n\n---\n\n## 🚀 Installation\n\n### For Neovim\n\nYou can install **Protols** via [mason.nvim](https://github.com/mason-org/mason-registry/blob/main/packages/protols/package.yaml), or install it directly from [crates.io](https://crates.io/crates/protols):\n\n```bash\ncargo install protols\n```\n\nThen, configure it in your `init.lua` using [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig):\n\n```lua\nrequire'lspconfig'.protols.setup{}\n```\n\n#### Setting Include Paths in Neovim\n\nFor dynamic configuration of include paths, you can use the `before_init` callback to set them via `initializationParams`:\n\n```lua\nrequire'lspconfig'.protols.setup{\n  before_init = function(_, config)\n    config.init_options = {\n      include_paths = {\n        \"/usr/local/include/protobuf\",\n        \"vendor/protos\",\n        \"../shared-protos\"\n      }\n    }\n  end\n}\n```\n\n### Command Line Options\n\nProtols supports various command line options to customize its behavior:\n\n```text\nUsage: protols [OPTIONS]\n\nOptions:\n  -i, --include-paths \u003cINCLUDE_PATHS\u003e  Include paths for proto files, comma-separated (can be used multiple times)\n  -h, --help                           Print help\n  -V, --version                        Print version\n\nTransport:\n      --stdio          Use stdin/stdout for communication (default)\n      --socket \u003cADDR\u003e  Use TCP communication with a specific address and port. Examples: \"192.168.1.10:5005\" or \"0.0.0.0:5005\"\n      --port \u003cPORT\u003e    Use TCP communication on localhost with a specific port. Example: \"5005\"\n      --pipe \u003cPATH\u003e    Use Unix domain socket (Linux/macOS) or Named Pipe (Windows). Examples: \"/tmp/protols.sock\" or \"protols-pipe\" (Windows)\n```\n\n#### Examples\n\n##### Specify include paths\n\nYou can provide include paths using a comma-separated list or by repeating the\nflag:\n\n```bash\nprotols --include-paths=/path/to/protos,/another/path/to/protos\n# or\nprotols -i /path/to/protos -i /another/path/to/protos\n```\n\n##### Communication via TCP\nTCP transport is useful when the language server and the IDE run in different\nenvironments.\n\n-   **Localhost only**: Connect within the same machine.\n    ```bash\n    protols --port 7301\n    ```\n-   **Container/Docker mode**: Listen on all interfaces to allow access from the\n    host machine to the container.\n    ```bash\n    protols --socket 0.0.0.0:7301\n    ```\n-   **Specific interface**: Listen on a specific network IP.\n    ```bash\n    protols --socket 192.168.1.10:7301\n    ```\n\n##### Communication via Unix Domain Socket\nOn Linux or macOS, you can use a socket file for communication:\n```bash\nprotols --pipe /tmp/protols.sock\n```\n\n##### Communication via Named Pipes (Windows)\nOn Windows, you can specify a pipe name. `protols` handles the `\\\\.\\pipe\\` prefix automatically:\n```bash\nprotols --pipe protols-pipe\n```\n\n### For Visual Studio Code\n\nIf you're using Visual Studio Code, you can install the [Protobuf Language Support](https://marketplace.visualstudio.com/items?itemName=ianandhum.protobuf-support) extension, which uses this LSP under the hood.\n\n\u003e **Note**: This extension is [open source](https://github.com/ianandhum/vscode-protobuf-support), but is not officially maintained by us.\n\n---\n\n## ⚙️Configuration\n\nProtols can be configured using a `protols.toml` file, which you can place in root of your project directory.\n\n### Sample `protols.toml`\n\n```toml\n[config]\ninclude_paths = [\"foobar\", \"bazbaaz\"] # Include paths to look for protofiles during parsing\n\n[config.path]\nclang_format = \"clang-format\"\nprotoc = \"protoc\"\n\n[config.rename]\nchain_rpc_request_response = false # Also rename \u003cRpc\u003eRequest/\u003cRpc\u003eResponse messages when renaming an rpc\n```\n\n### Configuration Sections\n\n#### Basic Configuration\n\nThe `[config]` section contains stable settings that should generally remain unchanged.\n\n- `include_paths`: These are directories where `.proto` files are searched. Paths can be absolute or relative to the LSP workspace root, which is already included in the `include_paths`. You can also specify include paths using:\n  - **Configuration file**: Workspace-specific paths defined in `protols.toml`\n  - **Command line**: Global paths using `--include-paths` flag that apply to all workspaces\n  - **Initialization parameters**: Dynamic paths set via LSP `initializationParams` (useful for editors like Neovim)\n\n  When a file is not found in any of the paths above, the following directories are searched:\n  - **Protobuf Include Path**: the path containing the [Protocol Buffers Well-Known Types](https://protobuf.dev/reference/protobuf/google.protobuf/) as detected by [`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/) (requires `pkg-config` present in environment and capable of finding the installation of `protobuf`)\n  - **Fallback Include Path**: the fallback include path configured at compile time\n\n\n  All include paths from these sources are combined when resolving proto imports.\n\n#### Path Configuration\n\nThe `[config.path]` section contains path for various tools used by LSP.\n\n- `clang_format`: Uses clang_format from this path for formatting\n- `protoc`: Uses protoc from this path for diagnostics\n\n#### Rename Configuration\n\nThe `[config.rename]` section tunes rename behaviour.\n\n- `chain_rpc_request_response` (default `false`): when enabled, renaming an `rpc`\n  also renames its convention-named `\u003cRpc\u003eRequest` and `\u003cRpc\u003eResponse` messages —\n  and renaming such a message renames the `rpc` and its sibling message. The chain\n  only fires when the names follow the [Google API design guide](https://cloud.google.com/apis/design/naming_convention#request_and_response_messages)\n  convention and the messages are used by exactly one `rpc`.\n\n---\n\n## 🛠 Usage\n\nProtols offers a rich set of features to enhance your `.proto` file editing experience.\n\n### Code Completion\n\n**Protols** offers intelligent autocompletion for messages, enums, and proto3 keywords within the current package. Simply start typing, and Protols will suggest valid completions.\n\n### Diagnostics\n\nSyntax errors are caught by the tree-sitter parser, which highlights issues directly in your editor. More advanced error reporting, is done by `protoc` which runs after a file saved. You must have `protoc` installed and added to your path or you can specify its path in the configuration above\n\n### Code Formatting\n\nFormat your `.proto` files using `clang-format`. To customize the formatting style, add a `.clang-format` file to the root of your project. Both document and range formatting are supported.\n\n### Workspace Symbols\n\nProtols implements workspace symbol capabilities allowing you to search for symbols across workspace or list them, including nested symbols such as messages and enums. This allows for easy navigation and reference across workspace.\n\n### Document Symbols\n\nProtols provides a list of symbols in the current document, including nested symbols such as messages and enums. This allows for easy navigation and reference.\n\n### Go to Definition\n\nJump directly to the definition of any custom symbol or imports, including those in other files or packages. This feature works across package boundaries.\n\n### Hover Information\n\nHover over any symbol or imports to get detailed documentation and comments associated with it. This works seamlessly across different packages and namespaces.\n\n### Rename Symbols\n\nRename symbols like messages, enums, services and RPC methods, and propagate the changes throughout the codebase. Rename also works when invoked on a type reference (e.g. the request or response type of an `rpc`) — the LSP pivots to the declaration and applies the rename from there. Field names, oneof names, and enum values can also be renamed at their declaration site (single-site rename, since they aren't referenced as types from other `.proto` files).\n\nWhen an `rpc` follows the `rpc \u003cName\u003e(\u003cName\u003eRequest) returns (\u003cName\u003eResponse)` convention from the [Google API design guide](https://google.aip.dev/) (AIPs 131–136), renaming any one of the three triggers a chained rename of the other two — but only when (a) the matching message name follows the convention exactly, (b) the request/response is used by exactly one rpc in the workspace, and (c) the user's new name preserves the convention. If any check fails, only the symbol the user invoked rename on is renamed.\n\n### Find References\n\nFind all references to user-defined types like messages or enums. Nested fields are fully supported, making it easier to track symbol usage across your project.\n\n## Protocol Buffers Well-Known Types\n\nProtols does not ship with the [Protocol Buffers Well-Known Types](https://protobuf.dev/reference/protobuf/google.protobuf/) unless configured to do so by a distribution.\nIn order for features above to work for the well-known types, the well-known imports must either resolve against one of the configured import paths or the environment must contain in `PATH` a `pkg-config` executable capable of resolving the package `protobuf`.\nYou can verify this by running\n\n```bash\npkg-config --modversion protobuf\n```\n\nin protols' environment.\n\n---\n\n## 📦 Packaging\n\nDistributions may set an absolute include path which contains the Protocol Buffers Well-Known Types,\nfor example pointing to the files provided by the `protobuf` package, by compiling protols with the\nenvironment variable `FALLBACK_INCLUDE_PATH` set to the desired path. This path will be used by the\ncompiled executable for resolution of any proto files that could not be resolved otherwise.\n\n## 🤝 Contributing\n\nWe welcome contributions from developers of all experience levels! To get started:\n\n1. **Fork** the repository and clone it to your local machine.\n2. Create a **new branch** for your feature or fix.\n3. Run the tests to ensure everything works as expected.\n4. **Open a pull request** with a detailed description of your changes.\n\n### Setting Up Locally\n\n#### Option 1: Using Dev Containers (Easiest)\n\nThe project includes a pre-configured **Dev Container**, which sets up Rust,\nNeovim, and all dependencies automatically.\n\n**Prerequisites:**\n\n- [Docker](https://docker.com) installed and running.\n  - (Windows users)\n  [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) must be enabled.\n- An IDE that supports Dev Containers (e.g., **Visual Studio Code** with the\n[Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)).\n\n**Steps:**\n\n1. Open the project folder in your IDE.\n2. If using Visual Studio Code, click **\"Reopen in Container\"** in the pop-up\nnotification or via the Command Palette (`F1` -\u003e `Dev Containers: Reopen in Container`).\n3. The environment will be built automatically. Once finished, you can start\ndeveloping immediately.\n\n\u003e [!TIP]\n\u003e A pre-configured **Neovim** is included in the container for instant LSP\ntesting.\n\n#### Option 2: Manual Setup\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/coder3101/protols.git\n   cd protols\n   ```\n\n2. Build and test the project:\n\n   ```bash\n   cargo build\n   cargo test\n   ```\n\n### 🐞 Debugging\n\nIf you want to contribute or debug the server logic, please refer to the\n[Debugging Guide](docs/debugging.md) for instructions on setting up a TCP-based\ndebug session with VS Code and Neovim.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoder3101%2Fprotols","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoder3101%2Fprotols","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoder3101%2Fprotols/lists"}