# Indentation

*Lx* detects indentation separately for every editable text document. You can leave that choice on Auto, override the size or type for one document, or convert the indentation already stored in the file.

## Read the status

The indentation item appears on the right side of the status bar:

| Example | Meaning |
| --- | --- |
| `Spaces: 4*` | **Tab** inserts spaces; size 4 comes from automatic detection or your configured default |
| `Tabs: 4*` | **Tab** inserts literal tabs; size 4 is still automatic |
| `Spaces: 2` | **Tab** inserts spaces; size 2 was chosen explicitly for this document |
| `Tabs: 8` | **Tab** inserts literal tabs; size 8 was chosen explicitly for this document |

The `*` belongs to the size, not the type. The status item does not separately mark whether the type is automatic. For example, *Alt*-clicking `Spaces: 4*` changes it to `Tabs: 4*`: the type is now explicit, but the size remains automatic.

Hover over the item to see the effective type and size, the automatic size, and the available cycle order.

## Change one document

You don't need a picker for the common choices:

- Click the indentation item to cycle its size.
- Middle-click it to re-scan the current content and restore automatic type and size.
- *Alt*-click it to switch between spaces and tabs without rewriting existing whitespace.

The default size order is `2`, `4`, then `8`. Auto anchors one complete pass through that order, so a document detected as 4 follows this sequence:

```text
Auto (4) → 8 → 2 → 4 → Auto (4)
```

The explicit 4 near the end is useful: it lets you keep the same visible width while turning automatic detection off.

## What Tab does

In spaces mode, **Tab** advances leading indentation to the next indentation stop. At other positions it inserts one full indentation step.

In tabs mode, **Tab** inserts one literal tab character.

**Shift+Tab** unindents the current line or selected lines. **Backspace** inside leading space indentation removes one indentation step when possible.

For now, `indent_size` is one shared grid. It controls space indentation, the displayed width of literal tabs, cursor movement through indentation, mouse hit-testing, and conversion between leading tabs and spaces. A separate tab display width is not supported yet.

## Change future indentation or convert the file

Open the [Command Palette](command_palette.md) with **Ctrl+Shift+P** when you need an exact action:

| Command | What it does |
| --- | --- |
| `doc:use-spaces` | Use spaces for future indentation without changing existing whitespace |
| `doc:use-tabs` | Use tabs for future indentation without changing existing whitespace |
| `doc:to-spaces` | Convert leading indentation to spaces and use spaces from then on |
| `doc:to-tabs` | Convert leading indentation to tabs and use tabs from then on |
| `doc:detect-indent` | Re-scan the document and restore automatic type and size |
| `doc:cycle-indent-size` | Perform the same size cycle as clicking the status item |

Conversion changes leading indentation only. Tabs or spaces in the middle of a line remain untouched.

The conversion preserves visual columns, including mixed leading whitespace and leftover spaces which do not fill a complete tab stop. The whole document conversion is one undoable edit, so **Ctrl+Z** puts the original indentation back.

## How Auto works

Automatic detection looks for repeated leading tabs, leading space widths, and changes between adjacent indentation levels. Weak or evenly mixed evidence does not force a guess; *Lx* uses your configured defaults instead.

Documents up to 128 lines are inspected completely. For larger documents, *Lx* reads sixteen evenly distributed blocks of eight consecutive lines, including the beginning and end. Evidence is combined across those blocks, but distant block boundaries are never treated as adjacent lines.

This matters in files with a long header, generated declarations, or another opening section which uses different alignment from the rest of the document. The beginning no longer gets to decide everything simply because it arrived first.

Tab-indented files reveal that they use literal tabs, but the bytes do not reveal how wide those tabs should look. In that case the size comes from `config.indent_size` unless you choose another size for the document.

## Set your defaults

Add the settings you want to your [user settings](settings.md):

```lua
local config = require("core.config")

config.indent_type = "spaces"
config.indent_size = 4
config.indent_size_cycle = { 2, 4, 8 }
```

`config.indent_type` must be `"spaces"` or `"tabs"`. `config.indent_size` supplies the default grid size when detection has no clear answer. `config.indent_size_cycle` controls the status-bar order; changing it also updates the tooltip.

These settings are defaults. An explicit choice on one document does not change other open documents or your global configuration.

You can also open one file with an explicit size from the command line:

```cli
lx --tab-size 8 source.txt
```

`--tab-size`, its `--tab` alias, and `-t` set the shared tab and indentation size for files opened by that command.
