Moving around the System

A defining characteristic of a shell is the ability to navigate and interact with the filesystem. Nushell is, of course, no exception. Here are some common commands you might use when interacting with the filesystem:

Viewing Directory Contents

> ls

As seen in other chapters, the ls command returns the contents of a directory. Nushell's ls will return the contents as a table.

The ls command also takes an optional argument to change what you'd like to view. For example, we can list the files that end in ".md"

> ls *.md
───┬────────────────────┬──────┬─────────┬────────────
 # │ name               │ type │ size    │ modified 
───┼────────────────────┼──────┼─────────┼────────────
 0 │ CODE_OF_CONDUCT.md │ File │  3.4 KB │ 5 days ago 
 1 │ CONTRIBUTING.md    │ File │   886 B │ 5 days ago 
 2 │ README.md          │ File │ 15.0 KB │ 5 days ago 
 3 │ TODO.md            │ File │  1.6 KB │ 5 days ago 
───┴────────────────────┴──────┴─────────┴────────────

Glob Patterns (wildcards)

The asterisk (*) in the above optional argument *.md is sometimes called a wildcard or a glob. It lets us match anything. You can read this glob *.md as "match any filename, so long as it ends with '.md'."

The most general glob is *, which will match all paths. More often, you'll see this pattern used as part of another pattern, for example *.bak and temp*.

Nushell also supports a double * which will traverse paths that are nested inside of other directories. For example, ls **/* will list all the non-hidden paths nested under the current directory.

 ls **/*.md
╭───┬───────────────────────────────┬──────┬──────────┬──────────────╮
│ # │             name              │ type │   size   │   modified   │
├───┼───────────────────────────────┼──────┼──────────┼──────────────┤
│ 0 │ CODE_OF_CONDUCT.md            │ file │  3.4 KiB │ 5 months ago │
│ 1 │ CONTRIBUTING.md               │ file │ 11.0 KiB │ a month ago  │
│ 2 │ README.md                     │ file │ 12.0 KiB │ a month ago  │
│ 3 │ SECURITY.md                   │ file │  2.6 KiB │ 5 hours ago  │
│ 4 │ benches/README.md             │ file │    249 B │ 2 months ago │
│ 5 │ crates/README.md              │ file │    795 B │ 5 months ago │
│ 6 │ crates/nu-cli/README.md       │ file │    388 B │ 5 hours ago  │
│ 7 │ crates/nu-cmd-base/README.md  │ file │    262 B │ 5 hours ago  │
│ 8 │ crates/nu-cmd-extra/README.md │ file │    669 B │ 2 months ago │
│ 9 │ crates/nu-cmd-lang/README.md  │ file │  1.5 KiB │ a month ago  │
╰───┴───────────────────────────────┴──────┴──────────┴──────────────╯

Here, we're looking for any file that ends with ".md". The double-asterisks further specify "in any directory starting from here."

Nushell's globbing syntax not only supports *, but also matching single characters with ? and character groups with [...].

Escaping the *, ?, and [] patterns works by enclosing them in a single-quoted, double-quoted, or raw string. For example, to show the contents of a directory named [slug], use ls "[slug]" or ls '[slug]'.

However, backtick quoted strings do not escape globs. For example, compare the following scenarios:

Unquoted: Glob pattern
An unquoted bare word string with glob characters is interpreted as a glob pattern, so the following will remove all files in the current directory that contain myfile as any part of the filename:
```
rm *myfile*
```
Quoted: String literal with asterisks
When quoting with single or double quotes, or using a raw string, a string with the literal, escaped asterisks (or other glob characters) is passed to the command. The result is not a glob. The following command will only remove a file literally named *myfile* (including the asterisks). Other files with myfile in the name are not affected:
```
rm "*myfile*"
```
Backtick-quoted: Glob pattern
Asterisks (and other glob patterns) within a backtick-quoted string are interpreted as a glob pattern. Notice that this is the same behavior as that of the bare-word string example in #1 above.
The following, as with that first example, removes all files in the current directory that contain myfile as part of the filename
```
rm `*myfile*`
```

Tips

Nushell also includes a dedicated glob command with support for more complex globbing scenarios.

Converting Strings to Globs

The quoting techniques above are useful when constructing glob-literals, but you may need to construct globs programmatically. There are several techniques available for this purpose:

into glob

The into glob command can be used to convert a string (and other types) into a glob. For instance:

# Find files whose name includes the current month in the form YYYY-mm
let current_month = (date now | format date '%Y-%m')
let glob_pattern = ($"*($current_month)*" | into glob)
ls $glob_pattern

The spread operator combined with the glob command:
The glob command (note: not the same as into glob) produces a list of filenames that match the glob pattern. This list can be expanded and passed to filesystem commands using the spread operator:
```
# Find files whose name includes the current month in the form YYYY-mm
let current_month = (date now | format date '%Y-%m')
ls ...(glob $"*($current_month)*")
```

Force glob type via annotation:

# Find files whose name includes the current month in the form YYYY-mm
let current_month = (date now | format date '%Y-%m')
let glob_pattern: glob = ($"*($current_month)*")
ls $glob_pattern

Changing the Current Directory

> cd new_directory

To change from the current directory to a new one, use the cd command.

Changing the current working directory can also be done if cd is omitted and a path by itself is given:

> ./new_directory

Just as in other shells, you can use either the name of the directory, or if you want to go up a directory you can use the .. shortcut.

You can also add additional dots to go up additional directory levels:

# Change to the parent directory
> cd ..
# or
> ..
# Go up two levels (parent's parent)
> cd ...
# or
> ...
# Go up three levels (parent of parent's parent)
> cd ....
# Etc.

Tips

Multi-dot shortcuts are available to both internal Nushell filesystem commands as well as to external commands. For example, running ^stat .... on a Linux/Unix system will show that the path is expanded to ../../../..

You can combine relative directory levels with directory names as well:

> cd ../sibling

IMPORTANT TIP

Changing the directory with cd changes the PWD environment variable. This means that a change of a directory is kept to the current scope (e.g. block or closure). Once you exit the block, you'll return to the previous directory. You can learn more about this in the Environment chapter.

Filesystem Commands

Nu also provides some basic filesystem commands that work cross-platform such as:

mv to rename or move a file or directory to a new location
cp to copy an item to a new location
rm to remove items from the filesystem
mkdir to create a new directory

NOTE

Under Bash and many other shells, most filesystem commands (other than cd) are actually separate binaries in the system. For instance, on a Linux system, cp is the /usr/bin/cp binary. In Nushell, these commands are built-in. This has several advantages:

They work consistently on platforms where a binary version may not be available (e.g. Windows). This allows the creation of cross-platform scripts, modules, and custom commands.
They are more tightly integrated with Nushell, allowing them to understand Nushell types and other constructs
As mentioned in the Quick Tour, they are documented in the Nushell help system. Running help <command> or <command> --help will display the Nushell documentation for the command.

While the use of the Nushell built-in versions is typically recommended, it is possible to access the Linux binaries. See Escaping to system for details.