From ca8eb856e85b4a0e7a84dd6f835b6ef6737139c5 Mon Sep 17 00:00:00 2001
From: NotTheDr01ds <32344964+NotTheDr01ds@users.noreply.github.com>
Date: Thu, 1 Aug 2024 16:22:25 -0400
Subject: [PATCH] Doc and examples for multi-dot directory traversal (#13513)

# Description

With this PR, we should be able to close
https://github.com/nushell/nushell.github.io/issues/1225

Help/doc/examples updated for:

* `cd` to show multi-dot traversal
* `cd` to show implicit `cd` with bare directory path
* Fixed/clarified another example that mentioned `$OLDPATH` while I was
in there
* `mv` and `cp` examples for multi-dot traversal
* Updated `cp` examples to use more consistent (and clear) filenames

# User-Facing Changes

Help/doc only

# Tests + Formatting

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

# After Submitting

N/A
---
 crates/nu-command/src/filesystem/cd.rs  | 12 +++++++++++-
 crates/nu-command/src/filesystem/ucp.rs | 11 ++++++++---
 crates/nu-command/src/filesystem/umv.rs |  5 +++++
 3 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/crates/nu-command/src/filesystem/cd.rs b/crates/nu-command/src/filesystem/cd.rs
index ba91e6d0ca..87071d2888 100644
--- a/crates/nu-command/src/filesystem/cd.rs
+++ b/crates/nu-command/src/filesystem/cd.rs
@@ -134,7 +134,7 @@ impl Command for Cd {
                 result: None,
             },
             Example {
-                description: "Change to the previous working directory ($OLDPWD)",
+                description: r#"Change to the previous working directory (same as "cd $env.OLDPWD")"#,
                 example: r#"cd -"#,
                 result: None,
             },
@@ -143,6 +143,16 @@ impl Command for Cd {
                 example: r#"def --env gohome [] { cd ~ }"#,
                 result: None,
             },
+            Example {
+                description: "Move two directories up in the tree (the parent directory's parent). Additional dots can be added for additional levels.",
+                example: r#"cd ..."#,
+                result: None,
+            },
+            Example {
+                description: "The cd command itself is often optional. Simply entering a path to a directory will cd to it.",
+                example: r#"/home"#,
+                result: None,
+            },
         ]
     }
 }
diff --git a/crates/nu-command/src/filesystem/ucp.rs b/crates/nu-command/src/filesystem/ucp.rs
index 447751220d..6077278c18 100644
--- a/crates/nu-command/src/filesystem/ucp.rs
+++ b/crates/nu-command/src/filesystem/ucp.rs
@@ -86,17 +86,22 @@ impl Command for UCp {
             },
             Example {
                 description: "Copy only if source file is newer than target file",
-                example: "cp -u a b",
+                example: "cp -u myfile newfile",
                 result: None,
             },
             Example {
                 description: "Copy file preserving mode and timestamps attributes",
-                example: "cp --preserve [ mode timestamps ] a b",
+                example: "cp --preserve [ mode timestamps ] myfile newfile",
                 result: None,
             },
             Example {
                 description: "Copy file erasing all attributes",
-                example: "cp --preserve [] a b",
+                example: "cp --preserve [] myfile newfile",
+                result: None,
+            },
+            Example {
+                description: "Copy file to a directory three levels above its current location",
+                example: "cp myfile ....",
                 result: None,
             },
         ]
diff --git a/crates/nu-command/src/filesystem/umv.rs b/crates/nu-command/src/filesystem/umv.rs
index 12d95e015b..9f68a6697f 100644
--- a/crates/nu-command/src/filesystem/umv.rs
+++ b/crates/nu-command/src/filesystem/umv.rs
@@ -40,6 +40,11 @@ impl Command for UMv {
                 example: "mv *.txt my/subdirectory",
                 result: None,
             },
+            Example {
+                description: r#"Move a file into the "my" directory two levels up in the directory tree"#,
+                example: "mv test.txt .../my/",
+                result: None,
+            },
         ]
     }