From e310dcc7c1920fa5a0b48cc700e709565e0221b7 Mon Sep 17 00:00:00 2001 From: Andrew Gallant Date: Thu, 14 Nov 2024 07:47:25 -0500 Subject: [PATCH] doc: tweak docs a bit We also update the docs for flags like `--extra` to note that they may result in an error if they try to enable extras that are conflicting. --- crates/uv-cli/src/lib.rs | 9 +++++++++ crates/uv-workspace/src/pyproject.rs | 24 ++++++++++++------------ docs/reference/cli.md | 6 ++++++ docs/reference/settings.md | 24 ++++++++++++------------ 4 files changed, 39 insertions(+), 24 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 46d7019ca..f31a8e849 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -2804,6 +2804,9 @@ pub struct SyncArgs { /// /// May be provided more than once. /// + /// When multiple extras or groups are specified that appear in + /// `tool.uv.conflicts`, uv will report an error. + /// /// Note that all optional dependencies are always included in the resolution; this option only /// affects the selection of packages to install. #[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)] @@ -2811,6 +2814,9 @@ pub struct SyncArgs { /// Include all optional dependencies. /// + /// When two or more extras are declared as conflicting in + /// `tool.uv.conflicts`, using this flag will always result in an error. + /// /// Note that all optional dependencies are always included in the resolution; this option only /// affects the selection of packages to install. #[arg(long, conflicts_with = "extra")] @@ -2841,6 +2847,9 @@ pub struct SyncArgs { /// Include dependencies from the specified dependency group. /// + /// When multiple extras or groups are specified that appear in + /// `tool.uv.conflicts`, uv will report an error. + /// /// May be provided multiple times. #[arg(long, conflicts_with("only_group"))] pub group: Vec, diff --git a/crates/uv-workspace/src/pyproject.rs b/crates/uv-workspace/src/pyproject.rs index c89431847..cf3a96429 100644 --- a/crates/uv-workspace/src/pyproject.rs +++ b/crates/uv-workspace/src/pyproject.rs @@ -462,23 +462,23 @@ pub struct ToolUv { /// Conflicting extras or groups may be declared here. /// - /// It's useful to declare conflicting extras when the extras have mutually - /// incompatible dependencies. For example, extra `foo` might depend on - /// `numpy==2.0.0` while extra `bar` might depend on `numpy==2.1.0`. These - /// extras cannot be activated at the same time. This usually isn't a - /// problem for pip-style workflows, but when using uv project support - /// with universal resolution, it will try to produce a resolution that - /// satisfies both extras simultaneously. + /// It's useful to declare conflicts when, for example, two or more extras + /// have mutually incompatible dependencies. Extra `foo` might depend + /// on `numpy==2.0.0` while extra `bar` might depend on `numpy==2.1.0`. + /// These extras cannot be activated at the same time. This usually isn't + /// a problem for pip-style workflows, but when using projects in uv that + /// support with universal resolution, it will try to produce a resolution + /// that satisfies both extras simultaneously. /// /// When this happens, resolution will fail, because one cannot install /// both `numpy 2.0.0` and `numpy 2.1.0` into the same environment. /// /// To work around this, you may specify `foo` and `bar` as conflicting - /// extras. When doing universal resolution in project mode, these extras - /// will get their own "forks" distinct from one another in order to permit - /// conflicting dependencies. In exchange, if one tries to install from the - /// lock file with both conflicting extras activated, installation will - /// fail. + /// extras (you can do the same with groups). When doing universal + /// resolution in project mode, these extras will get their own "forks" + /// distinct from one another in order to permit conflicting dependencies. + /// In exchange, if one tries to install from the lock file with both + /// conflicting extras activated, installation will fail. #[cfg_attr( feature = "schemars", schemars(description = "A list sets of conflicting groups or extras.") diff --git a/docs/reference/cli.md b/docs/reference/cli.md index ad493fead..d60596633 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -1390,6 +1390,8 @@ uv sync [OPTIONS]
--all-extras

Include all optional dependencies.

+

When two or more extras are declared as conflicting in tool.uv.conflicts, using this flag will always result in an error.

+

Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.

--all-packages

Sync all packages in the workspace.

@@ -1462,6 +1464,8 @@ uv sync [OPTIONS]

May be provided more than once.

+

When multiple extras or groups are specified that appear in tool.uv.conflicts, uv will report an error.

+

Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.

--extra-index-url extra-index-url

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

@@ -1485,6 +1489,8 @@ uv sync [OPTIONS]

May also be set with the UV_FROZEN environment variable.

--group group

Include dependencies from the specified dependency group.

+

When multiple extras or groups are specified that appear in tool.uv.conflicts, uv will report an error.

+

May be provided multiple times.

--help, -h

Display the concise help for this command

diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 70eff8f9c..df8c9a9fd 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -3,23 +3,23 @@ Conflicting extras or groups may be declared here. -It's useful to declare conflicting extras when the extras have mutually -incompatible dependencies. For example, extra `foo` might depend on -`numpy==2.0.0` while extra `bar` might depend on `numpy==2.1.0`. These -extras cannot be activated at the same time. This usually isn't a -problem for pip-style workflows, but when using uv project support -with universal resolution, it will try to produce a resolution that -satisfies both extras simultaneously. +It's useful to declare conflicts when, for example, two or more extras +have mutually incompatible dependencies. Extra `foo` might depend +on `numpy==2.0.0` while extra `bar` might depend on `numpy==2.1.0`. +These extras cannot be activated at the same time. This usually isn't +a problem for pip-style workflows, but when using projects in uv that +support with universal resolution, it will try to produce a resolution +that satisfies both extras simultaneously. When this happens, resolution will fail, because one cannot install both `numpy 2.0.0` and `numpy 2.1.0` into the same environment. To work around this, you may specify `foo` and `bar` as conflicting -extras. When doing universal resolution in project mode, these extras -will get their own "forks" distinct from one another in order to permit -conflicting dependencies. In exchange, if one tries to install from the -lock file with both conflicting extras activated, installation will -fail. +extras (you can do the same with groups). When doing universal +resolution in project mode, these extras will get their own "forks" +distinct from one another in order to permit conflicting dependencies. +In exchange, if one tries to install from the lock file with both +conflicting extras activated, installation will fail. **Default value**: `[]`