Home Explore Blog CI



nushell

6th chunk of `book/configuration.md`
97c0a1f43f8f56516d0da0173d1cada5773ed080bdc5b46e0000000100000ff2
The `XDG_*` variables are **not** Nushell-specific and should not be set to a directory with only Nushell files. Instead, set the environment variable to the directory _above_ the one with the `nushell` directory.

For example, if you set `$env.XDG_CONFIG_HOME` to:

```
/users/username/dotfiles/nushell
```

... Nushell will look for config files in `/Users/username/dotfiles/nushell/nushell`. The proper setting would be:

```
/users/username/dotfiles
```

Also keep in mind that if the system has already set `XDG` variables, then there may already be files in use in those directories. Changing the location may require that you move other application's files to the new directory.
:::

::: tip
You can easily test out config changes in a "fresh" environment using the following recipe. The following is run from inside Nushell, but can be
adapted to other shells as well:

```nu
# Create an empty temporary directory
let temp_home = (mktemp -d)
# Set the configuration path to this directory
$env.XDG_CONFIG_HOME = $temp_home
# Set the data-dir to this directory
$env.XDG_DATA_HOME = $temp_home
# Remove other potential autoload directories
$env.XDG_DATA_HOME = ""
# Run Nushell in this environment
nu

# Edit config
config nu
# Exit the subshell
exit
# Run the temporary config
nu
```

When done testing the configuration:

```nu
# Remove the temporary config directory, if desired
rm $temp_home
```

**Important:** Then exit the parent shell so that the `XDG` changes are not accidentally propagated to other processes.
:::

### Using Constants

Some important commands, like `source` and `use`, that help define custom commands (and other definitions) are parse-time keywords. Among other things, this means that all arguments must be known at parse-time.

In other words, **_variable arguments are not allowed for parser keywords_**.

However, Nushell creates some convenience _constants_ that can be used to help identify common file locations. For instance, you can source a file in the default configuration directory using:

```nu
source ($nu.default-config-dir | path join "myfile.nu")
```

Because the constant value is known at parse-time, it can be used with parse-time keywords like `source` and `use`.

:::tip See Also
See [Parse-time Constant Evaluation](./how_nushell_code_gets_run.md#parse-time-constant-evaluation) for more details on this process.
:::

#### `$nu` Constant

To see a list of the built-in Nushell constants, examine the record constant using `$nu` (including the dollar sign).

#### `NU_LIB_DIRS` Constant

Nushell can also make use of a `NU_LIB_DIRS` _constant_ which can act like the `$env.NU_LIB_DIRS` variable mentioned above. However, unlike `$env.NU_LIB_DIRS`, it can be defined _and_ used in `config.nu`. For example:

```nu
# Define module and source search path
const NU_LIB_DIRS = [
  '~/myscripts'
]
# Load myscript.nu from the ~/myscripts directory
source myscript.nu
```

If both the variable `$env.NU_LIB_DIRS` and the const `NU_LIB_DIRS` are defined, both sets
of paths will be searched. The constant `NU_LIB_DIRS` will be searched _first_ and have
precedence. If a file matching the name is found in one of those directories, the search will
stop. Otherwise, it will continue into the `$env.NU_LIB_DIRS` search path.

#### `NU_PLUGIN_DIRS` Constant

`const NU_PLUGIN_DIRS` works in the same way for the plugin search path.

The following `NU_PLUGIN_DIRS` configuration will allow plugins to be loaded from;

- The directory where the `nu` executable is located. This is typically where plugins are located in release packages.
- A directory in `$nu.data-dirs` named after the version of Nushell running (e.g. `0.100.0`).
- A `plugins` directory in your `$nu.config-path`.

```nu
const NU_PLUGIN_DIRS = [
  ($nu.current-exe | path dirname)
  ($nu.data-dir | path join 'plugins' | path join (version).version)
  ($nu.config-path | path dirname | path join 'plugins')
]
```

### Colors, Theming, and Syntax Highlighting

You can learn more about setting up colors and theming in the [associated chapter](coloring_and_theming.md).

Title: Advanced Nushell Configuration: Constants, `XDG` Variables, and Testing
Summary
This passage explains how to properly configure `XDG` environment variables for Nushell, emphasizing that they should point to the directory *above* the `nushell` configuration directory. It provides a recipe for testing configuration changes in a 'fresh' environment using temporary directories. It then introduces the concept of constants in Nushell, specifically `$nu`, `NU_LIB_DIRS`, and `NU_PLUGIN_DIRS`, which are parse-time keywords that can be used to identify common file locations. `NU_LIB_DIRS` and `NU_PLUGIN_DIRS` act similarly to `$env.NU_LIB_DIRS` and the plugin search path, but have precedence. Finally, it mentions a dedicated chapter for colors, theming, and syntax highlighting.