From a3aafa840de950f81e99553e52190a54c94d6bce Mon Sep 17 00:00:00 2001
From: Bartosz Sokorski <b.sokorski@gmail.com>
Date: Mon, 20 Jun 2022 00:16:07 +0200
Subject: [PATCH] docs: Add paragraph about @ operator (#5822)

Co-authored-by: Bjorn Neergaard <bjorn@neersighted.com>
---
 docs/cli.md                      |  4 ++++
 docs/dependency-specification.md | 33 ++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/docs/cli.md b/docs/cli.md
index 8898a0c585f..f1192f52ae0 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -304,6 +304,10 @@ poetry add "pendulum>=2.0.5"
 poetry add pendulum==2.0.5
 ```
 
+{{% note %}}
+See the [Dependency specification]({{< relref "dependency-specification#using-the--operator" >}}) page for more information about the `@` operator.
+{{% /note %}}
+
 If you try to add a package that is already present, you will get an error.
 However, if you specify a constraint, like above, the dependency will be updated
 by using the specified constraint.
diff --git a/docs/dependency-specification.md b/docs/dependency-specification.md
index 1e8aa7fd4d3..2feeb6e5563 100644
--- a/docs/dependency-specification.md
+++ b/docs/dependency-specification.md
@@ -84,6 +84,39 @@ You can specify the exact version of a package.
 This will tell Poetry to install this version and this version only.
 If other dependencies require a different version, the solver will ultimately fail and abort any install or update procedures.
 
+### Using the `@` operator
+
+When adding dependencies via `poetry add`, you can use the `@` operator.
+This is understood similarly to the `==` syntax, but also allows prefixing any
+specifiers that are valid in `pyproject.toml`. For example:
+
+```shell
+poetry add django@^4.0.0
+```
+
+The above would translate to the following entry in `pyproject.toml`:
+```toml
+Django = "^4.0.0"
+```
+
+The special keyword `latest` is also understood by the `@` operator:
+```shell
+poetry add django@latest
+```
+
+The above would translate to the following entry in `pyproject.toml`, assuming the latest release of `django` is `4.0.5`:
+```toml
+Django = "^4.0.5"
+```
+
+#### Extras
+
+Extras and `@` can be combined as one might expect (`package[extra]@version`):
+
+```shell
+poetry add django[bcrypt]@^4.0.0
+```
+
 ## `git` dependencies
 
 To depend on a library located in a `git` repository,