Problem
Commands that accept --format and -o handle file output inconsistently:
Command
Plain format
-o with plain format
find-updates
requirements
Works
package list-versions (#1127 )
versions, requirements
Warns and ignores
list-overrides
default (no --details)
Warns and ignores
Raised in #1127 review. Only list-overrides uses warn-and-ignore today; find-updates is the reference.
Proposed standard
Commands already share --format + -o. Users should not need to know which formats honor -o and which do not.
-o means "write output here." Always.
-o set → write to file; stdout empty (logs on stderr only)
-o omitted → write to stdout
No silent or warn-and-ignore behavior
Reference: src/fromager/commands/find_updates.py
Scope
package list-versions — wire -o into plain formats; remove feat(list-versions): show cooldown status and upload timestamps #1127 warning
list-overrides — write plain name list to -o; remove warnings
Tests — -o creates file with expected content; no -o prints to stdout
Docs — one line in help or CONTRIBUTING stating the rule above
Out of scope: cooldown filtering behavior (#1078 /#1127 ), commands without a format split (build-order, graph, minimize).
Related: #1165 covers output plumbing (click.File, dedupe writers); this issue defines the behavioral contract.
Acceptance criteria
Feedback welcome
This proposes one UX rule, but alternatives exist — please comment if you prefer a different approach:
Option A (proposed): -o works for every format, matching find-updates
Option B: keep plain formats stdout-only, but warn when -o is passed (current feat(list-versions): show cooldown status and upload timestamps #1127 approach for list-versions)
Option C: restrict -o to detail formats only (hide or reject -o for plain formats via CLI validation)
Happy to adjust before implementation. #1127 can land with a temporary compromise if needed; this issue tracks the longer-term standard.
References
#1078 · #1127 · #1165
Problem
Commands that accept
--formatand-ohandle file output inconsistently:-owith plain formatfind-updatesrequirementspackage list-versions(#1127)versions,requirementslist-overrides--details)Raised in #1127 review. Only
list-overridesuses warn-and-ignore today;find-updatesis the reference.Proposed standard
Commands already share
--format+-o. Users should not need to know which formats honor-oand which do not.-omeans "write output here." Always.-oset → write to file; stdout empty (logs on stderr only)-oomitted → write to stdoutReference:
src/fromager/commands/find_updates.pyScope
package list-versions— wire-ointo plain formats; remove feat(list-versions): show cooldown status and upload timestamps #1127 warninglist-overrides— write plain name list to-o; remove warnings-ocreates file with expected content; no-oprints to stdoutOut of scope: cooldown filtering behavior (#1078/#1127), commands without a format split (
build-order,graph,minimize).Related: #1165 covers output plumbing (
click.File, dedupe writers); this issue defines the behavioral contract.Acceptance criteria
-oonlist-versionsandlist-overrides--outputoption is ignored…" warningsfind-updatesunchangedFeedback welcome
This proposes one UX rule, but alternatives exist — please comment if you prefer a different approach:
-oworks for every format, matchingfind-updates-ois passed (current feat(list-versions): show cooldown status and upload timestamps #1127 approach forlist-versions)-oto detail formats only (hide or reject-ofor plain formats via CLI validation)Happy to adjust before implementation. #1127 can land with a temporary compromise if needed; this issue tracks the longer-term standard.
References
#1078 · #1127 · #1165