> ## Documentation Index
> Fetch the complete documentation index at: https://gluals.arnux.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace settings

> Configure library paths, ignore patterns, module maps, and file encoding.

## Overview

The `workspace` section tells the language server which files to analyze, which files to ignore, and where to find external libraries. It also controls module resolution and file encoding.

***

## Options

| Option                        | Type                   | Default       | Description                                                                                                                                                                                                                               |
| ----------------------------- | ---------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace.library`           | `array`                | `[]`          | External library paths to include in analysis (strings or objects)                                                                                                                                                                        |
| `workspace.workspaceRoots`    | `string[]`             | `[]`          | Additional workspace root directories for multi-root setups                                                                                                                                                                               |
| `workspace.ignoreDir`         | `string[]`             | `[]`          | Directory names to exclude from analysis                                                                                                                                                                                                  |
| `workspace.ignoreDirDefaults` | `(string \| object)[]` | built-in list | Built-in directories and patterns to ignore. Accepts strings or the objects described below.                                                                                                                                              |
| `workspace.useDefaultIgnores` | `boolean`              | `true`        | Whether to apply `workspace.ignoreDirDefaults`                                                                                                                                                                                            |
| `workspace.enableIsolation`   | `boolean`              | `false`       | Keep multi-root main workspaces isolated. Set to `false` to merge workspace configs into one global baseline (first workspace config wins scalar conflicts, arrays are unioned) while still allowing per-workspace file-scoped overrides. |
| `workspace.ignoreGlobs`       | `string[]`             | `[]`          | Glob patterns of files to exclude from analysis                                                                                                                                                                                           |
| `workspace.moduleMap`         | `array`                | `[]`          | Module path rewrite rules (regex patterns)                                                                                                                                                                                                |
| `workspace.encoding`          | `string`               | `"utf-8"`     | File encoding for all Lua files in the workspace                                                                                                                                                                                          |
| `workspace.enableReindex`     | `boolean`              | `false`       | Trigger a full workspace reindex when files change                                                                                                                                                                                        |
| `workspace.reindexDuration`   | `integer`              | `5000`        | Delay in ms before a reindex fires after a file change                                                                                                                                                                                    |
| `workspace.packageDirs`       | `string[]`             | `[]`          | Partial library load; only load package declarations from these dirs, not full analysis                                                                                                                                                   |

***

## Library paths

`workspace.library` adds directories to analysis without treating them as project source. Use this for annotation files, dependencies, or other code you need to reference from your project.

<Note>
  This helps gamemodes such as Helix, where your schema needs to reference the "core" Helix gamemode. Add `../helix` as a library path in your schema gamemode.
</Note>

Each entry is either a path string or an object with per-library ignore options:

```json .gluarc.json theme={null}
{
  "workspace": {
    "library": [
      "./types",
      {
        "path": "./vendor/stubs",
        "ignoreDir": ["test"],
        "ignoreGlobs": ["**/*.spec.lua"]
      }
    ]
  }
}
```

***

## Ignore patterns

Exclude directories or files from analysis:

```json .gluarc.json theme={null}
{
  "workspace": {
    "ignoreDir": ["node_modules", ".git", "tests"],
    "ignoreGlobs": [
      "**/*.min.lua",
      "legacy/**"
    ]
  }
}
```

Common directories to ignore for GMod projects:

* `garrysmod` (Steam engine files)
* `addons` (other addons' source, if not relevant to your project)
* `.git`
* `out`, `build`, `dist`

***

## Ignore default overrides

`workspace.ignoreDirDefaults` lets you override, disable, or extend the built-in ignore defaults without replacing the whole list.

The list accepts two forms:

* **Strings** replace the built-in list with your own patterns.
* **Objects** change, remove, or add individual entries while keeping the rest of the built-in list.

Built-in default ids:

| id                      | Default glob                  |
| ----------------------- | ----------------------------- |
| `wire-expression2`      | `**/gmod_wire_expression2/**` |
| `wire-expression-files` | `**/wire_expression*.lua`     |
| `tests`                 | `**/tests/**`                 |
| `test`                  | `**/test/**`                  |

Object entry fields:

| Field      | Type      | Description                                                    |
| ---------- | --------- | -------------------------------------------------------------- |
| `id`       | `string`  | Stable identifier matching a built-in or a custom id.          |
| `label`    | `string`  | Optional human-readable label (informational only).            |
| `glob`     | `string`  | Glob pattern to apply. Omit when only using `disabled`.        |
| `disabled` | `boolean` | Set `true` to remove this built-in default from the workspace. |

**Disable a single built-in:**

```json .gluarc.json theme={null}
{
  "workspace": {
    "ignoreDirDefaults": [
      { "id": "tests", "disabled": true }
    ]
  }
}
```

**Override a built-in pattern and add a custom entry:**

```json .gluarc.json theme={null}
{
  "workspace": {
    "ignoreDirDefaults": [
      { "id": "test", "glob": "**/my_tests/**" },
      { "id": "legacy-stuff", "glob": "**/legacy/**" }
    ]
  }
}
```

**Disable all built-in defaults globally:**

```json .gluarc.json theme={null}
{
  "workspace": {
    "useDefaultIgnores": false
  }
}
```

***

`moduleMap` rewrites require paths to file paths using regex replacement. Use it when your project uses non-standard require patterns.

```json .gluarc.json theme={null}
{
  "workspace": {
    "moduleMap": [
      {
        "pattern": "^libs/(.*)",
        "replace": "lua/libs/$1"
      }
    ]
  }
}
```

***

## Workspace roots

If your Lua files are not at the repository root, specify the Lua root:

```json .gluarc.json theme={null}
{
  "workspace": {
    "workspaceRoots": ["lua"]
  }
}
```

This affects require path resolution. GLuaLS resolves `require("mymodule")` relative to `lua/mymodule.lua`.

***

## File encoding

Most Lua files use UTF-8, but older addons may use a legacy encoding:

```json .gluarc.json theme={null}
{
  "workspace": {
    "encoding": "utf-8"
  }
}
```

Available values: `"utf-8"`, `"utf-16"`, `"gbk"`, `"latin1"`, `"ascii"`.

***

## VS Code extension settings

You can also configure these settings in VS Code settings with the `gluals.*` prefix:

| VS Code setting                      | .gluarc.json key              | Type              | Default | Description                       |
| ------------------------------------ | ----------------------------- | ----------------- | ------- | --------------------------------- |
| `gluals.workspace.enableReindex`     | `workspace.enableReindex`     | `boolean`         | `false` | Enable reindex after file changes |
| `gluals.workspace.reindexDuration`   | `workspace.reindexDuration`   | `integer`         | `5000`  | Delay before reindex (ms)         |
| `gluals.workspace.enableIsolation`   | `workspace.enableIsolation`   | `boolean \| null` | `null`  | Override multi-root isolation     |
| `gluals.workspace.useDefaultIgnores` | `workspace.useDefaultIgnores` | `boolean \| null` | `null`  | Override built-in ignore rules    |