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:
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 withmyfile
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 filenamerm `*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 asinto glob
) produces alist
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
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 anUnknown 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.
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 locationcp
to copy an item to a new locationrm
to remove items from the filesystem
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 Running System Commands for details.