Initial plan

When `nvm install <target>` found that `<target>` was already installed,
the post-`nvm use` steps
(`--reinstall-packages-from`, default packages, and `--alias`/`--default`)
were gated on `[ $EXIT_CODE -ne 0 ]`.
Since that branch is only entered when `nvm use` succeeded (EXIT_CODE == 0),
those conditions were always false, so the steps were silently skipped.

The fresh-install branch correctly uses `-eq 0`;
mirror that here so `--reinstall-packages-from` actually migrates global packages
(and the alias/default get set) when the target version already exists.

Includes a regression test covering the already-installed path.

Fixes #3858

.github/workflows/nodejs-org.yml

@@ -7,7 +7,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: 'nvm version tag (e.g., v0.40.4). Defaults to latest release.'
+        description: 'nvm version tag (e.g., v0.40.4). Defaults to the latest version tag.'
         required: false
         default: ''
 
@@ -18,7 +18,7 @@ jobs:
   update-nodejs-org:
     if: github.repository == 'nvm-sh/nvm' && github.actor == 'ljharb'
     permissions:
-      contents: none
+      contents: read  # for the "Extract and validate version" step's `gh api .../tags` call via the default github.token
     name: 'Create PR to nodejs/nodejs.org'
     runs-on: ubuntu-latest
     steps:
@@ -41,7 +41,8 @@ jobs:
           elif [ "${GITHUB_REF_TYPE}" = "tag" ]; then
             TAG="${GITHUB_REF#refs/tags/}"
           else
-            TAG="$(gh api "repos/${GITHUB_REPOSITORY}/releases/latest" --jq '.tag_name')"
+            TAG="$(gh api --paginate "repos/${GITHUB_REPOSITORY}/tags" --jq '.[].name' \
+              | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)"
           fi
 
           if ! printf '%s\n' "${TAG}" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
@@ -65,16 +66,19 @@ jobs:
           FORK_OWNER="$(gh api user --jq '.login')"
 
           DEFAULT_BRANCH="$(gh api repos/nodejs/nodejs.org --jq '.default_branch')"
+
+          gh repo sync "${FORK_OWNER}/nodejs.org" --branch "${DEFAULT_BRANCH}" || true
+
           UPSTREAM_SHA="$(gh api "repos/nodejs/nodejs.org/git/ref/heads/${DEFAULT_BRANCH}" --jq '.object.sha')"
 
           # Create or reset branch on fork to upstream HEAD
           if ! gh api "repos/${FORK_OWNER}/nodejs.org/git/refs" \
             -f "ref=refs/heads/${BRANCH}" \
-            -f "sha=${UPSTREAM_SHA}" > /dev/null 2>&1; then
+            -f "sha=${UPSTREAM_SHA}" > /dev/null; then
             gh api "repos/${FORK_OWNER}/nodejs.org/git/refs/heads/${BRANCH}" \
               -X PATCH \
               -f "sha=${UPSTREAM_SHA}" \
-              -f "force=true" > /dev/null
+              -F "force=true" > /dev/null
           fi
 
           printf 'fork_owner=%s\n' "${FORK_OWNER}" >> "${GITHUB_OUTPUT}"

.github/workflows/rebase.yml

@@ -2,16 +2,12 @@ name: Automatic Rebase
 
 on: [pull_request_target]
 
-permissions: read-all
+permissions:
+  contents: write  # for ljharb/rebase to push code to rebase
+  pull-requests: read  # for ljharb/rebase to get info about PR
 
 jobs:
   _:
-    name: "Automatic Rebase"
+    uses: ljharb/actions/.github/workflows/rebase.yml@main
-
+    secrets:
-    runs-on: ubuntu-latest
+      token: ${{ secrets.GITHUB_TOKEN }}
-
-    steps:
-      - uses: actions/checkout@v6
-      - uses: ljharb/rebase@master
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/require-allow-edits.yml

@@ -2,10 +2,14 @@ name: Require “Allow Edits”
 
 on: [pull_request_target]
 
-permissions: read-all
+permissions:
+  contents: read
 
 jobs:
   _:
+    permissions:
+      pull-requests: read  # for ljharb/require-allow-edits to check 'allow edits' on PR
+
     name: "Require “Allow Edits”"
 
     runs-on: ubuntu-latest

.github/workflows/tests-fast.yml

@@ -47,8 +47,17 @@ jobs:
             production.cloudflare.docker.com:443
             production.cloudfront.docker.com:443
       - uses: actions/checkout@v6
+        id: checkout
+        continue-on-error: true
         with:
           submodules: true
+      - name: 'nvmrc submodule fallback (forks without their own nvmrc)'
+        if: steps.checkout.outcome == 'failure'
+        shell: bash
+        run: |
+          git submodule set-url test/fixtures/nvmrc https://github.com/nvm-sh/nvmrc.git
+          git submodule sync --recursive
+          git submodule update --init --recursive
       - name: Install zsh, additional shells, and awk variant
         run: |
           sudo apt-get update

.github/workflows/tests-installation-iojs.yml

@@ -39,8 +39,17 @@ jobs:
             azure.archive.ubuntu.com:80
             packages.microsoft.com:443
       - uses: actions/checkout@v6
+        id: checkout
+        continue-on-error: true
         with:
           submodules: true
+      - name: 'nvmrc submodule fallback (forks without their own nvmrc)'
+        if: steps.checkout.outcome == 'failure'
+        shell: bash
+        run: |
+          git submodule set-url test/fixtures/nvmrc https://github.com/nvm-sh/nvmrc.git
+          git submodule sync --recursive
+          git submodule update --init --recursive
       - name: Install zsh and additional shells
         run: |
           sudo apt-get update

.github/workflows/tests-installation-node.yml

@@ -45,8 +45,17 @@ jobs:
             registry-1.docker.io:443
             auth.docker.io:443
       - uses: actions/checkout@v6
+        id: checkout
+        continue-on-error: true
         with:
           submodules: true
+      - name: 'nvmrc submodule fallback (forks without their own nvmrc)'
+        if: steps.checkout.outcome == 'failure'
+        shell: bash
+        run: |
+          git submodule set-url test/fixtures/nvmrc https://github.com/nvm-sh/nvmrc.git
+          git submodule sync --recursive
+          git submodule update --init --recursive
       - uses: ljharb/actions/node/install@main
         name: 'npm install && version checks'
         with:

.github/workflows/tests-xenial.yml

@@ -42,8 +42,17 @@ jobs:
             registry-1.docker.io:443
             auth.docker.io:443
       - uses: actions/checkout@v6
+        id: checkout
+        continue-on-error: true
         with:
           submodules: true
+      - name: 'nvmrc submodule fallback (forks without their own nvmrc)'
+        if: steps.checkout.outcome == 'failure'
+        shell: bash
+        run: |
+          git submodule set-url test/fixtures/nvmrc https://github.com/nvm-sh/nvmrc.git
+          git submodule sync --recursive
+          git submodule update --init --recursive
       - uses: ljharb/actions/node/install@main
         name: 'npm install && version checks'
         with:

.github/workflows/tests.yml

@@ -8,7 +8,7 @@ permissions:
 jobs:
   tests:
     permissions:
-      contents: write
+      contents: read  # for actions/checkout@v6
 
     name: "tests"
     runs-on: ubuntu-latest

.github/workflows/windows-npm.yml

@@ -94,6 +94,8 @@ jobs:
           bash.exe "%USERPROFILE%\setup.sh"
 
   wsl_matrix:
+    permissions:
+      contents: none
     continue-on-error: true
     name: 'WSL nvm install'
     defaults:
@@ -187,6 +189,8 @@ jobs:
           node -v
 
   wsl_matrix_unofficial:
+    permissions:
+      contents: none
     continue-on-error: true
     name: 'WSL nvm install'
     defaults:

README.md

@@ -31,6 +31,7 @@
 - [Usage](#usage)
   - [Long-term Support](#long-term-support)
   - [Migrating Global Packages While Installing](#migrating-global-packages-while-installing)
+  - [Migrating Global Packages Between Installed Versions](#migrating-global-packages-between-installed-versions)
   - [Offline Install](#offline-install)
   - [Default Global Packages From File While Installing](#default-global-packages-from-file-while-installing)
   - [io.js](#iojs)
@@ -429,6 +430,7 @@ In place of a version pointer like "14.7" or "16.3" or "12.22.1", you can use th
   - `iojs`: this installs the latest version of [`io.js`](https://iojs.org/en/)
   - `stable`: this alias is deprecated, and only truly applies to `node` `v0.12` and earlier. Currently, this is an alias for `node`.
   - `unstable`: this alias points to `node` `v0.11` - the last "unstable" node release, since post-1.0, all node versions are stable. (in SemVer, versions communicate breakage, not stability).
+  - `current`: the version currently active in this shell (i.e. what `node` resolves to via `$PATH`). It is **not** affected by `.nvmrc`. Useful when you want to refer to the active version explicitly — e.g. `nvm which current` always prints the path to the active `node`, regardless of whether an `.nvmrc` file is present.
 
 ### Long-term Support
 
@@ -482,6 +484,17 @@ nvm install-latest-npm
 
 If you've already gotten an error to the effect of "npm does not support Node.js", you'll need to (1) revert to a previous node version (`nvm ls` & `nvm use <your latest _working_ version from the ls>`), (2) delete the newly created node version (`nvm uninstall <your _broken_ version of node from the ls>`), then (3) rerun your `nvm install` with the `--latest-npm` flag.
 
+### Migrating Global Packages Between Installed Versions
+
+`--reinstall-packages-from` is tied to `nvm install`. To migrate global npm packages between versions you _already_ have installed, without (re)installing anything, `nvm use` the destination and run `nvm reinstall-packages` as a standalone command, pointing at the version you want to copy _from_:
+
+```sh
+nvm use 22.22.2
+nvm reinstall-packages 22.20.0
+```
+
+This reinstalls all global packages from `22.20.0` into the currently-active version (`22.22.2`). As with `--reinstall-packages-from`, the npm version itself is not changed.
+
 
 ### Offline Install
 
@@ -645,7 +658,7 @@ NVM_AUTH_HEADER="Bearer secret-token" nvm install node
 ### .nvmrc
 
 You can create a `.nvmrc` file containing a node version number (or any other string that `nvm` understands; see `nvm --help` for details) in the project root directory (or any parent directory).
-Afterwards, `nvm use`, `nvm install`, `nvm exec`, `nvm run`, and `nvm which` will use the version specified in the `.nvmrc` file if no version is supplied on the command line.
+Afterwards, `nvm use`, `nvm install`, and `nvm which` will use the version specified in the `.nvmrc` file if no version is supplied on the command line; if no `.nvmrc` is found either, they exit with status `127`. (`nvm exec` and `nvm run` follow the same `.nvmrc` lookup, but currently fall back to the active node if neither resolves &mdash; treat that fallback as undefined behavior; pass an explicit version if you need predictable scripting.) If you want the currently active version, pass `current` explicitly (e.g. `nvm which current`) &mdash; `current` is not affected by `.nvmrc`.
 
 For example, to make nvm default to the latest 5.9 release, the latest LTS version, or the latest node version for the current directory:
 

nvm.sh

@@ -622,7 +622,7 @@ nvm_rc_version() {
   NVMRC_PATH="$(nvm_find_nvmrc)"
   if [ ! -e "${NVMRC_PATH}" ]; then
     if [ "${NVM_SILENT:-0}" -ne 1 ]; then
-      nvm_err "No .nvmrc file found"
+      nvm_err "No version provided and no .nvmrc file found"
     fi
     return 1
   fi
@@ -3222,7 +3222,7 @@ nvm() {
         nvm_echo '  nvm --help                                  Show this message'
         nvm_echo '    --no-colors                               Suppress colored output'
         nvm_echo '  nvm --version                               Print out the installed version of nvm'
-        nvm_echo '  nvm install [<version>]                     Download and install a <version>. Uses .nvmrc if available and version is omitted.'
+        nvm_echo '  nvm install [<version>]                     Download and install a <version>. Uses .nvmrc if version is omitted; otherwise errors.'
         nvm_echo '   The following optional arguments, if provided, must appear directly after `nvm install`:'
         nvm_echo '    -s                                        Skip binary download, install from source only.'
         nvm_echo '    -b                                        Skip source download, install from binary only.'
@@ -3239,23 +3239,23 @@ nvm() {
         nvm_echo '  nvm uninstall <version>                     Uninstall a version'
         nvm_echo '  nvm uninstall --lts                         Uninstall using automatic LTS (long-term support) alias `lts/*`, if available.'
         nvm_echo '  nvm uninstall --lts=<LTS name>              Uninstall using automatic alias for provided LTS line, if available.'
-        nvm_echo '  nvm use [<version>]                         Modify PATH to use <version>. Uses .nvmrc if available and version is omitted.'
+        nvm_echo '  nvm use [current | <version>]               Modify PATH to use <version>. Uses .nvmrc if version is omitted; otherwise errors.'
         nvm_echo '   The following optional arguments, if provided, must appear directly after `nvm use`:'
         nvm_echo '    --silent                                  Silences stdout/stderr output'
         nvm_echo '    --lts                                     Uses automatic LTS (long-term support) alias `lts/*`, if available.'
         nvm_echo '    --lts=<LTS name>                          Uses automatic alias for provided LTS line, if available.'
         nvm_echo '    --save                                    Writes the specified version to .nvmrc.'
-        nvm_echo '  nvm exec [<version>] [<command>]            Run <command> on <version>. Uses .nvmrc if available and version is omitted.'
+        nvm_echo '  nvm exec [current | <version>] [<command>]  Run <command> on <version>. Uses .nvmrc if version is omitted; otherwise errors.'
         nvm_echo '   The following optional arguments, if provided, must appear directly after `nvm exec`:'
         nvm_echo '    --silent                                  Silences stdout/stderr output'
         nvm_echo '    --lts                                     Uses automatic LTS (long-term support) alias `lts/*`, if available.'
         nvm_echo '    --lts=<LTS name>                          Uses automatic alias for provided LTS line, if available.'
-        nvm_echo '  nvm run [<version>] [<args>]                Run `node` on <version> with <args> as arguments. Uses .nvmrc if available and version is omitted.'
+        nvm_echo '  nvm run [current | <version>] [<args>]      Run `node` on <version> with <args> as arguments. Uses .nvmrc if version is omitted; otherwise errors.'
         nvm_echo '   The following optional arguments, if provided, must appear directly after `nvm run`:'
         nvm_echo '    --silent                                  Silences stdout/stderr output'
         nvm_echo '    --lts                                     Uses automatic LTS (long-term support) alias `lts/*`, if available.'
         nvm_echo '    --lts=<LTS name>                          Uses automatic alias for provided LTS line, if available.'
-        nvm_echo '  nvm current                                 Display currently activated version of Node'
+        nvm_echo '  nvm current                                 Display the active node version (resolved via $PATH; not affected by .nvmrc).'
         nvm_echo '  nvm ls [<version>]                          List installed versions, matching a given <version> if provided'
         nvm_echo '    --no-colors                               Suppress colored output'
         nvm_echo '    --no-alias                                Suppress `nvm alias` output'
@@ -3276,7 +3276,7 @@ nvm() {
         nvm_echo '  nvm install-latest-npm                      Attempt to upgrade to the latest working `npm` on the current node version'
         nvm_echo '  nvm reinstall-packages <version>            Reinstall global `npm` packages contained in <version> to current version'
         nvm_echo '  nvm unload                                  Unload `nvm` from shell'
-        nvm_echo '  nvm which [current | <version>]             Display path to installed node version. Uses .nvmrc if available and version is omitted.'
+        nvm_echo '  nvm which [current | <version>]             Display path to installed node version. Uses .nvmrc if version is omitted; otherwise errors.'
         nvm_echo '    --silent                                  Silences stdout/stderr output when a version is omitted'
         nvm_echo '  nvm cache dir                               Display path to the cache directory for nvm'
         nvm_echo '  nvm cache clear                             Empty cache directory for nvm'
@@ -3338,7 +3338,9 @@ nvm() {
           fi
         ;;
         *)
-          >&2 nvm --help
+          nvm_err 'Usage: nvm cache dir'
+          nvm_err '       nvm cache clear'
+          nvm_err '  Run `nvm --help` for full help.'
           return 127
         ;;
       esac
@@ -3594,7 +3596,9 @@ nvm() {
         else
           { provided_version="$(nvm_rc_version 3>&1 1>&4)"; } 4>&1
           if [ $version_not_provided -eq 1 ] && [ -z "${provided_version}" ]; then
-            >&2 nvm --help
+            nvm_err 'Usage: nvm install [<version>]'
+            nvm_err '  Provide a <version>, or run from a directory containing an .nvmrc file.'
+            nvm_err '  Run `nvm --help` for full help.'
             return 127
           fi
         fi
@@ -3732,10 +3736,10 @@ nvm() {
             nvm install-latest-npm
             EXIT_CODE=$?
           fi
-          if [ $EXIT_CODE -ne 0 ] && [ -z "${SKIP_DEFAULT_PACKAGES-}" ]; then
+          if [ $EXIT_CODE -eq 0 ] && [ -z "${SKIP_DEFAULT_PACKAGES-}" ]; then
             nvm_install_default_packages
           fi
-          if [ $EXIT_CODE -ne 0 ] && [ -n "${REINSTALL_PACKAGES_FROM-}" ] && [ "_${REINSTALL_PACKAGES_FROM}" != "_N/A" ]; then
+          if [ $EXIT_CODE -eq 0 ] && [ -n "${REINSTALL_PACKAGES_FROM-}" ] && [ "_${REINSTALL_PACKAGES_FROM}" != "_N/A" ]; then
             nvm reinstall-packages "${REINSTALL_PACKAGES_FROM}"
             EXIT_CODE=$?
           fi
@@ -3753,7 +3757,7 @@ nvm() {
           EXIT_CODE=$?
         fi
 
-        if [ $EXIT_CODE -ne 0 ] && [ -n "${ALIAS-}" ]; then
+        if [ $EXIT_CODE -eq 0 ] && [ -n "${ALIAS-}" ]; then
           nvm alias "${ALIAS}" "${provided_version}"
           EXIT_CODE=$?
         fi
@@ -3852,7 +3856,10 @@ nvm() {
     ;;
     "uninstall")
       if [ $# -ne 1 ]; then
-        >&2 nvm --help
+        nvm_err 'Usage: nvm uninstall <version>'
+        nvm_err '       nvm uninstall --lts'
+        nvm_err '       nvm uninstall --lts=<LTS name>'
+        nvm_err '  Run `nvm --help` for full help.'
         return 127
       fi
 
@@ -4041,7 +4048,9 @@ nvm() {
       fi
 
       if [ -z "${VERSION}" ]; then
-        >&2 nvm --help
+        nvm_err 'Usage: nvm use [<version>]'
+        nvm_err '  Provide a <version>, or run from a directory containing an .nvmrc file.'
+        nvm_err '  Run `nvm --help` for full help.'
         return 127
       fi
 
@@ -4165,7 +4174,9 @@ nvm() {
           VERSION="$(nvm_version "${NVM_RC_VERSION}")" ||:
         fi
         if [ "${VERSION:-N/A}" = 'N/A' ]; then
-          >&2 nvm --help
+          nvm_err 'Usage: nvm run [<version>] [<args>]'
+          nvm_err '  Provide a <version>, or run from a directory containing an .nvmrc file.'
+          nvm_err '  Run `nvm --help` for full help.'
           return 127
         fi
       fi
@@ -4179,6 +4190,14 @@ nvm() {
             if [ $has_checked_nvmrc -ne 1 ]; then
               { NVM_RC_VERSION="$(NVM_SILENT="${NVM_SILENT:-0}" nvm_rc_version 3>&1 1>&4)"; } 4>&1 && has_checked_nvmrc=1
             fi
+            if [ -z "${NVM_RC_VERSION-}" ]; then
+              if [ "${NVM_SILENT:-0}" -ne 1 ]; then
+                nvm_err 'WARNING: `nvm run` was invoked without a version argument and without an .nvmrc file.'
+                nvm_err '  Falling back to the active node version; this will become an error in a future release.'
+                nvm_err '  Pass `current` explicitly (e.g. `nvm run current ...`) to silence this warning.'
+              fi
+              NVM_RC_VERSION="$(nvm_version current)" ||:
+            fi
             provided_version="${NVM_RC_VERSION}"
             IS_VERSION_FROM_NVMRC=1
             VERSION="$(nvm_version "${NVM_RC_VERSION}")" ||:
@@ -4236,19 +4255,36 @@ nvm() {
 
       local provided_version
       provided_version="$1"
+      local VERSION_SOURCE
+      VERSION_SOURCE=''
       if [ "${NVM_LTS-}" != '' ]; then
         provided_version="lts/${NVM_LTS:-*}"
         VERSION="${provided_version}"
+        VERSION_SOURCE='lts'
       elif [ -n "${provided_version}" ]; then
         VERSION="$(nvm_version "${provided_version}")" ||:
         if [ "_${VERSION}" = '_N/A' ] && ! nvm_is_valid_version "${provided_version}"; then
           { provided_version="$(NVM_SILENT="${NVM_SILENT:-0}" nvm_rc_version 3>&1 1>&4)"; } 4>&1 && has_checked_nvmrc=1
           VERSION="$(nvm_version "${provided_version}")" ||:
+          if [ -n "${provided_version}" ]; then
+            VERSION_SOURCE='nvmrc'
+          fi
         else
+          VERSION_SOURCE='arg'
           shift
         fi
       fi
 
+      if [ -z "${VERSION_SOURCE}" ]; then
+        if [ "${NVM_SILENT:-0}" -ne 1 ]; then
+          nvm_err 'WARNING: `nvm exec` was invoked without a version argument and without an .nvmrc file.'
+          nvm_err '  Falling back to the active node version; this will become an error in a future release.'
+          nvm_err '  Pass `current` explicitly (e.g. `nvm exec current ...`) to silence this warning.'
+        fi
+        provided_version='current'
+        VERSION="$(nvm_version current)" ||:
+      fi
+
       nvm_ensure_version_installed "${provided_version}"
       EXIT_CODE=$?
       if [ "${EXIT_CODE}" != "0" ]; then
@@ -4383,7 +4419,9 @@ nvm() {
         VERSION="${provided_version-}"
       fi
       if [ -z "${VERSION}" ]; then
-        >&2 nvm --help
+        nvm_err 'Usage: nvm which [current | <version>]'
+        nvm_err '  Provide a <version>, or run from a directory containing an .nvmrc file.'
+        nvm_err '  Run `nvm --help` for full help.'
         return 127
       fi
 
@@ -4480,7 +4518,8 @@ nvm() {
       NVM_ALIAS_DIR="$(nvm_alias_path)"
       command mkdir -p "${NVM_ALIAS_DIR}"
       if [ $# -ne 1 ]; then
-        >&2 nvm --help
+        nvm_err 'Usage: nvm unalias <name>'
+        nvm_err '  Run `nvm --help` for full help.'
         return 127
       fi
       if [ "${1#*\/}" != "${1-}" ]; then
@@ -4517,7 +4556,8 @@ nvm() {
     ;;
     "install-latest-npm")
       if [ $# -ne 0 ]; then
-        >&2 nvm --help
+        nvm_err 'Usage: nvm install-latest-npm'
+        nvm_err '  Run `nvm --help` for full help.'
         return 127
       fi
 
@@ -4525,7 +4565,8 @@ nvm() {
     ;;
     "reinstall-packages" | "copy-packages")
       if [ $# -ne 1 ]; then
-        >&2 nvm --help
+        nvm_err "Usage: nvm ${COMMAND} <version>"
+        nvm_err '  Run `nvm --help` for full help.'
         return 127
       fi
 

package.json

@@ -43,11 +43,11 @@
   "homepage": "https://github.com/nvm-sh/nvm",
   "devDependencies": {
     "dockerfile_lint": "^0.3.4",
-    "doctoc": "^2.2.1",
+    "doctoc": "^2.5.0",
     "eclint": "^2.8.1",
     "markdown-link-check": "^3.14.2",
     "replace": "^1.2.2",
-    "semver": "^7.7.3",
+    "semver": "^7.8.5",
     "urchin": "^0.0.5"
   }
 }

test/fast/Running 'nvm --help' documents current and the .nvmrc fallback

@@ -0,0 +1,44 @@
+#!/bin/sh
+
+set -e
+
+die () { echo "$@" ; exit 1; }
+
+export NVM_DIR="$(cd ../.. && pwd)"
+
+: nvm.sh
+\. ../../nvm.sh
+
+\. ../common.sh
+
+HELP="$(nvm --help 2>&1)"
+
+# Signatures for use/exec/run advertise `current` (mirroring `nvm which`).
+for EXPECTED in \
+  'nvm use [current | <version>]' \
+  'nvm exec [current | <version>] [<command>]' \
+  'nvm run [current | <version>] [<args>]' \
+  'nvm which [current | <version>]' \
+; do
+  case "${HELP}" in
+    *"${EXPECTED}"*) ;;
+    *) die "nvm --help did not contain signature >${EXPECTED}<" ;;
+  esac
+done
+
+# The .nvmrc fallback is documented as conditional, not free.
+case "${HELP}" in
+  *'Uses .nvmrc if version is omitted; otherwise errors.'*) ;;
+  *) die "nvm --help did not document the .nvmrc fallback caveat" ;;
+esac
+
+# The stale, looser phrasing must be gone.
+case "${HELP}" in
+  *'if available and version is omitted'*) die "nvm --help still contains the old .nvmrc phrasing" ;;
+esac
+
+# `nvm current` is documented as resolving via \$PATH, not .nvmrc.
+case "${HELP}" in
+  *'Display the active node version (resolved via $PATH; not affected by .nvmrc).'*) ;;
+  *) die "nvm --help did not document that 'nvm current' resolves via \$PATH" ;;
+esac

test/fast/Running 'nvm exec' and 'nvm run' without a resolvable version warn and fall back

@@ -0,0 +1,63 @@
+#!/bin/sh
+
+set -ex
+
+die () { echo "$@" ; cleanup ; exit 1; }
+
+cleanup() {
+  cd "${ORIG_PWD}" 2>/dev/null || true
+  [ -n "${TMP_DIR-}" ] && rm -rf "${TMP_DIR}"
+}
+
+export NVM_DIR="$(cd ../.. && pwd)"
+
+: nvm.sh
+\. ../../nvm.sh
+
+\. ../common.sh
+
+ORIG_PWD="$(pwd)"
+
+# Run from a fresh, empty directory so no ambient .nvmrc above the test dir
+# can satisfy the lookup and mask the warning.
+TMP_DIR="$(mktemp -d)"
+cd "${TMP_DIR}" || die "could not cd to temp dir"
+
+EXEC_WARNING='WARNING: `nvm exec` was invoked without a version argument and without an .nvmrc file.'
+RUN_WARNING='WARNING: `nvm run` was invoked without a version argument and without an .nvmrc file.'
+
+# `nvm exec` with no version and no .nvmrc should warn on stderr (and fall back).
+set +ex # needed for stderr
+EXEC_STDERR="$(nvm exec </dev/null 2>&1 1>/dev/null)"
+set -ex
+case "${EXEC_STDERR}" in
+  *"${EXEC_WARNING}"*) ;;
+  *) die "'nvm exec' with no version did not warn; got >${EXEC_STDERR}<" ;;
+esac
+
+# `--silent` should suppress the warning.
+set +ex # needed for stderr
+EXEC_SILENT_STDERR="$(nvm exec --silent </dev/null 2>&1 1>/dev/null)"
+set -ex
+case "${EXEC_SILENT_STDERR}" in
+  *WARNING*) die "'nvm exec --silent' should not warn; got >${EXEC_SILENT_STDERR}<" ;;
+esac
+
+# `nvm run` with an unresolvable version and no .nvmrc should warn (and fall back).
+set +ex # needed for stderr
+RUN_STDERR="$(nvm run bogusversion </dev/null 2>&1 1>/dev/null)"
+set -ex
+case "${RUN_STDERR}" in
+  *"${RUN_WARNING}"*) ;;
+  *) die "'nvm run' with no resolvable version did not warn; got >${RUN_STDERR}<" ;;
+esac
+
+# `--silent` should suppress the warning.
+set +ex # needed for stderr
+RUN_SILENT_STDERR="$(nvm run --silent bogusversion </dev/null 2>&1 1>/dev/null)"
+set -ex
+case "${RUN_SILENT_STDERR}" in
+  *WARNING*) die "'nvm run --silent' should not warn; got >${RUN_SILENT_STDERR}<" ;;
+esac
+
+cleanup

test/fast/Subcommands with missing or invalid args show a focused usage error

@@ -0,0 +1,68 @@
+#!/bin/sh
+
+set -ex
+
+die () { echo "$@" ; cleanup ; exit 1; }
+
+cleanup() {
+  cd "${ORIG_PWD}" 2>/dev/null || true
+  [ -n "${TMP_DIR-}" ] && rm -rf "${TMP_DIR}"
+}
+
+export NVM_DIR="$(cd ../.. && pwd)"
+
+: nvm.sh
+\. ../../nvm.sh
+
+\. ../common.sh
+
+ORIG_PWD="$(pwd)"
+
+# Run from a fresh, empty directory so the "no version + no .nvmrc" cases
+# (install/run/which) are not masked by an ambient .nvmrc above the test dir.
+TMP_DIR="$(mktemp -d)"
+cd "${TMP_DIR}" || die "could not cd to temp dir"
+
+# Asserts a subcommand emits the given focused usage line (not the full help
+# dump) on stderr, and exits 127.
+assert_usage() {
+  local EXPECTED_LINE
+  EXPECTED_LINE="$1"
+  shift
+
+  try_err "$@"
+
+  case "${CAPTURED_STDERR}" in
+    *"${EXPECTED_LINE}"*) ;;
+    *) die "\`$*\` did not show focused usage >${EXPECTED_LINE}<; got >${CAPTURED_STDERR}<" ;;
+  esac
+  # the focused usage should NOT be the full help dump
+  case "${CAPTURED_STDERR}" in
+    *'Show this message'*) die "\`$*\` dumped full help instead of a focused usage" ;;
+  esac
+  [ "_${CAPTURED_EXIT_CODE}" = "_127" ] \
+    || die "\`$*\` expected exit code 127; got ${CAPTURED_EXIT_CODE}"
+}
+
+assert_usage 'Usage: nvm cache dir'                  nvm cache bogus
+assert_usage 'Usage: nvm install [<version>]'        nvm install
+assert_usage 'Usage: nvm run [<version>] [<args>]'   nvm run
+assert_usage 'Usage: nvm which [current | <version>]' nvm which
+assert_usage 'Usage: nvm uninstall <version>'        nvm uninstall
+assert_usage 'Usage: nvm uninstall <version>'        nvm uninstall a b
+assert_usage 'Usage: nvm unalias <name>'             nvm unalias
+assert_usage 'Usage: nvm unalias <name>'             nvm unalias a b
+assert_usage 'Usage: nvm install-latest-npm'         nvm install-latest-npm extra
+assert_usage 'Usage: nvm reinstall-packages <version>' nvm reinstall-packages
+assert_usage 'Usage: nvm copy-packages <version>'    nvm copy-packages a b
+
+# `nvm use` reaches its focused-usage guard only when version resolution returns
+# an empty string. From the CLI that cannot happen: an omitted version is caught
+# earlier (the `Please see ... nvmrc` branch), and an unresolvable non-empty
+# version yields the "N/A" sentinel, never "". The branch is a defensive guard,
+# so drive it directly by stubbing the resolver to return empty. Keep this last:
+# the stub stays in effect for the rest of the shell.
+nvm_match_version() { nvm_echo ''; }
+assert_usage 'Usage: nvm use [<version>]'            nvm use foo
+
+cleanup

test/fast/Unit tests/nvm_rc_version errors when no version and no .nvmrc

@@ -0,0 +1,39 @@
+#!/bin/sh
+
+die () { echo "$@" ; cleanup ; exit 1; }
+
+cleanup() {
+  cd "${ORIG_PWD}" 2>/dev/null || true
+  [ -n "${TMP_DIR-}" ] && rm -rf "${TMP_DIR}"
+}
+
+: nvm.sh
+\. ../../../nvm.sh
+
+\. ../../common.sh
+
+ORIG_PWD="$(pwd)"
+
+# Run from a fresh, empty directory so no ambient .nvmrc above the test dir
+# is found by the upward lookup.
+TMP_DIR="$(mktemp -d)"
+cd "${TMP_DIR}" || die "could not cd to temp dir"
+
+# The message must name both halves of the problem: no argument AND no .nvmrc.
+try_err nvm_rc_version
+EXPECTED='No version provided and no .nvmrc file found'
+[ "_${CAPTURED_STDERR}" = "_${EXPECTED}" ] \
+  || die "nvm_rc_version did not print >${EXPECTED}<; got >${CAPTURED_STDERR}<"
+[ "_${CAPTURED_EXIT_CODE}" = "_1" ] \
+  || die "nvm_rc_version expected exit code 1; got ${CAPTURED_EXIT_CODE}"
+
+# NVM_SILENT suppresses the message but the call still fails.
+export NVM_SILENT=1
+try_err nvm_rc_version
+unset NVM_SILENT
+[ -z "${CAPTURED_STDERR}" ] \
+  || die "NVM_SILENT nvm_rc_version should be silent; got >${CAPTURED_STDERR}<"
+[ "_${CAPTURED_EXIT_CODE}" = "_1" ] \
+  || die "NVM_SILENT nvm_rc_version expected exit code 1; got ${CAPTURED_EXIT_CODE}"
+
+cleanup

test/installation_node/install while reinstalling packages

@@ -1,6 +1,27 @@
 #!/bin/sh
 
-die () { echo "$@" ; exit 1; }
+# State touched by the regression section below; cleanup restores it even on failure.
+DEFAULT_PACKAGES_FILE="${NVM_DIR}/default-packages"
+DEFAULT_PACKAGES_BACKUP=""
+DEFAULT_PACKAGES_WROTE=""
+TEST_ALIAS=""
+
+cleanup () {
+  if [ -n "${DEFAULT_PACKAGES_WROTE}" ]; then
+    rm -f "${DEFAULT_PACKAGES_FILE}"
+    DEFAULT_PACKAGES_WROTE=""
+  fi
+  if [ -n "${DEFAULT_PACKAGES_BACKUP}" ] && [ -f "${DEFAULT_PACKAGES_BACKUP}" ]; then
+    mv "${DEFAULT_PACKAGES_BACKUP}" "${DEFAULT_PACKAGES_FILE}"
+    DEFAULT_PACKAGES_BACKUP=""
+  fi
+  if [ -n "${TEST_ALIAS}" ]; then
+    nvm unalias "${TEST_ALIAS}" > /dev/null 2>&1 || true
+    TEST_ALIAS=""
+  fi
+}
+
+die () { echo "$@" ; cleanup ; exit 1; }
 
 \. ../../nvm.sh
 
@@ -44,3 +65,54 @@ nvm use --lts=argon
 node --version | grep v4.9.1 > /dev/null || die "nvm ls --lts=argon didn't use v4.9.1"
 
 npm list --global | grep object-is > /dev/null || die "object-is isn't installed"
+
+
+# Regression: `--reinstall-packages-from` must still migrate packages when the
+# target version is *already installed*. See https://github.com/nvm-sh/nvm/issues/3858
+
+# install a fresh global package on the source (v9.7.0) only
+nvm use 9.7.0
+npm install -g is-nan@1.0.0 || die "npm install -g is-nan failed"
+npm list --global | grep is-nan > /dev/null || die "is-nan isn't installed on v9.7.0"
+
+# precondition: the already-installed target (v9.10.0) must not have it yet
+nvm use 9.10.0
+npm list --global | grep is-nan > /dev/null && die "is-nan should not be installed on v9.10.0 before reinstall"
+
+# target is already installed, so this should report so AND still migrate packages
+OUTPUT="$(nvm install --reinstall-packages-from=9.7.0 9.10.0 2>&1)" || die "nvm install --reinstall-packages-from=9.7.0 9.10.0 failed: ${OUTPUT}"
+nvm_echo "${OUTPUT}" | grep "is already installed" > /dev/null || die "expected 'already installed' message, got: ${OUTPUT}"
+
+nvm use 9.10.0
+npm list --global | grep is-nan > /dev/null || die "is-nan was not migrated to already-installed v9.10.0"
+
+
+# ...the same is true for default packages: they must install on the already-installed path too.
+
+# back up any real default-packages file, then point it at a package the target lacks
+if [ -f "${DEFAULT_PACKAGES_FILE}" ]; then
+  DEFAULT_PACKAGES_BACKUP="${DEFAULT_PACKAGES_FILE}.3858.bak"
+  mv "${DEFAULT_PACKAGES_FILE}" "${DEFAULT_PACKAGES_BACKUP}" || die "could not back up ${DEFAULT_PACKAGES_FILE}"
+fi
+DEFAULT_PACKAGES_WROTE=1
+nvm_echo 'object-inspect@1.0.2' > "${DEFAULT_PACKAGES_FILE}"
+
+# precondition: the already-installed target must not have the default package yet
+nvm use 9.10.0
+npm list --global | grep object-inspect > /dev/null && die "object-inspect should not be installed on v9.10.0 before default-packages test"
+
+nvm install 9.10.0 > /dev/null 2>&1 || die "nvm install 9.10.0 (already installed, default-packages) failed"
+nvm use 9.10.0
+npm list --global | grep object-inspect > /dev/null || die "default packages were not installed on already-installed v9.10.0"
+
+# restore the default-packages file before the next assertion
+cleanup
+
+
+# ...and `--alias` must be set on the already-installed path too.
+TEST_ALIAS='nvm-3858-already-installed'
+nvm unalias "${TEST_ALIAS}" > /dev/null 2>&1 || true # ensure a clean precondition
+nvm install --alias="${TEST_ALIAS}" 9.10.0 > /dev/null 2>&1 || die "nvm install --alias=${TEST_ALIAS} 9.10.0 (already installed) failed"
+TERM=dumb nvm alias "${TEST_ALIAS}" | grep 'v9.10.0' > /dev/null || die "--alias was not set on already-installed v9.10.0"
+
+cleanup