Settings

Every key of gspot.toml, its accepted values, and its default. See gspot.toml to change them.

The JSON Schema describes every key. Editors apply it on their own once SchemaStore lists gspot.

Top-level keys

level

"recommended", "all". Default: "recommended".

Correctness, security, accessibility, type safety, routine formatting, and the project’s own declared checks apply at both levels. Level all adds checks and rules for word choice, architecture, naming, doc comments, declaration order, API style, and complexity. No level turns on experimental or preview lint rules.

allowed_words

List or a reasoned value { value = …, reason = "…" }. Default: []. Reason needed when: adding.

Words accepted beyond the shipped spelling list; adding needs a reason.

tool_timeout_seconds

Whole number. Default: 600.

The time limit in seconds for every tool command, including installation and version reads. Root only.

test_files

List. Default: ["**/test/**","**/tests/**","**/__tests__/**","**/*.test.*","**/*.spec.*","**/test_*.py","**/*_test.py","**/conftest.py","**/Tests/**","**/*Tests.swift"].

Test files. Linters apply their test rules to these files.

configurations

List. Default: [].

The configurations this repository uses besides the always-selected ones. gspot init writes the detected ones here; gspot add and gspot remove change the list.

removed_configurations

List. Default: [].

Configurations you removed, which detection does not add back; only gspot add and gspot remove write this list.

[[scope]]

Settings for one folder: its configurations and the tables that differ from the root.

See Monorepos and scopes for how a scope inherits settings.

scope.path

Text. Required.

The folder of the scope; no two records may name the same folder.

scope.configurations

List. Default: [].

Configurations for this folder, on top of the root ones; gspot add --scope writes this list.

scope.removed_configurations

List. Default: [].

Configurations removed in this folder; only gspot add and gspot remove write this list.

scope.test_files

List. Default: unset.

More test files for this folder, added to the root list.

Only the root takes these keys: level, allowed_words, tool_timeout_seconds, import_rule, ignore, command_check, hooks, ci, rules.

[format]

Indentation, line width, quotes, and line endings for every formatter, with overrides for some paths.

format.indent_style

"space", "tab". Default: "space".

The character of one indent level: space or tab.

format.indent_width

Whole number. Default: 4.

Spaces per indent level.

format.print_width

Whole number. Default: 120.

The line width formatters wrap at.

format.line_ending

"lf", "crlf". Default: "lf".

The line ending every file uses: lf or crlf.

format.final_newline

true or false. Default: true.

Whether every file ends with a newline.

format.quotes

"single", "double". Default: "single".

Single or double, for the languages where a formatter chooses.

format.trailing_commas

"all", "es5", "none". Default: "all".

Where trailing commas go: all, es5, or none.

format.semicolons

true or false. Default: true.

Whether JavaScript and TypeScript statements end with semicolons.

[[format.override]]

Formatting options for repository-relative paths, in order.

format.override.paths

List. Required.

The files these formatting values apply to.

format.override.indent_style

"space", "tab". Default: unset.

The character of one indent level: space or tab.

format.override.indent_width

Whole number. Default: unset.

Spaces per indent level.

format.override.print_width

Whole number. Default: unset.

The line width formatters wrap at.

format.override.line_ending

"lf", "crlf". Default: unset.

The line ending every file uses: lf or crlf.

format.override.final_newline

true or false. Default: unset.

Whether every file ends with a newline.

format.override.quotes

"single", "double". Default: unset.

Single or double, for the languages where a formatter chooses.

format.override.trailing_commas

"all", "es5", "none". Default: unset.

Where trailing commas go: all, es5, or none.

format.override.semicolons

true or false. Default: unset.

Whether JavaScript and TypeScript statements end with semicolons.

[limits]

Size and complexity limits for files and functions, with values per language.

Change a limit for the repository, or use limits.<language>.<name> for one language. A value that loosens a check needs a reason.

gspot set limits.block_nesting 4 --reason "The parser is one state machine."

configurations = ["bash"]
level = "all"

[limits]
block_nesting = { value = 4, reason = "The parser is one state machine." }

For one language, set limits.bash.block_nesting instead. Its recommended default is 3.

For a Bash function over this nesting limit, bash/function-size reports:

main has 4 levels of nesting, over the limit of 3.

The raised limit accepts that depth. To inspect the current value and source, run gspot explain limits.block_nesting.

limits.file_lines

Whole number or a reasoned value { value = …, reason = "…" }. Default: 300. Reason needed when: raising. Language defaults: sql 400, bash 140.

The most lines one file may have, not counting blank lines and comment-only lines.

limits.function_lines

Whole number or a reasoned value { value = …, reason = "…" }. Default: 60. Reason needed when: raising. Language defaults: bash 40.

The most lines one function may have.

limits.function_parameters

Whole number or a reasoned value { value = …, reason = "…" }. Default: 7. Reason needed when: raising.

The most parameters one function may take.

limits.function_statements

Whole number or a reasoned value { value = …, reason = "…" }. Default: 30. Reason needed when: raising.

The most statements one function may have.

limits.block_nesting

Whole number or a reasoned value { value = …, reason = "…" }. Default: 3. Reason needed when: raising. Language defaults: bash 3.

How deep blocks may nest inside one function.

limits.callback_nesting

Whole number or a reasoned value { value = …, reason = "…" }. Default: 3. Reason needed when: raising.

How deep callbacks may nest.

limits.cognitive_complexity

Whole number or a reasoned value { value = …, reason = "…" }. Default: 8. Reason needed when: raising.

The highest sonarjs cognitive score one function may have; the score grows as the function gets harder to follow.

limits.cyclomatic_complexity

Whole number or a reasoned value { value = …, reason = "…" }. Default: 8. Reason needed when: raising.

The most paths that may run through one function.

limits.function_branches

Whole number or a reasoned value { value = …, reason = "…" }. Default: 8. Reason needed when: raising. Language defaults: python 8, bash 8.

The most branches one function may have.

limits.function_returns

Whole number or a reasoned value { value = …, reason = "…" }. Default: 4. Reason needed when: raising. Language defaults: python 4.

The most return statements one function may have.

limits.function_assignments

Whole number or a reasoned value { value = …, reason = "…" }. Default: 8. Reason needed when: raising. Language defaults: bash 8.

The most variable assignments one shell function may make.

limits.closure_lines

Whole number or a reasoned value { value = …, reason = "…" }. Default: 60. Reason needed when: raising. Language defaults: swift 60.

The most lines one Swift closure may have.

limits.type_lines

Whole number or a reasoned value { value = …, reason = "…" }. Default: 300. Reason needed when: raising. Language defaults: swift 300.

The most lines one Swift type body may have.

limits.index_exports

Whole number or a reasoned value { value = …, reason = "…" }. Default: 20. Reason needed when: raising.

The most re-exports one index file may hold.

limits.trivial_function_statements

Whole number or a reasoned value { value = …, reason = "…" }. Default: 2. Reason needed when: lowering.

Report functions with this many statements or fewer; any whole number from 1 up works, a higher number reports more functions, and limits.<language> sets it for one language.

limits.shared_prefix_files

Whole number or a reasoned value { value = …, reason = "…" }. Default: 2. Reason needed when: raising.

The number of siblings sharing a name prefix that makes a finding.

limits.<language>

The keys of [limits] for one language: typescript, javascript, python, bash, swift, sql. A key you leave out takes the value of [limits].

[naming]

Banned words, case, and length for the names of files, folders, and identifiers, with values per language.

Allow an exact name only when an external contract requires it. Every shipped banned naming group applies at level all. The roles group rejects vague job labels such as helper and manager; defensive rejects qualifiers such as ensure and maybe; marketing rejects claims such as advanced and enhanced. naming.banned_words adds project words.

For export const helperCommand = 1;, naming/identifiers reports:

javascript variable "helperCommand": "helper" is banned (roles group).

This complete example accepts that exact variable name in one file:

configurations = ["javascript", "naming"]
level = "all"

[[naming.override]]
paths = ["helper.js"]
categories = ["variables"]
allowed_names = ["helperCommand"]
reason = "An external API requires this exact name."

Write override records by hand, then run gspot apply. The override removes this banned-word finding; other names keep their checks.

To change the word limit, run:

gspot set naming.max_words 5 --reason "The public API uses five words."

The words finding reports identifiers over the default of 4 words. The command permits 5 words.

naming.max_characters

Whole number or a reasoned value { value = …, reason = "…" }. Default: 35. Reason needed when: raising. Language defaults: swift 40, sql 55.

The most characters one identifier may have.

naming.max_words

Whole number or a reasoned value { value = …, reason = "…" }. Default: 4. Reason needed when: raising. Language defaults: swift 5, sql 7.

The most words one identifier may have.

naming.cases

List or a reasoned value { value = …, reason = "…" }. Default: []. Reason needed when: adding.

The case patterns that one identifier category accepts: camel, pascal, kebab, snake, upper-snake, pascal-extension (String+Format.swift), or timestamp-snake (20260103120000_create_users.sql). Ruff checks the case of Python classes, functions, and parameters, and SwiftLint checks Swift types, variables, parameters, and enum cases; this setting covers the rest.

naming.banned_words

List. Default: [].

Words this repository bans in identifiers, beyond the shipped groups.

[[naming.override]]

Naming rules for repository-relative paths, in order; each record has its reason.

naming.override.paths

List. Default: ["**"].

Where the override applies.

naming.override.languages

List. Default: unset.

The languages it applies to.

naming.override.categories

List. Default: unset.

The kinds of name it applies to. Unknown kinds are refused.

naming.override.ignored_prefix

Text. Default: unset.

A prefix not counted as a word, such as ^test_.

naming.override.allow_digits

true or false. Default: false.

Accept digits in names.

naming.override.allow_repeated_words

true or false. Default: false.

Accept a word twice in one name.

naming.override.allowed_names

List. Default: unset.

Names accepted despite the naming rules.

naming.override.cases

List. Default: unset.

The cases accepted here.

naming.override.reason

Text. Required.

Why these names may break the rules.

naming.<language>

The keys of [naming] for one language: typescript, javascript, python, swift, bash, sql, css, html. A key you leave out takes the value of [naming].

naming.<language>.<category> sets the same keys for one category of names, and a key you leave out takes the value of naming.<language>. The categories of each language:

Language	Categories
typescript	files, folders, types, functions, parameters, variables, properties
javascript	files, folders, types, functions, parameters, variables, properties
python	files, folders, types, functions, parameters, variables, properties
swift	files, folders, types, functions, parameters, variables, properties
bash	files, folders, functions, variables
sql	files, folders, functions, parameters
css	files, folders
html	files, folders

[cloudflare]

The file that holds the generated Cloudflare binding types, and its interface name.

cloudflare.types_file

Text. Default: "worker-configuration.d.ts".

Tracked Worker environment types file, relative to the repository root.

cloudflare.types_interface

Text. Default: "Env".

Environment interface name passed to wrangler types; OpenNext uses CloudflareEnv.

[coverage]

The lowest test coverage that the test checks accept.

coverage.lines

Number or a reasoned value { value = …, reason = "…" }. Default: recommended: 0; all: 80. Reason needed when: lowering.

The minimum percentage of source lines covered by tests.

coverage.branches

Number or a reasoned value { value = …, reason = "…" }. Default: recommended: 0; all: 80. Reason needed when: lowering.

The minimum percentage of source branches covered by tests.

coverage.functions

Number or a reasoned value { value = …, reason = "…" }. Default: recommended: 0; all: 80. Reason needed when: lowering.

The minimum percentage of source functions covered by tests.

coverage.statements

Number or a reasoned value { value = …, reason = "…" }. Default: recommended: 0; all: 80. Reason needed when: lowering.

The minimum percentage of source statements covered by tests.

[[coverage.swift_target]]

Line coverage floors for named Swift targets.

coverage.swift_target.name

Text. Required.

A Swift target named in the coverage report.

coverage.swift_target.lines

Number. Required.

The least share of lines that the target must cover, in place of coverage.lines.

coverage.swift_target.reason

Text. Default: unset.

Why this target may cover less.

[dependencies]

How many days a new release waits before an install picks it up, and the registries that lockfiles may use.

dependencies.min_release_age_days

Whole number or a reasoned value { value = …, reason = "…" }. Default: 7. Reason needed when: lowering.

How many days a new release waits before gspot installs it as one of its tools in .gspot.

dependencies.allowed_registries

List or a reasoned value { value = …, reason = "…" }. Default: ["registry.npmjs.org","registry.yarnpkg.com"]. Reason needed when: adding.

The hosts a lockfile may resolve packages from.

dependencies.bun_scanner

Text. Default: unset.

The npm package that Bun runs as its install security scanner. Without it, Bun runs no scanner.

[docs]

Headings that documentation may not use, and URLs that the link check accepts.

docs.banned_headings

List. Default: [].

Headings this repository bans beyond the shipped list.

docs.allowed_urls

List or a reasoned value { value = …, reason = "…" }. Default: []. Reason needed when: adding.

Allowed URL patterns; additions need a reason for the whole list.

[drizzle]

The names of Drizzle clients in your code.

drizzle.client_names

List. Default: ["db"].

The Drizzle client identifiers checked for update and delete operations without a where clause.

[javascript]

The script files, which may print to the console and exit.

javascript.script_files

List. Default: ["scripts/**","**/*.config.{js,mjs,cjs,ts}"].

Script files, which may print to the console and call process.exit.

[trpc]

The files that declare tRPC procedures, and the server files that other files import only as types.

trpc.router_files

List. Default: ["**/routers/**","**/*router*.ts","**/trpc/**"].

The files that declare tRPC procedures.

trpc.server_files

List. Default: [].

The server files that other files of a tRPC scope may import only as types; empty turns the rule off.

[zustand]

The files that may create a Zustand store.

zustand.store_files

List. Default: ["**/store.*","**/stores/*","**/store/*","**/*.store.*"].

The files that may create a store.

[licenses]

The licenses that dependencies may have, and single packages accepted with a reason.

licenses.allowed

List. Default: [].

The SPDX license IDs a dependency may report.

[[licenses.allowed_package]]

Packages accepted under a license outside the list: name, exact version, and reason.

licenses.allowed_package.name

Text. Required.

The package name, such as lightningcss or @fontsource-variable/geist.

licenses.allowed_package.version

Text. Required.

The exact installed version; gspot reports a record that matches no installed package.

licenses.allowed_package.reason

Text. Required.

Why you accept its license; name the license here.

[openapi]

The committed OpenAPI document, and the command that generates it.

openapi.document

Text. Default: unset.

The committed OpenAPI document, relative to the repository root, which init fills in when it finds one; without it, the OpenAPI checks do not run.

openapi.generate_command

List. Default: unset.

The command that writes the OpenAPI document from the code, run in the project scope folder.

[postgres]

The migrations folder, the schemas that clients read, and the migrations that may not change.

postgres.client_schemas

List. Default: [].

The schemas clients reach, where every table needs row level security.

postgres.frozen_through

Text. Default: "none".

The last migration version that has run everywhere (none, all, or a version); Squawk skips those migrations, and they may not change.

postgres.migrations_folder

Text. Default: unset.

The migrations folder, relative to the repository root; without it, the checks use the migration files of this configuration.

[secrets]

The env example files, and the functions in your code that read environment variables.

secrets.env_examples

List. Default: [".env.example",".env.template",".env.sample",".dev.vars.example"].

The env example filenames to search for environment keys; a key may appear in any one of them.

secrets.environment_functions

List. Default: [].

Functions of this project that read environment variables, such as read_env. The env-examples check reads the keys they take.

[site]

How the site builds, where the built files go, and the size limits of its files.

site.build_command

List. Default: ["npm","run","build"].

The command that builds the site. Without it, gspot runs the build script of the package manager.

site.build_folder

Text. Default: "dist".

The folder the build writes.

site.allowed_unlisted_pages

List or a reasoned value { value = …, reason = "…" }. Default: ["404.html"]. Reason needed when: adding.

Built pages the sitemap leaves out on purpose.

[[site.size_limit]]

Size limits: the built paths, and the most kilobytes they may weigh compressed.

site.size_limit.paths

List. Required.

Built files, such as docs/dist/_astro/*.js; the size check runs only when a record exists.

site.size_limit.kilobytes

Whole number. Required.

The most they may weigh together, compressed.

[spelling]

The language of the spelling check, such as en-us or en-gb.

spelling.locale

"en", "en-us", "en-gb", "en-au", "en-ca". Default: "en-us".

The English locale typos checks against: en, en-us, en-gb, en-ca, or en-au.

[supabase]

The folders of Supabase edge functions, the schemas, and the generated types file.

supabase.functions_folder

Text. Default: "supabase/functions".

The folder, relative to the repository root, with one folder for each edge function; the default starts from the project scope.

supabase.schemas

List. Default: ["public"].

The database schemas to include in generated types.

supabase.types_file

Text. Default: unset.

The committed database types file, relative to the repository root; without it, no type comparison runs.

[translations]

The base locale and the folder of message files.

translations.base_locale

Text. Default: "en".

The locale whose message keys every other locale must contain.

translations.messages_folder

Text. Default: unset.

The folder of the <locale>.json message files, relative to the repository root.

[swift]

The Xcode project, scheme, and destination that the Swift build uses.

swift.xcode_project

Text. Default: unset.

The Xcode project or workspace, relative to the repository root, which init fills in when it finds one; without it, the checks use the Swift package.

swift.xcode_scheme

Text. Default: unset.

The shared scheme the build, the analyzer, and Periphery use.

swift.xcode_destination

Text. Default: "generic/platform=iOS Simulator".

The xcodebuild destination.

[repository]

The largest file that Git may track, in kilobytes.

repository.max_file_kilobytes

Whole number or a reasoned value { value = …, reason = "…" }. Default: 1024. Reason needed when: raising.

The largest file, in kilobytes, that Git may track without Git LFS or a linguist-generated or linguist-vendored mark in .gitattributes.

[prose]

The longest sentence, list item, and paragraph that the prose check accepts.

prose.max_sentence_words

Whole number or a reasoned value { value = …, reason = "…" }. Default: 30. Reason needed when: raising.

The most words one sentence of documentation may have.

prose.max_list_item_words

Whole number or a reasoned value { value = …, reason = "…" }. Default: 45. Reason needed when: raising.

The most words one list item may have.

prose.max_paragraph_sentences

Whole number or a reasoned value { value = …, reason = "…" }. Default: 6. Reason needed when: raising.

The most sentences one paragraph may have.

[duplication]

The smallest copy, in lines and tokens, that the duplication check reports.

duplication.min_lines

Whole number or a reasoned value { value = …, reason = "…" }. Default: 8. Reason needed when: raising.

The fewest lines a copied block has before it counts.

duplication.min_tokens

Whole number or a reasoned value { value = …, reason = "…" }. Default: 40. Reason needed when: raising.

The fewest tokens a copied block has before it counts.

[xcode]

The entitlements that an Xcode project may request.

xcode.allowed_entitlements

List. Default: [].

The entitlements the app may hold; empty turns the check off.

[tools]

Options for single tools, such as lint rule options. gspot writes them into the tool files.

[tools.hadolint]

tools.hadolint.trusted_registries

List. Default: [].

The registries a base image may come from; empty allows any.

[tools.nginx]

tools.nginx.image

Text. Default: "nginx:1.29.3-alpine".

The image nginx -t runs in; name the one the deployment uses.

[tools.ruff]

tools.ruff.docstring_convention

"google", "numpy", "pep257". Default: unset.

The docstring style that Ruff and pydoclint check: google, numpy, or pep257.

[tools.semgrep]

tools.semgrep.registry_packs

List. Default: ["p/owasp-top-ten"].

The registry packs the manual registry check runs.

tools.semgrep.rule_files

List. Default: [].

Rule files or folders of the repository that Semgrep runs beside the shipped packs.

[tools.sqlfluff]

tools.sqlfluff.dialect

Text. Default: "ansi".

The SQL dialect that SQLFluff parses, such as postgres. The postgres configuration sets it.

[tools.swiftlint]

tools.swiftlint.always_keep_imports

List. Default: [].

Imports the analyzer keeps although it sees no use of them.

[tools.trivy]

tools.trivy.severity

List. Default: ["HIGH","CRITICAL"].

The severities Trivy reports.

[tools.eslint]

tools.eslint.extra

A reasoned value { value = …, reason = "…" }. Default: unset.

Extra options passed to the tool as written.

tools.eslint.import_extension

"js", "ts", "extensionless". Default: "js".

The import suffix in this scope: js for compiled ESM, ts for Deno and Bun, or extensionless for code that a bundler builds.

tools.eslint.rules

Table. Default: {}.

Option arrays by ESLint rule ID, without a severity, which apply only where the level turns the rule on; accept findings with gspot ignore --rule.

[[tools.eslint.restricted_imports]]

Imports that this repository refuses, each with a name and a message.

tools.eslint.restricted_imports.name

Text. Required.

The import to refuse.

tools.eslint.restricted_imports.message

Text. Required.

What to import instead.

[[tools.eslint.override]]

Lint rule options for repository-relative paths, in order, with ignores applied last.

tools.eslint.override.paths

List. Required.

The files that these lint rule options apply to.

tools.eslint.override.rules

Table. Default: unset.

Lint rule options for these files.

tools.eslint.override.runtime

One of 59 names. Default: unset.

The runtime of these files, such as serviceworker (the name the globals package uses).

[tools.commitlint]

tools.commitlint.types

List. Default: ["feat","fix","refactor","perf","docs","test","build","ci","chore","style","revert"].

The commit types the type-enum rule allows.

tools.commitlint.scopes

List. Default: [].

Commit scopes that the scope-enum rule accepts, and a message may leave out its scope. When empty, gspot uses the last segment of each project scope path, or no list without project scopes.

tools.commitlint.rules

Table. Default: {}.

Options for active commitlint rules, by rule name: an always/never condition and an optional value, without a severity; the level decides which rules run. Ignore a finding with gspot ignore commits/commitlint --rule <rule> --reason <why>.

[tools.yamllint]

[tools.yamllint.rules]

Option tables for active YAML rules; the level decides which rules run, and [format] sets the width. Ignore a finding with gspot ignore files/yamllint --rule <rule> --reason <why>.

[tools.yamllint.rules.indentation]

tools.yamllint.rules.indentation.level

"error". Default: unset.

tools.yamllint.rules.indentation.ignore

Value. Default: unset.

tools.yamllint.rules.indentation.ignore-from-file

Value. Default: unset.

tools.yamllint.rules.indentation.spaces

"consistent". Default: unset.

[tools.yamllint.rules.<name>]

tools.yamllint.rules.<name>.level

"error". Default: unset.

tools.yamllint.rules.<name>.ignore

Value. Default: unset.

tools.yamllint.rules.<name>.ignore-from-file

Value. Default: unset.

[tools.markdownlint]

tools.markdownlint.rules

Table. Default: {}.

Option tables by Markdown rule ID, such as MD024; the level decides which rules run. Ignore a finding with gspot ignore markdown/markdownlint --rule <rule> --reason <why>.

[tools.stylelint]

tools.stylelint.rules

Table. Default: {}.

Options for the Stylelint rules that run at the level, which stay errors. Accept a finding with gspot ignore css/stylelint --rule <rule> --reason <why>.

[tools.squawk]

tools.squawk.assume_in_transaction

true or false. Default: false.

Whether the migration runner wraps every migration in a transaction; the supabase configuration turns it on.

[tools.prettier]

tools.prettier.extra

A reasoned value { value = …, reason = "…" }. Default: unset.

Extra options passed to the tool as written.

[tools.editorconfig-checker]

tools.editorconfig-checker.extra

A reasoned value { value = …, reason = "…" }. Default: unset.

Extra options passed to the tool as written. These options go into .editorconfig.

[tools.typos]

tools.typos.extra

A reasoned value { value = …, reason = "…" }. Default: unset.

Extra options passed to the tool as written.

[tools.shellcheck]

tools.shellcheck.extra

A reasoned value { value = …, reason = "…" }. Default: unset.

Extra options passed to the tool as written.

[tools.knip]

tools.knip.extra

A reasoned value { value = …, reason = "…" }. Default: unset.

Extra options passed to the tool as written.

tools.knip.entry

List. Default: [].

Entry points knip starts from beyond the ones the framework configuration declares.

tools.knip.ignore_dependencies

List or a reasoned value { value = …, reason = "…" }. Default: []. Reason needed when: adding.

Exact package names that knip does not report as unused; new names need a reason, and a scope list applies to that project only.

[tools.purgecss]

tools.purgecss.safelist

List or a reasoned value { value = …, reason = "…" }. Default: []. Reason needed when: adding.

Class names a script adds at run time: the names and the reason.

[tools.v8r]

[[tools.v8r.schema]]

File patterns mapped to schema URLs, for files that the SchemaStore catalog does not know.

tools.v8r.schema.paths

List. Required.

Files SchemaStore does not know.

tools.v8r.schema.url

Text. Required.

The JSON Schema for them.

[tools.taplo]

tools.taplo.extra

A reasoned value { value = …, reason = "…" }. Default: unset.

Extra options passed to the tool as written.

[[import_rule]]

Groups of files in import order: code may import the files of its own rule and of every rule listed above it.

import_rule.name

Text. Required.

The name that other import rules use in can_also_import.

import_rule.paths

List. Required.

The files of the import rule.

import_rule.can_also_import

List. Default: [].

The import rules listed below this one that its files may import.

[[ignore]]

Checks and lint rules turned off for some paths or everywhere, each with a reason.

ignore.check

Text. Required.

The check whose findings you accept: a shipped check or a command check.

ignore.rule

Text. Default: unset.

One lint rule of that check.

ignore.paths

List. Default: unset.

Where the ignore applies.

ignore.reason

Text. Required.

Why you accept the findings.

ignore.until

Text. Default: unset.

Stop applying this ignore on this date, in YYYY-MM-DD format (UTC).

[[command_check]]

Your own commands, run as checks with a stage, a file list, and an output format.

command_check.command

List. Required.

The executable and arguments to run on selected files.

command_check.stage

"commit", "push", "manual". Required.

The earliest stage that runs this check.

command_check.summary

Text. Default: unset.

A short description shown in check listings.

command_check.help

Text. Default: unset.

Instructions for resolving findings.

command_check.fix

List. Default: unset.

The executable and arguments that correct findings.

command_check.exit_codes

List. Default: unset.

Nonzero statuses that mean findings from command and fix. Other nonzero statuses mean execution failure.

command_check.name

Text. Required.

The check ID that --only and [[ignore]] check use, which may not match a shipped check.

command_check.paths

List. Required.

Repository-relative glob patterns selecting inputs.

[command_check.output]

The parser and location patterns used to read findings.

command_check.output.format

One of these values:

Value	Meaning
"regex"	Read findings from lines matched by pattern and its named file, line, column, rule, and message groups.
"grouped"	Read a file heading matched by file_pattern, followed by findings matched by pattern.
"sarif"	Read SARIF results, rule metadata, source locations, and fixes.
"knip"	Read Knip JSON issue categories and source positions.
"semgrep"	Read Semgrep JSON results, locations, rule IDs, messages, and fixes provided by Semgrep.
"trufflehog"	Read TruffleHog JSON findings while withholding raw secret output.
"typos"	Read typos JSON and convert byte offsets to character columns.
"markdownlint"	Read markdownlint result objects and their rule and source locations.
"json"	Read JSON findings using items, children, and fields to select report entries.
"lines"	Report each nonempty output line as a finding without a source location.
"none"	Use the exit status without parsing output into findings.

Required.

How gspot reads the output: json, regex, grouped, lines, none, or the format of a named tool.

command_check.output.items

Text. Default: unset.

For json: the path to the list of findings.

command_check.output.children

Text. Default: unset.

For json: the field of each item that holds its findings.

command_check.output.line_base

0 or 1. Default: unset.

Whether the tool counts lines from 0 or 1.

command_check.output.file_type

"path", "link", "history". Default: "path".

What the file field holds: a path in the repository, a link target, or a path in a past commit.

command_check.output.pattern

Text. Default: unset.

For regex: the pattern for one finding, with named groups file, line, column, rule, and message.

command_check.output.file_pattern

Text. Default: unset.

For regex: the pattern for a line that names the file of the findings below it.

command_check.output.fixable

Text. Default: unset.

For regex: the pattern that marks a fixable finding.

command_check.output.message

Text. Default: unset.

For regex: the pattern for the message.

[command_check.output.fields]

command_check.output.fields.file

Text. Default: unset.

For json: the field that holds the file.

command_check.output.fields.line

Text. Default: unset.

For json: the field that holds the line.

command_check.output.fields.column

Text. Default: unset.

For json: the field that holds the column.

command_check.output.fields.rule

Text. Default: unset.

For json: the field that holds the lint rule.

command_check.output.fields.message

Text. Default: unset.

For json: the field that holds the message.

command_check.output.fields.fixable

Text. Default: unset.

For json: the field that is set when the tool can fix the finding.

[structure]

Whether files may re-export the exports of other files, and which files may read environment variables.

structure.reexports

"none", "index-only" or a reasoned value { value = …, reason = "…" }. Default: "none". Reason needed when: adding.

Where re-exports may go: none, or an index file that re-exports other files.

structure.environment_readers

List. Default: [].

The files that may read environment variables; other files get the values passed in.

[hooks]

Whether gspot install turns on the Git hooks.

hooks.enabled

true or false. Default: false.

Install and run the configured Git hooks.

[ci]

Whether gspot writes a CI workflow, for which provider, and on which systems it runs.

ci.enabled

true or false. Default: false.

Whether gspot writes a CI workflow; set it at the root only.

ci.provider

"github", "gitlab". Default: "github".

Which CI service gets the workflow; set it at the root only.

ci.setup_command

List. Default: unset.

A command that CI runs before gspot install, such as npm ci; set it at the root only.

ci.operating_systems

List. Default: ["linux"].

The operating systems of the CI jobs. GitHub only; refused with provider = “gitlab”.

[rules]

Whether gspot writes rules for coding agents, and which rule files it leaves out.

rules.enabled

true or false. Default: true.

Write the rules and the AGENTS.md block.

rules.exclude

List. Default: [].

Rule files or folders under .gspot/configurations/ to leave out, such as .gspot/configurations/general/engineering/rules/PLANNING.md.