Configuration

Learn how to configure Tombi using the tombi.toml configuration file.

Tombi uses a TOML configuration file named tombi.toml. Also, we supports [tool.tombi] in pyproject.toml.

Search Priority

  1. tombi.toml in the current directory
  2. [tool.tombi] in pyproject.toml in the current directory
  3. ...search parent directory recursively
  4. $XDG_CONFIG_HOME/tombi/config.toml
  5. ~/.config/tombi/config.toml
  6. ~/Library/Application Support/tombi/config.toml (macOS), %APPDATA%\tombi\config.toml (Windows)
  7. /etc/tombi/config.toml (Linux)

Full Structure

toml-version = "1.0.0"

[files]
include = ["**/*.toml"]
exclude = []

[format]
[format.rules]
array-bracket-space-width = 0
array-comma-space-width = 1
date-time-delimiter = "T"
indent-style = "space"
indent-sub-tables = false
indent-table-key-value-pairs = false
indent-width = 2
inline-table-brace-space-width = 1
inline-table-comma-space-width = 1
key-value-equals-sign-alignment = false
key-value-equals-sign-space-width = 1
line-ending = "lf"
line-width = 80
string-quote-style = "double"
trailing-comment-alignment = false
trailing-comment-space-width = 2

[lint]
[lint.rules]
dotted-keys-out-of-order = "warn"
key-empty = "warn"
tables-out-of-order = "warn"

[lsp]
code-action.enabled = true
completion.enabled = true
diagnostics.enabled = true
document-link.enabled = true
formatting.enabled = true
goto-declaration.enabled = true
goto-definition.enabled = true
goto-type-definition.enabled = true
hover.enabled = true
workspace-diagnostic.enabled = true

[schema]
enabled = true
strict = true
catalog = {
  paths = [
    "tombi://www.schemastore.org/api/json/catalog.json",
    "https://www.schemastore.org/api/json/catalog.json",
  ],
}

# Root Schema
[[schemas]]
toml-version = "1.0.0"
path = "https://example.com/schema.json"
include = ["example.toml"]

# Sub Schema
[[schemas]]
root = "tool.taskipy"
path = "schemas/partial-taskipy.schema.json"
include = ["pyproject.toml"]

# Override config
[[overrides]]
[overrides.files]
include = ["specific/**/*.toml"]
exclude = ["specific/**/ignored.toml"]

[overrides.format]
enabled = true

[overrides.format.rules]
array-bracket-space-width = 1
array-comma-space-width = 1
date-time-delimiter = "space"
indent-style = "tab"
indent-sub-tables = true
indent-table-key-value-pairs = true
indent-width = 4
inline-table-brace-space-width = 0
inline-table-comma-space-width = 1
key-value-equals-sign-alignment = true
key-value-equals-sign-space-width = 1
line-ending = "crlf"
line-width = 120
string-quote-style = "single"
trailing-comment-alignment = true
trailing-comment-space-width = 1

[overrides.lint]
enabled = true

[overrides.lint.rules]
dotted-keys-out-of-order = "error"
key-empty = "error"
tables-out-of-order = "error"

Available Options

toml-version

Specifies the TOML version to use if not specified in the schema and comment directive.

  • Type: "v1.0.0" | "v1.1.0-preview"
  • Default: "v1.0.0"

files

Configure file patterns for formatting and linting operations.

files.include

The file match pattern to include in formatting and linting. Supports glob pattern.

  • Type: String[]
  • Default: ["**/*.toml"]

files.exclude

The file match pattern to exclude from formatting and linting. Supports glob pattern.

  • Type: String[]

format

Formatter options for TOML files.

format.rules

Configure formatting styles.

format.rules.array-bracket-space-width

The number of spaces inside the brackets of a single line array.

  • Type: Number
  • Default: 0
key = [ 1, 2, 3 ]
#      ^       ^  <- this

format.rules.array-comma-space-width

The number of spaces after the comma in a single line array.

  • Type: Number
  • Default: 1
key = [ 1, 2, 3 ]
#         ^  ^  <- this

format.rules.date-time-delimiter

The delimiter between date and time

In accordance with RFC 3339, you can use T or space character between date and time.

  • Type: "T" | "space" | "preserve"
  • Default: "T"
  • Enumerated:
    • T: Use T between date and time like 2001-01-01T00:00:00
    • space: Use space between date and time like 2001-01-01 00:00:00
    • preserve: Preserve the original delimiter.

format.rules.indent-style

The style of indentation

Whether to use spaces or tabs for indentation.

  • Type: "space" | "tab"
  • Default: "space"
  • Enumerated:
    • space: Use spaces for indentation.
    • tab: Use tabs for indentation.

format.rules.indent-sub-tables

Whether to indent the sub-tables.

If true, the sub-table will be indented.

  • Type: Boolean
  • Default: false
[table]
    [table.sub-table]
    key = "value"
# ^^  <- this

format.rules.indent-table-key-value-pairs

Whether to indent the table key-value pairs.

If true, the table key-value pairs will be indented.

  • Type: Boolean
  • Default: false
[table]
    key = "value"
# ^^  <- this

format.rules.indent-width

The number of spaces per indentation level.

  • Type: Number
  • Default: 2
⚠️Warning

This option is only used when the indentation style is space.

format.rules.inline-table-brace-space-width

The number of spaces inside the brackets of a single line inline table.

  • Type: Number
  • Default: 1
key = { a = 1, b = 2 }
#      ^            ^  <- this

format.rules.inline-table-comma-space-width

The number of spaces after the comma in a single line inline table.

  • Type: Number
  • Default: 1
key = { a = 1, b = 2 }
#             ^  <- this

format.rules.key-value-equals-sign-alignment

Whether to align the equals sign in the key-value pairs.

If true, the equals sign in the key-value pairs will be aligned.

  • Type: Boolean
  • Default: false
# BEFORE
key = "value1"
key2 = "value2"
key3.key4 = "value3"

# AFTER
key       = "value1"
key2      = "value2"
key3.key4 = "value3"
⚠️Warning

This feature does not apply to key-value pairs inside single line inline tables.

format.rules.trailing-comment-alignment

Whether to align the trailing comments in the key-value pairs.

If true, the trailing comments in value/key-value pairs will be aligned.

  • Type: Boolean
  • Default: false
# BEFORE
key = "value1"  # comment 1
key2 = "value2"  # comment 2
key3.key4 = "value3"  # comment 3

# AFTER
key = "value1"        # comment 1
key2 = "value2"       # comment 2
key3.key4 = "value3"  # comment 3
🗒️Note

The trailing comments of table header are not targeted by alignment.

format.rules.key-value-equals-sign-space-width

The number of spaces around the equals sign in a key-value pair.

  • Type: Number
  • Default: 1
key = "value"
#  ^ ^  <- this

format.rules.line-ending

The type of line ending.

  • Type: "lf" | "crlf"
  • Default: "lf"
  • Enumerated:
    • lf: Line Feed only (\n), common on Linux and macOS as well as inside git repos.
    • crlf: Carriage Return Line Feed (\r\n), common on Windows.

format.rules.line-width

The maximum line width.

The formatter will try to keep lines within this width.

  • Type: Number
  • Default: 80

format.rules.string-quote-style

The preferred quote character for strings.

  • Type: "double" | "single" | "preserve"
  • Default: "double"
  • Enumerated:
    • double: Prefer the double quote like "value"
    • single: Prefer the single quote like 'value'
    • preserve: Preserve the original quote

format.rules.trailing-comment-space-width

The number of spaces before the trailing comment.

  • Type: Number
  • Default: 2
key = "value"  # trailing comment
#            ^^  <- this

lint

Linter options for TOML files.

lint.rules

Configure individual lint rules with severity levels.

lint.rules.key-empty

Check if the key is empty.

  • Type: "off" | "warn" | "error"
  • Default: "warn"
# VALID BUT DISCOURAGED
"" = true

lint.rules.dotted-keys-out-of-order

Check if dotted keys are defined out of order.

  • Type: "off" | "warn" | "error"
  • Default: "warn"
# VALID BUT DISCOURAGED
apple.type = "fruit"
orange.type = "fruit"
apple.skin = "thin"
orange.skin = "thick"

# RECOMMENDED
apple.type = "fruit"
apple.skin = "thin"
orange.type = "fruit"
orange.skin = "thick"

lint.rules.tables-out-of-order

Check if tables are defined out of order.

  • Type: "off" | "warn" | "error"
  • Default: "warn"
# VALID BUT DISCOURAGED
[fruit.apple]
[animal]
[fruit.orange]

# RECOMMENDED
[fruit.apple]
[fruit.orange]
[animal]

lsp

Language Server Protocol (LSP) feature configuration. Each feature can be individually enabled or disabled.

lsp.code-action

Configure code action feature.

lsp.code-action.enabled

Enable or disable code action feature.

  • Type: Boolean
  • Default: true

lsp.completion

Configure completion feature.

lsp.completion.enabled

Enable or disable completion feature.

  • Type: Boolean
  • Default: true

lsp.diagnostic

Configure diagnostic feature.

lsp.diagnostic.enabled

Enable or disable diagnostic feature.

  • Type: Boolean
  • Default: true

lsp.document-link

Configure document link feature.

lsp.document-link.enabled

Enable or disable document link feature.

  • Type: Boolean
  • Default: true

lsp.formatting

Configure formatting feature.

lsp.formatting.enabled

Enable or disable formatting feature.

  • Type: Boolean
  • Default: true

lsp.goto-declaration

Configure go to declaration feature.

lsp.goto-declaration.enabled

Enable or disable go to declaration feature.

  • Type: Boolean
  • Default: true

lsp.goto-definition

Configure go to definition feature.

lsp.goto-definition.enabled

Enable or disable go to definition feature.

  • Type: Boolean
  • Default: true

lsp.goto-type-definition

Configure go to type definition feature.

lsp.goto-type-definition.enabled

Enable or disable go to type definition feature.

  • Type: Boolean
  • Default: true

lsp.hover

Configure hover feature.

lsp.hover.enabled

Enable or disable hover feature.

  • Type: Boolean
  • Default: true

lsp.workspace-diagnostic

Configure workspace diagnostic feature.

lsp.workspace-diagnostic.enabled

Enable or disable workspace diagnostic feature.

  • Type: Boolean
  • Default: true

schema

JSON Schema validation options for TOML files.

schema.enabled

Enable or disable schema validation.

  • Type: Boolean
  • Default: true

schema.strict

Enable strict schema validation. If additionalProperties is not specified in the JSON Schema, the strict mode treats it as additionalProperties: false, which is different from the JSON Schema specification.

  • Type: Boolean
  • Default: true

schema.catalog

Configure schema catalog for automatic schema detection.

schema.catalog.paths

The schema catalog path/url array. The catalog is evaluated after the schemas specified by [[schemas]]. Schemas are loaded in order from the beginning of the catalog list.

  • Type: String[]
  • Default: ["tombi://www.schemastore.org/api/json/catalog.json", "https://www.schemastore.org/api/json/catalog.json"]

schemas

Define custom schemas for specific TOML files. You can specify both root schemas and sub-schemas.

Root Schema

Apply a schema to the entire TOML document.

[[schemas]]
toml-version = "v1.0.0"  # optional
path = "https://example.com/schema.json"
include = ["example.toml"]
  • toml-version(optional): The TOML version that the schema is available for
  • path: The schema path (URL or local file path)
  • include: File match patterns to apply this schema (supports glob patterns)

Sub Schema

Apply a schema to a specific part of the TOML document. Sub schemas are mainly provided for configuring extension features, such as the tool section in pyproject.toml or similar cases where only part of the document should be validated or structured according to an additional schema.

[[schemas]]
root = "tool.taskipy"
path = "schemas/partial-taskipy.schema.json"
include = ["pyproject.toml"]
  • root: The accessor path to apply the sub-schema (e.g., "tools.tombi", "items[0].name")
  • path: The schema path (URL or local file path)
  • include: File match patterns to apply this schema (supports glob patterns)

overrides

Override configuration settings for specific file patterns. You can define multiple override rules, and matching settings will be applied to files.

[[overrides]]
files.include = ["tests/**/*.toml"]

[overrides.format.rules]
indent-width = 4
line-width = 120

[overrides.lint.rules]
key-empty = "off"

overrides[*].files

Specify file patterns to which the override should be applied.

  • Type: Table
  • Required: true

overrides[*].files.include

File patterns to apply the override. Supports glob patterns.

  • Type: String[]
  • Required: true

overrides[*].files.exclude

File patterns to exclude from the override. Supports glob patterns.

  • Type: String[]

overrides[*].format

Override format settings.

overrides[*].format.enabled

Enable or disable formatting feature.

  • Type: Boolean
  • Default: true

overrides[*].format.rules

Override format rules. Only the specified rules will be overridden, and the rest will use the base configuration.

Available rules are the same as format.rules.

overrides[*].lint

Override lint settings.

overrides[*].lint.enabled

Enable or disable linting feature.

  • Type: Boolean
  • Default: true

overrides[*].lint.rules

Override lint rules. Only the specified rules will be overridden, and the rest will use the base configuration.

Available rules are the same as lint.rules.

Zed ExtensionJSON Schema