Skip to content

Commit 85e5717

Browse files
committed
Fixup and update cmd.exe shelling out docs
The documentation about shelling out cmd.exe commands was outdated, incomplete, and confusing. * It mixed past tense "used to" and the forwarded commands without being clear about their relationship and differences * There have been multiple undocumented changes across versions * Neither Nu release notes nor this or the book escaping [the shell] mention these version differences The docs receive a significant update to structure and information: * Introduce a headlined section for the forwarded commands * Introduce version-blocks to describe differences between versions * Describe forwarded command list changes across versions within a same-behavior block * Differentiates between CMD.EXE and `cmd.exe` (the shell and the executable/forward call) These version docs may not be useful in the long run, given the version release ages. Nevertheless, these docs will serve as a good, thorough reference even if the information about older versions will be removed at some point or even soon. The docs themselves provide enough context and source links to verify their correctness. I will not repeat those here in the commit description.
1 parent 2155303 commit 85e5717

File tree

1 file changed

+43
-2
lines changed

1 file changed

+43
-2
lines changed

book/coming_from_cmd.md

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Coming from CMD.EXE
22

3-
This table was last updated for Nu 0.67.0.
3+
This table was last updated for Nu 0.99.1.
44

55
| CMD.EXE | Nu | Task |
66
| ------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
@@ -57,4 +57,45 @@ This table was last updated for Nu 0.67.0.
5757
| `VERIFY` | | Verify that file writes happen |
5858
| `VOL` | | Show drive information |
5959

60-
Before Nu version 0.67, Nu [used to](https://www.nushell.sh/blog/2022-08-16-nushell-0_67.html#windows-cmd-exe-changes-rgwood) use CMD.EXE to launch external commands, which meant that the above builtins could be run as an `^external` command. As of version 0.67, however, Nu no longer uses CMD.EXE to launch externals, meaning the above builtins cannot be run from within Nu, except for `ASSOC`, `CLS`, `ECHO`, `FTYPE`, `MKLINK`, `PAUSE`, `START`, `VER`, and `VOL`, which are explicitly allowed to be interpreted by CMD if no executable by that name exists.
60+
## Forwarded CMD.EXE commands
61+
62+
Nu accepts and runs *some* CMD.EXE commands through `cmd.exe`.
63+
Which ones, and under which precedence depends on the Nu version.
64+
65+
### Version 0.94 onward
66+
67+
Nu version 0.94 released *(on 2024-05-28)* with [a behavior change](https://github.com/nushell/nushell/pull/12921).
68+
69+
If the command is one of the forwarded CMD.EXE commands, `cmd.exe` is called with that command.
70+
71+
The forwarded commands have not changed since version 0.75.0 ([v0.94 src](https://github.com/nushell/nushell/blob/0.94.0/crates/nu-command/src/system/run_external.rs#L531-L538)):
72+
73+
`ASSOC`, `CLS`, `ECHO`, `FTYPE`, `MKLINK`, `PAUSE`, `START`, `VER`, `VOL`
74+
75+
Note that, contrary to earlier versions, the forwards take precedence over other external commands.
76+
77+
For example, with a `ver.bat` file in the current working directory, executing `^ver` leads to the CMD.EXE `VER` being executed, *NOT* the `ver.bat` file.
78+
79+
Executing `./ver` or `ver.bat` *will* execute the local bat file though.
80+
81+
### Version 0.67 until before 0.94
82+
83+
Nu version 0.67 released *(on 2022-08-16)* with [a behavior change](https://www.nushell.sh/blog/2022-08-16-nushell-0_67.html#windows-cmd-exe-changes-rgwood).
84+
85+
When a command is not found as an executable, if the command is one of the forwarded CMD.EXE commands, `cmd.exe` is called with that command.
86+
87+
The forwarded commands are:
88+
89+
* v0.67.0 onward ([src](https://github.com/nushell/nushell/blob/0.67.0/crates/nu-command/src/system/run_external.rs#L148)):\
90+
`ASSOC`, `DIR`, `ECHO`, `FTYPE`, `MKLINK`, `START`, `VER`, `VOL`
91+
* v0.68.0 onward ([src](https://github.com/nushell/nushell/blob/0.68.0/crates/nu-command/src/system/run_external.rs#L168-L169)):\
92+
`ASSOC`, `CLS`, `DIR`, `ECHO`, `FTYPE`, `MKLINK`, `PAUSE`, `START`, `VER`, `VOL`
93+
* v0.75.0 onward ([src](https://github.com/nushell/nushell/blob/0.75.0/crates/nu-command/src/system/run_external.rs#L207), [change](https://github.com/nushell/nushell/pull/7740)):\
94+
`ASSOC`, `CLS`, `ECHO`, `FTYPE`, `MKLINK`, `PAUSE`, `START`, `VER`, `VOL`
95+
96+
## Prior to version 0.67
97+
98+
If a command is not found, `cmd.exe` is called with that command.
99+
That means that effectively *all* CMD.EXE commands can be called from within Nu.
100+
101+
The disadvantage is that commands that do not resolve in `cmd.exe`, the command not found error message comes from `cmd.exe` rather than Nu.

0 commit comments

Comments
 (0)