Skip to content

Documentation updates and reformatting #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Gogotchuri merged 2 commits into from
Aug 5, 2025
Merged

Documentation updates and reformatting #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8e4bed
Documentation updates and reformatting
Gogotchuri Aug 2, 2025
6e34797
Complete reformatting of docs
Gogotchuri Aug 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 17 additions & 49 deletions docs/SETTINGS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Clients which expose these config options to the end-user are advised to match t

The language server supports the following configuration options:

## `terraform` (object `{}`)
## `tofu` (object `{}`)

OpenTofu CLI related settings (used e.g. in formatting code via `tofu fmt`).

Expand All @@ -32,17 +32,17 @@ Path to the OpenTofu binary.
This is usually looked up automatically from `$PATH` and should not need to be
specified in majority of cases. Use this to override the automatic lookup.

## **DEPRECATED**: `terraformLogFilePath` (`string`)
## **DEPRECATED**: `tofuExecLogFilePath` (`string`)

Deprecated in favour of `terraform.logFilePath`
Deprecated in favour of `tofu.logFilePath`

## **DEPRECATED**: `terraformExecTimeout` (`string`)
## **DEPRECATED**: `tofuExecTimeout` (`string`)

Deprecated in favour of `terraform.timeout`
Deprecated in favour of `tofu.timeout`

## **DEPRECATED**: `terraformExecPath` (`string`)
## **DEPRECATED**: `tofuExecPath` (`string`)

Deprecated in favour of `terraform.path`
Deprecated in favour of `tofu.path`

## **DEPRECATED**: `rootModulePaths` (`[]string`)

Expand Down Expand Up @@ -76,7 +76,7 @@ of the target platform (e.g. `\` on Windows, or `/` on Unix),
symlinks are followed, trailing slashes automatically removed,
and `~` is replaced with your home directory.

## `ignoreDirectoryNames` (`[]string`)
### `ignoreDirectoryNames` (`[]string`)

This allows excluding directories from being indexed upon initialization by passing a list of directory names.

Expand Down Expand Up @@ -122,9 +122,10 @@ This object contains inner settings used to opt into experimental features not y

### `validateOnSave` (`bool`)

Enabling this feature will run terraform validate within the folder of the file saved. This comes with some user experience caveats.
- Validation is not run on file open, only once it's saved.
- When editing a module file, validation is not run due to not knowing which "rootmodule" to run validation from (there could be multiple). This creates an awkward workflow where when saving a file in a rootmodule, a diagnostic is raised in a module file. Editing the module file will not clear the diagnostic for the reason mentioned above, it will only clear once a file is saved back in the original "rootmodule". We will continue to attempt improve this user experience.
Enabling this feature will run `tofu validate` within the folder of the file saved. This comes with some user experience caveats.

- Validation is not run on file open, only once it's saved.
- When editing a module file, validation is not run due to not knowing which "rootmodule" to run validation from (there could be multiple). This creates an awkward workflow where when saving a file in a rootmodule, a diagnostic is raised in a module file. Editing the module file will not clear the diagnostic for the reason mentioned above, it will only clear once a file is saved back in the original "rootmodule". We will continue to attempt improve this user experience.

### `prefillRequiredFields` (`bool`)

Expand All @@ -148,49 +149,16 @@ Enables/disables enhanced validation, as documented under [`validation.md`](vali
The server expects static settings to be passed as part of LSP `initialize` call,
but how settings are requested from on the UI side depends on the client.

### Sublime Text

Use `initializationOptions` key under the `clients.terraform` section, e.g.

```json
{
"clients": {
"terraform": {
"initializationOptions": {
"rootModulePaths": ["/any/path"]
},
}
}
}
```
or
```json
{
"clients": {
"terraform": {
"initializationOptions": {
"excludeModulePaths": ["/any/path"]
},
}
}
}
```

### VS Code

Use `tofu-ls`, e.g.

```json
{
"tofu-ls": {
"rootModulePaths": ["/any/path"]
}
"tofu-ls": {
"tofu": {
"path": "path/to/tofu/binary"
}
}
}
```
or
```json
{
"tofu-ls": {
"excludeRootModules": ["/any/path"]
}
}
79 changes: 21 additions & 58 deletions docs/TROUBLESHOOTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,14 @@ in the default "stdio" mode where stdout & stdin are used as communication
channels for LSP. For example:

<!-- TODO: Update this link when we get a better display and itemName. See https://github.com/opentofu/vscode-opentofu/issues/30 -->

[**OpenTofu VS Code Extension**](https://marketplace.visualstudio.com/items?itemName=opentofu.vscode-opentofu)

1. `View` -> `Output`\
![vscode-view-output-menu](./images/vscode-view-output-menu.png)
2. `Output` -> `OpenTofu`\
![vscode-output-pane](./images/vscode-output-pane.png)

[**Sublime Text LSP-terraform**](https://github.com/sublimelsp/LSP-terraform)

1. Open the command palette via `⌘/Ctrl + Shift + P`
2. `LSP: Toggle Log Panel`\
![sublime-text-cmd-palette-log](./images/sublime-text-cmd-palette-log.png)
3. See logs in the bottom pane\
![sublime-text-log-panel](./images/sublime-text-log-panel.png)

### Logging to Files

Server logs can also be directed to files using **`-log-file=<filepath>`**
Expand All @@ -39,28 +32,14 @@ $ tofu-ls serve -log-file='/tmp/tofu-ls-{{pid}}.log'
```

Clients which manage LS installation typically allow passing extra arguments.
For example:

<!-- TODO: Update this link when we get a better display and itemName. See https://github.com/opentofu/vscode-opentofu/issues/30 -->
[**OpenTofu VS Code Extension**](https://marketplace.visualstudio.com/items?itemName=opentofu.vscode-opentofu)

1. Open the command palette via `⌘/Ctrl + Shift + P`
2. ![vscode-open-settings-json](./images/vscode-open-settings-json.png)
3. ![vscode-json-ls-settings](./images/vscode-json-ls-settings.png)

[**Sublime Text LSP-terraform**](https://github.com/sublimelsp/LSP-terraform)

1. Open the command palette via `⌘/Ctrl + Shift + P`
2. ![sublime-text-cmd-palette-settings](./images/sublime-text-cmd-palette-settings.png)
3. ![sublime-text-settings](./images/sublime-text-settings.png)

### OpenTofu CLI Execution Logs

Given that the server may also execute OpenTofu itself, it may be useful
to collect logs from all these executions too. This is equivalent
to setting [`TF_LOG_PATH` variable](https://www.terraform.io/internals/debugging).
to setting [`TF_LOG_PATH` variable](https://opentofu.org/docs/internals/debugging/).

This can be enabled via [`terraformLogFilePath` LSP settings](./SETTINGS.md#terraformlogfilepath-string).
This can be enabled via [`tofu.logFilePath` LSP settings](./SETTINGS.md#logfilepath-string).

Clients which manage LS installation typically expose this as a dedicated setting option.
For example:
Expand All @@ -69,21 +48,7 @@ For example:

1. Open the command palette via `⌘/Ctrl + Shift + P`
2. ![vscode-open-settings-json](./images/vscode-open-settings-json.png)
3. Set `"tofu-ls.terraformLogFilePath"` to a file path, such as `/tmp/tf-exec-{{lsPid}}-{{method}}-{{timestamp}}.log`

<!-- TODO: We don't have a Sublime Text LSP yet -->
<!-- [**Sublime Text LSP-terraform**](https://github.com/sublimelsp/LSP-terraform) -->

1. Open the command palette via `⌘/Ctrl + Shift + P`
2. ![sublime-text-cmd-palette-settings](./images/sublime-text-cmd-palette-settings.png)
3. Set `terraformLogFilePath` under `initializationOptions`
```json
{
"initializationOptions": {
"terraformLogFilePath": "/tmp/tf-exec-{{lsPid}}-{{method}}-{{timestamp}}.log"
}
}
```
3. Set `"tofu-ls.tofu.logFilePath"` to a file path, such as `/tmp/tf-exec-{{lsPid}}-{{method}}-{{timestamp}}.log`

### How To Share Logs

Expand All @@ -95,9 +60,7 @@ and attach the link to your issue/comment, or [attach the file to your issue/com

### Sensitive Data

Logs may contain sensitive data (such as content of the files being edited in the editor).
If you consider the content sensitive you may PGP encrypt it using [HashiCorp's key](https://www.hashicorp.com/security#secure-communications)
to reduce the exposure of the sensitive data to HashiCorp.
Be careful and review your logs before submitting the issue. Logs may contain sensitive data (such as content of the files being edited in the editor).

### Log Rotation

Expand All @@ -111,21 +74,21 @@ templated paths (as described below) may produce many log files over time.

Log paths support template syntax. This allows for separation of logs while accounting for:

- multiple server instances
- multiple clients
- multiple OpenTofu executions which may happen in parallel
- multiple server instances
- multiple clients
- multiple OpenTofu executions which may happen in parallel

**`-log-file`** flag supports the following functions:

- `timestamp` - current timestamp (formatted as [`Time.Unix()`](https://golang.org/pkg/time/#Time.Unix), i.e. the number of seconds elapsed since January 1, 1970 UTC)
- `pid` - process ID of the language server
- `ppid` - parent process ID (typically editor's or editor plugin's PID)
- `timestamp` - current timestamp (formatted as [`Time.Unix()`](https://golang.org/pkg/time/#Time.Unix), i.e. the number of seconds elapsed since January 1, 1970 UTC)
- `pid` - process ID of the language server
- `ppid` - parent process ID (typically editor's or editor plugin's PID)

**`terraformLogFilePath`** option supports the following functions:
**`tofu.logFilePath`** option supports the following functions:

- `timestamp` - current timestamp (formatted as [`Time.Unix()`](https://golang.org/pkg/time/#Time.Unix), i.e. the number of seconds elapsed since January 1, 1970 UTC)
- `lsPid` - process ID of the language server
- `lsPpid` - parent process ID of the language server (typically editor's or editor plugin's PID)
- `timestamp` - current timestamp (formatted as [`Time.Unix()`](https://golang.org/pkg/time/#Time.Unix), i.e. the number of seconds elapsed since January 1, 1970 UTC)
- `lsPid` - process ID of the language server
- `lsPpid` - parent process ID of the language server (typically editor's or editor plugin's PID)
- `method` - [`tofu-exec`](https://pkg.go.dev/github.com/opentofu/tofu-exec) method (e.g. `Format` or `Version`)

The path is interpreted as [Go template](https://golang.org/pkg/text/template/), e.g. `/tmp/tofu-ls-{{timestamp}}.log`.
Expand Down Expand Up @@ -153,9 +116,9 @@ Path supports template syntax. This allows for separation of logs while accounti

**`-cpuprofile`** supports the following functions:

- `timestamp` - current timestamp (formatted as [`Time.Unix()`](https://golang.org/pkg/time/#Time.Unix), i.e. the number of seconds elapsed since January 1, 1970 UTC)
- `pid` - process ID of the language server
- `ppid` - parent process ID (typically editor's or editor plugin's PID)
- `timestamp` - current timestamp (formatted as [`Time.Unix()`](https://golang.org/pkg/time/#Time.Unix), i.e. the number of seconds elapsed since January 1, 1970 UTC)
- `pid` - process ID of the language server
- `ppid` - parent process ID (typically editor's or editor plugin's PID)

The path is interpreted as [Go template](https://golang.org/pkg/text/template/), e.g. `/tmp/tofu-ls-cpuprofile-{{timestamp}}.log`.

Expand All @@ -182,8 +145,8 @@ Path supports template syntax. This allows for separation of logs while accounti

**`-memprofile`** supports the following functions:

- `timestamp` - current timestamp (formatted as [`Time.Unix()`](https://golang.org/pkg/time/#Time.Unix), i.e. the number of seconds elapsed since January 1, 1970 UTC)
- `pid` - process ID of the language server
- `ppid` - parent process ID (typically editor's or editor plugin's PID)
- `timestamp` - current timestamp (formatted as [`Time.Unix()`](https://golang.org/pkg/time/#Time.Unix), i.e. the number of seconds elapsed since January 1, 1970 UTC)
- `pid` - process ID of the language server
- `ppid` - parent process ID (typically editor's or editor plugin's PID)

The path is interpreted as [Go template](https://golang.org/pkg/text/template/), e.g. `/tmp/tofu-ls-memprofile-{{timestamp}}.log`.
9 changes: 3 additions & 6 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ flowchart LR
Out4 -.-> Result4["..."]
linkStyle default stroke:#FF6D00
```

## Schema

Decoder needs schema to produce relevant completion candidates, hover data etc. [`opentofu/opentofu-schema`](https://pkg.go.dev/github.com/opentofu/opentofu-schema) houses most of the OpenTofu Core schema (such as `terraform`, `resource` or `variable` blocks) + helpers to combine that [Core schema](https://github.com/opentofu/opentofu-schema/tree/main/internal/schema) with provider schemas (such as inner parts of `resource` or `data` blocks) and help assemble schemas for modules.
Expand Down Expand Up @@ -88,7 +89,6 @@ flowchart LR
linkStyle default stroke:#FF6D00
```


## Global State

Most of the global state is maintained within various [`go-memdb`](https://pkg.go.dev/github.com/hashicorp/go-memdb) tables under [`state`](https://pkg.go.dev/github.com/opentofu/tofu-ls@main/internal/state) package, passed around via [`state.StateStore`](https://pkg.go.dev/github.com/opentofu/tofu-ls@main/internal/state#StateStore).
Expand Down Expand Up @@ -209,8 +209,8 @@ The existing `variables` feature is a good starting point when introducing a new
1. Add a parsing job that gets triggered from an event
1. Add a decoder that makes use of some kind of schema
1. Register the new feature in `internal/langserver/handlers/service.go`
- Start the feature as part of `configureSessionDependencies()`
- Make sure to call the `Stop()` function in `shutdown()` as well
- Start the feature as part of `configureSessionDependencies()`
- Make sure to call the `Stop()` function in `shutdown()` as well
1. If the feature reports diagnostics, add a call to collect them in `updateDiagnostics()` in `internal/langserver/handlers/hooks_module.go`

## Job Scheduler
Expand Down Expand Up @@ -296,7 +296,6 @@ Jobs also depend on each other. These dependencies are illustrated in the diagra

### didOpen Job Flow


```mermaid
---
config:
Expand Down Expand Up @@ -414,7 +413,6 @@ The [`eventbus`](https://github.com/opentofu/tofu-ls/blob/main/internal/eventbus

### Event Sources


```mermaid
---
config:
Expand Down Expand Up @@ -461,7 +459,6 @@ flowchart LR
linkStyle default stroke:#FF6D00
```


## Walker

The Walker is responsible for walking the file system hierarchy of the entire workspace (including files that the user may not have open) in the background to gain a better understanding of the workspace structure. The walker doesn't schedule any jobs and doesn't do any additional work other than reporting the directory structure and the files it contains. The walker follows the LSP/RPC lifecycle of the server, i.e. it is started by an `initialize` request and shut down by a `shutdown` request.
Expand Down
Loading
Loading