nushell config file loading

config_loading.md

Config file loading rules

1. default_config.nu and default_env.nu refer to the files that are compiled inside of the nushell executable and are also located in our repo.
2. personal env.nu/config.nu/login.nu refer to the files that are in the $nu.default-config-dir that you have personally edited.
3. specified config.nu/env.nu refer to files that are specified on the command line with the --config and --env-config command line parameters.

nu

• ✅ Always reads the nushell standard library
• ✅ Always reads personal plugin.msgpackz file if it exists
• ✅ Always reads personal env.nu file if it exists
• ✅ Always reads personal config.nu file if it exists
• ❌ Does not read personal login.nu file if it exists
• ❌ Does not read default_env.nu file
• ❌ Does not read default_config.nu file

nu -c "ls"

• ✅ Always reads the nushell standard library
• ✅ Always reads personal plugin.msgpackz file if it exists
• ✅ Always reads the default_env.nu file
• ❌ Does not read default_config.nu file
• ❌ Does not read personal env.nu file
• ❌ Does not read personal config.nu file
• ❌ Does not read personal login.nu file

nu -l -c "ls"

• ✅ Always reads the nushell standard library
• ✅ Always reads personal plugin.msgpackz file if it exists
• ✅ Always reads personal env.nu file if it exists
• ✅ Always reads personal config.nu file if it exists
• ✅ Always reads personal login.nu file if it exists
• ❌ Does not read default_env.nu file
• ❌ Does not read default_config.nu file

nu -l -c "ls" --config foo_config.nu

• ✅ Always reads the nushell standard library
• ✅ Always reads personal plugin.msgpackz file if it exists
• ✅ Always reads personal env.nu file if it exists
• ✅ Always reads specified config file if it exists
• ✅ Always reads personal login.nu file if it exists
• ❌ Does not read default_env.nu file
• ❌ Does not read default_config.nu file

nu -l -c "ls" --config foo_config.nu --env-config foo_env.nu

• ✅ Always reads the nushell standard library
• ✅ Always reads personal plugin.msgpackz file if it exists
• ✅ Always reads specified env.nu file if it exists
• ✅ Always reads specified config.nu file if it exists
• ✅ Always reads personal login.nu file if it exists
• ❌ Does not read default_env.nu file
• ❌ Does not read default_config.nu file

nu -n -l -c "ls"

• ✅ Always reads the nushell standard library
• ❌ Does not read personal plugin.msgpackz file
• ❌ Does not read personal env.nu file
• ❌ Does not read personal config.nu file
• ❌ Does not read personal login.nu file
• ❌ Does not read default_env.nu file (seems odd to me that it's not loading deafult_env.nu)
• ❌ Does not read default_config.nu file (seems odd to me that it's not loading deafult_config.nu)

nu test.nu

• ✅ Always reads the nushell standard library
• ✅ Always reads personal plugin.msgpackz file if it exists
• ❌ Does not read personal env.nu file
• ❌ Does not read personal config.nu file
• ❌ Does not read personal login.nu file
• ✅ Always reads default_env.nu file
• ❌ Does not read default_config.nu file

nu --config foo_config.nu --env-config foo_env.nu test.nu

• ✅ Always reads the nushell standard library
• ✅ Always reads personal plugin.msgpackz file if it exists
• ✅ Always reads specified env.nu file if it exists
• ✅ Always reads specified config.nu file if it exists
• ❌ Does not read personal login.nu file
• ❌ Does not read default_env.nu file
• ❌ Does not read default_config.nu file

nu -n --no-std-lib

• ❌ Does not read the nushell standard library
• ❌ Does not read personal plugin.msgpackz file
• ❌ Does not read personal env.nu file
• ❌ Does not read personal config.nu file
• ❌ Does not read personal login.nu file
• ❌ Does not read default_env.nu file
• ❌ Does not read default_config.nu file

special case nu

When nushell is initially launched, and there is no config directory created yet, nushell will prompt you to create one and add the default_config.nu and default_env.nu in that folder. If you say no to this, a nushell folder will be created anyway without putting any config files in that folder and a history.txt file will be placed in that folder. Once that is done, these files are sourced. Each time you start nushell, and there is no config.nu or env.nu in the config folder, the default_config.nu and default_env.nu are sourced and you can see the settings in $env.

• ✅ Always reads the nushell standard library
• ❌ Always reads personal plugin.msgpackz file if it exists
• ❌ Always reads personal env.nu file if it exists
• ❌ Always reads personal config.nu file if it exists
• ❌ Does not read personal login.nu file if it exists
• ✅ Always reads default_env.nu file
• ✅ Always reads default_config.nu file

I just updated this 2024-09-26 nushell version 0.98.1

what about the behavior when used in scripts?

Updated

i thought having that in a table would be easier to read 😋

cmd	std	plugin.msgpackz	env.nu	config.nu	login.nu	default_env.nu	default_config.nu
nu	✅	✅	✅	✅	❌	❌	❌
nu -c "ls"	✅	✅	❌	❌	❌	✅	❌
nu -l -c "ls"	✅	✅	✅	✅	✅	❌	❌
nu -l -c "ls" --config config.nu	✅	✅	✅	✅	✅	❌	❌
nu -l -c "ls" --config config.nu --env-config env.nu	✅	✅	✅	✅	✅	❌	❌
nu -n -l -c "ls"	✅	❌	❌	❌	❌	❌	❌
nu test.nu	✅	✅	❌	❌	❌	✅	❌
nu --config config.nu --env-config env.nu test.nu	✅	✅	✅	✅	❌	❌	❌
nu -n --no-std-lib	❌	❌	❌	❌	❌	❌	❌

It makes me think my listing is wrong since nothing is marked as reading the default_config.nu file.

@fdncred
is the following correct?

• if config.nu is not loaded, then default_config.nu is
• if env.nu is not loaded, then default_env.nu is

i.e. everywhere there is a ❌ in the config.nu column, there should be a ✔️ in the default_config.nu column, and the same with env?

@amtoine I don't think this is right. I could be wrong but how I arrived at this document.

1. Analyze the code.
2. Put debug messages in every config & env file and where config and env files are loaded to see what's happening.

We know there are defaults in the rust code that get used but defaults getting used and sourcing the default_config.nu are not the same thing and in some ways differ. Unfortunately, the Rust code for our config system isn't the easiest to follow, which is why I put debug messages everywhere as indicated in point 2.

There is, of course, the possibility that I'm wrong in certain places as well. Feel free to debug it and let me know your results.

if the Rust defaults and the default config files, differ, that's a bug, right?

i think that, when no custom config files are loaded, the Rust defaults are used by construction of the Nushell code and thus it's the same as "loading the default config files".
it's been a while i haven't looked at the code for this, so i might be wrong 😌

if the Rust defaults and the default config files, differ, that's a bug, right?

probably so

i think that, when no custom config files are loaded, the Rust defaults are used by construction of the Nushell code and thus it's the same as "loading the default config files".
it's been a while i haven't looked at the code for this, so i might be wrong 😌

This is the way it theoretically should work but it doesn't. Last I looked, the prompt is different and NU_LIB_DIRS (and maybe other nu.env settings) are different. So, at a minimum those things are different. The config.nu may have some things that need to be updated too.