Skip to content

Commit ce38a4b

Browse files
authored
New chapter page collecting the list of special variables (#1860)
* New chapter page collecting the list of special variables * Added PROCESS_PATH
1 parent ae71cf1 commit ce38a4b

File tree

2 files changed

+167
-0
lines changed

2 files changed

+167
-0
lines changed

.vuepress/configs/sidebar/en.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ export const sidebarEn: SidebarConfig = {
3838
'/book/working_with_records.md',
3939
'/book/working_with_tables.md',
4040
'/book/navigating_structured_data.md',
41+
'/book/special_variables.md',
4142
],
4243
},
4344
{

book/special_variables.md

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Special Variables
2+
3+
Nushell makes available and uses a number of special variables and constants. Many of these are mentioned or documented in other places in this Book, but this page
4+
should include _all_ variables for reference.
5+
6+
[[toc]]
7+
8+
## `$nu`
9+
10+
The `$nu` constant is a record containing several useful values:
11+
12+
- `default-config-dir`: The directory where the configuration files are stored and read.
13+
- `config-path`: The path of the main Nushell config file, normally `config.nu` in the config directory.
14+
- `env-path`: The optional environment config file, normally `env.nu` in the config directory.
15+
- `history-path`: The text or SQLite file storing the command history.
16+
- `loginshell-path`: The optional config file which runs for login shells, normally `login.nu` in the config directory.
17+
- `plugin-path`: The plugin registry file, normally `plugin.msgpackz` in the config directory.
18+
- `home-path`: The user's home directory which can be accessed using the shorthand `~`.
19+
- `data-dir`: The data directory for Nushell, which includes the `./vendor/autoload` directories loaded at startup and other user data.
20+
- `cache-dir`: A directory for non-essential (cached) data.
21+
- `vendor-autoload-dirs`: A list of directories where third-party applications should install configuration files that will be auto-loaded during startup.
22+
- `user-autoload-dirs`: A list of directories where the user may create additional configuration files which will be auto-loaded during startup.
23+
- `temp-path`: A path for temporary files that should be writeable by the user.
24+
- `pid`: The PID of the currently running Nushell process.
25+
- `os-info`: Information about the host operating system.
26+
- `startup-time`: The amount of time (in duration) that it took for Nushell to start and process all configuration files.
27+
- `is-interactive`: A boolean indicating whether Nushell was started as an interactive shell (`true`) or is running a script or command-string. For example:
28+
29+
```nu
30+
$nu.is-interactive
31+
# => true
32+
nu -c "$nu.is-interactive"
33+
# => false
34+
35+
# Force interactive with --interactive (-i)
36+
nu -i -c "$nu.is-interactive"
37+
# => true
38+
```
39+
40+
Note: When started as an interactive shell, startup config files are processed. When started as a non-interactive shell, no config files are read unless explicitly called via flag.
41+
42+
- `is-login`: Indicates whether or not Nushell was started as a login shell.
43+
- `history-enabled`: History may be disabled via `nu --no-history`, in which case this constant will be `false`.
44+
- `current-exe`: The full path to the currently-running `nu` binary. Can be combined with `path dirname` (which is constant) to determine the directory where the binary is located.
45+
46+
## `$env`
47+
48+
`$env` is a special mutable variable containing the current environment variables. As with any process, the initial environment is inherited from the parent process which started `nu`.
49+
50+
There are also several environment variables that Nushell uses for specific purposes:
51+
52+
### `$env.config`
53+
54+
`$env.config` is the main configuration record used in Nushell. Settings are documented in `config nu --doc`.
55+
56+
### `$env.PATH`
57+
58+
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.
59+
60+
It is converted back to a string before running a child-process.
61+
62+
### `$env.ENV_CONVERSIONS`
63+
64+
Allows users to specify how to convert certain environment variables to Nushell types. See [ENV_CONVERSIONS](./configuration.md#env_conversions).
65+
66+
### `$env.LAST_EXIT_CODE`
67+
68+
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:
69+
70+
```nu
71+
^ls file-that-does-not-exist e> /dev/null
72+
$env.LAST_EXIT_CODE
73+
# => 2
74+
75+
# or
76+
try {
77+
^ls file-that-does-not-exist e> /dev/null
78+
} catch {|e|
79+
print $e.exit_code
80+
}
81+
# => 2
82+
```
83+
84+
### `env.CMD_DURATION_MS`
85+
86+
The amount of time in milliseconds that the previous command took to run.
87+
88+
### `$env.NU_VERSION`
89+
90+
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.
91+
92+
### `$env.CURRENT_FILE`
93+
94+
Inside a script, module, or sourced-file, this variable holds the fully-qualified filename. Note that this
95+
information is also available as a constant through the [`path self`](/commands/docs/path_self.md) command.
96+
97+
### `$env.FILE_PWD`
98+
99+
Inside a script, module, or sourced-file, this variable holds the fully qualified name of the directory in which
100+
the file resides. Note that this value is also available as a constant through:
101+
102+
```nu
103+
path self | path dirname
104+
```
105+
106+
### `$env.PROCESS_PATH`
107+
108+
When _executing a script_, this variable represents the name and relative path of the script. Unlike the two variables
109+
above, it is not present when sourcing a file or importing a module.
110+
111+
Note: Also unlike the two variables above, the exact path (including symlinks) that was used to _invoke_ the file is returned.
112+
113+
### `$env.NU_LIB_DIRS`
114+
115+
A list of directories which will be searched when using the `source`, `use`, or `overlay use` commands. See also:
116+
117+
- The `$NU_LIB_DIRS` constant below
118+
- [Module Path](./modules/using_modules.md#module-path)
119+
- [Configuration - `$NU_LIB_DIRS`](./configuration.md#nu_lib_dirs-constant)
120+
121+
### `$env.NU_PLUGIN_DIRS`
122+
123+
A list of directories which will be searched when registering plugins with `plugin add`. See also:
124+
125+
- [Plugin Search Path](./plugins.md#plugin-search-path)
126+
127+
### `$env.PROMPT_*` and `$env.TRANSIENT_PROMPT_*`
128+
129+
A number of variables are available for configuring the Nushell prompt that appears on each commandline. See also:
130+
131+
- [Configuration - Prompt Configuration](./configuration.md#prompt-configuration)
132+
- `config nu --doc`
133+
134+
### `$env.SHLVL`
135+
136+
`SHLVL` is incremented by most shells when entering a new subshell. It can be used to determine the number of nested shells. For instance,
137+
if `$env.SHLVL == 2` then typing `exit` should return you to a parent shell.
138+
139+
### `$env.XDG_CONFIG_HOME`
140+
141+
Can be used to optionally override the `$nu.default-config-dir` location. See [Configuration - Startup Variables](./configuration.md#startup-variables).
142+
143+
### `$env.XDG_DATA_DIR`
144+
145+
Can be used to optionally override the `$nu.data-dir` location. See [Configuration - Startup Variables](./configuration.md#startup-variables).
146+
147+
## `$in`
148+
149+
The `$in` variable represents the pipeline input into an expression. See [Pipelines - The Special `$in` Variable](./pipelines.md#pipeline-input-and-the-special-in-variable).
150+
151+
## `$it`
152+
153+
`$it` is a special variable that is _only_ available in a `where` "row condition" — a convenient shorthand which simplifies field access. See `help where` for more information.
154+
155+
## `$NU_LIB_DIRS`
156+
157+
A constant version of `$env.NU_LIB_DIRS` - a list of directories which will be searched when using the `source`, `use`, or `overlay use` commands. See also:
158+
159+
- [Module Path](./modules/using_modules.md#module-path)
160+
- [Configuration - `$NU_LIB_DIRS`](./configuration.md#nu_lib_dirs-constant)
161+
162+
## `$NU_PLUGIN_DIRS`
163+
164+
A constant version of `$env.NU_PLUGIN_DIRS` - a list of directories which will be searched when registering plugins with `plugin add`. See also:
165+
166+
- [Plugin Search Path](./plugins.md#plugin-search-path)

0 commit comments

Comments
 (0)