Add format option to `cargo tree` to print the package version requirement #16192

devodev · 2025-11-01T20:42:01Z

Description

Add a new formatting option {ver-req} to cargo tree that prints the resolved version requirement of packages as specified in Cargo.toml.
Add a unit test to verify that the version constraint is printed correctly.
Update the cargo tree command documentation with the new option.

As per the issue linked below, I implemented the second suggestion which was to add a new formatting option.
Adding a new flag would also be relatively simple, but I'd like to know what people think before adding a commit.

Fixes: #16163

Example

Example output using the cargo repo:

cargo tree output

$ cargo tree --format '{p} satisfies {vr}'
cargo v0.93.0 (E:\dev\github.com\rust-lang\cargo) satisfies *
├── annotate-snippets v0.12.4 satisfies ^0.12.4
│   ├── anstyle v1.0.13 satisfies ^1.0.4
│   ├── memchr v2.7.6 satisfies ^2.7.4
│   └── unicode-width v0.2.1 satisfies ^0.2.0
├── anstream v0.6.20 satisfies ^0.6.20
│   ├── anstyle v1.0.13 satisfies ^1.0.0
│   ├── anstyle-parse v0.2.7 satisfies ^0.2.0
│   │   └── utf8parse v0.2.2 satisfies ^0.2.1
│   ├── anstyle-query v1.1.4 satisfies ^1.0.0
│   │   └── windows-sys v0.60.2 satisfies ^0.60.0
│   │       └── windows-targets v0.53.4 satisfies ^0.53.2
│   │           └── windows_x86_64_msvc v0.53.0 satisfies ^0.53.0
│   ├── anstyle-wincon v3.0.10 satisfies ^3.0.5
│   │   ├── anstyle v1.0.13 satisfies ^1.0.0
│   │   ├── once_cell_polyfill v1.70.1 satisfies ^1.56.0
│   │   └── windows-sys v0.60.2 satisfies ^0.60.0 (*)
│   ├── colorchoice v1.0.4 satisfies ^1.0.0
│   ├── is_terminal_polyfill v1.70.1 satisfies ^1.48
│   └── utf8parse v0.2.2 satisfies ^0.2.1
├── anstyle v1.0.13 satisfies ^1.0.13
├── anyhow v1.0.100 satisfies ^1.0.100
├── base64 v0.22.1 satisfies ^0.22.1
├── blake3 v1.8.2 satisfies ^1.8.2
│   ├── arrayref v0.3.9 satisfies ^0.3.5
│   ├── arrayvec v0.7.6 satisfies ^0.7.4
│   ├── cfg-if v1.0.3 satisfies ^1.0.0
│   └── constant_time_eq v0.3.1 satisfies ^0.3.1
│   [build-dependencies]
│   └── cc v1.2.39 satisfies ^1.1.12
│       ├── find-msvc-tools v0.1.2 satisfies ^0.1.2
│       ├── jobserver v0.1.34 satisfies ^0.1.30
│       │   └── getrandom v0.3.3 satisfies ^0.3.2
│       │       └── cfg-if v1.0.3 satisfies ^1
│       └── shlex v1.3.0 satisfies ^1.3.0
├── cargo-credential v0.4.9 (E:\dev\github.com\rust-lang\cargo\credential\cargo-credential) satisfies ^0.4.2
│   ├── anyhow v1.0.100 satisfies ^1.0.100
│   ├── serde v1.0.228 satisfies ^1.0.228
│   │   ├── serde_core v1.0.228 satisfies =1.0.228
│   │   └── serde_derive v1.0.228 (proc-macro) satisfies ^1
│   │       ├── proc-macro2 v1.0.101 satisfies ^1.0.74
│   │       │   └── unicode-ident v1.0.20 satisfies ^1.0
│   │       ├── quote v1.0.41 satisfies ^1.0.35
│   │       │   └── proc-macro2 v1.0.101 satisfies ^1.0.80
│   │       │       └── unicode-ident v1.0.20 satisfies ^1.0
│   │       └── syn v2.0.106 satisfies ^2.0.81
│   │           ├── proc-macro2 v1.0.101 satisfies ^1.0.91
│   │           │   └── unicode-ident v1.0.20 satisfies ^1.0
│   │           ├── quote v1.0.41 satisfies ^1.0.35 (*)
│   │           └── unicode-ident v1.0.20 satisfies ^1

epage · 2025-11-01T21:59:26Z

src/cargo/ops/tree/graph.rs

 }

+#[derive(Debug, Clone, Eq, PartialEq, Hash)]
+pub struct NodePackage {


Why was this split out?

Also, best if splitting something out like this be left to a refactor commit before the main commit.

I just pushed this change as an attempt to scope down the Ord-related changes. Trying to implement Ord for Node was quite ugly because of the enum branches. Before that, I also tried wrapping the version requirement into another type and directly implementing Ord on OptVersionReq.

I'm open to suggestions on the cleanest way to achieve this, what do you think we should do?

Not particularly happy with the latest attempt using a new struct NodePackage. Feels rather verbose simply to ignore a field. I can think of two other ways to approach this: either implement Ord/Eq on OptVersionReq, or wrap OptVersionReq in a type that does. There are also third party crate that allows ignoring fields in derived impl, such as "derivative" (https://docs.rs/derivative/latest/derivative/) but unsure we need another dependency just for that.

Not particularly happy with the latest attempt using a new struct NodePackage. Feels rather verbose simply to ignore a field.

Looking closer, ignoring a field is likely not the right approach.

For instance, in one place we rely on Ord we have the comment

// Created a sorted list for consistent output. let mut edges = edges.to_owned(); edges.sort_unstable_by(|a, b| self.node(a.node()).cmp(&self.node(b.node())));

If you added a test case for multiple deps to the same package, like below, I expect it could end up with less pleasant results

[dependencies] clap3 = { package = "clap", version = "3" } clap4 = { package = "clap", version = "4" }

Also, best if splitting something out like this be left to a refactor commit before the main commit.

FYI the refactor commit I was looking for was to have no behavior or logic changes, which means it wouldn't have the version requirement.

Interesting. Alright I can take a look at implementing Ord on OptVersionReq in a way that makes the most sense.

Also, best if splitting something out like this be left to a refactor commit before the main commit.

FYI the refactor commit I was looking for was to have no behavior or logic changes, which means it wouldn't have the version requirement.

Sounds good, will move the version requirement changes to the next commit where we update the tests.

I pushed an alternate implementation that does not require storing additional data on the Node itself.
Instead, we record the version requirement in the Graph mapped by PackageID. We have already other data recorded the same way so I thought it was fitting for this use-case as well.

One thing I am not sure is whether we should default to OptVersionReq::Any for packages without version requirement (root packages). This was the behavior I went with previously, but looking back now, I noticed that some format args like license conditionally write a value, therefore I replicated here as well. Only thing is if we use a format string like the one in tests with {p} satisfies {ver-req}, it shows as: dep satisfies which doesn't feel great.

I'd like to know what people think of this. I personally am divided 😄

src/cargo/ops/tree/graph.rs

epage · 2025-11-01T22:02:28Z

src/cargo/ops/tree/format/mod.rs

                RawChunk::Argument("r") => Chunk::Repository,
                RawChunk::Argument("f") => Chunk::Features,
                RawChunk::Argument("lib") => Chunk::LibName,
+                RawChunk::Argument("c") => Chunk::Constraint,


Thats unfortunate that r is taken as we tend to refer to this as a version requirement, not constraint. As it corresponds to the version field, v might be ok but that could mean something else

Yeah naming is hard, thanks for the clarification 😄 We have lib as precedent for multi-letters, we could use vr as version requirement if v could be ambiguous with version.

or just ver-req, less ambiguous . I don't feel like we need to pursue shortness here.

Yeah, I hadn't done that because of the precedent for single characters.

@ehuss why are the single characters used? Should we treat this like the CLI and offer long forms while short forms are only used as shortcuts in very specific cases?

I don't know. I assume it is because shorter forms are more convenient. One would need to look through the history in the original repo to see if that was ever mentioned.

I think using longer forms makes sense, with shortcuts only for common options.

I posted #16204.

For myself, I tend to shorten "version requirement" to "version-req" but I could see us going in a lot of different directions.

tests/testsuite/cargo_tree/deps.rs

epage · 2025-11-03T17:03:47Z

tests/testsuite/cargo_tree/deps.rs

+foo v0.1.0 ([ROOT]/foo) satisfies *
+├── dep v1.0.0 satisfies =1.0
+├── dep_that_is_awesome v1.0.0 satisfies >=1.0, <2
+└── other-dep v1.0.0 satisfies ^1.0
+    └── dep v1.0.0 satisfies =1.0


both paths to dep involve the same version requirement. It would help if they were different.

Signed-off-by: Alexandre Barone <[email protected]>

Update cargo tree format tests and introduce different version requirements and new placeholder tests to prepare for the next commits which will add a new formatting option to display package version requirements. Signed-off-by: Alexandre Barone <[email protected]>

Also update unit tests with test cases for normal and inverted output. Signed-off-by: Alexandre Barone <[email protected]>

Signed-off-by: Alexandre Barone <[email protected]>

epage · 2025-11-10T15:05:47Z

tests/testsuite/cargo_tree/deps.rs


            [dependencies]
-            dep = {version="1.0", optional=true}
+            dep = {version="=1.0"}


This is removing coverage.

I suspect the test changes here should be purely additive rather than mutating existing stuff.

I also question our having a single format test and wonder if we should break out your new cases into a separate test or even multiple tests

Yes that's a good callout, I can work on splitting this out.

epage · 2025-11-10T15:09:46Z

tests/testsuite/cargo_tree/deps.rs

-└── other-dep v1.0.0
-    └── dep v1.0.0
+foo v0.1.0 ([ROOT]/foo) satisfies 
+├── dep v1.0.0 satisfies ^1.0


Am I misreading things? This says foo has ^1.0 when it instead has:

dep = {version="=1.0"}

You're right, this version requirement seems to belong to other-dep. I think I see what's happening. We don't consider the parent when registering the version requirement in the lookup map, so it's probably replacing previous entries for the same package?

I think using NodeID as index should make this unique.

As a forewarning, a problem I suspect we'll see when we have two different, compatible version requirements on the same package and --invert it is that we'll only see one of them.

version requirements are more of a property of edges and not nodes. We don't annotate edges. Is that good enough, a blocker for this feature, or a cause to re-think some base assumptions?

As an example of the latter, maybe for --invert, we put the version requirement on the dependent package and not the dependency.

rustbot added A-cli-help Area: built-in command-line help A-documenting-cargo-itself Area: Cargo's documentation A-semver Area: semver specifications, version matching, etc. Command-tree labels Nov 1, 2025

devodev mentioned this pull request Nov 1, 2025

Option to show semver constraints in cargo tree #16163

Open

devodev force-pushed the pr/devodev/tree-show-constraints branch 3 times, most recently from 29b53e0 to 92544e2 Compare November 1, 2025 21:55

epage reviewed Nov 1, 2025

View reviewed changes

tests/testsuite/cargo_tree/deps.rs Show resolved Hide resolved

devodev force-pushed the pr/devodev/tree-show-constraints branch 2 times, most recently from 54706e8 to f28f30f Compare November 1, 2025 23:16

devodev changed the title ~~Add format option to cargo tree to print the package version constraint~~ Add format option to cargo tree to print the package version requirement Nov 1, 2025

devodev force-pushed the pr/devodev/tree-show-constraints branch from f28f30f to bf10d3c Compare November 1, 2025 23:44

epage reviewed Nov 3, 2025

View reviewed changes

epage mentioned this pull request Nov 4, 2025

feat(tree): Support long forms for --format variables #16204

Open

devodev force-pushed the pr/devodev/tree-show-constraints branch from bf10d3c to 5dbbb18 Compare November 8, 2025 00:50

devodev added 5 commits November 7, 2025 19:51

Add unit tests for cargo tree format parser

0949c7e

Signed-off-by: Alexandre Barone <[email protected]>

Support hyphens in cargo tree format parser

8e7b557

Add version requirement format option to cargo tree

995e693

Also update unit tests with test cases for normal and inverted output. Signed-off-by: Alexandre Barone <[email protected]>

Update cargo tree command docs with new version requirement option

9381123

Signed-off-by: Alexandre Barone <[email protected]>

devodev force-pushed the pr/devodev/tree-show-constraints branch from 5dbbb18 to 9381123 Compare November 8, 2025 00:51

epage reviewed Nov 10, 2025

View reviewed changes

Add format option to cargo tree to print the package version requirement #16192

Are you sure you want to change the base?

Add format option to cargo tree to print the package version requirement #16192

Conversation

devodev commented Nov 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Example

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devodev Nov 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Add format option to `cargo tree` to print the package version requirement #16192

Add format option to `cargo tree` to print the package version requirement #16192

devodev commented Nov 1, 2025 •

edited

Loading

devodev Nov 1, 2025 •

edited

Loading