Nushell Version Management
Relevant source files
The following files were used as context for generating this wiki page:
Nushell Version Management is a core system within Numan that provides side-by-side installation, discovery, and activation of managed Nushell binaries. This system allows users to pin specific versions of Nushell to ensure compatibility with various plugins and modules, addressing the problem of "drift" where a global Nushell upgrade might break existing package integrations.
The architecture centers around a versioned file layout under the Numan root, an "active-version" marker for selection state, and a bootstrap mechanism that fetches official releases directly from GitHub. It supports both "on-tree" managed versions (installed within Numan's tools directory) and "off-tree" selections (user-provided binaries registered with Numan).
Sources: README.md:14-30, AGENTS.md:130-150, CHANGELOG.md:15-30
Versioned Layout and Storage
Numan utilizes a structured filesystem layout to manage multiple Nushell versions simultaneously. Every managed version is stored in its own content-addressed directory to prevent clobbering existing installations.
On-Tree Directory Structure
Managed binaries are stored under the tools/nushell/ directory within the Numan root.
- Versioned Path:
<root>/tools/nushell/<version>/ - Binary Location:
<root>/tools/nushell/<version>/nu(ornu.exeon Windows) - Version Marker: A
VERSIONfile is stored alongside the binary for metadata compatibility.
Sources: src/nu/bootstrap.rs:163-185, CHANGELOG.md:32-38
Active Version State
The selection of which Nushell version is currently "active" for Numan's operations is governed by a state file:
- Path:
<root>/nu_state/active-version.json - Schema: A JSON object containing the version string and an optional
binary_pathfor off-tree binaries.
Sources: AGENTS.md:144-150, CHANGELOG.md:21-25
The diagram above illustrates the relationship between the versioned tool storage and the active state marker.
Sources: src/nu/bootstrap.rs:43-50, src/nu/version_manager.rs
Bootstrapping and Installation
The bootstrap module handles the retrieval and deployment of official Nushell releases. It queries the GitHub Releases API to find assets matching the user's platform triple (OS, Architecture, and Crate Environment).
Platform Support
Numan resolves artifacts based on a compile-time triple rather than runtime environment variables. Supported archive formats include .zip, .tar.gz, and .tar.xz.
| OS | Architecture | Suffix |
|---|---|---|
| Windows | X86_64 / Aarch64 | -pc-windows-msvc.zip |
| Linux | X86_64 / Aarch64 | -unknown-linux-gnu.tar.gz |
| Linux (Musl) | X86_64 / Aarch64 | -unknown-linux-musl.tar.gz |
| macOS | X86_64 / Aarch64 | -apple-darwin.tar.gz |
Sources: src/nu/bootstrap.rs:58-85, AGENTS.md:175-180
Installation Workflow
- Release Discovery: Queries GitHub for
latestor a specific tag. - Asset Selection: Matches the platform triple to the asset list.
- Verification: Downloads the archive and verifies the SHA256 checksum and file size.
- Extraction: Unpacks the archive into a temporary
.nushell-extractdirectory. - Deployment: Moves the binary to the versioned directory and sets executable permissions (on Unix).
- State Update: Writes the
active-version.jsonmarker.
Sources: src/nu/bootstrap.rs:151-240
Version Selection and "Use" Command
The numan use command allows users to switch between previously installed managed versions. Unlike setup nu, this command is intended to be a local state mutation that does not trigger network downloads.
Selection Logic
The use_cmd module executes the following flow:
- Mutation Lock: Acquires the advisory
MutationLockto prevent concurrent writes. - Snapshot: Creates a
PreMutationsnapshot of the Numan root for rollback safety. - Resolution: Validates if the requested version (or
latest) exists on-disk. - Marker Update: Atomic write to
active-version.json.
Sources: src/cmd/use_cmd.rs, CHANGELOG.md:18-30
Function Overview in version_manager.rs
| Function | Purpose |
|---|---|
list_installed_versions | Scans the tools directory for valid semver directories. |
latest_installed_version | Returns the highest semver version found on-tree. |
active_nu_binary | Resolves the absolute path to the binary defined in the active marker. |
write_active_version | Atomics updates to the active version state file. |
Sources: src/nu/version_manager.rs
Process Integration and PATH Management
For Nushell version management to be effective, Numan ensures the managed binary is discoverable by the user's shell and the Numan process itself.
PATH Persistence
Numan can persistently add managed binary directories to the user's PATH:
- Windows: Updates the User environment variables via a PowerShell script.
- Unix: Appends an export line to
.zshrc,.bashrc, or.profile. - Local Bin (Unix): Creates a symlink in
~/.local/bin/nu.
Sources: src/nu/bootstrap.rs:400-500
The sequence illustrates the journaled and locked transition between Nushell versions.
Sources: src/cmd/use_cmd.rs, AGENTS.md:140-150
Summary
Nushell Version Management in Numan provides a robust, fail-safe mechanism for handling multiple Nu installations. By isolating binaries into versioned directories and utilizing atomic JSON writes for state management, Numan ensures that environment changes are reproducible and reversible. The system’s integration with snapshots and advisory locking provides the "production-grade" reliability required for managing shell environments across Linux, macOS, and Windows.
Sources: README.md:130-145, AGENTS.md:10-25