From 342f2a9e4ab9670da6e887f7db213a1a9ff19b83 Mon Sep 17 00:00:00 2001
From: Arun Babu Neelicattu <arun.neelicattu@gmail.com>
Date: Wed, 28 Feb 2024 17:47:46 -0800
Subject: [PATCH] cmd/shell: fix incorrect documentation (#9060)

Co-authored-by: Bjorn Neergaard <bjorn@neersighted.com>
---
 docs/cli.md                          | 16 ++++++++++++----
 src/poetry/console/commands/shell.py | 17 ++++++++++-------
 2 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 30aa7f10072..83640a066cb 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -637,10 +637,13 @@ Note that this command has no option.
 
 ## shell
 
-The `shell` command spawns a shell,
-according to the `$SHELL` environment variable,
-within the virtual environment.
-If one doesn't exist yet, it will be created.
+The shell command spawns a shell within the project's virtual environment.
+
+By default, the current active shell is detected and used. Failing that,
+the shell defined via the environment variable `SHELL` (on *nix) or
+`COMSPEC` (on Windows) is used.
+
+If a virtual environment does not exist, it will be created.
 
 ```bash
 poetry shell
@@ -650,6 +653,11 @@ Note that this command starts a new shell and activates the virtual environment.
 
 As such, `exit` should be used to properly exit the shell and the virtual environment instead of `deactivate`.
 
+{{% note %}}
+Poetry internally uses the [Shellingham](https://github.com/sarugaku/shellingham) project to detect current
+active shell.
+{{% /note %}}
+
 ## check
 
 The `check` command validates the content of the `pyproject.toml` file
diff --git a/src/poetry/console/commands/shell.py b/src/poetry/console/commands/shell.py
index a1be57c7f58..62e9e39ce2d 100644
--- a/src/poetry/console/commands/shell.py
+++ b/src/poetry/console/commands/shell.py
@@ -1,8 +1,8 @@
 from __future__ import annotations
 
+import os
 import sys
 
-from os import environ
 from typing import TYPE_CHECKING
 from typing import cast
 
@@ -17,9 +17,12 @@ class ShellCommand(EnvCommand):
     name = "shell"
     description = "Spawns a shell within the virtual environment."
 
-    help = """The <info>shell</> command spawns a shell, according to the
-<comment>$SHELL</> environment variable, within the virtual environment.
-If one doesn't exist yet, it will be created.
+    help = f"""The <info>shell</> command spawns a shell within the project's virtual environment.
+
+By default, the current active shell is detected and used. Failing that,
+the shell defined via the environment variable <comment>{'COMSPEC' if os.name == 'nt' else 'SHELL'}</> is used.
+
+If a virtual environment does not exist, it will be created.
 """
 
     def handle(self) -> int:
@@ -41,14 +44,14 @@ def handle(self) -> int:
         env = cast("VirtualEnv", env)
 
         # Setting this to avoid spawning unnecessary nested shells
-        environ["POETRY_ACTIVE"] = "1"
+        os.environ["POETRY_ACTIVE"] = "1"
         shell = Shell.get()
         shell.activate(env)
-        environ.pop("POETRY_ACTIVE")
+        os.environ.pop("POETRY_ACTIVE")
 
         return 0
 
     def _is_venv_activated(self) -> bool:
-        return bool(environ.get("POETRY_ACTIVE")) or getattr(
+        return bool(os.environ.get("POETRY_ACTIVE")) or getattr(
             sys, "real_prefix", sys.prefix
         ) == str(self.env.path)