Approaches for Surfacing Download Progress
Carriage-Return Progress Bar on stderr
Use a carriage return (\r) to update a single line on stderr. This keeps the progress bar out of stdout pipes, so scripts that capture only stdout remain unaffected. The bar can show percentage, bytes transferred, and estimated time remaining.
Integration with Existing Download Loop
Hook into Homebrew's Ruby Net::HTTP or curl-based downloader. When a Content-Length header is present, calculate the percentage from bytes received. For chunked or unknown-length responses, fall back to a spinner or byte counter.
Verbosity and TTY Detection
Respect the existing verbosity flags:
--quiet: suppress all progress output entirely.--verbose: always show the progress bar, even when not attached to a TTY.- Default (no flag): show the progress bar only when
stderr is a TTY; otherwise use the non‑interactive fallback.
Non‑Interactive Fallback
In CI/CD or when output is redirected, emit progress at fixed intervals (e.g., every 10%) using newlines. This avoids flooding logs with thousands of \r characters while still giving operators visibility.
Preserving the "Downloading..." Prefix
Keep the current Downloading… line as the first message. Legacy regex‑based parsers that look for this prefix will continue to work, and the progress bar can appear on the same line or immediately after.
Interaction with --verbose and --quiet Flags
The design above maps directly to the flag semantics:
--quiet → zero progress output, matching current silent behavior.--verbose → force progress bar on, useful for debugging in non‑TTY environments.- Default → adaptive: TTY gets live bar; non‑TTY gets interval logs.
No new flags are required, and existing scripts that rely on flag behavior see no change.
Compatibility Risks for Output Parsers
- Staircase output: In legacy terminals or log aggregators that don't handle
\r cleanly, the progress bar may leave trailing characters. Mitigation: detect known problematic terminfo entries and fall back to interval logging.
- Performance overhead: Frequent
stderr writes can add latency on slow filesystems or trigger excessive screen‑reader events. Throttle updates to a maximum of 10‑20 Hz.
- Brittle line‑count scripts: Tools that count lines to detect download completion may miscount if the progress bar shares a line with the prefix. Keeping the prefix on its own line and updating the bar on a separate line (or using a single line with
\r after the prefix) preserves line counts.
Verification Steps
- Run
brew install --build-from-source <formula> in a standard TTY and confirm the progress bar updates smoothly.
- Pipe the same command to a file (
brew install … 2>log.txt) and verify the log contains clean interval‑based lines, not raw \r sequences.
- Execute with
--quiet and ensure no progress output appears on either stream.
- Test with
--verbose in a non‑TTY environment (e.g., a script) to confirm the bar is forced on.
Missing Diagnostic Detail
Which terminal emulators and CI systems are most prevalent among your user base? This determines whether the \r‑based bar can be the default or if a more conservative interval fallback should be the default for non‑TTY output.
homebrew