Skip to content
Skills Library
Programming · Building & coding

topiary

/topiary

Universal code formatter leveraging Tree-sitter queries. Use when formatting code in languages without dedicated formatters, writing custom .scm query files, or configuring Topiary via languages.ncl.

Licence
MIT
Last repository change
07.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 07.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Universal code formatter leveraging Tree-sitter queries. Use when formatting code in languages without dedicated formatters, writing custom .scm query files, or configuring Topiary via languages.ncl.

Original author description

Universal code formatter leveraging Tree-sitter queries. Use when formatting code in languages without dedicated formatters, writing custom .scm query files, or configuring Topiary via languages.ncl.

How it works

  1. Key Concepts
  2. Installation
  3. CLI Usage
  4. Configuration
  5. Adding Custom Languages
  6. Writing Formatting Queries
  7. Supported Languages
  8. Mise Task Examples
  9. References
  10. Anti-Fabrication Note
Original SKILL.md headings · 362 lines, 1,218 words
SKILL.md preview
---
name: topiary
description: "Universal code formatter leveraging Tree-sitter queries. Use when formatting code in languages without dedicated formatters, writing custom .scm query files, or configuring Topiary via languages.ncl."
license: MIT
---

# Topiary

Topiary is a universal code formatter that uses Tree-sitter grammars and queries to define formatting rules. Rather than implementing language-specific formatting logic, Topiary uses declarative Tree-sitter query files (.scm) to specify how code should be formatted.

## Key Concepts

### Tree-Sitter Queries

Tree-sitter is a parser generator that creates language parsers from grammar definitions. Topiary uses Tree-sitter queries to analyze code structures and apply formatting rules. Queries match patterns in the syntax tree using S-expression syntax and decorate matched nodes with capture names (prefixed with `@`) that describe formatting actions.

### Query Files and Capture Names

Language formatting is defined in `.scm` (Scheme) query files. Each capture name instructs Topiary how to format the matched node:

- **Line breaks**: `@prepend_hardline`, `@append_hardline` (always insert newline), `@prepend_empty_softline`, `@append_empty_softline` (newline or nothing), `@prepend_spaced_softline`, `@append_spaced_softline` (newline or space)
- **Indentation**: `@prepend_indent_start`, `@append_indent_start`, `@prepend_indent_end`, `@append_indent_end` (mark indentation scopes)
- **Spacing**: `@prepend_space`, `@append_space` (add single space)
- **Control**: `@delete` (remove matched node), `@do_nothing` (suppress default behavior), `@leaf` (prevent formatting within node)
- **Input-aware**: `@prepend_input_softline`, `@append_input_softline` (preserve original line break presence)

### Idempotency

Topiary formatting is idempotent—running the formatter repeatedly on already-formatted code produces identical output. This guarantee allows safe integration into version control hooks and CI pipelines.

### Author Intent Preservation

Topiary respects the structural intent of code by preserving language-specific semantics. It focuses on whitespace, indentation, and line breaks rather than restructuring code. This approach works especially well with languages whose semantics are simple and whitespace-independent.

## Installation

### Via Mise

Add Topiary to your `mise.toml`:

```toml
[tools]
topiary = "latest"

[tasks]
fmt = "topiary fmt"
fmt:check = "topiary fmt --check"
```

### Via Cargo

Install directly from crates.io:

```bash
cargo install topiary-cli
```

### Verify Installation

Check the installed version and available languages:

```bash
topiary --version
topiary config show-sources
```

## CLI Usage

### Format Files

Format files in place by detected file extension:

```bash
topiary fmt src/main.ml
topiary fmt config.json
topiary fmt *.toml
```

Add `--check` to verify formatting without modifications:

```bash
topiary fmt --check src/
```

### Format Standard Input

Format piped input by specifying language and optional query file:

```bash
echo '{"name":"example"}' | topiary format --language json
cat script.sh | topiary format --language bash
```

### Visualize Parse Trees

Use `visualise` to debug queries by inspecting the syntax tree:

```bash
topiary visualise script.json
topiary visualise --language bash script.sh
```

This outputs the Tree-sitter parse tree, useful for understanding node structure when writing `.scm` queries.

### Query Configuration

Override the default query file for a language:

```bash
topiary fmt --language nickel --query custom.scm script.ncl
```

### Show Current Configuration

Display the active configuration including registered languages and indentation settings:

```bash
topiary config show-sources
```

## Configuration

### languages.ncl Format

Create a `.topiary/languages.ncl` file in your project root to customize language registration, indentation, and grammar sources. This file uses Nickel syntax:

```nickel
{
  languages = {
    json = {
      extensions = ["json"],
      indent = "  ",
    },
    bash = {
      extensions = ["sh", "bash"],
      indent = "  ",
    }
  }
}
```

### Configuration Search Order

Topiary searches for configuration in this order (first found wins):
1. `--configuration` CLI argument
2. `.topiary/languages.ncl` in current directory or parent directories
3. User configuration directory (OS-specific): `~/.config/topiary/languages.ncl` (Linux), `~/Library/Application Support/topiary/languages.ncl` (macOS), `%APPDATA%\topiary\languages.ncl` (Windows)
4. Built-in defaults compiled into Topiary

### Custom Grammar Sources

Register custom Tree-sitter grammars by specifying Git source or local path:

```nickel
{
  languages = {
    my-lang = {
      extensions = ["ml"],
      grammar.source.git = {
        git = "https://github.com/example/tree-sitter-my-lang",
        rev = "abc123def456"
      }
    }
  }
}
```

Or reference a pre-compiled grammar on disk:

```nickel
{
  languages = {
    my-lang = {
      extensions = ["ml"],
      grammar.source.path = "./grammars/my-lang.so"
    }
  }
}
```

## Adding Custom Languages

Add formatting support for new languages by following these steps:

### Step 1: Register the Grammar

Create `.topiary/languages.ncl` in your project with the grammar source:

```nickel
{
  languages = {
    my-lang = {
      extensions = ["ml"],
      indent = "  ",
      grammar.source.git = {
        git = "https://github.com/my-org/tree-sitter-my-lang",
        rev = "main"
      }
    }
  }
}
```

Verify the grammar source URL points to a valid Tree-sitter grammar repository.

### Step 2: Create Query File

Create `.topiary/queries/my-lang.scm` with formatting rules. Start minimal:

```scm
; Format binary operators with surrounding spaces
((binary_op) @op
 (#match? @op "^(+|-|=)$"))
@prepend_space
@append_space

; Hard line after statements
((statement) @stmt)
@append_hardline
```

Use `topiary visualise` to inspect the parse tree and understand node names and structure.

### Step 3: Test Formatting

Test the formatter on sample files:

```bash
topiary fmt --language my-lang test-file.ml
topiary visualise --language my-lang test-file.ml
```

Iterate on the query file until formatting behaves as expected. Run `topiary fmt` on actual code to verify formatting is idempotent (run twice, should produce identical output).

## Writing Formatting Queries

### Query Syntax Overview

Tree-sitter queries use S-expression syntax. A basic query matches nodes and captures them:

```scm
; Match a function definition and capture its name
(function_def
  name: (identifier) @func-name)
```

The `@func-name` is a capture; `function_def`, `name`, and `identifier` are node types. Field names like `name:` link to specific children.

### Common Capture Patterns

Format operators with spaces on both sides:

```scm
((binary_op operator: _ @op))
@prepend_space
@append_space
```

Indent function bodies:

```scm
(function_def
  body: (block) @body)
@append_indent_start
@prepend_indent_end
```

Insert line breaks between statements:

```scm
((statement) @stmt)
@append_hardline
```

Preserve input line breaks (single line or multi-line lists):

```scm
(list
  "[" @open
  _ @item
  "]" @close)
@append_spaced_softline
```

### Predicates and Matching

Use predicates to refine matches:

```scm
; Match only specific operators
((binary_op operator: _ @op)
 (#match? @op "^(=|==|!=)$"))
@prepend_space
@append_space

; Match nodes that are NOT in comments
((statement) @stmt
 (#not-eq? @stmt comment))
```

Available predicates: `#match?` (regex), `#eq?` (equality), `#not-eq?` (inequality).

## Supported Languages

### Official Languages

Topiary actively maintains formatting for:
- **Bash** - Shell scripting
- **JSON** - Data serialization
- **Nickel** - Configuration language
- **OCaml** - Functional programming (implementations and interfaces)
- **OCamllex** - Lexer definitions
- **TOML** - Configuration file format
- **Tree-sitter Queries** - Query file formatting

### Community-Contributed Languages

External maintainers provide formatters for:
- **CSS** - Stylesheets
- **OpenSCAD** - 3D modeling language
- **SDML** - Semantic Data Modeling Language
- **WIT** - WebAssembly Interface Types

### Language Limitations

Topiary works best with languages where formatting is independent of semantics. Whitespace-sensitive languages (Python, Haskell) present challenges and are not officially supported, as formatting changes could alter code meaning.

## Mise Task Examples

Define formatting tasks in `mise.toml`:

```toml
[tasks.fmt]
description = "Format all code"
run = """
topiary fmt src/
"""

[tasks.fmt:check]
description = "Check formatting without modifying"
run = """
topiary fmt --check src/
"""

[tasks.fmt:debug]
description = "Visualize parse tree for debugging"
run = """
topiary visualise {file}
"""
```

Run tasks with:

```bash
mise run fmt
mise run fmt:check
mise run fmt:debug -- script.ncl
```

## References

- `references/query-syntax.md` — the S-expression query syntax Topiary uses to match code patterns and apply formatting rules. Read when writing or debugging a `.scm` query file.

## Anti-Fabrication Note

Before claiming that Topiary formats a language or query correctly, verify behavior by running `topiary fmt` on actual code files and inspecting the output. Do not assume query behavior without testing; use `topiary visualise` to inspect the parse tree and confirm node names and structure match the query. Test idempotency by running the formatter twice and confirming output is identical.
Files in this package (3)
  • SKILL.md 9 KB
  • references/query-syntax.md 7 KB
  • templates/languages.ncl 4 KB

Versions

The database has no other skills named topiary.

Database snapshot: 13.11.2026 · package version 93af377a932a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100tree-sitter-language-pack
    Parse and extract code intelligence from 372 programming languages using tree-sitter grammars. Use when writing code that parses source, extracts structure/imports/exports/symbols/docstrings/comments, detects a language, runs syntax diagnostics, or produces syntax-aware chunks…
  • 84tree-sitter-language-pack
    Parse and extract code intelligence from 372 programming languages using tree-sitter grammars. Use when writing code that parses source, extracts structure/imports/exports/symbols/docstrings/comments, detects a language, runs syntax diagnostics, or produces syntax-aware chunks…
  • 95biome-formatting
    Use when formatting JavaScript/TypeScript code with Biome's fast formatter including patterns, options, and code style management.
  • 100coderlm
    Structural codebase navigation for supported languages (Rust, Python, TypeScript, JavaScript, Go, Java, Scala, Ruby, PHP, Zig, SQL). Provides tree-sitter-backed indexing: find symbols by name, get exact function bodies, follow caller chains, discover tests. Works best combined…
  • 100code-symbols
    Find and edit symbols in code using ast-grep (tree-sitter based). Use when finding function definitions, class definitions, symbol usages, renaming symbols, or replacing code in JavaScript, TypeScript, Python, Go, Rust, and other languages. NOT for Clojure - use clj-symbols instead.
  • 100graph-build
    Builds or updates the code knowledge graph via tree-sitter AST and SQLite. Use when setting up the graph before search or blast-radius analysis.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.