uutils / uutils/coreutils

Do we want clap's context-aware usage strings or our custom usage strings?

Open
#2,527 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

I - Discussion wontfix
Dominant language
Rust
Stars
24.1k
Forks
2k
Avg merge
1d 5h
Merged PRs (30d)
365

Description

It looks like all utilities specify their own usage string. For example, sort:

fn get_usage() -> String {
    format!(
        "{0} [OPTION]... [FILE]...
Write the sorted concatenation of all FILE(s) to standard output.
Mandatory arguments for long options are mandatory for short options too.
With no FILE, or when FILE is -, read standard input.",
        NAME
    )
}

Quoting clap's documentation of usage():

CAUTION: Using this setting disables claps "context-aware" usage strings. After this
setting is set, this will be the only usage string displayed to the user!

This means that when you give the wrong argument (let's say you write sort -o x -o y), you don't get a usage string about the misused flag (USAGE: sort --output <FILENAME>), but you always get our custom usage string.

I quite like the context-aware usage strings, and I wondered if we could not specify our own usage strings but let clap generate them instead in all cases. In the help output they'd look a bit different (sort [FLAGS] [OPTIONS] [--] [files]..., or sort [OPTIONS] [--] [files]... if we enable UnifiedHelpMessage).

Thoughts?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the utilities' custom get_usage implementations, using sort as the example, and read clap's usage() documentation alongside the UnifiedHelpMessage behavior. Determine how context-aware errors and help output would change; the work is done only after the project decides between the approaches and applies the chosen policy consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.