[Docs] document current and clarify .nvmrc fallback in help/README

- Help text for `nvm install`/`use`/`exec`/`run`/`which` now ends with
  "Uses .nvmrc if version is omitted; otherwise errors."
  so it's clear that omitting the version is not a free fallback.
- Help signatures for `use`/`exec`/`run` now show `[current | <version>]`
  to mirror `nvm which` and document that `current` is accepted.
- `nvm current` description now spells out that it resolves via `$PATH`
  and is not affected by `.nvmrc`.
- README: add `current` to the list of special aliases, with the same caveat.
  The `.nvmrc` section now states that `nvm use`/`install`/`which`
  exit with status 127 when neither a version nor an `.nvmrc` resolves,
  notes the (current) `exec`/`run` fallback as undefined behavior,
  and points readers at `current` for the explicit "active node" use case.

Refs #3755

README.md

@@ -429,6 +429,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
 
@@ -645,7 +646,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 — 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`) — `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

@@ -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'

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