{"canonical_url":"https://engineer.company/glossary/linter/","content_markdown":"# Linter\n\n## What it is\n\nA linter is a program that reads source code and reports the parts that look\nlike mistakes, without building the program or running it. Each report names a\nrule, a file and a line: a variable assigned and never used, a comparison that\nis always true, a shell variable left unquoted, a format string built from user\ninput.\n\nThe name comes from lint, a checker for C programs, and NetBSD still ships one.\nIts manual gives the job as detecting features of C program files \"that are\nlikely to be bugs, to be non-portable, or to be wasteful\", and adds that it does\nstricter type checking than traditional pre-C90 compilers. It works in two\npasses: first each file is checked as a separate unit, then the results are\ncross-checked for inconsistencies between files.\n\nMost languages now have linters of their own, often several:\n\n- **ESLint** for JavaScript.\n- **Ruff** for Python.\n- **ShellCheck** for shell scripts. Its stated goals run from beginner syntax\n  issues to subtle caveats that may make a working script fail under future\n  circumstances.\n- **Stylelint** for CSS, **markdownlint** for Markdown and **yamllint** for\n  YAML.\n\nEvery linter is built from rules. Each rule has an identifier, such as F841 in\nRuff or SC2059 in ShellCheck, and a severity. A configuration file decides which\nrules are on and how serious each one is, and many rules come with an automatic\nfix.\n\nA formatter rewrites layout and has no opinion on meaning; a type checker\nreasons about what each value is. A linter sits between them and looks at how\nthe code is written: misuse of the language, risky patterns and the conventions\na project has agreed on.\n\n## Why it matters\n\nA linter reads every branch, including the error handler that runs once a year\nand that no test reaches. It takes seconds over a whole repository, so it can\nrun on every save and every commit, and a finding costs least at the moment the\nline is written.\n\nRules settle arguments once. Whether a bare `except:` is acceptable, or whether\nevery shell variable must be quoted, is decided in the configuration and then\napplied the same way to every author and every review. Human reviewers keep\ntheir attention for the questions a rule cannot express.\n\nThe exit code is the interface between a linter and whatever runs it.\nShellCheck's README says the tool \"makes canonical use of exit codes\", so a\nbuild can call it as one more command. Ruff and ESLint document the same\nthree-way convention: 0 when the check is clean, 1 when it found violations, and\n2 when the tool itself failed, for instance on an invalid configuration. A gate\ncan then tell \"the code is wrong\" apart from \"the checker is broken\", and both\nshould stop it.\n\nSeverity decides which findings reach that exit code. ESLint exits with success\nwhen it finds warnings and no errors, unless `--max-warnings` sets a limit, and\nlint(1) has `-w` to treat warnings as errors. A project that wants its linters\nto block mistakes, and not only describe them, writes that choice down where\nevery run uses it:\n\n```sh\n# every finding fails the run, warnings included\nlint -w -abcFghprSxz source.c\neslint --max-warnings 0 src/\nruff check src/\nshellcheck scripts/*.sh\n```\n\nThis site takes the strict end of that choice. Its own gate counts every\ndiagnostic as an error and prohibits inline suppressions such as `# noqa`, so a\nfinding is fixed at its cause.\n\n## What it looks like in practice\n\nA linter's configuration often begins as whichever rules happened to be quiet on\nthe day someone set it up. One page turns that around:\n[every rule of a Python linter enabled as an error](/portfolio/enabled-every-linter-rule-as-an-error/).\nThe first run produced 1,815 findings. They were worked through by category\nrather than by file, because the categories carry information: unused arguments\nand shadowed builtins were noise, while the security, mutable-default and\nexception-handling categories each pointed at real behaviour. The few\nexemptions carry a written reason at the line, and two of them are backed by a\ntest that asserts the property the disabled rule would have enforced. Strict\ntype checking ran alongside and caught a different kind of defect, about what a\nvalue is rather than how it is written. The cost is stated too: someone has to\nmake a judgement 1,815 times.\n\nAnother page starts from an awkward discovery. The site's quality gate,\nthirty-two scripts and 10,242 lines of JavaScript, was the largest body of code\nin the repository and the only one that no formatter, linter or type checker\nread.\n[Bringing the gate's own code under a linter](/portfolio/linted-the-10242-line-quality-gate-itself/)\nstarted with the formatter, set to two-space indentation for those files so\nthat 38 lines changed instead of 2,173. The linter then produced thirteen real\nfindings, all fixed and none suppressed, and a type checker found two defects\nthe linter had passed. The reason for the effort is stated with it: a defect in\na checker shows up as a check that passes when it should not.\n\nThe idea also works on prose. A third page describes\n[a linter for the repository's own documentation](/portfolio/put-the-documentation-under-its-own-linter/),\nwith limits that fail rather than advise. Its eight mechanical policies include\na per-file line budget that can only shrink, a rule that a plan's status must\nagree with its own checkboxes, and a check that every path and code symbol a\ndocument names exists in the tree. The first run found six plans marked done\nwith unchecked boxes, fourteen tasks gating every commit that appeared in no\ndocument, three broken links, one orphaned document and three dead paths.\n\n## Where it goes wrong\n\nA linter seldom fails loudly. The usual fault is a run that exits 0 when it\nshould have stopped something.\n\n**Findings that never change the exit code.** ESLint's `--max-warnings`\ndefaults to -1, which switches the limit off, and lint(1)'s manual says its\ncross-file pass always exits successfully. A finding that cannot fail the run\nis read once and then scrolled past. Decide per rule: an error that fails the\nrun, or off, and set any warnings-as-errors switch in the shared configuration.\n\n**A fix that reports success.** Ruff exits 0 when every violation it found was\nfixed automatically. That is convenient at a desk, but a gate running with fixes\non repairs only its own working copy, and the commit that arrived still holds\nevery violation. Run the gate without fixes, or add `--exit-non-zero-on-fix` so\na fix counts as a failure. Search for `--exit-zero` too: Ruff exits 0 with it\neven when violations are found, and a flag added for one noisy migration tends\nto stay.\n\n**A pattern that selects zero files.** A renamed directory or a moved\nconfiguration can leave a linter pointed at an empty set, and checking zero\nfiles is a clean result. ESLint treats a quoted glob that matches zero files as\nan error by default. `--no-error-on-unmatched-pattern` turns that into a quiet\npass, and `--pass-on-no-patterns` exits 0 when no file patterns are given. Keep\nthe default, and keep one file with a known violation that the gate must report.\n\n**A rule set chosen by what was quiet.** A configuration built by switching off\nwhatever fired on day one records the code's habits, not a standard. Start\nfrom a deliberate selection, either everything at once or Ruff's suggested\nsmall base of `E` and `F` with one group added at a time, and write down why\neach disabled rule is off. Ruff warns that `ALL` implicitly enables new rules\nwhenever the tool is upgraded, so pin the linter's version and upgrade it as a\nchange of its own.\n\n**Suppressions spread one line at a time.** Every linter has an escape hatch:\n`/* LINTED */` in lint(1), `# noqa: F841` in Ruff,\n`# shellcheck disable=SC2059` in ShellCheck and `// eslint-disable-next-line`\nin ESLint. Each records what was silenced, not why. Require a written reason\nbeside every exemption, and for the ones that matter, switch the rule off and\nadd a test for the property it protected. Keeping exceptions in one place helps\ntoo: ESLint's `--no-inline-config` makes disable comments ineffective, and\nShellCheck reads project-wide `disable` lines from a `.shellcheckrc` file.\n\n## Further reading\n\n- [lint(1)](https://man.netbsd.org/lint.1) — NetBSD's manual for the C checker\n  the word comes from: its two passes, `-w` and its suppression comments.\n- [The Ruff Linter](https://docs.astral.sh/ruff/linter/) — rule selection, fix\n  safety, suppression comments and exit codes.\n- [Command Line Interface Reference](https://eslint.org/docs/latest/use/command-line-interface)\n  — ESLint's `--max-warnings`, inline configuration, unmatched patterns and\n  exit codes.\n- [ShellCheck](https://github.com/koalaman/shellcheck) — the project's README:\n  what it looks for and how it fits into a build.\n- [Ignore](https://github.com/koalaman/shellcheck/wiki/Ignore) — ShellCheck's\n  ways to ignore a finding per line, per run and per project.\n\n\u003chttps://engineer.company/glossary/linter/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"What a linter checks without running code, how rules, severities and exit codes decide a build, and how a lint step can pass while it misses things.","formats":{"gemtext":"https://engineer.company/glossary/linter/index.gmi","gopher":"https://engineer.company/glossary/linter/gophermap","html":"https://engineer.company/glossary/linter/","json":"https://engineer.company/glossary/linter/index.json","markdown":"https://engineer.company/glossary/linter/index.md","pdf":"https://engineer.company/glossary/linter/index.pdf"},"kind":"page","language":"en","title":"What is a linter?","url":"https://engineer.company/glossary/linter/","version":1}