Quickstart

Install

Install sawmill and a plugin for your tool:

$ pip install sawmill sawmill-plugin-vivado

Verify the installation:

$ sawmill --version
sawmill 0.1.0

$ sawmill --list-plugins
┌────────┬─────────┬───────────────────────────────────────┐
│ Name   │ Version │ Description                           │
├────────┼─────────┼───────────────────────────────────────┤
│ vivado │ 0.1.0   │ Xilinx Vivado log parser for sawmill  │
└────────┴─────────┴───────────────────────────────────────┘

Browse interactively

Open a log file in the TUI:

$ sawmill build.log

Sawmill auto-detects the plugin (Vivado, Quartus, etc.) and opens an interactive view:

  • Severity bar at the top shows message counts per level. Press number keys (1–4) to toggle levels on and off.

  • Search bar accepts regex patterns, or prefix filters like sev:error or id:Synth 8-*.

  • Message table shows Line, Severity, ID, and Message columns. Use arrow keys, j/k, or g/G to navigate.

  • Detail panel shows the full text of the highlighted message.

  • Press s to suppress a message ID, w to waive it, Ctrl+S to save, and q to quit.

See TUI Usage for the full TUI reference.

Run in CI

Use --check to gate your pipeline on log quality:

$ sawmill build.log --check --fail-on warning --report report.json

This command:

  1. Parses the log and loads any waivers from .sawmill/waivers.toml.

  2. Checks for unwaived messages at warning level or above.

  3. Writes a JSON report to report.json.

  4. Exits with code 1 if failures are found, 0 otherwise.

See CI Integration for CI pipeline examples.

The .sawmill/ directory

After your first save (Ctrl+S in the TUI), a .sawmill/ directory appears in your project root:

.sawmill/
├── config.toml      # Output preferences (optional)
├── suppress.toml    # Suppressed message IDs
└── waivers.toml     # Waiver entries (commit this!)

Commit waivers.toml and config.toml to version control. Consider adding suppress.toml to .gitignore since suppressions are personal display preferences.

See The .sawmill/ Directory for details.