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 is | how its files are listed |
|---|---|
| inside a git work tree | git ls-files, tracked and untracked, so .gitignore applies exactly |
| outside git | a directory walk that applies every .gitignore in it with git's pattern rules |
anywhere, git not on PATH | the 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.
| path | result |
|---|---|
| does not exist | error, exit 2 |
| a file that is not TypeScript or JavaScript | error, exit 2 |
| a directory it cannot read, or a path it cannot reach | stanza: cannot read <path>: <reason> on stderr, exit 2 |
| a FIFO, socket or device file | stanza: not a regular file: <path> on stderr, exit 2 |
| a name that is not valid UTF-8 | reported, exit 2 |
| selects nothing | one line on stderr saying why, exit 0 |
For a folder locked that the run cannot open, stderr reads:
stanza: cannot read locked: permission deniedFor a FIFO named pipe.ts:
stanza: not a regular file: pipe.tsThe 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:
stanza: skipped git submodule vendor/sub, pass its path to format its filesNaming 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
| kind | skipped |
|---|---|
| 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 |
| directories | node_modules, dist, build, .next, out, coverage, migrations, drizzle |
| git attributes | files marked linguist-generated in .gitattributes |
| stanza attribute | files whose stanza git attribute is unset or false, written -stanza or stanza=false in .gitattributes, see below |
| generated by header | files 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:
@generatedCode generated by protoc. DO NOT EDIT., or any comment that startsCode generatedand says do not editThis file was automatically generated, and the same withis,has been,codeorclassauto-generated file,autogenerated codeand 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=falseNo 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 code | when a rule applies under --hunks |
|---|---|
| a gap between two statements | one of the two statements around it, or a blank line between them, is on a changed line |
| a braced body | the block holds a changed line, or sits next to such a gap |
| an untracked file | always, 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 file | what stderr says |
|---|---|
| no unstaged changes, whole file in scope | one command that fixes these files and stages them again |
| also has unstaged changes | listed on its own line, to fix with --fix and restage by hand |
under --hunks, scope narrower than the whole file | listed 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>
);
}