> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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 built-in formatter reprints your Lua files with consistent indentation and spacing, and 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={"system"}
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.

## Leaving code alone

Some code reads worse after any formatter touches it — a hand-aligned lookup
table, a block of generated data. Say so, and it is left exactly as written:

```lua theme={"system"}
-- glua-format-ignore
local COLOURS = {
	red   = Color(255,   0,   0),
	green = Color(  0, 255,   0),
	blue  = Color(  0,   0, 255),
}
```

The directive protects the statement on the line below it, and nothing else —
the rest of the file is formatted normally. It has to sit on its own line;
`local x = 1 -- glua-format-ignore` is a comment about `x`, not a directive
about whatever follows.

For a whole file, usually one that is generated:

```lua theme={"system"}
-- Generated by build.lua. Do not edit.
-- glua-format-ignore-file
```

The file is then reported as unchanged by `glua fmt` and never rewritten.

## Setting up

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

```json theme={"system"}
{
  "[glua]": {
    "editor.defaultFormatter": "blight.glua-gmod"
  }
}
```

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={"system"}
{
  "useTabs": false,
  "indentSize": 4,
  "maxLineWidth": 120,
  "quoteStyle": "double",
  "keepSingleLineBlocks": true,
  "overrides": [
    {
      "files": ["sh_*.lua"],
      "options": { "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-path overrides, each `{ "files": [...], "options": {...} }` |

## 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`.

See the [`gluafmtrc.schema.json` reference](/glua/reference/gluafmtrc-schema) for every property this file accepts, including the ones left out of the table above.

<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>