From 8c0d60d0fbfd72a76b436c7f867bd6efc34948f7 Mon Sep 17 00:00:00 2001
From: WindSoilder <WindSoilder@outlook.com>
Date: Thu, 16 Jun 2022 19:37:44 +0800
Subject: [PATCH] add notes for def_env (#5807)

* add notes for def_env

* Update crates/nu-command/src/core_commands/export_def_env.rs

Co-authored-by: Stefan Holderbach <sholderbach@users.noreply.github.com>

* Update crates/nu-command/src/core_commands/def_env.rs

Co-authored-by: Stefan Holderbach <sholderbach@users.noreply.github.com>

Co-authored-by: Stefan Holderbach <sholderbach@users.noreply.github.com>
---
 .../nu-command/src/core_commands/def_env.rs   | 28 ++++++++++++++++++-
 .../src/core_commands/export_def_env.rs       | 28 ++++++++++++++++++-
 2 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/crates/nu-command/src/core_commands/def_env.rs b/crates/nu-command/src/core_commands/def_env.rs
index e880d1d89d..14c66022be 100644
--- a/crates/nu-command/src/core_commands/def_env.rs
+++ b/crates/nu-command/src/core_commands/def_env.rs
@@ -28,7 +28,33 @@ impl Command for DefEnv {
 
     fn extra_usage(&self) -> &str {
         r#"This command is a parser keyword. For details, check:
-  https://www.nushell.sh/book/thinking_in_nushell.html"#
+  https://www.nushell.sh/book/thinking_in_nushell.html
+
+=== EXTRA NOTE ===
+All blocks are scoped, including variable definition and environment variable changes.
+
+Because of this, the following doesn't work:
+
+def-env cd_with_fallback [arg = ""] {
+    let fall_back_path = "/tmp"
+    if $arg != "" {
+        cd $arg
+    } else {
+        cd $fall_back_path
+    }
+}
+
+Instead, you have to use cd in the top level scope:
+
+def-env cd_with_fallback [arg = ""] {
+    let fall_back_path = "/tmp"
+    let path = if $arg != "" {
+        $arg
+    } else {
+        $fall_back_path
+    }
+    cd $path
+}"#
     }
 
     fn is_parser_keyword(&self) -> bool {
diff --git a/crates/nu-command/src/core_commands/export_def_env.rs b/crates/nu-command/src/core_commands/export_def_env.rs
index 65de978865..b08311b0c6 100644
--- a/crates/nu-command/src/core_commands/export_def_env.rs
+++ b/crates/nu-command/src/core_commands/export_def_env.rs
@@ -28,7 +28,33 @@ impl Command for ExportDefEnv {
 
     fn extra_usage(&self) -> &str {
         r#"This command is a parser keyword. For details, check:
-  https://www.nushell.sh/book/thinking_in_nushell.html"#
+  https://www.nushell.sh/book/thinking_in_nushell.html
+
+=== EXTRA NOTE ===
+All blocks are scoped, including variable definition and environment variable changes.
+
+Because of this, the following doesn't work:
+
+export def-env cd_with_fallback [arg = ""] {
+    let fall_back_path = "/tmp"
+    if $arg != "" {
+        cd $arg
+    } else {
+        cd $fall_back_path
+    }
+}
+
+Instead, you have to use cd in the top level scope:
+
+export def-env cd_with_fallback [arg = ""] {
+    let fall_back_path = "/tmp"
+    let path = if $arg != "" {
+        $arg
+    } else {
+        $fall_back_path
+    }
+    cd $path
+}"#
     }
 
     fn is_parser_keyword(&self) -> bool {