Logging & diagnostics

zut writes to two channels, both on stderr (stdout is reserved for machine-readable output):

• Program output — the build report, help text, the fetch summary. This is the command’s product and is always printed.
• Diagnostics — errors, warnings, and trace messages, gated by a log level.

Levels

From least to most verbose:

Each level includes everything above it. Diagnostics are tagged (error: , warning: , debug: ) and colored when stderr is a color terminal — colors are suppressed automatically under NO_COLOR, on a pipe, or on redirection.

Setting the level

Three equivalent ways, in increasing precedence:

$ ZUT_LOG=debug zut build //:x          # environment, applied first
$ echo 'log-level = debug' >> .zutrc    # config file
$ zut build //:x --log-level=debug      # flag, wins
$ zut build //:x --verbose              # shorthand for --log-level=debug
$ zut build //:x --quiet                # shorthand for --log-level=off

Example

$ zut build //:hello --verbose
debug: config: sandbox=namespace jobs=null remote-cache=null (read_write)
zut build //:hello
  ...

At the default info level you’d see only the build report; --verbose adds the debug: lines showing the resolved configuration and, on failure, the underlying error name.

For contributors

The logger is a standalone module (src/log.zig, depends only on std). Inside the codebase you never call std.debug.print directly — you use:

const log = @import("log");

log.out("  -> {s}\n", .{path});   // always-on program output (verbatim)
log.err("cannot read '{s}'", .{p}); // tagged, gated diagnostics
log.warn(...); log.info(...); log.debug(...); log.trace(...);

log.out is a verbatim drop-in for the old prints (caller supplies the newline); the leveled functions add the tag and a trailing newline and respect the global threshold.