Closed epage closed 2 years ago
This is a proposal to merge cargo-add into cargo
In addition to users being used to this as they migrate from other ecosystems (see prior art), this provides guard rails to help the user avoid errors and even guide them to best practices, including
*
version
and path
for dependencies
but path
only for dev-dependencies
(see crate-ci/cargo-release#288 which led to killercup/cargo-edit#480)--help
is able to provide a targeted subset of the Manifest format documentationThis is another area of consideration for new RFCs like rust-lang/rfcs#3143 or rust-lang/rfcs#2906
This is a high UX feature that will draw a lot of attention (ie Issue influx), e.g.
Help output
Example commands
cargo add regex
cargo add regex serde
cargo add regex@1
cargo add regex@~1.0
cargo add regex --vers 1.0
cargo add regex --upgrade minor # for some reason this is the policy name for `^`
cargo add https://github.com/rust-lang/regex
cargo add regex --git https://github.com/rust-lang/regex
cargo add ../dependency
cargo add dep --path ../dependency
For an exhaustive set of examples, see test .toml
specs
Particular points
--vers
, --features
, etc)dependencies
table is sorted and preserve that sorting when adding a new dependency--rename
will remove a prior --rename
--optional
is never removed (cargo-edit#298)--features
removes a prior one--vers
, --path
, and --git
overwrite each othergit+
is needed for inferring git dependencies--vers
and --git
flags--branch
--upgrade <policy>
argument to control the version requirement operator--sort
to force sorting of dependenciesname@data
where data can be version, git (with fragment for branch), etc-E
/ --exact
, -T
/ --tilde
, -C
/ --caret
to control version requirement operator instead of --upgrade <policy>
(also controlled through defaultSemverRangePrefix
in config)--cached
for using the lock file (killercup/cargo-edit#41)--dev
, it has --prefer-dev
which will only add the dependency if it doesn't already exist in dependencies
as well as dev-dependencies
--mode update-lockfile
will ensure the lock file gets updated as well@<version>
<name>[@<version>]
with path and repogithub:user/repo
--save-exact
/ -E
for operators outside of the default@<version>
@none
--version
/ -v
instead of --vers
(we use --vers
because of --version
/ -V
)--source
instead of path
(path
correlates to manifest field)--git
/ --branch
like cargo-add
--git-url
instead of --git
--git-ref
instead of --branch
, --tag
, --rev
--local
flagcargo-rm
, cargo-upgrade
, and cargo-set-version
(in that order of priority)cargo add
snippets in addition to or replacing the manifest snippetsFor more, see https://github.com/killercup/cargo-edit/issues?q=is%3Aissue+is%3Aopen+label%3Acargo-add
--sort
flag.cargo/config.toml
or in the "rustfmt for manifests"--upgrade <policy>
isn't quite right
^
being called minor
, should be semver
--vers <req>
and <name>@<req>
except when "take latest" which people are unlikely to do if they also care about the version requirement operator--vers
is redundant with @
and is an awkward name--git
and --path
are redundant with accepting a path / git url directly<name>[:<version-req>]
or <path>
:
like pkgids--git <url>[#<type>=<ref>]
where type is one of branch
, tag,
or rev
#<ref>
(maybe only do this?)--git <url>
with git+<url>
positional like Poetry--branch
, --vers
--allow-prelease
?
--allow-prerelease
, this helps encourage a best practice that prevents users from being broken
This is more a scratchpad for myself to iterate on thoughts without pinging everybody in https://github.com/rust-lang/cargo/pull/8062#issuecomment-606910003