Thinking in Nu

Nushell is different! It's common (and expected!) for new users to have some existing "habits" or mental models coming from other shells or languages.

The most common questions from new users typically fall into one of the following topics:

Nushell isn't Bash

It can sometimes look like Bash

Nushell is both a programming language and a shell. Because of this, it has its own way of working with files, directories, websites, and more. You'll find that some features in Nushell work similar to those you're familiar with in other shells. For instance, pipelines work by combining two (or more) commands together, just like in other shells.

For example, the following commandline works the same in both Bash and Nushell on Unix/Linux platforms:

curl -s https://api.github.com/repos/nushell/nushell/contributors | jq -c '.[] | {login,contributions}'
# => returns contributors to Nushell, ordered by number of contributions

Nushell has many other similarities with Bash (and other shells) and many commands in common.

http get https://api.github.com/repos/nushell/nushell/contributors | select login contributions

But it's not Bash

Because of this, however, it's sometimes easy to forget that some Bash (and POSIX in general) style constructs just won't work in Nushell. For instance, in Bash, it would be normal to write:

# Redirect using >
echo "hello" > output.txt
# But compare (greater-than) using the test command
test 4 -gt 7
echo $?
# => 1

In Nushell, however, the > is used as the greater-than operator for comparisons. This is more in line with modern programming expectations.

4 > 10
# => false

Since > is an operator, redirection to a file in Nushell is handled through a pipeline command that is dedicated to saving content - save:

"hello" | save output.txt

Implicit Return

Users coming from other shells will likely be very familiar with the echo command. Nushell's echo might appear the same at first, but it is very different.

First, notice how the following output looks the same in both Bash and Nushell (and even PowerShell and Fish):

echo "Hello, World"
# => Hello, World

But while the other shells are sending Hello, World straight to standard output, Nushell's echo is simply returning a value. Nushell then renders the return value of a command, or more technically, an expression.

More importantly, Nushell implicitly returns the value of an expression. This is similar to PowerShell or Rust in many respects.

In other words, the string "Hello, World" and the output value from echo "Hello, World" are equivalent:

"Hello, World" == (echo "Hello, World")
# => true

Here's another example with a custom command definition:

def latest-file [] {
    ls | sort-by modified | last
}

The output of that pipeline (its "value") becomes the return value of the latest-file custom command.

Single Return Value per Expression

It's important to understand that an expression can only return a single value. If there are multiple subexpressions inside an expression, only the last value is returned.

A common mistake is to write a custom command definition like this:

def latest-file [] {
    echo "Returning the last file"
    ls | sort-by modified | last
}

latest-file

New users might expect:

• Line 2 to output "Returning the last file"
• Line 3 to return/output the file

However, remember that echo returns a value. Since only the last value is returned, the Line 2 value is discarded. Only the file will be returned by line 3.

To make sure the first line is displayed, use the print command:

def latest-file [] {
    print "Returning last file"
    ls | sort-by modified | last
}

Also compare:

40; 50; 60

40
50
60

echo 40
echo 50
echo 60

In all of the above:

• The first value is evaluated as the integer 40 but is not returned
• The second value is evaluated as the integer 50 but is not returned
• The third value is evaluated as the integer 60, and since it is the last value, it is is returned and displayed (rendered).

Every Command Returns a Value

Some languages have the concept of "statements" which don't return values. Nushell does not.

In Nushell, every command returns a value, even if that value is null (the nothing type). Consider the following multiline expression:

let p = 7
print $p
$p * 6

1. Line 1: The integer 7 is assigned to $p, but the return value of the let command itself is null. However, because it is not the last value in the expression, it is not displayed.
2. Line 2: The return value of the print command itself is null, but the print command forces its argument ($p, which is 7) to be displayed. As with Line 1, the null return value is discarded since this isn't the last value in the expression.
3. Line 3: Evaluates to the integer value 42. As the last value in the expression, this is the return result, and is also displayed (rendered).

Think of Nushell as a Compiled Language

In Nushell, there are exactly two, separate, high-level stages when running code:

1. Stage 1 (Parser): Parse the entire source code
2. Stage 2 (Engine): Evaluate the entire source code

It can be useful to think of Nushell's parsing stage as compilation in static languages like Rust or C++. By this, we mean that all of the code that will be evaluated in Stage 2 must be known and available during the parsing stage.

Features Built on Static Parsing

On the other hand, the static results of Parsing are key to many features of Nushell its REPL, such as:

• Accurate and expressive error messages
• Semantic analysis for earlier and robust detection of error conditions
• IDE integration
• The type system
• The module system
• Completions
• Custom command argument parsing
• Syntax highlighting
• Real-time error highlighting
• Profiling and debugging commands
• (Future) Formatting
• (Future) Saving IR (Intermediate Representation) "compiled" results for faster execution

Limitations

The static nature of Nushell often leads to confusion for users coming to Nushell from languages where an eval is available.

Consider a simple two-line file:

<line1 code>
<line2 code>

1. Parsing:
   1. Line 1 is parsed
   2. Line 2 is parsed
2. If parsing was successful, then Evaluation:
   1. Line 1 is evaluated
   2. Line 2 is evaluated

This helps demonstrate why the following examples cannot run as a single expression (e.g., a script) in Nushell:

Example: Dynamically Generating Source

Consider this scenario:

"print Hello" | save output.nu
source output.nu
# => Error: nu::parser::sourced_file_not_found
# =>
# =>   × File not found
# =>    ╭─[entry #5:2:8]
# =>  1 │ "print Hello" | save output.nu
# =>  2 │ source output.nu
# =>    ·        ────┬────
# =>    ·            ╰── File not found: output.nu
# =>    ╰────
# =>   help: sourced files need to be available before your script is run

This is problematic because:

1. Line 1 is parsed but not evaluated. In other words, output.nu is not created during the parsing stage, but only during evaluation.
2. Line 2 is parsed. Because source is a parser-keyword, resolution of the sourced file is attempted during Parsing (Stage 1). But output.nu doesn't even exist yet! If it does exist, then it's probably not even the correct file! This results in the error.

Example: Dynamically Creating a Filename to be Sourced

Another common scenario when coming from another shell might be attempting to dynamically create a filename that will be sourced:

let my_path = "~/nushell-files"
source $"($my_path)/common.nu"
# => Error:
# =>   × Error: nu::shell::not_a_constant
# =>   │
# =>   │   × Not a constant.
# =>   │    ╭─[entry #6:2:11]
# =>   │  1 │ let my_path = "~/nushell-files"
# =>   │  2 │ source $"($my_path)/common.nu"
# =>   │    ·           ────┬───
# =>   │    ·               ╰── Value is not a parse-time constant
# =>   │    ╰────
# =>   │   help: Only a subset of expressions are allowed constants during parsing. Try using the 'const' command or typing the value literally.
# =>   │
# =>    ╭─[entry #6:2:8]
# =>  1 │ let my_path = "~/nushell-files"
# =>  2 │ source $"($my_path)/common.nu"
# =>    ·        ───────────┬───────────
# =>    ·                   ╰── Encountered error during parse-time evaluation
# =>    ╰────

Because the let assignment is not resolved until evaluation, the parser-keyword source will fail during parsing if passed a variable.

#include <string>

std::string my_path("foo");
#include <my_path + "/common.h">

let my_path = "foo";
use format!("{}::common", my_path);

const my_path = "~/nushell-files"
source $"($my_path)/common.nu"

Example: Change to a different directory (cd) and source a file

Here's one more — Change to a different directory and then attempt to source a file in that directory.

if ('spam/foo.nu' | path exists) {
    cd spam
    source-env foo.nu
}

Based on what we've covered about Nushell's Parse/Eval stages, see if you can spot the problem with that example.

    source-env spam/foo.nu

Summary

Variables are Immutable by Default

Another common surprise when coming from other languages is that Nushell variables are immutable by default. While Nushell has optional mutable variables, many of Nushell's commands are based on a functional-style of programming which requires immutability.

Immutable variables are also key to Nushell's par-each command, which allows you to operate on multiple values in parallel using threads.

See Immutable Variables and Choosing between mutable and immutable variables for more information.

Nushell's Environment is Scoped

Nushell takes multiple design cues from compiled languages. One such cue is that languages should avoid global mutable state. Shells have commonly used global mutation to update the environment, but Nushell attempts to steer clear of this approach.

In Nushell, blocks control their own environment. Changes to the environment are scoped to the block where they occur.

In practice, this lets you write (as just one example) more concise code for working with subdirectories. Here's an example that builds each sub-project in the current directory:

ls | each { |row|
  cd $row.name
  make
}

The cd command changes the PWD environment variables, but this variable change does not survive past the end of the block. This allows each iteration to start from the current directory and then enter the next subdirectory.

Having a scoped environment makes commands more predictable, easier to read, and when the time comes, easier to debug. It's also another feature that is key to the par-each command we discussed above.

Nushell also provides helper commands like load-env as a convenient way of loading multiple updates to the environment at once.