From 36ad7f15c42b59f421eeb5fc6598d425c1b70c84 Mon Sep 17 00:00:00 2001
From: NotTheDr01ds <32344964+NotTheDr01ds@users.noreply.github.com>
Date: Wed, 5 Jun 2024 14:35:31 -0400
Subject: [PATCH] `cd`/`def --env` examples (#13068)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

# Description

Per a Discord question
(https://discord.com/channels/601130461678272522/1244293194603167845/1247794228696711198),
this adds examples to the `help` for both:

* `cd`
* `def`

to demonstrate that `def --env` is required when changing directories in
a custom command.

Since the existing examples for `def` were a bit more complex (and had
output) but the `cd` ones were more simplified, I did use slightly
different examples in each. Either or both could be tweaked if desired.

# User-Facing Changes

Command `help` examples

# Tests + Formatting

- :green_circle: `toolkit fmt`
- :green_circle: `toolkit clippy`
- :green_circle: `toolkit test`
- :green_circle: `toolkit test stdlib`

# After Submitting

N/A

---------

Co-authored-by: Jakub Žádník <kubouch@gmail.com>
---
 crates/nu-cmd-lang/src/core_commands/def.rs | 5 +++++
 crates/nu-command/src/filesystem/cd.rs      | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/crates/nu-cmd-lang/src/core_commands/def.rs b/crates/nu-cmd-lang/src/core_commands/def.rs
index eb1124da19..e4a169ffcc 100644
--- a/crates/nu-cmd-lang/src/core_commands/def.rs
+++ b/crates/nu-cmd-lang/src/core_commands/def.rs
@@ -60,6 +60,11 @@ impl Command for Def {
                 example: r#"def --env foo [] { $env.BAR = "BAZ" }; foo; $env.BAR"#,
                 result: Some(Value::test_string("BAZ")),
             },
+            Example {
+                description: "cd affects the environment, so '--env' is required to change directory from within a command",
+                example: r#"def --env gohome [] { cd ~ }; gohome; $env.PWD == ('~' | path expand)"#,
+                result: Some(Value::test_string("true")),
+            },
             Example {
                 description: "Define a custom wrapper for an external command",
                 example: r#"def --wrapped my-echo [...rest] { echo $rest }; my-echo spam"#,
diff --git a/crates/nu-command/src/filesystem/cd.rs b/crates/nu-command/src/filesystem/cd.rs
index 57fe1c17e3..4e09d900d2 100644
--- a/crates/nu-command/src/filesystem/cd.rs
+++ b/crates/nu-command/src/filesystem/cd.rs
@@ -135,6 +135,11 @@ impl Command for Cd {
                 example: r#"cd -"#,
                 result: None,
             },
+            Example {
+                description: "Changing directory with a custom command requires 'def --env'",
+                example: r#"def --env gohome [] { cd ~ }"#,
+                result: None,
+            },
         ]
     }
 }