Home

Awesome

Build status GNU ELPA MELPA

M-x Eglot

Emacs Polyglot is the Emacs LSP client that stays out of your way:

See also eglot-x for non-standard protocol extensions support.

Get stable GNU ELPA version

Just type M-x package-install RET eglot RET into Emacs 26.3+.

Now find some source file, any source file, and type M-x eglot.

That's it. If you're lucky, this guesses the LSP program to start for the language you're using. Otherwise, it prompts you to enter one.

Get latest development version from GNU-Devel ELPA

First, configure this repository.

(add-to-list 'package-archives '("gnu-devel" . "https://elpa.gnu.org/devel/"))

Then, use M-x package-install or M-x package-update to install an ELPA package from the latest upstream.

<a name=emacscore></a>

Contribute to Eglot's development

Eglot is now in Emacs's core! Upcoming Emacs 29 will have M-x eglot built-in.

The recommended way to experiment with changes to the latest Eglot is to compile Emacs yourself.

From a development perspective, moving to core allows us to work on Eglot in tandem with other related packages already in Emacs, such as Flymake, ElDoc, Xref, Project.

This means adding or tweaking an Emacs LSP feature is a matter of submitting a single patch targetting multiple relevant packages, not just Eglot.

These :core packages (Eglot included) are then released periodically to GNU ELPA, so users of other Emacs's versions can get them via M-x package-install.

Status of this GitHub repository

This repository is not the development upstream anymore, but it's not dead (yet):

<a name="connecting"></a>

Connecting to a server

These are just some of the servers that M-x eglot can use out of the box. The full list can be consulted in the eglot-server-programs variable, where you can easily add your own servers.

<a name="animated_gifs"></a>

Obligatory animated gif section

Completion

eglot-completions

The animation shows company-mode presenting the completion candidates to the user, but Eglot works with the built-in completion-at-point function as well, which is usually bound to C-M-i.

Snippet completion

eglot-snippets-on-completion

Eglot provides template based completion if the server supports snippet completion and yasnippet is enabled before Eglot connects to the server. The animation shows company-mode, but completion-at-point also works with snippets.

Diagnostics

eglot-diagnostics

Eglot relays the diagnostics information received from the LSP server to Emacs's Flymake, which annotates/underlines the problematic parts of the buffer. The information is shared with the ElDoc system, meaning that the commands eldoc and eldoc-doc-buffer (the latter bound to C-h-. for convenience) show diagnostics along with other documentation under point.

Flymake provides other convenient ways to view and manage diagnostic errors. These are described in its manual.

When Eglot manages a buffer, it disables pre-existing Flymake backends. See variable eglot-stay-out-of to change that.

Code Actions

eglot-code-actions

The LSP server may provide code actions, for example, to fix a diagnostic error or to suggest refactoring edits. The commands are frequently associating with Flymake diagnostic annotations, so that left-clicking them shows a menu. Additionally, the command eglot-code-actions asks the server for any code spanning a given region.

Sometimes, these code actions are initiated by the server. See eglot-confirm-server-initiated-edits to control that behaviour.

Hover on symbol /function signature

eglot-hover-on-symbol

Here, too, the LSP server's view of a given symbol or function signature is relayed to the ElDoc system. The commands eldoc and eldoc-doc-buffer commands access that information.

There are customization variables to help adjust ElDoc's liberal use of the lower "echo area", among other options. If you still find the solicitous nature of this LSP feature too distracing, you can use eglot-ignored-server-capabilities to turn it off.

Rename

eglot-rename

Type M-x eglot-rename RET to rename the symbol at point.

Find definition

eglot-xref-find-definition

To jump to the definition of a symbol, use the built-in xref-find-definitions command, which is bound to M-..

Find references

eglot-xref-find-references

Eglot here relies on Emacs' built-in functionality as well. xref-find-references is bound to M-?. Additionally, Eglot provides the following similar commands: eglot-find-declaration, eglot-find-implementation, eglot-find-typeDefinition.

Historical differences to lsp-mode.el

Around May 2018, I wrote a comparison of Eglot to lsp-mode.el, and was discussed with its then-maintainer. That mode has since been refactored/rewritten and now purports to support a lot of features that differentiated Eglot from it. It may now be very different or very similar to Eglot, or even sing with the birds in the trees, so go check it out. That said, here's the original comparison, which I will not be updating any more.

"Eglot is considerably less code and hassle than lsp-mode.el. In most cases, there's nothing to configure. It's a minimalist approach focused on user experience and performance.

User-visible differences:

Under the hood:

Copyright Assignment

Eglot is subject to the same copyright assignment policy as GNU Emacs.

Any legally significant contributions can only be merged after the author has completed their paperwork. Please ask for the request form, and we'll send it to you.

<!-- Language servers --> <!-- Other references -->