Skip to content

docs(mkdir): the --verbose example showed output that never occurs - #19023

Merged
fdncred merged 1 commit into
nushell:mainfrom
Developer1010x:mkdir-verbose-example-output
Sep 14, 2026
Merged

fdncred merged 1 commit into
nushell:mainfrom
Developer1010x:mkdir-verbose-example-output

Conversation

@Developer1010x

Copy link
Copy Markdown
Contributor

Description

help mkdir shows this for the --verbose example:

path created error
foo/bar true
foo2 true

mkdir never produces that. Every argument goes through
nu_path::expand_path_with(..) before it reaches the output, so the reported
paths are absolute:

> mkdir -v foo/bar foo2 | get 0.path
/tmp/.tmpHDMTuH/mkdir_verbose_absolute/foo/bar

Since the value depends on the working directory, it cannot be written down as
a literal at all — so this drops the declared result, the way the first
example in the same command already does, and says in the description that the
paths are absolute.

Why it went unnoticed: umkdir.rs has no test_examples(), unlike the commands
in crates/nu-command/src/path/, so the declared result was never compared
against what the command actually returns.

User-facing changes (Release notes)

n/a — documentation only. The help mkdir example no longer shows output that
the command cannot produce.

Tests + Formatting

Added verbose_reports_the_expanded_path, which asserts the reported path
equals the expanded path rather than the argument as typed. It is not vacuous:
pointing it at the value the example used to claim produces

assertion `left == right` failed
  left: "foo/bar"
 right: "/tmp/.tmpHDMTuH/mkdir_verbose_absolute/foo/bar"

which is the bug this PR fixes. All 18 umkdir tests pass;
cargo fmt --all -- --check and cargo clippy --all-targets are clean.

I did not add test_examples() for this command: its examples create
directories as a side effect, which is presumably why it has none.

Additional notes

Follow-up to #19017, same command, unrelated bug.

`help mkdir` documents `mkdir -v foo/bar foo2` as returning `path: "foo/bar"`
and `path: "foo2"`. It does not: each argument goes through
`nu_path::expand_path_with` before it is reported, so the real values are
absolute paths.

The output depends on the working directory, so it cannot be written down as a
literal at all. Drop the declared result, as the first example already does,
and say in the description that the paths are absolute.

`umkdir.rs` has no `test_examples()` — unlike the `path` commands — so nothing
checked the declared result against reality. Pin the behavior with an
integration test instead: `verbose_reports_the_expanded_path` asserts the
reported path equals the expanded one, and fails against the value the example
used to claim.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
@fdncred
fdncred merged commit 8eb16b2 into nushell:main Sep 14, 2026
15 checks passed
@fdncred

fdncred commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Thanks

@github-actions github-actions Bot added this to the v0.116.0 milestone Sep 14, 2026
fdncred pushed a commit that referenced this pull request Sep 14, 2026
…9024)

## Description

`view source` renders a rest parameter without a space after the colon,
unlike
every other parameter kind:

```nu
> def test [a?:any --b:int ...rest:string] { echo 'test' }; view source test
def test [ a?: any --b: int ...rest:string] { echo 'test' }
```

`a?: any` and `--b: int` are spaced; `...rest:string` is not. In
`render_def`
the branches are:

| kind | format |
| --- | --- |
| required positional | `"{}: {} "` |
| optional positional | `"{}?: {} "` |
| flag with an argument | `": {arg}"` |
| rest | `"...{}:{}"` |

The rest branch is the only one missing the space. The command's own
examples
already show `...rest: string`, in two of them, so the documented form
was the
right one and the code disagreed with it.

Why it was not caught: `view_source.rs` declares eight example results
and had
no test running them. Adding `test_examples` for `ViewSource` is what
surfaced
this, and it also caught a second, smaller mismatch — the module example
claimed

```
" export-env { $env.FOO_ENV = 'BAZ' }"
```

while `view source` returns the source between the module's braces
verbatim,
so the real value has the trailing space too. That one is the example
being
wrong rather than the code, so the example is corrected.

## User-facing changes (Release notes)

`view source` now renders a rest parameter as `...rest: string` rather
than
`...rest:string`, matching how it already renders every other parameter.

## Tests + Formatting

Added `test_examples` for `ViewSource`, which runs all eight declared
example
results. It is not vacuous — it is what found both mismatches, failing
first on

```
expected: "def --env --wrapped foo [ ...rest: string] { print $rest }"
got:      "def --env --wrapped foo [ ...rest:string] { print $rest }"
```

and then on the module example. Both are green now.

The full `nu-command` lib suite (815 tests) and the existing
`view_source`
integration tests pass. I checked nothing asserted the old spelling: the
only
other `...name:type` in the tree is input source in an unrelated parser
test,
not an assertion on `view source` output. `cargo fmt --all -- --check`
and
`cargo clippy --all-targets` are clean.

## Additional notes

Third small `nu-command` fix from me after #19017 and #19023, same
theme: a
declared example result that nothing was checking.

Co-authored-by: Prajwal Narayana <[email protected]>
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
@fdncred fdncred added notes:fixes Noted in "Bug fixes" section notes:ready Indicates Ready for Release notes labels Sep 14, 2026
@cptpiepmatz cptpiepmatz added notes:mention Noted in "Hall of Fame" section and removed notes:fixes Noted in "Bug fixes" section labels Sep 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

notes:mention Noted in "Hall of Fame" section notes:ready Indicates Ready for Release notes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants