Clarify removal for non-installed extras & optional groups (python-po…

…etry#6229)
chimaerase · Sep 7, 2022 · 48a3d2c · 48a3d2c
1 parent 28d0175
commit 48a3d2c
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 5 deletions.
diff --git a/docs/cli.md b/docs/cli.md
@@ -144,7 +144,7 @@ This ensures that everyone using the library will get the same versions of the d
 
 If there is no `poetry.lock` file, Poetry will create one after dependency resolution.
 
-If you want to exclude one or more dependency group for the installation, you can use
+If you want to exclude one or more dependency groups for the installation, you can use
 the `--without` option.
 
 ```bash
@@ -201,6 +201,12 @@ poetry install -E mysql -E pgsql
 poetry install --all-extras
 ```
 
+Extras are not sensitive to `--sync`.  Any extras not specified will always be removed.
+
+```bash
+poetry install --extras "A B"  # C is removed
+```
+
 By default `poetry` will install your project's package every time you run `install`:
 
 ```bash

diff --git a/docs/managing-dependencies.md b/docs/managing-dependencies.md
@@ -184,10 +184,9 @@ to remove packages from a specific group:
 poetry remove mkdocs --group docs
 ```
 
-
 ## Synchronizing dependencies
 
-Poetry supports what's called dependency synchronization. What this does is ensuring
+Poetry supports what's called dependency synchronization. Dependency synchronization ensures
 that the locked dependencies in the `poetry.lock` file are the only ones present
 in the environment, removing anything that's not necessary.
 
@@ -198,7 +197,8 @@ poetry install --sync
 ```
 
 The `--sync` option can be combined with any [dependency groups]({{< relref "#dependency-groups" >}}) related options
-to synchronize the environment with specific groups.
+to synchronize the environment with specific groups. Note that extras are separate.  Any 
+extras not selected for install are always removed, regardless of `--sync`.
 
 ```bash
 poetry install --without dev --sync
@@ -209,3 +209,9 @@ poetry install --only dev
 {{% note %}}
 The `--sync` option replaces the `--remove-untracked` option which is now deprecated.
 {{% /note %}}
+
+## Layering optional groups
+
+When you omit the `--sync` option, you can install any subset of optional groups without removing 
+those that are already installed.  This is very useful, for example, in multi-stage
+Docker builds, where you run `poetry install` multiple times in different build stages.
diff --git a/docs/pyproject.md b/docs/pyproject.md
@@ -385,7 +385,11 @@ poetry install --extras "mysql pgsql"
 poetry install -E mysql -E pgsql
 ```
 
-Or, you can install all extras with the `--all-extras` option:
+Any extras you don't specify will be removed. Note this behavior is different from 
+[optional dependency groups]({{< relref "managing-dependencies#optional-groups" >}}) not 
+selected for install, e.g. those not specified via `install --with`.
+
+You can install all extras with the `--all-extras` option:
 
 ```bash
 poetry install --all-extras