Background
mosdepth has no built-in way to emit machine-parseable progress to stderr during a coverage pass. With --fast-mode --no-per-base (the hot path for WGS pipelines), stderr is silent except for occasional htslib index warnings. Pipelines that wrap mosdepth want to surface a live progress bar to users; tailing stderr is the conventional mechanism, but there's nothing to tail.
A 30x WGS coverage pass takes 5–10 minutes. ~22–24 per-chrom progress events is enough resolution for a smooth UI bar without cluttering logs.
Proposed addition
A new CLI flag --progress (short: -p).
When set, mosdepth emits one stderr line at the start of each contig's processing pass:
[progress] chrom chr1 1 of 24
[progress] chrom chr2 2 of 24
...
[progress] chrom chrY 24 of 24
Hard requirements
- stderr, not stdout. mosdepth's data outputs are file-based, so stderr is free for status.
\n-terminated, one event per line. No \r carriage-return rewriting — line-by-line tailers go blind on \r-updated lines until the loop ends.- Both index and total in every line.
N of M lets a parser compute fraction = N/M without external state.
- Stable machine-readable prefix:
[progress] so a regex can cleanly skip htslib [W::*] / [M::*] warnings.
- Emitted BEFORE the contig's work, not after. End-of-chrom events are useless — the last contig doesn't update until after the work is already done.
- Works with
--fast-mode --no-per-base. That's the hot path.
- Opt-in via the new flag. No change to default behavior; not gated behind
-v/--verbose.
Motivation
Downstream tools (pipeline orchestrators, Nextflow/Snakemake wrappers, GUI wrappers) want to show real-time progress to users. Currently there's nothing to parse from stderr during the silent 5–10 minute WGS pass. This flag provides just enough signal for a smooth progress bar with minimal log noise.
I'm planning to send a PR with an implementation — wanted to raise this first so you can weigh in on the approach or flag any concerns before I invest time in it.
Background
mosdepth has no built-in way to emit machine-parseable progress to stderr during a coverage pass. With
--fast-mode --no-per-base(the hot path for WGS pipelines), stderr is silent except for occasional htslib index warnings. Pipelines that wrap mosdepth want to surface a live progress bar to users; tailing stderr is the conventional mechanism, but there's nothing to tail.A 30x WGS coverage pass takes 5–10 minutes. ~22–24 per-chrom progress events is enough resolution for a smooth UI bar without cluttering logs.
Proposed addition
A new CLI flag
--progress(short:-p).When set, mosdepth emits one stderr line at the start of each contig's processing pass:
Hard requirements
\n-terminated, one event per line. No\rcarriage-return rewriting — line-by-line tailers go blind on\r-updated lines until the loop ends.N of Mlets a parser computefraction = N/Mwithout external state.[progress]so a regex can cleanly skip htslib[W::*]/[M::*]warnings.--fast-mode --no-per-base. That's the hot path.-v/--verbose.Motivation
Downstream tools (pipeline orchestrators, Nextflow/Snakemake wrappers, GUI wrappers) want to show real-time progress to users. Currently there's nothing to parse from stderr during the silent 5–10 minute WGS pass. This flag provides just enough signal for a smooth progress bar with minimal log noise.
I'm planning to send a PR with an implementation — wanted to raise this first so you can weigh in on the approach or flag any concerns before I invest time in it.