What is Sawmill?

Sawmill is a terminal-based log analysis tool for working with structured tool logs. It provides two modes of operation:

Interactive log browser — Launch sawmill build.log to open a TUI where you can scroll, filter, suppress, and waive messages from tools like Vivado, Quartus, or any tool with a sawmill plugin.

CI quality gate — Add --check to run sawmill in batch mode. It exits non-zero when unwaived messages exceed a severity threshold, making it easy to embed in CI pipelines.

Key Concepts

Plugin architecture

Sawmill’s core is tool-agnostic. It does not know how to parse any log format on its own. Instead, plugins teach sawmill how to read a specific tool’s output. Each plugin is a separate Python package that you install alongside sawmill:

$ pip install sawmill sawmill-plugin-vivado

Plugins define everything tool-specific: severity levels, message IDs, multi-line grouping rules, and pre-defined filter categories.

Suppress vs. waive

Sawmill draws a hard line between two concepts:

Suppressions are display preferences. When you suppress a message ID in the TUI, it is hidden from view. Suppressions are stored in .sawmill/suppress.toml and have no effect on CI pass/fail. Think of them as “hide this noise.”

Waivers are auditable team decisions. A waiver records who accepted a message, when, and why. Waivers are stored in .sawmill/waivers.toml, require reason, author, and date fields, and do affect CI — waived messages are excluded from the failure count in --check mode. Think of them as “reviewed and accepted.”

Dual mode

Running sawmill with just a filename opens the TUI:

$ sawmill build.log

Adding any flag (--severity, --check, --format, etc.) switches to batch mode automatically. You can also force batch mode with --batch:

$ sawmill build.log --batch --severity warning