Skip to content

Add TOML version catalog formatter step#2917

Open
mkutz wants to merge 5 commits intodiffplug:mainfrom
mkutz:feature/toml-version-catalog-step
Open

Add TOML version catalog formatter step#2917
mkutz wants to merge 5 commits intodiffplug:mainfrom
mkutz:feature/toml-version-catalog-step

Conversation

@mkutz
Copy link
Copy Markdown

@mkutz mkutz commented May 4, 2026

Resolves #2916

Adds a dedicated FormatterStep for formatting and sorting Gradle version catalog (.toml) files, with no external dependencies.

Features

  • Normalize spacing around = and inside inline tables { } and arrays [ ]
  • Sort entries alphabetically within each section
  • Sort sections in canonical order: [versions], [libraries], [bundles], [plugins]
  • Preserve comments — leading comments travel with their entry during sorting; inline comments are preserved
  • Multi-line inline tables — parsed correctly and joined/split based on line length
  • maxLineLength (default 120, configurable) — long inline tables are split across lines (one pair per line, 2-space indent, trailing commas)
  • stripQuotedKeys (opt-in, default false) — removes unnecessary quotes from keys when the bare form is valid

Usage

Gradle:

spotless {
  toml {
    target 'gradle/libs.versions.toml'
    versionCatalog()
    // or with options:
    // versionCatalog { maxLineLength(80); stripQuotedKeys(true) }
  }
}

Maven:

<toml>
  <includes>
    <include>gradle/libs.versions.toml</include>
  </includes>
  <versionCatalog />
</toml>

Known limitations

Documented in lib/src/main/java/com/diffplug/spotless/toml/TODO.md. These are valid TOML constructs that won't appear in typical Gradle version catalogs:

  • Quoted keys containing =
  • Dotted/quoted table headers
  • Single-quoted (literal) strings in inline tables
  • Triple-quoted multiline strings

Checklist

  • Class name ends in Step (VersionCatalogStep)
  • Public static create method returning FormatterStep
  • Test class VersionCatalogStepTest using StepHarness
  • Equality test using SerializableEqualityTester
  • Changelog entries in all three CHANGES.md files
  • spotlessApply clean
  • spotbugsMain clean

mkutz added 5 commits May 4, 2026 10:08
Add a dedicated FormatterStep for formatting and sorting Gradle version
catalog files (libs.versions.toml). The step normalizes spacing around
operators and inside inline tables/arrays, sorts entries alphabetically,
and orders tables canonically ([versions], [libraries], [bundles], [plugins]).
- Preserve comments inside sections by attaching them to the entry
  below, so they travel with the entry during sorting
- Strip and re-attach inline comments (# ...) before formatting
  inline tables/arrays
- Preserve blank lines in the file preamble
- Sort entries by logical key name, stripping surrounding quotes
- Add TODO.md documenting remaining TOML spec edge cases
Adds a stripQuotedKeys parameter (default false) that removes unnecessary
quotes from keys when the unquoted form is a valid bare TOML key. Keys
like "foo.bar" that would change semantics are preserved.
- Parse multi-line inline tables by tracking brace/bracket depth and
  joining continuation lines into a single entry
- Add configurable maxLineLength (default 120): lines exceeding the
  limit split their inline table across multiple lines (one pair per
  line, 2-space indent, trailing commas); multi-line tables that fit
  are joined into a single line
- Update TODO.md with fixed items
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TOML: dedicated plugin to format and sort libs.versions.toml files in Gradle projects

1 participant