Clarify removal for non-installed extras & optional groups (#6229)

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

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.

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