Skip to main content
ubx fmt formats .xcl files using the XCL formatter — normalising indentation, aligning = signs within blocks, and collapsing multiple blank lines between blocks to one. It is idempotent: running it twice produces the same result as running it once.

​
Usage

ubx fmt [path] [--check] [--diff]
FormDescription
ubx fmtFormat all .xcl files in the current directory (recursive)
ubx fmt ./infra/Format all .xcl files under ./infra/ (recursive)
ubx fmt stack.xclFormat a single file
ubx fmt --checkCheck formatting without writing; exit 1 if any file would change
ubx fmt --diffPrint a diff of what would change without writing

​
What the formatter normalises

  • Blank lines — two or more consecutive blank lines between top-level blocks are collapsed to one
  • Indentation — block bodies are tab-indented
  • = alignment — assignment operators within the same block are column-aligned
  • Trailing newline — files always end with a single newline
The formatter does not modify comments or reorder declarations.

​
Output

When files are changed, ubx fmt prints one line per modified file followed by a summary: 
formatted: infra/stack.xcl
formatted: infra/input.xcl
2 file(s) formatted
When nothing needs changing: 
all files already formatted

​
Flags

FlagDefaultDescription
--checkfalseCheck mode — print unformatted filenames, exit 1 if any; no files written
--difffalseDiff mode — print a unified diff per file; no files written

​
--check — CI usage

In check mode, ubx fmt prints the name of each file that would be changed and exits with code 1 if any file is unformatted. No files are written. 
ubx fmt --check
# infra/stack.xcl
# exit code: 1
Recommended: add ubx fmt --check to your CI pipeline alongside ubx validate: 
# GitHub Actions example
- run: ubx fmt --check
- run: ubx validate
A clean ubx fmt --check means every .xcl file in the repository is consistently formatted.

​
--diff — preview changes

In diff mode, ubx fmt prints a unified diff showing what would change for each unformatted file. No files are written. 
ubx fmt --diff

--- infra/stack.xcl
+++ infra/stack.xcl
@@ -3,6 +3,5 @@
 }
-
 
 stack "app" {

​
Parse errors

If a .xcl file has a syntax error, ubx fmt skips that file and prints an error to stderr, then continues formatting the remaining files. A single broken file never blocks the rest. 
error: infra/bad.xcl: unexpected token "@" at line 1
formatted: infra/stack.xcl
1 file(s) formatted
The exit code is 0 as long as no --check violation is found — parse errors are reported but do not themselves cause a non-zero exit.

​
Hidden directories

ubx fmt skips directories whose names start with . (.git, .ubx, .terraform, etc.) when walking a directory tree.

​
Idempotency

Running ubx fmt on already-formatted files is safe and fast — the formatter compares the original and formatted bytes before writing, so formatted files are never unnecessarily touched.