[New] nvm alias: store --lts and --lts=<name>

`nvm alias default --lts node` writes `--lts node` to the alias file,
so it resolves to the latest installed LTS version, using each version's recorded LTS status;
`--lts=<name>` limits it to one LTS line.
The flags of the outermost alias apply when one alias points at another,
an alias with a flag this version of nvm doesn't recognize resolves to nothing, rather than ignoring the flag,
and `nvm uninstall` also removes aliases with flags that point at the uninstalled version.
A new shell never downloads index.tab, so it explains a default alias that needs LTS status that isn't recorded yet.
This commit is contained in:
Jordan Harband committed 2026-10-21 12:57:19 -07:00
1 parent e5f1288b40
commit fe2900d176
5 files changed
+253 -14

No files matched your search

+4
View File
@@ -635,8 +635,12 @@ To set a default Node version to be used in any new shell, use the alias 'defaul
nvm alias default node # this refers to the latest installed version of node
nvm alias default 18 # this refers to the latest installed v18.x version of node
nvm alias default 18.12 # this refers to the latest installed v18.12.x version of node
nvm alias default --lts node # this refers to the latest installed LTS version of node
nvm alias default --lts=iron 20 # this refers to the latest installed v20.x version of node from the "iron" LTS line
```
nvm records the LTS status of every version each time it downloads the list of available versions, so `--lts` aliases know which installed versions are LTS.
### Use a mirror of node binaries
To use a mirror of the node binaries, set `$NVM_NODEJS_ORG_MIRROR`:
+167 -14
View File
@@ -1135,11 +1135,50 @@ nvm_version() {
return $?
fi
# flags stored in an alias, like `--lts`, precede the version they apply to
local NVM_LTS_FILTER
NVM_LTS_FILTER=''
while :; do
case "${PATTERN}" in
'--lts '*)
NVM_LTS_FILTER='*'
;;
--lts=*' '*)
NVM_LTS_FILTER="${PATTERN%% *}"
NVM_LTS_FILTER="${NVM_LTS_FILTER#--lts=}"
;;
--*)
nvm_echo 'N/A'
return 3
;;
*) break ;;
esac
PATTERN="${PATTERN#* }"
done
# like `nvm_resolve_alias`, these flags replace those of an alias they precede
if [ -n "${NVM_LTS_FILTER}" ]; then
local NVM_FLAGGED_TARGET
if NVM_FLAGGED_TARGET="$(nvm_resolve_alias "${PATTERN}" 2>/dev/null)" && [ "_${NVM_FLAGGED_TARGET}" != '_∞' ]; then
while :; do
case "${NVM_FLAGGED_TARGET}" in
--*' '*) NVM_FLAGGED_TARGET="${NVM_FLAGGED_TARGET#* }" ;;
*) break ;;
esac
done
PATTERN="${NVM_FLAGGED_TARGET}"
fi
fi
local NVM_NODE_PREFIX
NVM_NODE_PREFIX="$(nvm_node_prefix)"
case "_${PATTERN}" in
"_${NVM_NODE_PREFIX}" | "_${NVM_NODE_PREFIX}-")
PATTERN="stable"
"_${NVM_NODE_PREFIX}" | "_${NVM_NODE_PREFIX}-" | _stable)
# `stable` is only the latest version, which might not match the LTS filter
if [ -n "${NVM_LTS_FILTER}" ]; then
PATTERN="${NVM_NODE_PREFIX}"
else
PATTERN="stable"
fi
;;
esac
@@ -1147,12 +1186,16 @@ nvm_version() {
# itself, unless an alias of the same name takes precedence. Short-circuiting
# it here avoids the `nvm_ls` subprocess pipeline on shell startup; every
# other pattern falls through to `nvm_ls` unchanged.
if nvm_is_installed_exact_version "${PATTERN}"; then
if [ -z "${NVM_LTS_FILTER}" ] && nvm_is_installed_exact_version "${PATTERN}"; then
nvm_echo "${PATTERN}"
return 0
fi
VERSION="$(nvm_ls "${PATTERN}" | command tail -1)"
if [ -n "${NVM_LTS_FILTER}" ]; then
VERSION="$(nvm_ls "${PATTERN}" | nvm_filter_lts_versions "${NVM_LTS_FILTER}" | command tail -1)"
else
VERSION="$(nvm_ls "${PATTERN}" | command tail -1)"
fi
case "${VERSION}" in
system[[:blank:]]*)
VERSION='system'
@@ -1877,6 +1920,11 @@ nvm_resolve_alias() {
local ALIAS_TEMP
local ALIAS_OUTPUT
# flags stored in an alias, like `--lts`, precede its target; the outermost alias's apply
local ALIAS_FLAGS
ALIAS_FLAGS=''
local ALIAS_TEMP_FLAGS
local SEEN_ALIASES
SEEN_ALIASES="
${ALIAS}
@@ -1885,6 +1933,19 @@ ${ALIAS}
ALIAS_OUTPUT="$(nvm_alias "${ALIAS}" 2>/dev/null)" || ALIAS_OUTPUT=''
ALIAS_TEMP="${ALIAS_OUTPUT%%
*}"
ALIAS_TEMP_FLAGS=''
while :; do
case "${ALIAS_TEMP}" in
--*' '*)
ALIAS_TEMP_FLAGS="${ALIAS_TEMP_FLAGS:+${ALIAS_TEMP_FLAGS} }${ALIAS_TEMP%% *}"
ALIAS_TEMP="${ALIAS_TEMP#* }"
;;
*) break ;;
esac
done
if [ -z "${ALIAS_FLAGS}" ]; then
ALIAS_FLAGS="${ALIAS_TEMP_FLAGS}"
fi
if [ -z "${ALIAS_TEMP}" ]; then
break
@@ -1910,13 +1971,15 @@ ${ALIAS_TEMP}
local NVM_NODE_PREFIX
NVM_NODE_PREFIX="$(nvm_node_prefix)"
case "${ALIAS}" in
'∞' | \
"${NVM_IOJS_PREFIX}" | "${NVM_IOJS_PREFIX}-" | \
"${NVM_NODE_PREFIX}")
'∞')
nvm_echo "${ALIAS}"
;;
"${NVM_IOJS_PREFIX}" | "${NVM_IOJS_PREFIX}-" | \
"${NVM_NODE_PREFIX}")
nvm_echo "${ALIAS_FLAGS:+${ALIAS_FLAGS} }${ALIAS}"
;;
*)
nvm_ensure_version_prefix "${ALIAS}"
nvm_echo "${ALIAS_FLAGS:+${ALIAS_FLAGS} }$(nvm_ensure_version_prefix "${ALIAS}")"
;;
esac
return 0
@@ -2281,13 +2344,31 @@ nvm_record_lts_status() {
nvm_ensure_lts_status() {
if [ -f "$(nvm_lts_status_path)" ]; then
return 0
elif [ "${NVM_OFFLINE-}" = 1 ]; then
elif [ "${NVM_OFFLINE-}" = 1 ] || [ -n "${NVM_INDEX_NO_FETCH-}" ]; then
return 3
fi
NVM_LTS='' nvm_ls_remote_index_tab node std '' >/dev/null 2>&1
[ -f "$(nvm_lts_status_path)" ]
}
# args: an LTS codename, or `*` for any
# Keeps the version lines on stdin whose recorded LTS status matches.
nvm_filter_lts_versions() {
if ! nvm_ensure_lts_status; then
nvm_err 'The LTS status of installed versions is not recorded yet; run `nvm ls-remote` to record it.'
return 3
fi
command awk -v lts="${1-}" -v record="$(nvm_lts_status_path)" '
BEGIN {
while ((getline line < record) > 0) {
split(line, fields, " ");
status[fields[1]] = fields[2];
}
}
($1 in status) && status[$1] != "-" && (lts == "*" || status[$1] == lts) { print }
'
}
# args flavor, type, version
nvm_ls_remote_index_tab() {
local LTS
@@ -2589,7 +2670,8 @@ nvm_get_remote_aliases() {
NVM_ALIAS_TARGET="$(nvm_resolve_alias "${NVM_ALIAS_NAME}" 2>/dev/null)" || continue
case "${NVM_ALIAS_TARGET}" in
'' | *[[:cntrl:]]*) continue ;;
# flags, like `--lts`, select among installed versions, not remote ones
'' | --* | *[[:cntrl:]]*) continue ;;
esac
command printf '%s\t%s\n' "${NVM_ALIAS_TARGET}" "${NVM_ALIAS_NAME}"
@@ -4301,6 +4383,8 @@ nvm() {
nvm_echo ' nvm alias [<pattern>] Show all aliases beginning with <pattern>'
nvm_echo ' --no-colors Suppress colored output'
nvm_echo ' nvm alias <name> <version> Set an alias named <name> pointing to <version>'
nvm_echo ' --lts Only resolve to installed LTS (long-term support) versions'
nvm_echo ' --lts=<LTS name> Only resolve to installed versions of a specific LTS line'
nvm_echo ' nvm unalias <name> Deletes the alias named <name>'
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'
@@ -4999,8 +5083,20 @@ nvm() {
# rm any aliases that point to uninstalled version.
nvm_is_zsh && setopt local_options nonomatch
local NVM_ALIAS_FILE
local NVM_ALIAS_TARGET
for NVM_ALIAS_FILE in "$(nvm_alias_path)"/*; do
if [ -f "${NVM_ALIAS_FILE}" ] && [ "_$(nvm_print_alias_file "${NVM_ALIAS_FILE}" | command head -n 1)" = "_${VERSION}" ]; then
if [ ! -f "${NVM_ALIAS_FILE}" ]; then
continue
fi
NVM_ALIAS_TARGET="$(nvm_print_alias_file "${NVM_ALIAS_FILE}" | command head -n 1)"
# flags, like `--lts`, precede the target
while :; do
case "${NVM_ALIAS_TARGET}" in
--*' '*) NVM_ALIAS_TARGET="${NVM_ALIAS_TARGET#* }" ;;
*) break ;;
esac
done
if [ "_${NVM_ALIAS_TARGET}" = "_${VERSION}" ]; then
nvm unalias "$(command basename "${NVM_ALIAS_FILE}")"
fi
done
@@ -5570,6 +5666,8 @@ nvm() {
local TARGET
local NVM_NO_COLORS
NVM_NO_COLORS=''
local NVM_ALIAS_FLAGS
NVM_ALIAS_FLAGS=''
ALIAS='--'
TARGET='--'
@@ -5577,6 +5675,23 @@ nvm() {
case "${1-}" in
--) ;;
--no-colors) NVM_NO_COLORS="${1}" ;;
--lts=)
nvm_err '`--lts=` needs an LTS name.'
return 55
;;
--lts | --lts=*)
if [ -n "${NVM_ALIAS_FLAGS}" ]; then
nvm_err '`--lts` may only be provided once.'
return 55
fi
case "${1#--lts=}" in
*[!abcdefghijklmnopqrstuvwxyz0123456789._-]*)
nvm_err 'LTS names must be lowercase'
return 3
;;
esac
NVM_ALIAS_FLAGS="${1}"
;;
--*)
nvm_err "Unsupported option \"${1}\"."
return 55
@@ -5606,12 +5721,16 @@ nvm() {
nvm_err 'Aliases in subdirectories are not supported.'
return 1
fi
TARGET="${NVM_ALIAS_FLAGS:+${NVM_ALIAS_FLAGS} }${TARGET}"
VERSION="$(nvm_version "${TARGET}")" ||:
if [ "${VERSION}" = 'N/A' ]; then
nvm_err "! WARNING: Version '${TARGET}' does not exist."
fi
nvm_make_alias "${ALIAS}" "${TARGET}"
NVM_NO_COLORS="${NVM_NO_COLORS-}" NVM_CURRENT="${NVM_CURRENT-}" DEFAULT=false nvm_print_formatted_alias "${ALIAS}" "${TARGET}" "${VERSION}"
elif [ -n "${NVM_ALIAS_FLAGS}" ]; then
nvm_err "\`${NVM_ALIAS_FLAGS}\` needs a target version, like \`nvm alias ${ALIAS#--} ${NVM_ALIAS_FLAGS} node\`."
return 55
else
if [ "${ALIAS-}" = '--' ]; then
unset ALIAS
@@ -5659,7 +5778,19 @@ nvm() {
local NVM_ALIAS_ORIGINAL
NVM_ALIAS_ORIGINAL="$(nvm_alias "${1}")"
command rm -f "${NVM_ALIAS_DIR}/${1}"
nvm_echo "Deleted alias ${1} - restore it with \`nvm alias \"${1}\" \"${NVM_ALIAS_ORIGINAL}\"\`"
# flags, like `--lts`, are separate arguments, before the quoted target
local NVM_ALIAS_ORIGINAL_FLAGS
NVM_ALIAS_ORIGINAL_FLAGS=''
while :; do
case "${NVM_ALIAS_ORIGINAL}" in
--*' '*)
NVM_ALIAS_ORIGINAL_FLAGS="${NVM_ALIAS_ORIGINAL_FLAGS}${NVM_ALIAS_ORIGINAL%% *} "
NVM_ALIAS_ORIGINAL="${NVM_ALIAS_ORIGINAL#* }"
;;
*) break ;;
esac
done
nvm_echo "Deleted alias ${1} - restore it with \`nvm alias \"${1}\" ${NVM_ALIAS_ORIGINAL_FLAGS}\"${NVM_ALIAS_ORIGINAL}\"\`"
;;
"install-latest-npm")
if [ $# -ne 0 ]; then
@@ -5782,7 +5913,7 @@ nvm() {
nvm_is_iojs_version nvm_is_alias nvm_has_non_aliased \
nvm_ls_remote nvm_ls_remote_iojs nvm_ls_remote_index_tab nvm_get_remote_aliases \
nvm_ls nvm_remote_version nvm_remote_versions nvm_sort_versions \
nvm_lts_status_path nvm_record_lts_status nvm_ensure_lts_status \
nvm_lts_status_path nvm_record_lts_status nvm_ensure_lts_status nvm_filter_lts_versions \
nvm_install_binary nvm_install_source nvm_clang_version \
nvm_get_mirror nvm_get_download_slug nvm_download_artifact nvm_is_cached_artifact \
nvm_install_npm_if_needed nvm_use_if_needed nvm_check_file_permissions \
@@ -5945,6 +6076,9 @@ nvm_auto() {
case "${NVM_MODE}" in
none) return 0 ;;
use)
# don't download anything while a shell starts up
local NVM_INDEX_NO_FETCH
NVM_INDEX_NO_FETCH=1
local VERSION
local NVM_CURRENT
NVM_CURRENT="$(nvm_ls_current)"
@@ -5954,6 +6088,13 @@ nvm_auto() {
if [ "_${VERSION}" != '_N/A' ] && nvm_is_valid_version "${VERSION}"; then
nvm use --silent "${VERSION}" >/dev/null
else
case "$(nvm_resolve_alias default 2>/dev/null)" in
'--lts '* | --lts=*' '*)
if [ ! -f "$(nvm_lts_status_path)" ]; then
nvm_err 'The default alias needs the LTS status of installed versions, which is not recorded yet; run `nvm ls-remote` to record it.'
fi
;;
esac
return 0
fi
elif nvm_rc_version 3>/dev/null >/dev/null 2>&1; then
@@ -5966,8 +6107,20 @@ nvm_auto() {
install)
local VERSION
VERSION="$(nvm_alias default 2>/dev/null || nvm_echo)"
local NVM_DEFAULT_LTS
NVM_DEFAULT_LTS=''
case "${VERSION}" in
'--lts '* | --lts=*' '*)
NVM_DEFAULT_LTS="${VERSION%% *}"
VERSION="${VERSION#* }"
;;
esac
if [ -n "${VERSION}" ] && [ "_${VERSION}" != '_N/A' ] && nvm_is_valid_version "${VERSION}"; then
nvm install "${VERSION}" >/dev/null
if [ -n "${NVM_DEFAULT_LTS}" ]; then
nvm install "${NVM_DEFAULT_LTS}" "${VERSION}" >/dev/null
else
nvm install "${VERSION}" >/dev/null
fi
elif nvm_rc_version 3>/dev/null >/dev/null 2>&1; then
nvm install >/dev/null
else
+78
View File
@@ -0,0 +1,78 @@
#!/bin/sh
ORIG_NVM_DIR="${NVM_DIR}"
TMP_DIR=''
cleanup () {
case "${TMP_DIR}" in
/*) rm -rf "${TMP_DIR}" ;;
esac
NVM_DIR="${ORIG_NVM_DIR}"
export NVM_DIR
}
die () { echo "$@" ; cleanup ; exit 1; }
: nvm.sh
\. ../../../nvm.sh
\. ../../common.sh
TMP_DIR="$(mktemp -d)"
NVM_DIR="${TMP_DIR}/nvm"
export NVM_DIR
mkdir -p "${NVM_DIR}/alias" || die 'could not create alias dir'
for VERSION in v20.19.0 v22.11.0 v24.0.0 v24.11.0 v26.12.1; do
make_fake_node "${VERSION}" || die "fake node ${VERSION} could not be made"
done
row () {
printf '%s\t2024-01-01\tsrc\t-\t-\t-\t-\t-\t-\t%s\t-\n' "$1" "$2"
}
{ row v26.12.1 -; row v24.11.0 Krypton; row v24.0.0 -; row v22.11.0 Jod; row v20.19.0 Iron; } | nvm_record_lts_status || die 'could not record LTS status'
nvm alias default --lts node >/dev/null 2>&1 || die 'nvm alias default --lts node failed'
[ "_$(cat "$(nvm_alias_path)/default")" = '_--lts node' ] || die "the alias file should store >--lts node<; got >$(cat "$(nvm_alias_path)/default")<"
[ "_$(nvm version default)" = '_v24.11.0' ] || die "default should be the latest installed LTS version; got >$(nvm version default)<"
nvm alias nested default >/dev/null 2>&1 || die 'nvm alias nested default failed'
[ "_$(nvm version nested)" = '_v24.11.0' ] || die "an alias to default should keep its --lts; got >$(nvm version nested)<"
OUTPUT="$(nvm alias --no-colors outer --lts=iron default 2>&1)" || die 'nvm alias outer --lts=iron default failed'
[ "_${OUTPUT}" = '_outer -> --lts=iron default (-> v20.19.0 *)' ] || die "outer flags should replace those of the alias they point at; got >${OUTPUT}<"
[ "_$(nvm version outer)" = '_v20.19.0' ] || die "outer should be the latest installed iron version; got >$(nvm version outer)<"
nvm alias work --lts=jod 22 >/dev/null 2>&1 || die 'nvm alias work --lts=jod 22 failed'
[ "_$(nvm version work)" = '_v22.11.0' ] || die "work should be the latest installed jod version; got >$(nvm version work)<"
nvm alias other --lts=iron 22 >/dev/null 2>&1
[ "_$(nvm version other)" = '_N/A' ] || die "no installed v22 is iron; got >$(nvm version other)<"
OUTPUT="$(nvm unalias work)"
[ "_${OUTPUT}" = '_Deleted alias work - restore it with `nvm alias "work" --lts=jod "22"`' ] || die "the restore hint should keep --lts=jod as its own argument; got >${OUTPUT}<"
try_err nvm alias bad --lts=Krypton node
[ "_${CAPTURED_EXIT_CODE}" = '_3' ] || die "an uppercase LTS name should exit 3; got ${CAPTURED_EXIT_CODE}"
[ ! -e "$(nvm_alias_path)/bad" ] || die 'an alias with an uppercase LTS name should not be written'
try_err nvm alias bad --lts
[ "_${CAPTURED_EXIT_CODE}" = '_55' ] || die "--lts without a target should exit 55; got ${CAPTURED_EXIT_CODE}"
try_err nvm alias bad --lts= node
[ "_${CAPTURED_EXIT_CODE}" = '_55' ] || die "--lts= without an LTS name should exit 55; got ${CAPTURED_EXIT_CODE}"
[ ! -e "$(nvm_alias_path)/bad" ] || die 'an alias with an empty LTS name should not be written'
# a new shell doesn't download index.tab, so explains a default that needs it
rm -f "$(nvm_lts_status_path)"
DOWNLOADS="${TMP_DIR}/downloads"
nvm_download() {
echo "$*" >> "${DOWNLOADS}"
return 1
}
try_err nvm_auto use
[ "_${CAPTURED_STDERR}" = '_The default alias needs the LTS status of installed versions, which is not recorded yet; run `nvm ls-remote` to record it.' ] || die "nvm_auto use should explain the missing LTS status; got >${CAPTURED_STDERR}<"
[ ! -f "${DOWNLOADS}" ] || die "a new shell should not download index.tab; got $(cat "${DOWNLOADS}")"
unset -f nvm_download
echo '--unknown v26.12.1' > "$(nvm_alias_path)/unknown"
[ "_$(nvm version unknown)" = '_N/A' ] || die "an alias with a flag this nvm does not know should not resolve; got >$(nvm version unknown)<"
cleanup
@@ -28,12 +28,14 @@ make_fake_node v20.1.10 || die 'fake node v20.1.10 could not be made'
nvm_make_alias one v20.1.1 || die 'could not alias one'
nvm_make_alias ten v20.1.10 || die 'could not alias ten'
printf 'v20.1.1 # a comment\n' > "$(nvm_alias_path)/commented" || die 'could not alias commented'
nvm_make_alias flagged '--lts v20.1.1' || die 'could not alias flagged'
nvm deactivate >/dev/null 2>&1
nvm uninstall v20.1.1 >/dev/null 2>&1 || die 'nvm uninstall v20.1.1 failed'
! nvm_is_version_installed v20.1.1 || die 'v20.1.1 should be uninstalled'
[ ! -e "$(nvm_alias_path)/one" ] || die 'the alias to v20.1.1 should be removed'
[ ! -e "$(nvm_alias_path)/commented" ] || die 'the alias to v20.1.1 with a comment should be removed'
[ ! -e "$(nvm_alias_path)/flagged" ] || die 'the alias to v20.1.1 with --lts should be removed'
[ "_$(nvm_alias ten)" = '_v20.1.10' ] || die "the alias to v20.1.10 should be kept; got >$(nvm_alias ten 2>&1)<"
cleanup
@@ -51,6 +51,8 @@ recorded () {
(NVM_OFFLINE=1 nvm_ensure_lts_status)
[ $? = 3 ] || die 'nvm_ensure_lts_status should not download while offline'
(NVM_INDEX_NO_FETCH=1 nvm_ensure_lts_status)
[ $? = 3 ] || die 'nvm_ensure_lts_status should not download when told not to, like while a shell starts up'
[ ! -f "${DOWNLOADS}" ] || die "nothing should have been downloaded while offline; got $(cat "${DOWNLOADS}")"
nvm_ensure_lts_status || die 'nvm_ensure_lts_status should download and record LTS status'