From 6887554888f0dd1e706ef54393f95b70427cb738 Mon Sep 17 00:00:00 2001
From: siedentop <284732+siedentop@users.noreply.github.com>
Date: Thu, 23 Apr 2020 17:17:11 -0700
Subject: [PATCH] [docs/enter] Warn about `enter` opening multiple shells
 (#1645)

Opening a JSON with a top-level list, opens one shell per list element. This can be extremely confusing to unexpected users.
---
 docs/commands/enter.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/commands/enter.md b/docs/commands/enter.md
index 426fe0ec4b..26b0ff47a7 100644
--- a/docs/commands/enter.md
+++ b/docs/commands/enter.md
@@ -37,3 +37,23 @@ It also provides the ability to work with multiple directories at the same time.
 /> n
 /tmp>
 ```
+
+## Note
+
+If you `enter` a JSON file with multiple a top-level list, this will open one new shell for each list element. 
+
+```shell
+/private/tmp> printf "1\\n2\\n3\\n" | lines | save foo.json
+/private/tmp> enter foo.json
+/> shells
+───┬────────┬─────────────────────────┬──────────────
+ # │ active │ name                    │ path
+───┼────────┼─────────────────────────┼──────────────
+ 0 │        │ filesystem              │ /private/tmp
+ 1 │        │ {/private/tmp/foo.json} │ /
+ 2 │        │ {/private/tmp/foo.json} │ /
+ 3 │ X      │ {/private/tmp/foo.json} │ /
+───┴────────┴─────────────────────────┴──────────────
+/>
+```
+