== Using `lsp-mode`

=== Workspace/Session Management
For a language server to work with a file, it needs to know the *project root*,
a (usually higher-level) directory, containing the project to which the
file belongs to.

On opening a file in a new project, `lsp-mode` will try to guess the project
root, and present you with several options:

* Import the root directory `lsp-mode` guessed.
* Select a project root directory interactively (ask the user), and import it.
* Blacklist the guessed root directory, and ignore it in the future.
* Select a project root directory interactively, and blacklist it.
* Do nothing, but try importing the project again when any other file in the
  project is opened.

The root directory is then known to `lsp-mode` as a *workspace*, and every
file in the project is associated with it.

[id="session-file"]
The list of imported/whitelisted and blacklisted directories is stored in a
*Session File*, located at `~/.emacs.d/.lsp-session-v1` by default. Its
location can be changed by modifying <<lsp-session-file, `lsp-session-file`>>.

`lsp-mode` will try using https://github.com/bbatsov/projectile[Projectile]
(if installed), or the in-built project library `project.el` to guess the
root.

==== Logging
By default, `lsp-mode` will log everything to the the `*lsp-log*` buffer.
This can be controlled using <<lsp-log-max>>, which is set to
https://www.gnu.org/software/emacs/manual/html_node/elisp/Logging-Messages.html[message-log-max]
by default. Additionally, `lsp-mode` can log all LSP requests, responses
and notifications sent and received from a language server.

==== Workspace Management Commands

[id="lsp-workspace-folders-remove"]
===== `lsp-workspace-folders-remove PROJECT-ROOT`
If called interactively (through `M-x lsp-workspace-folders-remove RET`),
it will ask the user to select a directory from a list of project roots that
`lsp-mode` has yet imported. The selected directory will be removed from
the <<session file,session file>>, and currently opened workspaces under it will
be shut down (they will no longer be associated with a language server, and
wouldn't support `lsp-mode` features).
This only removes the directory from the <<session file, session file>>, and
opening any file from the removed project will cause `lsp-mode` to ask the
user about importing/blacklisting the directory again.

[id="lsp-workspace-folders-add"]
===== Function: `lsp-workspace-folders-add PROJECT-ROOT`
If called interactively, it will ask the user to select a directory, and
import it as a project root. All files located under the directory will be
treated as belonging to the project rooted at this directory.

[id="lsp-workspace-folders-open"]
===== Function: `lsp-workspace-folders-open PROJECT-ROOT`
If called interactively, it asks the user to choose from a list of imported
project roots, and opens the selected directory in `dired`.

[id="lsp-workspace-shutdown"]
===== Function: `lsp-workspace-shutdown WORKSPACE`
If called interactively, it asks the user to select an opened project,
and shuts down the workspace and the language server associated with it.

[id="lsp-workspace-restart"]
===== Function: `lsp-workspace-restart WORKSPACE`
If called interactively, it asks the user to select an opened project,
and restarts the workspace and the language server associated with it.

[id="lsp-workspace-blacklist-remove"]
===== Function: `lsp-workspace-blacklist-remove WORKSPACE`
If called interactively, it asks the user to select a blacklisted project,
and remove the project folder from the blacklist.
