nvm: Node versions and shell state
Reading nvm source: PATH ordering and a parser that is not a version resolver
Reproduce the pinned PATH replacement rules and .nvmrc validation boundaries with 16 isolated cases instead of guessing from command names.
What you will learn
- PATH replacement is conditional
- Parsing .nvmrc does not prove availability
- Keep the experiment narrower than the product
Before you start
- Basic shell commands and process environments
- Distinguish runtime installation from runtime selection
Diagnose requested versus active Node versions and design explicit setup and verification boundaries.
Key takeaways
- Switching paths can preserve earlier custom entries and older duplicates.
- Removing managed entries is a different function from replacing one.
- A returned .nvmrc string is not proof of a recognized or installed Node version.
PATH replacement is conditional
nvm_change_path returns the new directory when input is empty and prepends it when no managed path is recognized. If a recognized system binary directory precedes an old nvm path, it also prepends, retaining the old entry. Otherwise sed replaces a matching managed entry in place, preserving earlier custom directories. Those branches implement ordering policy, not universal deduplication.
Our fixtures observed a custom /tools/bin prefix remaining before the replacement, an earlier /usr/bin causing prepend-and-retain behavior, and only the first duplicate modern managed path being replaced. nvm_strip_path has a different job: its awk-based pass removes matching managed entries and preserves a trailing colon. These results should not be generalized to every conceivable path spelling.
Parsing .nvmrc does not prove availability
nvm_process_nvmrc_content strips comments, trims whitespace and rejects an empty effective file or multiple bare lines. The inspected implementation accepts distinct key/value lines alongside a single bare version request, rejects a node key and duplicate ordinary keys, and still requires the bare line. The README reserves key/value material for future use, so it should not be used as an application configuration mechanism.
The helper accepted a bare not-a-node-version string in the experiment. That result means this parsing stage returned text, not that nvm can install or run such a version. Availability and recognized-selector checks belong downstream. Separating syntax, resolution and installation prevents a superficially successful parse from becoming a false claim that the project environment is ready.
Keep the experiment narrower than the product
The harness verifies the complete nvm.sh Git blob, extracts five inspected functions unchanged and executes them in fresh Bash children. It substitutes only inert diagnostic-output adapters; upstream color formatting is not tested. Sixteen cases passed without sourcing the entire manager, installing Node, changing a parent PATH or editing any shell profile.
An early harness attempt passed multiline fixture content through Windows command arguments and lost the intended input shape. The corrected harness uses standard input for that content. This was a test-transport issue, not an upstream parser defect. Record exact inputs, outputs and scope so an experiment validates the implementation rather than an accidental property of its launcher.
Implementation steps
- 1
Verify the fixed source hash before extracting helpers.
- 2
Test empty, custom-prefix, system-prefix and duplicate paths.
- 3
Test valid, missing and conflicting .nvmrc content through standard input.
- 4
Separate parser results from runtime resolution and installation.
Copy-ready example
{
"observedCases": 16,
"customPrefix": "preserved",
"systemBeforeOld": "prepend new; retain old",
"duplicateModernPath": "first replacement only",
"unknownBareVersionText": "parser returns text",
"runtimeAvailabilityVerified": false,
"fullManagerSourced": false
}Frequently asked questions
Does the parser accepting unknown text mean a bug in installation?
No such conclusion follows. The parser returns a request string; later resolution and installation checks have different responsibilities.
Were all upstream tests run?
No. The review executed five extracted helpers with diagnostic adapters in 16 bounded cases, not the full upstream test suite.
Sources
- nvm.shSource checked 2026-09-08
- test/fast/Unit tests/nvm_change_pathSource checked 2026-09-08
- test/fast/Unit tests/nvm_strip_pathSource checked 2026-09-08
- README.mdSource checked 2026-09-08