From 035b882db1e719e8f5e77ff8516eb977c2e290bf Mon Sep 17 00:00:00 2001 From: Douglas <32344964+NotTheDr01ds@users.noreply.github.com> Date: Thu, 12 Dec 2024 11:43:20 -0500 Subject: [PATCH] Update sample and scaffold files (#14568) # Description Tidying up some of the wording of the sample and scaffold files to align with our current recommendations: * Continue to generate a commented-only `env.nu` and `config.nu` on first launch. * The generated `env.nu` mentions that most configuration can be done in `config.nu` * The `sample_env.nu` mentions the same. I might try getting rid of `config env --sample` entirely (it's new since 0.100 anyway). * All configuration is now documented "in-shell" in `sample_config.nu`, which can be viewed using `config nu --sample` - This means that environment variables that used to be in `sample_env.nu` have been moved to `sample_config.new`. # User-Facing Changes Doc-only # Tests + Formatting Doc-only changes, but: - :green_circle: `toolkit fmt` - :green_circle: `toolkit clippy` - :green_circle: `toolkit test` - :green_circle: `toolkit test stdlib` # After Submitting Need to work on updates to Config chapter --- .../src/default_files/sample_config.nu | 142 +++++++++++++++++ .../nu-utils/src/default_files/sample_env.nu | 145 +----------------- .../src/default_files/scaffold_env.nu | 19 +-- 3 files changed, 158 insertions(+), 148 deletions(-) diff --git a/crates/nu-utils/src/default_files/sample_config.nu b/crates/nu-utils/src/default_files/sample_config.nu index 143e56aae4..ceb65835cd 100644 --- a/crates/nu-utils/src/default_files/sample_config.nu +++ b/crates/nu-utils/src/default_files/sample_config.nu @@ -785,3 +785,145 @@ $env.config.explore = { }, selected_cell: { bg: light_blue }, } + +# --------------------------------------------------------------------------------------- +# Environment Variables +# --------------------------------------------------------------------------------------- + +# In addition to the $env.config record, a number of other environment variables +# also affect Nushell's behavior: + +# PROMPT_* +# -------- +# Prompt configuration +# PROMPT_ variables accept either a string or a closure that returns a string + +# PROMPT_COMMAND +# -------------- +# Defines the primary prompt. Note that the PROMPT_INDICATOR (below) is appended to this value. +# Simple example - Static string: +$env.PROMPT_COMMAND = "Nushell" +# Simple example - Dynamic closure displaying the path: +$env.PROMPT_COMMAND = {|| pwd} + +# PROMPT_COMMAND_RIGHT +# -------------------- +# Defines a prompt which will appear right-aligned in the terminal +$env.PROMPT_COMMAND_RIGHT = {|| date now | format date "%d-%a %r" } + +# PROMPT_INDICATOR* +# ----------------- +# The prompt indicators are environmental variables that represent +# the state of the prompt. The specified character(s) will appear +# immediately following the PROMPT_COMMAND + +# When in Emacs mode (default): +$env.PROMPT_INDICATOR = "> " + +# When in normal vi mode: +$env.PROMPT_INDICATOR_VI_NORMAL = "> " +# When in vi insert-mode: +$env.PROMPT_INDICATOR_VI_INSERT = ": " + +# When a commandline extends across multiple lines: +$env.PROMPT_MULTILINE_INDICATOR = "::: " + +# TRANSIENT_PROMPT_* +# ------------------ +# Allows a different prompt to be shown after a command has been executed. This +# can be useful if you have a 2-line prompt. Instead of each previously-entered +# command taking up at least 2 lines, the transient prompt can condense it to a +# shorter version. The following example shows a rocket emoji before each +# previously-entered command: +$env.TRANSIENT_PROMPT_COMMAND = "🚀 " +$env.TRANSIENT_PROMPT_INDICATOR = "" +$env.TRANSIENT_PROMPT_INDICATOR_VI_INSERT = "" +$env.TRANSIENT_PROMPT_INDICATOR_VI_NORMAL = "" +# Tip: Removing the transient multiline indicator and right-prompt can simplify +# copying from the terminal +$env.TRANSIENT_PROMPT_MULTILINE_INDICATOR = "" +$env.TRANSIENT_PROMPT_COMMAND_RIGHT = "" + +# ENV_CONVERSIONS +# --------------- +# Certain variables, such as those containing multiple paths, are often stored as a +# colon-separated string in other shells. Nushell can convert these automatically to a +# more convenient Nushell list. The ENV_CONVERSIONS variable specifies how environment +# variables are: +# - converted from a string to a value on Nushell startup (from_string) +# - converted from a value back to a string when running external commands (to_string) +# +# Note: The OS Path variable is automatically converted before env.nu loads, so it can +# be treated a list in this file. +# +# Note: Environment variables are not case-sensitive, so the following will work +# for both Windows and Unix-like platforms. +# +# By default, the internal conversion looks something like the following, so there +# is no need to add this in your actual env.nu: +$env.ENV_CONVERSIONS = { + "Path": { + from_string: { |s| $s | split row (char esep) | path expand --no-symlink } + to_string: { |v| $v | path expand --no-symlink | str join (char esep) } + } +} + +# Here's an example converts the XDG_DATA_DIRS variable to and from a list: +$env.ENV_CONVERSIONS = $env.ENV_CONVERSIONS | merge { + "XDG_DATA_DIRS": { + from_string: { |s| $s | split row (char esep) | path expand --no-symlink } + to_string: { |v| $v | path expand --no-symlink | str join (char esep) } + } +} +# +# Other common directory-lists for conversion: TERMINFO_DIRS. +# Note that other variable conversions take place after `config.nu` is loaded. + +# NU_LIB_DIRS +# ----------- +# Directories in this constant are searched by the +# `use` and `source` commands. +# +# By default, the `scripts` subdirectory of the default configuration +# directory is included: +const NU_LIB_DIRS = [ + ($nu.default-config-dir | path join 'scripts') # add /scripts + ($nu.data-dir | path join 'completions') # default home for nushell completions +] +# You can replace (override) or append to this list by shadowing the constant +const NU_LIB_DIRS = $NU_LIB_DIRS ++ [($nu.default-config-dir | path join 'modules')] + +# An environment variable version of this also exists. It is searched after the constant. +$env.NU_LIB_DIRS ++= [ ($nu.data-dir | path join "nu_scripts") ] + +# NU_PLUGIN_DIRS +# -------------- +# Directories to search for plugin binaries when calling add. + +# By default, the `plugins` subdirectory of the default configuration +# directory is included: +const NU_PLUGIN_DIRS = [ + ($nu.default-config-dir | path join 'plugins') # add /plugins +] +# You can replace (override) or append to this list by shadowing the constant +const NU_PLUGIN_DIRS = $NU_PLUGIN_DIRS ++ [($nu.default-config-dir | path join 'plugins')] + +# As with NU_LIB_DIRS, an $env.NU_PLUGIN_DIRS is searched after the constant version + +# Appending to the OS path is a common configuration task. +# Because of the previous ENV_CONVERSIONS (performed internally +# before your config.nu loads), the path variable is a list that can +# be appended to using, for example: +$env.path ++= "~/.local/bin" + +# Or prepend using +$env.path = "~/.local/bin" ++ $env.path + +# The `path add` function from the Standard Library also provides +# a convenience method for prepending to the path: +use std/util "path add" +path add "~/.local/bin" +path add ($env.CARGO_HOME | path join "bin") + +# You can remove duplicate directories from the path using: +$env.PATH = ($env.PATH | uniq) diff --git a/crates/nu-utils/src/default_files/sample_env.nu b/crates/nu-utils/src/default_files/sample_env.nu index ea323c6c22..c081c87609 100644 --- a/crates/nu-utils/src/default_files/sample_env.nu +++ b/crates/nu-utils/src/default_files/sample_env.nu @@ -1,142 +1,9 @@ # Sample Nushell Environment Config File # -# Environment variables are usually configured in `env.nu`. Nushell -# sets sensible defaults for many environment variables, so the user's -# `env.nu` only needs to override these defaults if desired. -# -# This file serves as simple "in-shell" documentation for these -# settings, or you can view a more complete discussion online at: -# https://nushell.sh/book/configuration -# -# You can pretty-print and page this file using: -# config env --sample | nu-highlight | less -R +# Previously, environment variables were typically configured in `env.nu`. +# In general, most configuration can and should be performed in `config.nu` +# or one of the autoload directories. -# PROMPT_* -# -------- -# Prompt configuration -# PROMPT_ variables accept either a string or a closure that returns a string - -# PROMPT_COMMAND -# -------------- -# Defines the primary prompt. Note that the PROMPT_INDICATOR (below) is appended to this value. -# Simple example - Static string: -$env.PROMPT_COMMAND = "Nushell" -# Simple example - Dynamic closure displaying the path: -$env.PROMPT_COMMAND = {|| pwd} - -# PROMPT_COMMAND_RIGHT -# -------------------- -# Defines a prompt which will appear right-aligned in the terminal -$env.PROMPT_COMMAND_RIGHT = {|| date now | format date "%d-%a %r" } - -# PROMPT_INDICATOR* -# ----------------- -# The prompt indicators are environmental variables that represent -# the state of the prompt. The specified character(s) will appear -# immediately following the PROMPT_COMMAND - -# When in Emacs mode (default): -$env.PROMPT_INDICATOR = "> " - -# When in normal vi mode: -$env.PROMPT_INDICATOR_VI_NORMAL = "> " -# When in vi insert-mode: -$env.PROMPT_INDICATOR_VI_INSERT = ": " - -# When a commandline extends across multiple lines: -$env.PROMPT_MULTILINE_INDICATOR = "::: " - -# TRANSIENT_PROMPT_* -# ------------------ -# Allows a different prompt to be shown after a command has been executed. This -# can be useful if you have a 2-line prompt. Instead of each previously-entered -# command taking up at least 2 lines, the transient prompt can condense it to a -# shorter version. The following example shows a rocket emoji before each -# previously-entered command: -$env.TRANSIENT_PROMPT_COMMAND = "🚀 " -$env.TRANSIENT_PROMPT_INDICATOR = "" -$env.TRANSIENT_PROMPT_INDICATOR_VI_INSERT = "" -$env.TRANSIENT_PROMPT_INDICATOR_VI_NORMAL = "" -# Tip: Removing the transient multiline indicator and right-prompt can simplify -# copying from the terminal -$env.TRANSIENT_PROMPT_MULTILINE_INDICATOR = "" -$env.TRANSIENT_PROMPT_COMMAND_RIGHT = "" - -# ENV_CONVERSIONS -# --------------- -# Certain variables, such as those containing multiple paths, are often stored as a -# colon-separated string in other shells. Nushell can convert these automatically to a -# more convenient Nushell list. The ENV_CONVERSIONS variable specifies how environment -# variables are: -# - converted from a string to a value on Nushell startup (from_string) -# - converted from a value back to a string when running external commands (to_string) -# -# Note: The OS Path variable is automatically converted before env.nu loads, so it can -# be treated a list in this file. -# -# Note: Environment variables are not case-sensitive, so the following will work -# for both Windows and Unix-like platforms. -# -# By default, the internal conversion looks something like the following, so there -# is no need to add this in your actual env.nu: -$env.ENV_CONVERSIONS = { - "Path": { - from_string: { |s| $s | split row (char esep) | path expand --no-symlink } - to_string: { |v| $v | path expand --no-symlink | str join (char esep) } - } -} - -# Here's an example converts the XDG_DATA_DIRS variable to and from a list: -$env.ENV_CONVERSIONS = $env.ENV_CONVERSIONS | merge { - "XDG_DATA_DIRS": { - from_string: { |s| $s | split row (char esep) | path expand --no-symlink } - to_string: { |v| $v | path expand --no-symlink | str join (char esep) } - } -} -# -# Other common directory-lists for conversion: TERMINFO_DIRS. -# Note that other variable conversions take place after `config.nu` is loaded. - -# NU_LIB_DIRS -# ----------- -# Directories in this constant are searched by the -# `use` and `source` commands. -# -# By default, the `scripts` subdirectory of the default configuration -# directory is included: -const NU_LIB_DIRS = [ - ($nu.default-config-dir | path join 'scripts') # add /scripts - ($nu.data-dir | path join 'completions') # default home for nushell completions -] -# You can replace (override) or append to this list by shadowing the constant -const NU_LIB_DIRS = $NU_LIB_DIRS ++ [($nu.default-config-dir | path join 'modules')] - -# NU_PLUGIN_DIRS -# -------------- -# Directories to search for plugin binaries when calling add. - -# By default, the `plugins` subdirectory of the default configuration -# directory is included: -const NU_PLUGIN_DIRS = [ - ($nu.default-config-dir | path join 'plugins') # add /plugins -] -# You can replace (override) or append to this list by shadowing the constant -const NU_PLUGIN_DIRS = $NU_PLUGIN_DIRS ++ [($nu.default-config-dir | path join 'plugins')] - -# Appending to the OS path is a common configuration task. -# Because of the previous ENV_CONVERSIONS (performed internally -# before your env.nu loads), the path variable is a list that can -# be appended to using, for example: -$env.path ++= "~/.local/bin" - -# Or prepend using -$env.path = "~/.local/bin" ++ $env.path - -# The `path add` function from the Standard Library also provides -# a convenience method for prepending to the path: -use std/util "path add" -path add "~/.local/bin" -path add ($env.CARGO_HOME | path join "bin") - -# You can remove duplicate directories from the path using: -$env.PATH = ($env.PATH | uniq) +# To pretty-print the in-shell documentation for Nushell's various configuration +# settings, you can run: +config nu --sample | nu-highlight | less -R \ No newline at end of file diff --git a/crates/nu-utils/src/default_files/scaffold_env.nu b/crates/nu-utils/src/default_files/scaffold_env.nu index a3ce3cab07..7071b9fb3d 100644 --- a/crates/nu-utils/src/default_files/scaffold_env.nu +++ b/crates/nu-utils/src/default_files/scaffold_env.nu @@ -1,17 +1,18 @@ # env.nu # -# This file is typically used to add or override environment variables. +# Previously, environment variables were typically configured in `env.nu`. +# In general, most configuration can and should be performed in `config.nu` +# or one of the autoload directories. +# +# This file is generated for backwards compatibility for now. +# It is loaded before config.nu and login.nu +# # See https://www.nushell.sh/book/configuration.html # -# This file is loaded before config.nu and login.nu +# To pretty-print a sample of the configuration settings, run: +# config nu --sample | nu-highlight | less -R # -# You can open this file in your default editor using: -# config env -# -# To pretty-print a sample env.nu with documentation, run: -# config env --sample | nu-highlight | less -R -# -# To pretty-print the default environment values, run: +# To pretty-print the default env.nu, run: # config env --default | nu-highlight | less -R # # You can remove these comments if you want or leave