`cargo add -p crates-io-crate` could be clearer about what's wrong

[kornelski]

Problem

Sometimes cargo commands require -p to refer to a package (e.g. cargo tree and cargo upgrade from cargo-edit), so I've developed a habit of just always typing -p. This got me a surprising failure when running

cargo add -p crates-io-crate

error: the following required arguments were not provided:
  <DEP_ID|--path <PATH>|--git <URI>>

Usage: cargo add [OPTIONS] <DEP>[@<VERSION>] ...
       cargo add [OPTIONS] --path <PATH> ...
       cargo add [OPTIONS] --git <URL> ...

I didn't expect to be told an argument is missing, because I thought I have provided it.

Due to --path and --git mentioned, at first I thought that -p was only for adding git or path dependencies (similar to how cargo install needs both a git url and a crate name).

I've ran --help to check what -p does, and the discrepancy between DEP_ID and [<SPEC>] distracted me from noticing "Package to modify" below.

I took me a while to notice that -p refers to the workspace, and not to the new package I wanted to add.

Proposed Solution

I'd be great if Cargo could check the value of the -p argument despite the arguments parsing failure. The external crate name is extremely unlikely to match any name in the workspace, so Cargo could detect that and report plainly that -p is the wrong place for the new crate name.

At very least the help for -p could include something like "The current workspace package".

Notes

cargo 1.87.0-nightly (a6c604d 2025-03-26)

[epage]

Thanks for reporting this!

I can see how that would be confusing and how it would be good to improve that error message. Currently, the error comes from clap. It does a decent job of explaining the problem otherwise. The issue is just the -p flag. I'd miss the value of this auto-generated error but it seems like it might be worth it to improve this.

Hmm, I wonder if looking up unknown package names on a registry would be a information disclosure that we wouldn't want (similar to #10656 and completions for cargo add in #14520). If we did it in offline mode (for however well we can override global settings for one off calls...), it would at least help when the system has seen the package before.

Looking more at that error, I wonder how much clap-rs/clap#4191 would help as it would let us use an auto-generated usage which for errors would look like:

$ cargo add -p crates-io-crate
error: the following required arguments were not provided:
  <DEP_ID|--path <PATH>|--git <URI>>

Usage: cargo add [OPTIONS] --package <SPEC> <DEP_ID> ...
       cargo add [OPTIONS] --package <SPEC> --path <PATH> ...
       cargo add [OPTIONS] --package <SPEC> --git <URL> ...

This shows both --package <SPEC> and <DEP> at once which might help. Might help further if we changed some of the value_names.

[kornelski]

looking up unknown package names on a registry would be a information disclosure

This only needs to check against the local workspace. If the package name isn't local, and there's no argument given for the remote package, then IMHO it's safe to assume it was meant to be a registry crate name without registry lookup. For the super rare case of somebody both misspelling their local crate name and forgetting remote crate name, the error message can still explicitly mention something like "the typoed-name isn't in the workspace".

[epage]

I don't think we should exclusively assume one way or the other but we could probably get away without checking crates.io. If the source is empty, we could always append a help: to the end of the error for an unmatched package spec.

[kzdnk]

It might be reasonable to consider changing the selected group to be required unless --package is present, and add better error reporting here.

Also, right now this line will only execute when --path or --git is present e.g. cargo add -p --path .. If we make that group conditionally required, then cargo add -p will print the error about possible packages in a workspace instead of "the following required arguments were not provided".