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 the Quick Tour, 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 KiB │ 9 months ago │
# => │ 1 │ CONTRIBUTING.md    │ file │ 11.0 KiB │ 5 months ago │
# => │ 2 │ README.md          │ file │ 12.0 KiB │ 6 days ago   │
# => │ 3 │ SECURITY.md        │ file │  2.6 KiB │ 2 months 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:

1. 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*

2. 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*"

3. 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*`

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:

1. 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

2. 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)*")

3. 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

Creating a Directory

As with most other shells, the mkdir command is used to create new directories. One subtle difference is that Nushell's internal mkdir command operates like the Unix/Linux mkdir -p by default, in that it:

• Will create multiple directory levels automatically. For example:

  mkdir modules/my/new_module

  This will create all three directories even if none of them currently exists. On Linux/Unix, this requires mkdir -p.

• Will not error if the directory already exists. For example:

  mkdir modules/my/new_module
  mkdir modules/my/new_module
  # => No error

  Tips

  A common mistake when coming to Nushell is to attempt to use mkdir -p <directory> as in the native Linux/Unix version. However, this will generate an Unknown Flag error on Nushell.

  Just repeat the command without the -p to achieve the same effect.

Changing the Current Directory

cd cookbook

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:

cookbook/

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.

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

cd ../sibling

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