Formatting

badness format lays out LaTeX and BibTeX source deterministically. The formatter’s rules and layout engine determine the output, so there are no special cases for individual constructs to memorize.

In Place, stdin, or check

badness format paper.tex          # rewrite the file in place
cat paper.tex | badness format    # stdin → stdout
badness format --check paper.tex  # diff, don't write; non-zero if unformatted

Pass several paths to format them all:

badness format intro.tex methods.tex results.tex

Pass - to read from standard input and write the formatted result to standard output—handy for piping or editor integrations:

cat paper.tex | badness format -

Badness also reads piped input when you omit paths, so the shorter cat paper.tex | badness format works too. At an interactive prompt, badness format with no paths reports a usage error. See Checking Without Writing for --check reporting.

Checking Without Writing

In CI you usually want to verify that files are already formatted rather than rewrite them. The --check flag prints a diff of what would change and exits with a nonzero status if any file needs formatting:

badness format --check paper.tex

Diff in paper.tex:12:
 \section{Introduction}
-Some    text with   odd spacing.
+Some text with odd spacing.
1 of 1 file(s) would be reformatted

The report shows what would change and appears by default. Pass --quiet for just the file list and summary—useful when a first run over an unformatted project would otherwise flood a CI log:

badness format --check --quiet .

The report goes to stdout and uses color when writing to a terminal. Only errors use stderr. Override the color setting with --color always|never; Badness also honors NO_COLOR.

Style Options

Style flags such as --line-width, --indent-width, --item-indent, and --wrap mirror the [format] section of badness.toml and override it for a single run. The Configuration reference lists each option’s default and meaning.

For example, set the line width, indentation, and wrapping mode for one run:

badness format --line-width 100 --indent-width 4 --wrap preserve paper.tex

See the CLI Reference for every flag and the Configuration reference for what --wrap controls.

For persistent settings, Badness discovers badness.toml from each input file’s directory upward; pass --config <PATH> to point at a specific file or --no-config to ignore any discovered one. Run badness init to write a starter badness.toml. See Configuration to share settings and exclude files from formatting and linting.

Under reflow, textual optional arguments wrap at existing top-level comma-space boundaries and fill each line to the configured width. Continuation lines are indented, and brackets remain attached wherever adding a space would change the argument. Known key-value arguments instead expand to one entry per line when they do not fit. Opaque braced environment arguments keep values such as {section in head/foot} together instead of wrapping their words. Existing comments retain their binding; the formatter does not insert % markers to create new break opportunities.

Known key-value lists discard padding around their top-level entries. Package name lists also discard padding, so \usepackage[ letterpaper , scale=0.8 ]{ geometry } formats as \usepackage[letterpaper,scale=0.8]{geometry}. Spaces inside braced option values remain intact.

For a literal top-level \documentclass{cas-sc} or \documentclass{cas-dc}, Badness treats the braced affiliation fields and the trailing address options of \affiliation as key-value lists. Short lists stay inline; longer lists expand to one entry per line. Other classes retain ordinary argument formatting, and definitions in the document or a loaded local package override the class signature.

In align and other math alignment grids, including nested aligned environments, a leading \label{key} sits on its own line. Formula rows align without counting the label toward column widths. Trailing comments stay attached to their labels, and labels within formula rows stay in place. This layout applies independently of math-wrap.

Under math-wrap = "break" (the default unless wrap = "preserve"), multiline sibling environments in display math form separate blocks, even when a joined line would fit. Intervening expressions sit on their own lines, and punctuation stays attached to the preceding block. A prefix such as A = can still introduce the first environment on the same line. Explicit preserve and single-line math modes retain their existing line-break policies.

Inside algorithm and algorithm2e environments (including their starred forms), Badness normalizes text in \KwIn, \KwOut, \KwData, and \KwResult. It indents the braced bodies of \For, \ForEach, \ForAll, \While, \If, \ElseIf, \Else, \eIf, and \Repeat, placing each statement ending in \; on its own source line. Math spacing commands remain inside their formulas, and trailing comments stay attached to their statements. Control-flow commands need their complete braced arguments to receive this layout; custom commands and forms with parenthesized side comments use the ordinary fallback. Top-level \; statements require a recognized control-flow call in the environment’s direct body, since the separate algorithm package uses the same float name and can use \; for ordinary spacing.

BibTeX Field Order

BibTeX entries share one field order across all entry types, including custom types. The formatter places title, subtitle, titleaddon, and shorttitle first, followed by author and other contributors, container titles, dates, publication details, identifiers, and notes. Fields outside the shared order appear afterward in alphabetical order. Whether a field is required or optional does not affect its position.

Repeated fields retain their relative order, and comments move with the fields they belong to.

Turning the formatter off

Sometimes you want to preserve a block laid out by hand, such as a tikzpicture aligned by eye or a table whose columns line up in the source. Comment directives turn the formatter off for the selected construct, region, or file. Content inside is reproduced byte for byte.

Skip the next construct:

% badness-format skip: hand-aligned by eye
\begin{tikzpicture}
  \foreach \p/\pos in {A/left, B/left, C/right, D/right}%
  \node[\pos] at (\p) {$\p$};%
\end{tikzpicture}

Skip a region:

% badness-format off
\begin{tabular}{ll}
  a   &   b \\
  ccc &   d \\
\end{tabular}
% badness-format on

Skip a whole file, wherever in it the directive sits:

% badness-format skip-file: generated, do not edit

An off with no matching on runs to the end of the file. The optional : <reason> explains the directive to the next reader; Badness does not interpret it.

Each directive has a bare counterpart that turns off both the formatter and every lint rule over the same span: % badness skip, % badness off / % badness on, and % badness skip-file. Use the -format spelling when you want the linter to keep reporting.

To exclude whole files by path instead, use exclude/extend-exclude in badness.toml; see the Configuration reference. That is the better tool when you control the config, since it keeps the directive out of the document.

% badness-lint suppresses diagnostics without changing layout and takes an optional rule name; see Linting.

A directive must be its own % comment. On a .dtx documentation line, the leading % is a documentation margin rather than a comment, so a directive written there has no effect. Inside a macrocode chunk, it works normally.

Guarantees

The formatter is built around a small set of invariants that double as test oracles:

• Idempotence: format(format(x)) == format(x).
• Losslessness: the parsed tree reconstructs the input byte-for-byte, so the formatter never loses or corrupts content.
• Protected regions: verbatim-like content (verbatim, lstlisting, \verb, comments) is never altered. An environment Badness cannot recognize as verbatim, such as one defined through macros the scanner cannot follow, can be named in [environments], which also lets you declare a \bea and \eea pair defined in a sibling .sty.
• Whitespace-only: formatting changes whitespace, line breaks, and comment placement, and nothing else. It never inserts, deletes, or rewrites a token of real content.

Content rewrites, such as changing x^{2} to x^2 or $$…$$ to \[…\], are therefore lint fixes. Run badness lint --fix for those.