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

# Formatting

> GLuaLS formats your GLua files with built-in presets or an external formatter.

## Overview

GLuaLS includes an opinionated Lua formatter. Format the current file with `Shift+Alt+F` (or right-click → **Format Document**).

## Built-in presets

GLuaLS includes three presets for common GMod style choices:

| Preset    | Description                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------ |
| `default` | Standard, no specific style                                                                      |
| `cfc`     | [Follows CFC-Servers style guidelines](https://github.com/CFC-Servers/cfc_glua_style_guidelines) |
| `custom`  | Use only `styleOverrides`                                                                        |

Set the preset in `.gluarc.json`:

<Tip>
  Use the settings menu instead of editing the JSON file directly. This helps you avoid config mistakes.
</Tip>

```json .gluarc.json theme={null}
{
  "format": {
    "preset": "default"
  }
}
```

## Style overrides

Use `styleOverrides` to change individual rules within a preset:

<Tip>
  Use the settings menu instead of editing the JSON file directly. This helps you avoid config mistakes.
</Tip>

```json .gluarc.json theme={null}
{
  "format": {
    "preset": "default",
    "styleOverrides": {
      "indent_style": "tab",
      "indent_size": 4,
      "tab_width": 4,
      "max_line_length": 120,
      "trailing_table_separator": "smart",
      "call_arg_parentheses": "keep"
    }
  }
}
```

### Key style options

| Option                     | Values                                                                          | Description                                                    |
| -------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `indent_style`             | `"tab"`, `"space"`                                                              | Indentation mode                                               |
| `indent_size`              | `1`–`8`                                                                         | Number of spaces per indent level (when using spaces)          |
| `tab_width`                | `1`–`8`                                                                         | Visual width of tabs                                           |
| `quote_style`              | `"none"`, `"single"`, `"double"`                                                | Preferred quote style for string literals                      |
| `call_arg_parentheses`     | `"keep"`, `"remove"`, `"remove_table_only"`, `"remove_string_only"`, `"always"` | How to handle parentheses around single-string/table call args |
| `max_line_length`          | integer                                                                         | Line wrap threshold                                            |
| `trailing_table_separator` | `"keep"`, `"never"`, `"always"`, `"smart"`                                      | Trailing separator in table constructors                       |

See [Configuration: Formatting](/configuration/formatting) for the full list.

## External formatter

Use an external formatting tool, such as `stylua` or `GLuaFixer`, instead of the built-in formatter:

<Tip>
  Use the settings menu instead of editing the JSON file directly. This helps you avoid config mistakes.
</Tip>

```json .gluarc.json theme={null}
{
  "format": {
    "externalTool": {
      "program": "stylua",
      "args": ["-"],
      "timeout": 10
    }
  }
}
```

The external formatter receives file content over stdin and must write the formatted result to stdout.

## EditorConfig

GLuaLS can read `.editorconfig` indent settings. Those values can override matching `styleOverrides` entries based on your priority setting between `.editorconfig` and `.gluarc.json`.

## Format on save

Enable format-on-save in VS Code:

```json VS Code settings theme={null}
{
  "editor.formatOnSave": true,
  "[lua]": {
    "editor.defaultFormatter": "Pollux.gmod-glua-ls"
  }
}
```