Configurations

Tugboat reads settings from configuration files, environment variables, and command-line flags. Most teams rely on a shared config file, with env vars or flags layered on top when they need overrides.

Config File Discovery

Starting from the working directory, Tugboat walks up each parent folder until it finds a .tugboat.toml or pyproject.toml.

Both files use the TOML format and expose the same settings. When you use pyproject.toml, follow PEP 518 and place the keys under tool.tugboat.

Here is an example configuration file:

output_format = "console"
exclude = ["helm-chart/templates/**"]

[console_output]
snippet_lines_ahead = 3
snippet_lines_behind = 3

[tool.tugboat]
output_format = "console"
exclude = ["helm-chart/templates/**"]

[tool.tugboat.console_output]
snippet_lines_ahead = 3
snippet_lines_behind = 3

Environment Variables

Set any configuration with an environment variable.

Basics:

  • Prefix the variable name with TUGBOAT_.

  • Configuration keys ignore case.

For example, set output_format with:

export tugboat_output_format=junit

Nested configuration keys use double underscores (__) between each level. Because snippet_lines_ahead lives in the console_output section, you can set it with:

export TUGBOAT_CONSOLE_OUTPUT__SNIPPET_LINES_AHEAD=5

When an option expects a list, provide the value as JSON:

export TUGBOAT_EXCLUDE='["helm-chart/templates/**"]'

Settings

Here are the available settings, their default values, and what they control.

Top-level

color
Default:
null

Controls whether Tugboat colorizes its output.

  • true: always use color.

  • false: never use color.

  • null: use color only when writing to a terminal.

Color is currently supported only when output_format is console.

Tugboat respects both NO_COLOR and FORCE_COLOR environment variables. These may override the color setting.

exclude
Default:
[]

Skip files, folders, or glob patterns by listing them here.

If a path matches both include and exclude, exclusion wins. See path globbing for details on pattern syntax.

include
Default:
["."] (All YAML files in the current directory)

Choose which files Tugboat checks.

  • File paths: select specific files.

  • Directory paths: include all YAML files under the directory.

  • Patterns: glob-style patterns (see path globbing).

Important

If a file matches both include and exclude, the file is excluded.

Default:
false

Follow symbolic links when scanning for files.

output_format
Default:
console

Choose how Tugboat formats its results. See Output Formats for details on each format.

Available options:

  • console: human-readable output in the terminal.

  • junit: JUnit XML format for CI systems.

console_output section

snippet_lines_ahead
Default:
2

The number of lines to include before the diff snippet.

snippet_lines_behind
Default:
2

The number of lines to include after the diff snippet.

Path Globbing

Tugboat reuses Python’s pattern language for matching file paths. Supported wildcards include:

** (entire segment)

Matches zero or more path segments.

* (entire segment)

Matches exactly one path segment.

* (part of a segment)

Matches any number of non-separator characters.

?

Matches a single non-separator character.

[seq]

Matches a single character from seq.

[!seq]

Matches a single character not in seq.

Here are some examples:

  • *.yaml matches all YAML files in the current directory.

  • **/*.yaml matches all YAML files in the current directory and all subdirectories.