diff --git a/book/configuration.md b/book/configuration.md index 2876cdff5d1..380c33284d0 100644 --- a/book/configuration.md +++ b/book/configuration.md @@ -66,8 +66,9 @@ Nushell uses multiple, optional configuration files. These files are loaded in t 1. The first file loaded is `env.nu`, which was historically used to override environment variables. However, the current "best-practice" recommendation is to set all environment variables (and other configuration) using `config.nu` and the autoload directories below. 2. `config.nu` is typically used to override default Nushell settings, define (or import) custom commands, or run any other startup tasks. -3. Files in `$nu.vendor-autoload-dirs` are loaded. These files can be used for any purpose and are a convenient way to modularize a configuration. -4. `login.nu` runs commands or handles configuration that should only take place when Nushell is running as a login shell. +3. `*.nu` files in `$nu.vendor-autoload-dirs` are loaded. These directories are intended for vendors' and package managers' startup files. +4. `*.nu` files in `$nu.user-autoload-dirs` are loaded. These files may be used for any startup tasks and are a good way to modularize the configuration. +5. `login.nu` runs commands or handles configuration that should only take place when Nushell is running as a login shell. By default, `env.nu`, `config.nu`, and `login.nu` are read from the `$nu.default-config-dir` directory. For example: @@ -379,14 +380,14 @@ Some variables that control Nushell startup file locations must be set **before* The variables that affect Nushell file locations are: -- `$env.XDG_CONFIG_HOME`: If this environment variable is set, it is used to change the directory that Nushell searches for its configuration files such as `env.nu`, `config.nu`, and `login.nu`. The history and plugin files are also stored in this directory by default. +- `$env.XDG_CONFIG_HOME`: If this environment variable is set, it is used to change the directory that Nushell searches for its configuration files such as `env.nu`, `config.nu`, `login.nu`, and the `/autoload` directory. The history and plugin files are also stored in this directory by default. Once Nushell starts, this value is stored in the `$nu.default-config-path` constant. See [Using Constants](#using-constants) below. - `$env.XDG_DATA_HOME`: If this environment variable is set, Nushell sets the `$nu.data-dir` constant to this value. The `data-dir` is used in several startup tasks: - `($nu.data-dir)/nushell/completions` is added to the `$env.NU_LIB_DIRS` search path. - - `($nu.data-dir)/vendor/autoload` is added as the last path in `nu.vendor-autoload-dirs`. This means that files in this directory will be read last during startup (and thus override any definitions made in earlier files). + - `($nu.data-dir)/vendor/autoload` is added as the last path in `nu.vendor-autoload-dirs`. Files in this directory will be read after the other vendor-auto-load directories, thus overriding any of their settings. Note that the directory represented by `$nu.data-dir`, nor any of its subdirectories, are created by default. Creation and use of these directories is up to the user. @@ -422,7 +423,7 @@ $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_DIRS = "" +$env.XDG_DATA_HOME = "" # Run Nushell in this environment nu @@ -552,36 +553,39 @@ change Nushell's startup behavior. The following stages and their steps _may_ occur during startup, based on the flags that are passed to `nu`. See [Flag Behavior](#flag-behavior) immediately following this table for how each flag impacts the process: -| Step | Stage | Nushell Action | -| ---- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 0. | (misc) | Sets internal defaults via its internal Rust implementation. In practice, this may not take place until "first use" of the setting or variable, but there will typically be a Rust default for most (but not all) settings and variables that control Nushell's behavior. These defaults can then be superseded by the steps below. | -| 1. | (main) | Inherits its initial environment from the calling process. These will initially be converted to Nushell strings, but can be converted to other structures later using `ENV_CONVERSIONS` (see below). | -| 2. | (main) | Gets the configuration directory. This is OS-dependent (see [dirs::config_dir](https://docs.rs/dirs/latest/dirs/fn.config_dir.html)), but can be overridden using `XDG_CONFIG_HOME` on all platforms as discussed [above](#changing-default-directories). | -| 3. | (main) | Creates the initial `$env.NU_LIB_DIRS` variable. By default, it includes (1) the `scripts` directory under the configuration directory, and (2) `nushell/completions` under the default data directory (either `$env.XDG_DATA_HOME` or [the default provided by the dirs crate](https://docs.rs/dirs/latest/dirs/fn.data_dir.html)). These directories are not created by default. | -| 4. | (main) | Creates the initial `$env.NU_PLUGIN_DIRS` variable. By default, this will include the configuration directory. | -| 5. | (main) | Initializes the in-memory SQLite database. This allows the `stor` family of commands to be used in the following configuration files. | -| 6. | (main) | Processes commandline arguments such as `--plugin-config `, `--plugins `, and others. See `nu --help` for a complete list. | -| 7. | (main) | Gets the path to `env.nu` and `config.nu`. By default, these are located in the config directory, but either or both can be overridden using the `--env-config ` and `--config ` flags. | -| 8. | (main) | If the `--include-path (-I)` flag was used, it overrides the default `$env.NU_LIB_DIRS` that was obtained above. | -| 9. | (main) | Loads the initial `$env.config` values from the internal defaults. | -| 10. | (stdlib) | Loads the [Standard Library](./standard_library.md) into the virtual filesystem. It is not parsed or evaluated at this point. | -| 11. | (stdlib) | Parses and evaluates `std/core`, which brings the `banner` and `pwd` commands into scope. | -| 12. | (main) | Generates the initial [`$nu` record constant](#using-constants) so that items such as `$nu.default-config-dir` can be used in the following config files. | -| 13. | (main) | Loads any plugins that were specified using the `--plugin` flag. | -| 14. | (config files) (plugin) | Processes the signatures in the user's `plugin.msgpackz` (located in the configuration directory) so that added plugins can be used in the following config files. | -| 15. | (config files) | If this is the first time Nushell has been launched, then it creates the configuration directory. "First launch" is determined by whether or not the configuration directory exists. | -| 16. | (config files) | Also, if this is the first time Nushell has been launched, creates a mostly empty (other than a few comments) `env.nu` and `config .nu` in that directory. | -| 17. | (config files) (default_env.nu) | Loads default environment variables from the internal `default_env.nu`. This file can be viewed with: `nu config env --default \| nu-highlight \| less -R`. | -| 18. | (config files) (env.nu) | Converts the `PATH` variable into a list so that it can be accessed more easily in the next step. | -| 19. | (config files) (env.nu) | Loads (parses and evaluates) the user's `env.nu` (the path to which was determined above). | -| 20. | (config files) (config.nu) | Processes any `ENV_CONVERSIONS` that were defined in the user's `env.nu` so that those environment variables can be treated as Nushell structured data in the `config.nu`. | -| 21. | (config files) (config.nu) | Loads a minimal `$env.config` record from the internal `default_config.nu`. This file can be viewed with: `nu config nu --default \| nu-highlight \| less -R`. Most values that are not defined in `default_config.nu` will be auto-populated into `$env.config` using their internal defaults as well. | -| 22. | (config files) (config.nu) | Loads (parses and evaluates) the user's `config.nu` (the path to which was determined above). | -| 23. | (config files) (login) | When Nushell is running as a login shell, loads the user's `login.nu`. | -| 24. | (config files) | Loops through autoload directories and loads any `.nu` files found. The directories are processed in the order found in `$nu.vendor-autoload-dirs`, and files in those directories are processed in alphabetical order. | -| 25. | (repl) | Processes any additional `ENV_CONVERSIONS` that were defined in `config.nu` or the autoload files. | -| 26. | (repl) and (stdlib) | Shows the banner if configured. | -| 27. | (repl) | Nushell enters the normal commandline (REPL). | +| Step | Stage | Nushell Action | +| ---- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 0. | (misc) | Sets internal defaults via its internal Rust implementation. In practice, this may not take place until "first use" of the setting or variable, but there will typically be a Rust default for most (but not all) settings and variables that control Nushell's behavior. These defaults can then be superseded by the steps below. | +| 1. | (main) | Inherits its initial environment from the calling process. These will initially be converted to Nushell strings, but can be converted to other structures later using `ENV_CONVERSIONS` (see below). | +| 2. | (main) | Gets the configuration directory. This is OS-dependent (see [dirs::config_dir](https://docs.rs/dirs/latest/dirs/fn.config_dir.html)), but can be overridden using `XDG_CONFIG_HOME` on all platforms as discussed [above](#changing-default-directories). | +| 3. | (main) | Creates the initial `$env.NU_LIB_DIRS` variable. By default, it is an empty list. | +| 4. | (main) | Creates the initial `$NU_LIB_DIRS` variable. By default, it includes (1) the `scripts` directory under the configuration directory, and (2) `nushell/completions` under the default data directory (either `$env.XDG_DATA_HOME` or [the default provided by the dirs crate](https://docs.rs/dirs/latest/dirs/fn.data_dir.html)). These directories are not created by default. | +| 5. | (main) | Creates the initial `$env.NU_PLUGIN_DIRS` variable. By default, it is an empty list. | +| 6. | (main) | Creates the initial `$NU_PLUGIN_DIRS` variable. By default, this will include (1) the `plugins` directory under the configuration directory, and (2) the directory where the currently running `nu`/`nu.exe` is located. | +| 7. | (main) | Initializes the in-memory SQLite database. This allows the `stor` family of commands to be used in the following configuration files. | +| 8. | (main) | Processes commandline arguments such as `--plugin-config `, `--plugins `, and others. See `nu --help` for a complete list. | +| 9. | (main) | Gets the path to `env.nu` and `config.nu`. By default, these are located in the config directory, but either or both can be overridden using the `--env-config ` and `--config ` flags. | +| 10. | (main) | If the `--include-path (-I)` flag was used, it overrides the default `$env.NU_LIB_DIRS` that was obtained above. | +| 11. | (main) | Loads the initial `$env.config` values from the internal defaults. | +| 12. | (main) | Converts the search path from the inherited `string` to a Nushell `list`. | +| 13. | (stdlib) | Loads the [Standard Library](./standard_library.md) and `std-rfc` into the virtual filesystem. It is not parsed or evaluated at this point. | +| 14. | (stdlib) | Parses and evaluates `std/prelude`, which brings the `banner` and `pwd` commands into scope. | +| 15. | (main) | Generates the initial [`$nu` record constant](#using-constants) so that items such as `$nu.default-config-dir` can be used in the following config files. | +| 16. | (main) | Loads any plugins that were specified using the `--plugin` flag. | +| 17. | (repl) | Sets several default environment variables that only apply in the REPL (prompt-related and `SHLVL`). Note that prompt-related variables using closures are set in `default_env.nu`. | +| 18. | (config files) (plugin) | Processes the signatures in the user's `plugin.msgpackz` (located in the configuration directory) so that added plugins can be used in the following config files. | +| 19. | (config files) | If this is the first time Nushell has been launched, then it creates the configuration directory. "First launch" is determined by whether or not the configuration directory exists. | +| 20. | (config files) | Also, if this is the first time Nushell has been launched, creates a mostly empty (other than a few comments) `env.nu` and `config .nu` in that directory. | +| 21. | (config files) (default_env.nu) | Loads default environment variables from the internal `default_env.nu`. This file can be viewed with: `nu config env --default \| nu-highlight \| less -R`. | +| 22. | (config files) (env.nu) | Converts the `PATH` variable into a list so that it can be accessed more easily in the next step. | +| 23. | (config files) (env.nu) | Loads (parses and evaluates) the user's `env.nu` (the path to which was determined above). | +| 24. | (config files) (config.nu) | Loads a minimal `$env.config` record from the internal `default_config.nu`. This file can be viewed with: `nu config nu --default \| nu-highlight \| less -R`. Most values that are not defined in `default_config.nu` will be auto-populated into `$env.config` using their internal defaults as well. | +| 25. | (config files) (config.nu) | Loads (parses and evaluates) the user's `config.nu` (the path to which was determined above). | +| 26. | (config files) (login) | When Nushell is running as a login shell, loads the user's `login.nu`. | +| 27. | (config files) | Loops through the vendor autoload directories and loads any `.nu` files found. The directories are processed in the order found in `$nu.vendor-autoload-dirs`, and files in those directories are processed in alphabetical order. | +| 28. | (config files) | Loops through the user autoload directories and loads any `.nu` files found. The directories are processed in the order found in `$nu.user-autoload-dirs`, and files in those directories are processed in alphabetical order. | +| 29. | (repl) and (stdlib) | Shows the banner if configured. | +| 29. | (repl) | Nushell enters the normal commandline (REPL). | ### Flag Behavior