From 1df1b4db3fdc852549534e27f3856151399f3294 Mon Sep 17 00:00:00 2001
From: Jan Klass <kissaki@posteo.de>
Date: Sat, 12 Jul 2025 21:55:50 +0200
Subject: [PATCH] Order `$env` variables in Special Variables

The order C P E L C N C F P N N P S X X was quite confusing.

While there is value in putting the config and PATH first, because they are common and important variables, the table of contents becomes very inconsistent and confusing when mixed like before.
---
 book/special_variables.md | 62 +++++++++++++++++++--------------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/book/special_variables.md b/book/special_variables.md
index ccff688a7ed..782f5c1d9ca 100644
--- a/book/special_variables.md
+++ b/book/special_variables.md
@@ -49,20 +49,32 @@ The `$nu` constant is a record containing several useful values:
 
 There are also several environment variables that Nushell uses for specific purposes:
 
+### `$env.CMD_DURATION_MS`
+
+The amount of time in milliseconds that the previous command took to run.
+
 ### `$env.config`
 
 `$env.config` is the main configuration record used in Nushell. Settings are documented in `config nu --doc`.
 
-### `$env.PATH`
-
-The search path for executing other applications. It is initially inherited from the parent process as a string, but converted to a Nushell `list` at startup for easy access.
+### `$env.CURRENT_FILE`
 
-It is converted back to a string before running a child-process.
+Inside a script, module, or sourced-file, this variable holds the fully-qualified filename. Note that this
+information is also available as a constant through the [`path self`](/commands/docs/path_self.md) command.
 
 ### `$env.ENV_CONVERSIONS`
 
 Allows users to specify how to convert certain environment variables to Nushell types. See [ENV_CONVERSIONS](./configuration.md#env-conversions).
 
+### `$env.FILE_PWD`
+
+Inside a script, module, or sourced-file, this variable holds the fully qualified name of the directory in which
+the file resides. Note that this value is also available as a constant through:
+
+```nu
+path self | path dirname
+```
+
 ### `$env.LAST_EXIT_CODE`
 
 The exit code of the last command, usually used for external commands — Equivalent to `$?` from POSIX. Note that this information is also made available to the `catch` block in a `try` expression for external commands. For instance:
@@ -81,27 +93,29 @@ try {
 # => 2
 ```
 
-### `$env.CMD_DURATION_MS`
+### `$env.NU_LIB_DIRS`
 
-The amount of time in milliseconds that the previous command took to run.
+A list of directories which will be searched when using the `source`, `use`, or `overlay use` commands. See also:
 
-### `$env.NU_VERSION`
+- The `$NU_LIB_DIRS` constant below
+- [Module Path](./modules/using_modules.md#module-path)
+- [Configuration - `$NU_LIB_DIRS`](./configuration.md#nu-lib-dirs-constant)
 
-The current Nushell version. The same as `(version).version`, but, as an environment variable, it is exported to and can be read by child processes.
+### `$env.NU_PLUGIN_DIRS`
 
-### `$env.CURRENT_FILE`
+A list of directories which will be searched when registering plugins with `plugin add`. See also:
 
-Inside a script, module, or sourced-file, this variable holds the fully-qualified filename. Note that this
-information is also available as a constant through the [`path self`](/commands/docs/path_self.md) command.
+- [Plugin Search Path](./plugins.md#plugin-search-path)
 
-### `$env.FILE_PWD`
+### `$env.NU_VERSION`
 
-Inside a script, module, or sourced-file, this variable holds the fully qualified name of the directory in which
-the file resides. Note that this value is also available as a constant through:
+The current Nushell version. The same as `(version).version`, but, as an environment variable, it is exported to and can be read by child processes.
 
-```nu
-path self | path dirname
-```
+### `$env.PATH`
+
+The search path for executing other applications. It is initially inherited from the parent process as a string, but converted to a Nushell `list` at startup for easy access.
+
+It is converted back to a string before running a child-process.
 
 ### `$env.PROCESS_PATH`
 
@@ -110,20 +124,6 @@ above, it is not present when sourcing a file or importing a module.
 
 Note: Also unlike the two variables above, the exact path (including symlinks) that was used to _invoke_ the file is returned.
 
-### `$env.NU_LIB_DIRS`
-
-A list of directories which will be searched when using the `source`, `use`, or `overlay use` commands. See also:
-
-- The `$NU_LIB_DIRS` constant below
-- [Module Path](./modules/using_modules.md#module-path)
-- [Configuration - `$NU_LIB_DIRS`](./configuration.md#nu-lib-dirs-constant)
-
-### `$env.NU_PLUGIN_DIRS`
-
-A list of directories which will be searched when registering plugins with `plugin add`. See also:
-
-- [Plugin Search Path](./plugins.md#plugin-search-path)
-
 ### `$env.PROMPT_*` and `$env.TRANSIENT_PROMPT_*`
 
 A number of variables are available for configuring the Nushell prompt that appears on each commandline. See also: