Settings Reference

This page is generated from Shuck's Rust configuration metadata and lists the supported shuck.toml and .shuck.toml settings.

Use Configuration for discovery, precedence, and examples of how config files are resolved.

[check]

File-level analysis behavior for shuck check.

embedded

Lint supported embedded shell scripts in non-shell files, including GitHub Actions workflow run blocks and composite action steps.

Default value: true

Type: bool

Example usage:

[check]
embedded = false

[format]

Formatter style options for shuck format.

binary-next-line

Place binary list and pipeline operators at the start of continuation lines when a command is split.

Default value: false

Type: bool

Example usage:

[format]
binary-next-line = true

function-next-line

Place function opening braces on the line after the function name.

Default value: false

Type: bool

Example usage:

[format]
function-next-line = true

indent-style

Indent with tabs or spaces. Supported values are tab and space.

Default value: "tab"

Type: string

Example usage:

[format]
indent-style = "space"

indent-width

Number of spaces to use for each indentation level when indent-style = "space".

Default value: 8

Type: integer

Example usage:

[format]
indent-width = 2

keep-padding

Preserve existing horizontal padding in source regions where the formatter can do so safely.

Default value: false

Type: bool

Example usage:

[format]
keep-padding = true

never-split

Prefer compact layouts and avoid optional line splitting.

Default value: false

Type: bool

Example usage:

[format]
never-split = true

space-redirects

Insert spaces between redirection operators and their targets where the shell grammar allows it.

Default value: false

Type: bool

Example usage:

[format]
space-redirects = true

switch-case-indent

Indent case branch bodies one level deeper than the branch pattern.

Default value: false

Type: bool

Example usage:

[format]
switch-case-indent = true

[lint]

Rule selection, per-file ignores, fix eligibility, and rule-specific behavior for shuck check.

extend-fixable

Add rules to the set that can receive automatic fixes when shuck check --fix is enabled.

Default value: []

Type: list[selector]

Example usage:

[lint]
extend-fixable = ["S074"]

extend-per-file-ignores

Add more per-file ignores without replacing the existing per-file-ignores table.

Default value: {}

Type: table[str, list[selector]]

Example usage:

[lint]
extend-per-file-ignores = { "vendor/**" = ["ALL"] }

extend-select

Enable additional rules or named selectors on top of the default or explicitly selected rule set.

Default value: []

Type: list[selector]

Example usage:

[lint]
extend-select = ["google"]

fixable

Replace the set of rules that can receive automatic fixes when fixes are available.

Default value: ["ALL"]

Type: list[selector]

Example usage:

[lint]
fixable = ["C", "S074"]

ignore

Remove rules from the active rule set.

Default value: []

Type: list[selector]

Example usage:

[lint]
ignore = ["S074"]

per-file-ignores

Ignore selected rules for files that match a glob pattern.

Default value: {}

Type: table[str, list[selector]]

Example usage:

[lint]
per-file-ignores = { "scripts/*.sh" = ["S074"] }

select

Replace the default rule set with the selectors listed here, including named selectors such as google.

Default value: all implemented non-style rules

Type: list[selector]

Example usage:

[lint]
select = ["google"]

unfixable

Prevent selected rules from receiving automatic fixes, even when --fix is enabled.

Default value: []

Type: list[selector]

Example usage:

[lint]
unfixable = ["C001"]

[lint.contracts]

Ambient contract settings for runtime behavior that cannot be recovered from the source graph alone.

well-known

Enable or disable Shuck's built-in ambient contract registry.

Default value: true

Type: bool

Example usage:

[lint.contracts]
well-known = false

disabled

Disable built-in ambient contracts by exact ID, by group selector, or with * for every built-in contract.

Default value: []

Type: list[string]

Example usage:

[lint.contracts]
disabled = ["zsh/oh-my-zsh", "runtime/github-actions/env"]

[[lint.contracts.custom]]

User-authored ambient contracts layered on top of, or in place of, the built-in registry.

id

Stable identifier for the custom contract.

Default value: required

Type: string

Example usage:

[[lint.contracts.custom]]
id = "github-actions-env"

replaces

Built-in contract selectors that this custom contract replaces.

Default value: []

Type: list[string]

Example usage:

[[lint.contracts.custom]]
replaces = ["zsh/oh-my-zsh/plugin/tmux"]

when

Activation for the contract, either "always" or an object such as { type = "zsh_plugin", framework = "oh-my-zsh", plugin = "tmux" }.

Default value: required

Type: string | table

Example usage:

[[lint.contracts.custom]]
when = { type = "zsh_plugin", framework = "oh-my-zsh", plugin = "tmux" }

files

Optional file globs that limit where the contract applies.

Default value: []

Type: list[glob]

Example usage:

[[lint.contracts.custom]]
files = ["**/.zshrc"]

reads

Ambient names the activated runtime reads from the caller environment.

Default value: []

Type: list[name]

Example usage:

[[lint.contracts.custom]]
reads = ["GITHUB_ENV", "GITHUB_OUTPUT"]

functions

Provided function contracts with caller reads and caller-visible sets.

Default value: []

Type: list[{ name, reads?, sets? }]

Example usage:

[[lint.contracts.custom]]
functions = [{ name = "helper", reads = ["CALLER_VALUE"], sets = ["REPLY"] }]

[lint.contracts.custom.consumes]

Assignments that stay live because external runtime behavior consumes them.

names

Exact names consumed by external runtime behavior.

Default value: []

Type: list[name]

Example usage:

[[lint.contracts.custom]]
[lint.contracts.custom.consumes]
names = ["HISTFILE", "SAVEHIST"]

prefixes

Name prefixes consumed by external runtime behavior.

Default value: []

Type: list[prefix]

Example usage:

[[lint.contracts.custom]]
[lint.contracts.custom.consumes]
prefixes = ["ZSH_TMUX_"]

all

Treat every assignment in the file as externally consumed.

Default value: false

Type: bool

Example usage:

[[lint.contracts.custom]]
[lint.contracts.custom.consumes]
all = true

[lint.contracts.custom.provides]

Bindings made available by the activated runtime at file entry or activation time.

variables

Variables provided by the contract.

Default value: []

Type: list[name]

Example usage:

[[lint.contracts.custom]]
[lint.contracts.custom.provides]
variables = ["reply", "REPLY"]

functions

Callable function names provided by the contract.

Default value: []

Type: list[name]

Example usage:

[[lint.contracts.custom]]
[lint.contracts.custom.provides]
functions = ["helper"]

[lint.rule-options]

Rule-specific behavior overrides for diagnostics that intentionally support more than one analysis mode.

[lint.rule-options.c001]

Behavior overrides for C001 unused assignment analysis.

treat-indirect-expansion-targets-as-used

Treat scalar indirect-expansion targets such as ${!name} as a use of the referenced target.

Default value: false

Type: bool

Example usage:

[lint.rule-options.c001]
treat-indirect-expansion-targets-as-used = true

[lint.rule-options.c063]

Behavior overrides for C063 overwritten and unreached function analysis.

report-unreached-nested-definitions

Report nested function definitions when no reachable direct call reaches the enclosing function scope before it exits.

Default value: false

Type: bool

Example usage:

[lint.rule-options.c063]
report-unreached-nested-definitions = true

[lint.rule-options.s078]

Behavior overrides for S078 shebang shell policy.

allowed-shells

Interpreter names accepted in shebangs for this project.

Default value: ["bash"]

Type: list[string]

Example usage:

[lint.rule-options.s078]
allowed-shells = ["bash", "zsh"]

[lint.rule-options.s079]

Behavior overrides for S079 shebang invocation form policy.

allowed-forms

Shebang invocation forms accepted for this project. Supported values are absolute-path and env-lookup.

Default value: ["env-lookup"]

Type: list[string]

Example usage:

[lint.rule-options.s079]
allowed-forms = ["env-lookup"]

allowed-paths

Exact shebang invocation strings accepted regardless of invocation form.

Default value: ["/bin/bash", "/usr/bin/env bash"]

Type: list[string]

Example usage:

[lint.rule-options.s079]
allowed-paths = ["/usr/bin/env bash"]

[lint.rule-options.s080]

Behavior overrides for S080 script size policy.

max-lines

Maximum accepted line count for one script.

Default value: 100

Type: integer

Example usage:

[lint.rule-options.s080]
max-lines = 100

count

Line-counting mode. Supported values are physical and non-comment-non-blank.

Default value: "physical"

Type: string

Example usage:

[lint.rule-options.s080]
count = "non-comment-non-blank"

[lint.rule-options.s081]

Behavior overrides for S081 file description comments.

ignore-shebang-only-files

Do not report scripts whose only content is a shebang line.

Default value: false

Type: bool

Example usage:

[lint.rule-options.s081]
ignore-shebang-only-files = true

[lint.rule-options.s082]

Behavior overrides for S082 action comment formatting.

kinds

Comment markers checked at the start of a comment.

Default value: ["TODO", "FIXME", "XXX"]

Type: list[string]

Example usage:

[lint.rule-options.s082]
kinds = ["TODO", "FIXME"]

require-owner

Require a checked marker to be followed immediately by a parenthesized owner.

Default value: true

Type: bool

Example usage:

[lint.rule-options.s082]
require-owner = false

require-message

Require a checked marker to include non-empty explanatory text.

Default value: true

Type: bool

Example usage:

[lint.rule-options.s082]
require-message = false

[lint.rule-options.s083]

Behavior overrides for S083 missing function documentation.

require-for

Choose which functions require a leading documentation comment: all, exported, long, or parameterized.

Default value: long

Type: string

Example usage:

[lint.rule-options.s083]
require-for = "exported"

long-function-line-threshold

Minimum body line count for require-for = "long".

Default value: 10

Type: integer

Example usage:

[lint.rule-options.s083]
long-function-line-threshold = 20

[lint.rule-options.s084]

Behavior overrides for S084 function documentation content.

require-globals

Require a Globals section when a documented function reads or writes non-local variables.

Default value: true

Type: bool

Example usage:

[lint.rule-options.s084]
require-globals = false

require-arguments

Require an Arguments section when a documented function uses positional parameters.

Default value: true

Type: bool

Example usage:

[lint.rule-options.s084]
require-arguments = false

require-outputs

Require an Outputs section when a documented function writes with echo or printf.

Default value: true

Type: bool

Example usage:

[lint.rule-options.s084]
require-outputs = false

require-returns

Require a Returns section when a documented function has an explicit return code.

Default value: true

Type: bool

Example usage:

[lint.rule-options.s084]
require-returns = false

[lint.rule-options.s085]

Behavior overrides for S085 missing main entrypoint analysis.

non-trivial-line-threshold

Minimum source line count before the script is checked.

Default value: 30

Type: int

Example usage:

[lint.rule-options.s085]
non-trivial-line-threshold = 20

non-trivial-function-count

Minimum function definition count before the script is checked.

Default value: 2

Type: int

Example usage:

[lint.rule-options.s085]
non-trivial-function-count = 3

main-name

Function name expected as the final top-level call in non-trivial scripts.

Default value: "main"

Type: string

Example usage:

[lint.rule-options.s085]
main-name = "run"

[lint.rule-options.c158]

Behavior overrides for C158 implicit global assignment analysis.

treat-readonly-as-documented

Treat top-level readonly declarations as documented intentional globals.

Default value: true

Type: bool

Example usage:

[lint.rule-options.c158]
treat-readonly-as-documented = false

treat-export-as-intentional

Treat top-level exported bindings as intentional globals.

Default value: true

Type: bool

Example usage:

[lint.rule-options.c158]
treat-export-as-intentional = false

[lint.rule-options.c159]

Behavior overrides for C159 mutable global analysis.

allow-conditional-init

Allow self-referential default initializers such as name=${name:-value} without treating them as global mutations.

Default value: true

Type: bool

Example usage:

[lint.rule-options.c159]
allow-conditional-init = false

[lint.rule-options.c160]

Behavior overrides for C160 unanchored source path analysis.

allowed-anchors

Path prefix expressions accepted as script-directory anchors for source or dot commands.

Default value: ["${BASH_SOURCE[0]%/*}", "$(dirname \"$0\")", "$(dirname \"${BASH_SOURCE[0]}\")"]

Type: list[string]

Example usage:

[lint.rule-options.c160]
allowed-anchors = ["$SCRIPT_DIR"]

[lint.rule-options.c161]

Behavior overrides for C161 function call ordering analysis.

ignore-after-source

Ignore later calls after a source command because the sourced file may define functions.

Default value: true

Type: bool

Example usage:

[lint.rule-options.c161]
ignore-after-source = false

[lint.zsh]

Zsh-specific lint behavior for shuck check.

[lint.zsh.plugins]

Zsh plugin-resolution settings used to import real plugin entrypoints into semantic analysis.

resolution

Enable or disable zsh plugin resolution while leaving ordinary source closure enabled.

Default value: true

Type: bool

Example usage:

[lint.zsh.plugins]
resolution = false

roots

Fallback framework roots keyed by logical framework name.

Default value: {}

Type: table[str, path]

Example usage:

[lint.zsh.plugins]
roots = { oh-my-zsh = "~/.oh-my-zsh" }

plugin-loads

Additional logical plugin loads to attach to matching files.

Default value: []

Type: list[{ pattern, framework, name }]

Example usage:

[lint.zsh.plugins]
plugin-loads = [{ pattern = "**/.zshrc", framework = "oh-my-zsh", name = "git" }]

theme-loads

Additional logical theme loads to attach to matching files.

Default value: []

Type: list[{ pattern, framework, name }]

Example usage:

[lint.zsh.plugins]
theme-loads = [{ pattern = "**/.zshrc", framework = "oh-my-zsh", name = "agnoster" }]

entrypoints

Raw plugin entrypoint paths to import for matching files.

Default value: []

Type: list[{ pattern, paths }]

Example usage:

[lint.zsh.plugins]
entrypoints = [{ pattern = "**/.zshrc", paths = ["./vendor/prompt/prompt.plugin.zsh"] }]

[run]

Interpreter defaults and managed shell version pins for shuck run and related commands.

shell

Default managed shell to use when a script does not declare its own shell.

Default value: none

Type: string

Example usage:

[run]
shell = "bash"

shell-version

Default version constraint to use when no script metadata or per-shell pin is more specific.

Default value: "latest"

Type: string

Example usage:

[run]
shell-version = "5.2"

[run.shells]

Per-shell version pins applied after the shell has been resolved for the current script.

bash

Version constraint for Bash scripts.

Default value: none

Type: string

Example usage:

[run.shells]
bash = "5.2"

gbash

Version constraint for gbash scripts.

Default value: none

Type: string

Example usage:

[run.shells]
gbash = "0.0.32"

bashkit

Version constraint for Bashkit scripts.

Default value: none

Type: string

Example usage:

[run.shells]
bashkit = "0.2.1"

zsh

Version constraint for Zsh scripts.

Default value: none

Type: string

Example usage:

[run.shells]
zsh = "5.9"

dash

Version constraint for Dash scripts.

Default value: none

Type: string

Example usage:

[run.shells]
dash = "0.5.12"

mksh

Version constraint for mksh scripts.

Default value: none

Type: string

Example usage:

[run.shells]
mksh = "59c"

busybox

Version constraint for BusyBox scripts on Linux hosts.

Default value: none

Type: string

Example usage:

[run.shells]
busybox = "1.36.1"