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

# GLua Code Formatter

> The GLua formatter reprints code from the syntax tree, never drops comments, never touches files that do not parse, and preserves idiomatic one-liners.

The GLua Language Server includes a built-in code formatter that reprints your Lua files from the parsed syntax tree. It is designed to be safe: it refuses to format files that do not parse, and it never drops a comment even when the layout is complex.

## How it works

The formatter reads your file into a syntax tree and then prints it back with consistent indentation and spacing. It follows two safety rules:

1. **Refuses unparseable files** — If your file contains a syntax error, the formatter exits without making changes.
2. **Never drops a comment** — If the formatter cannot determine where to place a comment in the output, it falls back to the original text for that statement rather than discarding it.

## Idiomatic one-liners

The formatter recognises common GLua guard clauses and keeps them on a single line instead of expanding them.

```lua theme={null}
if not IsValid(ent) then return end

if ply:IsAdmin() then return true end
```

These patterns stay compact because the formatter knows they are idiomatic in Garry's Mod code.

## Setting up

To make the GLua formatter the default for Lua files in your workspace, add it to your VS Code settings:

```json theme={null}
{
  "[glua]": {
    "editor.defaultFormatter": "bluejutzu.glua-lsp"
  }
}
```

You can also format manually with the **Format Document** command (Shift+Alt+F or Shift+Option+F).

## Config file

Create a `.gluafmtrc.json` file in your workspace root to share formatting rules with your team.

```json theme={null}
{
  "useTabs": false,
  "indentSize": 4,
  "maxLineWidth": 120,
  "quoteStyle": "double",
  "keepSingleLineBlocks": true,
  "overrides": [
    {
      "files": ["sh_*.lua"],
      "indentSize": 2
    }
  ]
}
```

| Key                    | Type                     | Description                                 |
| ---------------------- | ------------------------ | ------------------------------------------- |
| `useTabs`              | boolean                  | Indent with tabs instead of spaces          |
| `indentSize`           | number                   | Number of spaces per indent                 |
| `maxLineWidth`         | number                   | Maximum characters per line                 |
| `quoteStyle`           | `"single"` or `"double"` | Preferred string quote style                |
| `keepSingleLineBlocks` | boolean                  | Preserve one-line blocks like guard clauses |
| `overrides`            | array                    | Per-file-pattern overrides                  |

## Existing config files

The formatter also reads settings from `.editorconfig` and `.prettierrc` if they exist in your workspace.

| File            | Keys used                                                               |
| --------------- | ----------------------------------------------------------------------- |
| `.editorconfig` | `indent_style`, `indent_size`, `max_line_length`, `end_of_line`         |
| `.prettierrc`   | `useTabs`, `tabWidth`, `printWidth`, `singleQuote`, `endOfLine`, `semi` |

Values in `.gluafmtrc.json` take precedence over `.editorconfig` and `.prettierrc`.

<Note>
  Run the **GLua: Create Formatter Config File** command from the Command Palette to generate a `.gluafmtrc.json` with sensible defaults in your workspace root.
</Note>


## Related topics

- [Install GLua Language Server for VS Code](/installation.md)
- [GLua Language Server: GMod Lua IDE Support](/index.md)
- [GLua Language Server Commands](/reference/commands.md)
- [Committed Config Files for GLua](/configuration/config-files.md)