Shell completion descriptions may mislabel input files and output archive

[mr-yifeiwang]

Version

0.7.1

Description

Shell completions for ouch compress can show misleading completion descriptions.

Current Behavior

When I'm typing ouch compress (a space in the end), the hint shows:

~/Projects/test
> ls
file.txt

~/Projects/test
> ouch compress 
output -- The resulting file. Its extensions can be used to specify the compression formats // completion desc

Then, I continue typing ouch compress file.txt (a space in the end):

~/Projects/test
> ouch compress file.txt
files -- Files to be compressed // completion desc

This is confusing because users expect ouch compress <FILES>... <OUTPUT>, but completion description can make it look as ouch compress <OUTPUT> <FILES>....

Expected Behavior

Completion descriptions should reflect the documented argument order: ouch compress <FILES>... <OUTPUT>. They should not suggest that the output archive comes before the input files.

Likely Cause

CAUTION: The content in this section is suggested by openai/gpt-5.5.

// src/cli/args.rs
Subcommand::Compress {
    /// Files to be compressed
    #[arg(required = true, value_hint = ValueHint::FilePath)]
    files: Vec<PathBuf>,

    /// The resulting file. Its extensions can be used to specify the compression formats
    #[arg(required = true, value_hint = ValueHint::FilePath)]
    output: PathBuf,
}

A variadic positional argument followed by another required positional is parseable once the full command is known, but it is inherently hard for shell completion because the command line is incomplete while completion is being requested.

build.rs appears to only expose this via generated completions:

for shell in Shell::value_variants() {
    generate_to(*shell, cmd, "ouch", out).unwrap();
}

Possible Fixes

CAUTION: The content in this section is suggested by openai/gpt-5.5.

1. Prefer an explicit output option for future CLI shape, e.g.

   ouch compress file1 file2 --output archive.zip

   This removes the ambiguity for completions.

2. If preserving the current syntax is required, add custom completion behavior for compress so completions do not present misleading files/output labels.

3. At minimum, adjust generated/manual completion text to avoid suggesting that output comes before input files.

Related

[figsoda]

what shell are you using? I tried fish, which doesn't seem to show <FILES> or <OUTPUT>, and bash, which seems to show both <FILES> and <OUTPUT> no matter what

I don't think there would be a way for ouch to know when the next argument will be the last argument (<OUTPUT>), so maybe we should just not show <OUTPUT> at all in completions?

[mr-yifeiwang]

The textual output above is from Zsh with OMZ's zsh-autocomplete plugin. Sorry for not mentioning that earlier.

I agree there probably isn't a simple, direct way for ouch to distinguish <OUTPUT> from <FILES> without introducing an explicit flag such as -d/--dir, which already exists

For the no-flag case such as ouch compress <FILE_1> <FILE_2> <OUTPUT>, I would suggest combining the completion descriptions for <FILES> and <OUTPUT>. This may also leave room for future improvements or more precise differentiation.

// src/cli/args.rs:61-70

/// Compress one or more files into one output file
#[command(visible_alias = "c")]
Compress {
    /// Input files; or output archive with compression format when placed last
    #[arg(required = true, value_hint = ValueHint::FilePath)]
    files: Vec<PathBuf>,

    /// Input files; or output archive with compression format when placed last
    #[arg(required = true, value_hint = ValueHint::FilePath)]
    output: PathBuf,

I also updated the issue to use "completion description" for consistency, since the original wording could be ambiguous in shell terminology.

[figsoda]

combining the completion descriptions sounds good to me, i wonder if there is a way to only change them for completions and not the help messages or man pages

[marcospb19]

@mr-yifeiwang to explain what @figsoda is saying, combining the completion makes sense for completions, but that comment is also used in the --help message:

$ ouch compress --help

Compress one or more files into one output file

Usage: ouch compress [OPTIONS] <FILES>... <OUTPUT>

Arguments:
  <FILES>...  Files to be compressed
  <OUTPUT>    The resulting file. Its extensions can be used to specify the compression formats

@figsoda only solution I can think off is using a feature flag, then conditional compilation with #[cfg_attr] to put different comments on these two fields, and we change the script to build these artifacts twice, once with the feature flag for completions, again for manpages.

Some like

#[cfg_attr(condition, doc = "text if true")]
#[cfg_attr(not(condition), doc = "text if false")]

I checked that #[cfg(...)] works in build.rs.

It's ugly, real ugly, but I could ask AI to do it for me and that'd be easy so, mmmmmmm, idk.