Stanza

File Selection

See which files a run takes, and which it always skips.

A run takes its files from exactly one source: paths, --changed, --staged, or a single buffer on --stdin. Whatever the source, the always skipped list and generated file detection apply.

Stanza formats .ts, .tsx, .mts, .cts, .js, .jsx, .mjs and .cjs files.

Paths

stanza --fix <paths...> and stanza --check <paths...> take files and directories. Directories recurse. Put -- before paths that start with -.

where the path ishow its files are listed
inside a git work treegit ls-files, tracked and untracked, so .gitignore applies exactly
outside gita directory walk that applies every .gitignore in it with git's pattern rules
anywhere, git not on PATHthe directory walk, with a warning on stderr

A file named directly is taken even when a .gitignore lists it. The always skipped list and generated file detection still apply to it.

pathresult
does not existerror, exit 2
a file that is not TypeScript or JavaScripterror, exit 2
a directory it cannot read, or a path it cannot reachstanza: cannot read <path>: <reason> on stderr, exit 2
a FIFO, socket or device filestanza: not a regular file: <path> on stderr, exit 2
a name that is not valid UTF-8reported, exit 2
selects nothingone line on stderr saying why, exit 0

For a folder locked that the run cannot open, stderr reads:

Unreadable Folder
stanza: cannot read locked: permission denied

For a FIFO named pipe.ts:

Not a Regular File
stanza: not a regular file: pipe.ts

The line for an empty selection names the reason: the stanza attribute opts its files out, every file under it is generated, git ignores its files, its files are always skipped, or it holds no TypeScript or JavaScript files.

Submodules

Files inside a git submodule belong to the submodule's own repository, so a path in the superproject leaves them out, and stderr gives one line for each submodule it skipped:

Skipped Submodule
stanza: skipped git submodule vendor/sub, pass its path to format its files

Naming the submodule, or a path inside it, formats its files. --changed and --staged print the same line when the submodule has changes or a staged new commit. The hook prints nothing for a submodule.

Always Skipped

kindskipped
declaration files*.d.ts, *.d.mts, *.d.cts
generated by name*.gen.ts, *.gen.tsx, *.gen.mts, *.gen.cts, *.gen.js, *.gen.jsx, *.gen.mjs, *.gen.cjs, *.generated.*, *.min.js, *.min.mjs, *.min.cjs
directoriesnode_modules, dist, build, .next, out, coverage, migrations, drizzle
git attributesfiles marked linguist-generated in .gitattributes
stanza attributefiles whose stanza git attribute is unset or false, written -stanza or stanza=false in .gitattributes, see below
generated by headerfiles whose first ten lines hold a comment that marks them as generated, see below

Generated Files

A comment in the first ten lines marks a file as generated when it says so outright:

  • @generated
  • Code generated by protoc. DO NOT EDIT., or any comment that starts Code generated and says do not edit
  • This file was automatically generated, and the same with is, has been, code or class
  • auto-generated file, autogenerated code and the like

A Generated by (or from, with, using) line counts only when another comment in those ten lines warns not to edit the file. A comment that only says do not edit is not enough on its own.

stanza explain still explains a generated or skipped file, and says that --fix and --check skip it.

Opting a File Out

To keep stanza off a file without editing it, unset its stanza git attribute:

# .gitattributes
packages/shared/src/pinned.ts -stanza
legacy/** stanza=false

No source takes the file, not paths, --changed, --staged, --stdin or the hook, and it is never reported as generated. Stanza reads the attribute through git, so .gitattributes, .git/info/attributes and the global and system attributes files all count. With no git on PATH the directory walk reads no attributes, so the opt out needs git, as linguist-generated does. Setting it, or giving it any other value, leaves the file selected. Unlike a stanza-off comment, the file itself stays untouched.

stanza explain still explains an opted out file, and says the attribute is why --fix and --check skip it.

Changed Files

stanza --fix --changed
stanza --check --changed --hunks

--changed takes the files from git diff --name-only HEAD plus untracked files, across the whole repository whatever the working directory. Before the first commit it takes every tracked and untracked file. Outside a git repository, or with no git on PATH, it is an error and exits 2. A changed file under a directory stanza cannot search, or an untracked directory git cannot open, prints the cannot read line a path run prints and exits 2, while a file deleted from the working tree is skipped without a word.

Hunks

--hunks narrows --changed or --staged to the lines changed against HEAD.

part of the codewhen a rule applies under --hunks
a gap between two statementsone of the two statements around it, or a blank line between them, is on a changed line
a braced bodythe block holds a changed line, or sits next to such a gap
an untracked filealways, the whole file counts as changed

What counts as a changed line:

  • Braces stanza removed do not make a line changed, so a second run changes nothing.
  • A deleted line that held only a brace is no change at all.
  • Any other deleted line counts only for the gap it sat in.

For holding new changes to the rules in a codebase that does not follow them yet, see Existing Codebases.

Staged

stanza --check --staged
stanza --check --staged --hunks

--staged checks what is in the index, not the working tree. It picks files by the same rules as --changed, and reads .gitattributes from the index too. A file the stanza attribute opts out in either the index or the working tree is skipped, since --fix would skip it. Lint config still comes from each file's real path. It works only with --check.

With --hunks it narrows to the lines the index changes against HEAD. Before the first commit every staged line counts. A staged file with a filter attribute counts as changed throughout, since its index blob is not the text being checked. A staged file whose filter differs between the index and the working tree needs git 2.40 or later.

When findings --fix can apply remain, stderr ends with what to do about each file:

staged filewhat stderr says
no unstaged changes, whole file in scopeone command that fixes these files and stages them again
also has unstaged changeslisted on its own line, to fix with --fix and restage by hand
under --hunks, scope narrower than the whole filelisted on its own line, to fix by hand and restage with git add -p

So no unstaged work gets staged, and --fix, which has no staged line scope, never rewrites lines outside the check. For running this as a hook, see Pre-Commit Hook.

Names That Are Not UTF-8

Linux lets a file or directory name hold bytes that are not valid UTF-8. Stanza cannot read such a name as a path, so a TypeScript or JavaScript file under one is reported, quoted as git quotes it, and left untouched:

stanza: name is not valid UTF-8: "src/bad\377.ts"

A path argument, a directory, --changed, --staged and a symlink leading to such a name all print the line and exit 2, and the rest of the run still goes ahead. --staged leaves the file out of the command it suggests. The stanza attribute and linguist-generated skip such a file as they skip any other. The hook prints the line after stanza hook: and exits 1, without blocking. A working directory with such a name is treated as one stanza cannot read, so a run that needs it exits 2. A file whose name ends in another extension is skipped as before. macOS refuses these names, so there is nothing to report there.

JSX

.tsx, .jsx, .js, .mjs and .cjs files can hold JSX.

Stanza leaves JSX markup as written: tags, attributes, text and the lines between them. The code inside it, such as an onClick callback, a function passed to map in children or a render prop, gets every rule a .ts or .js file gets. A {/* stanza-off */} comment inside markup leaves the code below it alone up to a {/* stanza-on */}. A stanza-ignore needs a statement directly below it, so it goes inside the callback, above that statement.

import { addTodo } from "./todos";

export function TodoList({ todos }: { todos: string[] }) {
  const count = todos.length;

  if (count === 0) return null;

  return (
    <section>
      <button
        type="button"
        onClick={() => {
          const todo = todos[0];

          if (!todo) return;

          addTodo(todo);
        }}
      >
        Add first todo
      </button>

      <ul>
        {todos.map((todo) => {
          const label = todo.trim();

          if (!label) {
            return null;
          }

          if (!label) return null;
          return <li key={todo}>{label}</li>;
        })}
      </ul>
    </section>
  );
}

On this page