feat(true,false): print Usage: line before the description in --help#12815
Open
koopatroopa787 wants to merge 2 commits into
Open
feat(true,false): print Usage: line before the description in --help#12815koopatroopa787 wants to merge 2 commits into
koopatroopa787 wants to merge 2 commits into
Conversation
GNU's `true --help`/`false --help` start with a "Usage:" synopsis
line, but uutils printed the long description first instead:
$ LANG=C false --help | head -1
Returns false, an unsuccessful exit status.
vs. GNU:
$ LANG=C /usr/bin/false --help | head -1
Usage: /usr/bin/false [ignored command line arguments]
Adds a `localized_help_template_usage_first()` helper in uucore that
places the localized "Usage:" line before `{about-with-newline}`
(the default ordering for every other utility is unchanged), and
gives true/false their own `*-usage` strings ("true [ignored command
line arguments] / or: true OPTION", and similarly for false) wired up
via `override_usage`.
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds GNU-aligned help output for true/false by moving the “Usage:” synopsis ahead of the description and overriding the usage synopsis text, with new tests asserting the behavior.
Changes:
- Introduce a
localized_help_template_usage_firsthelp template variant inuucore - Override
true/falseusage strings via localized*-usagemessages andoverride_usage - Add integration tests asserting
--helpstarts with the expected usage synopsis
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/by-util/test_true.rs | Adds a test asserting true --help begins with the expected usage synopsis |
| tests/by-util/test_false.rs | Adds a test asserting false --help begins with the expected usage synopsis |
| src/uucore/src/lib/lib.rs | Adds a “usage first” localized help template and refactors color detection into a helper |
| src/uu/true/src/true.rs | Switches to usage-first template and overrides usage with a localized string |
| src/uu/true/locales/fr-FR.ftl | Adds localized true-usage string |
| src/uu/true/locales/en-US.ftl | Adds English true-usage string |
| src/uu/false/src/false.rs | Switches to usage-first template and overrides usage with a localized string |
| src/uu/false/locales/fr-FR.ftl | Adds localized false-usage string |
| src/uu/false/locales/en-US.ftl | Adds English false-usage string |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+35
to
+41
| // GNU's `true --help` starts with a "Usage:" line; ensure ours does too. | ||
| let result = new_ucmd!().args(&["--help"]).succeeds(); | ||
| assert!( | ||
| result | ||
| .stdout_str() | ||
| .starts_with("Usage: true [ignored command line arguments]") | ||
| ); |
Comment on lines
+32
to
+38
| // GNU's `false --help` starts with a "Usage:" line; ensure ours does too. | ||
| let result = new_ucmd!().args(&["--help"]).fails(); | ||
| assert!( | ||
| result | ||
| .stdout_str() | ||
| .starts_with("Usage: false [ignored command line arguments]") | ||
| ); |
Comment on lines
+301
to
314
| /// Determine whether colored output should be used, based on the same | ||
| /// environment variables and TTY checks as `configure_localized_command`. | ||
| fn detect_colors_enabled() -> bool { | ||
| use std::io::IsTerminal; | ||
|
|
||
| // Determine if colors should be enabled - same logic as configure_localized_command | ||
| let colors_enabled = if std::env::var("NO_COLOR").is_ok() { | ||
| if std::env::var("NO_COLOR").is_ok() { | ||
| false | ||
| } else if std::env::var("CLICOLOR_FORCE").is_ok() || std::env::var("FORCE_COLOR").is_ok() { | ||
| true | ||
| } else { | ||
| IsTerminal::is_terminal(&std::io::stdout()) | ||
| && std::env::var("TERM").unwrap_or_default() != "dumb" | ||
| }; | ||
|
|
||
| localized_help_template_with_colors(util_name, colors_enabled) | ||
| } | ||
| } |
Merging this PR will not alter performance
Warning Please fix the performance issues or acknowledge them on CodSpeed. Performance Changes
Tip Investigate this regression by commenting Comparing 
Footnotes
|
|
GNU testsuite comparison: |
- Set NO_COLOR=1 in the new --help tests so the starts_with("Usage: ...")
assertion doesn't break when CLICOLOR_FORCE/FORCE_COLOR are set.
- Deduplicate color-detection logic: detect_colors_enabled() now reuses
clap_localization::should_use_color_for_stream() instead of
re-implementing the same NO_COLOR/CLICOLOR_FORCE/FORCE_COLOR/TERM checks.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #10279
true --help/false --helpwere missing the leading "Usage:" line that GNU prints first:vs GNU:
As discussed on the issue, scoping this to
true/falsefirst rather than changing the global help template (which would affect every utility's--helpoutput).Changes
localized_help_template_usage_first()touucore, a variant oflocalized_help_template()that places the localized "Usage:" line before{about-with-newline}instead of after. The default ordering used by every other utility is unchanged (refactored the shared logic into a privatelocalized_help_template_with_order()helper, verified withcargo clippy/cargo fmt).true-usage/false-usageFluent strings (en-US + fr-FR) modeled on GNU'sUsage: true [ignored command line arguments]\n or: true OPTION, wired up via.override_usage(format_usage(&translate!(...))).test_help_starts_with_usagetotest_true.rs/test_false.rsasserting--helpoutput starts with the newUsage:line.Before / after
Test plan
cargo test --test tests --features "true false" -- test_true test_false— 14/14 passcargo test --test test_localization_and_colors— 5/5 pass (en/fr help + error message localization unaffected)cargo fmt -- --checkcleancargo clippy -p uu_true -p uu_false -p uucore --no-depscleanpwd --help) to confirm the default about-first ordering is unchanged