From 8546dd686bab11b41aade28972307c8f12bfa042 Mon Sep 17 00:00:00 2001
From: Mark Forrer <mark.forrer@lbl.gov>
Date: Tue, 6 Sep 2022 17:46:50 -0700
Subject: [PATCH] Clarify removal for non-installed extras & optional groups
 (#6229)

---
 docs/cli.md                   |  8 +++++++-
 docs/managing-dependencies.md | 12 +++++++++---
 docs/pyproject.md             |  6 +++++-
 3 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 3ae708c43a0..cfef79d91f9 100644
--- 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
index e138cd838e0..c1fa129674c 100644
--- 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
index defb4636aa3..55004615ccb 100644
--- 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