[Marukome0743]

Summary

• prefer an exact available release when mise use pinning would otherwise reuse a more-specific installed fuzzy match
• preserve normal fuzzy resolution, explicit prefix: selectors, exact installed fast paths, lockfile precedence, and offline behavior
• clarify that --pin saves the resolved concrete version rather than changing every request into an exact selector

Problem

mise use --pin erlang@27.3 could reuse an installed 27.3.4.10 before checking whether the exact 27.3 release existed remotely. The result therefore depended on which matching versions were already installed.

The resolver now receives an exact-release preference only from effective mise use pinning (--pin, MISE_PIN=1, or asdf compatibility, unless overridden by --fuzzy). It keeps an already installed exact match network-free, otherwise checks for an exact release before accepting an installed fuzzy match. Online lookup failures are returned instead of silently pinning the wrong version; explicit offline mode keeps local resolution.

Addresses #4889

Verification

• mise run test:e2e e2e/cli/test_use_pin_exact
• mise exec -- cargo test --all-features toolset::tool_version (37 passed)
• mise exec -- cargo check --all-features
• mise exec -- cargo clippy --workspace --all-features --all-targets -- -D warnings
• mise exec -- cargo fmt --all -- --check
• mise exec -- shfmt -d e2e/cli/test_use_pin_exact
• mise exec -- shellcheck e2e/cli/test_use_pin_exact
• mise run render:usage
• isolated macOS dry-run with installed erlang@27.3.4.10: selected erlang@27.3 and would save 27.3

mise run format and mise run lint cannot run their hk wrapper in this Sapling working copy because hk reports failed to find git repository; the underlying Rustfmt, shfmt, ShellCheck, Clippy, and Markdownlint checks were run individually. The existing broader test_use currently reaches an unrelated network-dependent ubi installation and failed with GitHub HTTP 401; all new offline regression cases pass in the dedicated E2E.

AI-assisted — Tool: Codex; model: OpenAI/GPT-5; version: unavailable.

Summary by CodeRabbit

• New Features

  • mise use --pin now saves the resolved concrete tool version to the configuration.
  • Exact version requests prefer matching available releases over fuzzy installed versions.
  • Use the prefix: syntax for recursive prefix matching.
  • Version resolution provides more predictable exact-release selection, including offline scenarios.

• Documentation

  • Updated CLI help, manual pages, and usage documentation with revised pinning behavior and examples.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 5a61bab5-0fad-45d0-8ecf-de84c1a000f0

📥 Commits

Reviewing files that changed from the base of the PR and between 248b9e7 and eca815b.

📒 Files selected for processing (4)

• e2e/cli/test_use_pin_exact
• man/man1/mise.1
• mise.usage.kdl
• src/toolset/tool_version.rs

🚧 Files skipped from review as they are similar to previous changes (3)

• man/man1/mise.1
• mise.usage.kdl
• src/toolset/tool_version.rs

---

📝 Walkthrough

Walkthrough

The resolver now supports exact remote release preference for mise use --pin. Pinning saves the resolved concrete version, while install and upgrade flows retain fuzzy resolution. End-to-end tests cover remote, installed, fuzzy, prefix, offline, and error cases.

Changes

Exact pin resolution

Layer / File(s)	Summary
Resolver preference and fallback src/toolset/tool_version.rs	ResolveOptions adds prefer_exact_version. The resolver checks exact remote releases before fuzzy installed matches and reuses remote results when available.
CLI resolution wiring src/cli/use.rs, src/cli/install.rs, src/cli/upgrade.rs	mise use --pin enables exact-version preference. Install and upgrade paths explicitly disable it.
Pin behavior and documentation e2e/cli/test_use_pin_exact, docs/cli/use.md, man/man1/mise.1, mise.usage.kdl	Tests cover pinning modes and lookup failures. CLI documentation describes concrete-version resolution and explicit prefix: matching.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant UseCommand
  participant VersionResolver
  participant RemoteBackend
  User->>UseCommand: use tool with --pin
  UseCommand->>VersionResolver: resolve with exact preference
  VersionResolver->>RemoteBackend: validate exact release
  RemoteBackend-->>VersionResolver: return available release or lookup error
  VersionResolver-->>UseCommand: return resolved concrete version
  UseCommand-->>User: write pinned configuration

Loading

Possibly related PRs

• jdx/mise#11145: Both PRs modify version-selector resolution through shared resolve options.
• jdx/mise#11255: Both PRs modify src/toolset/tool_version.rs and ToolVersion::resolve_version for specialized version selectors.

Poem

A rabbit pins the release just right,
Exact versions hop into sight.
Fuzzy matches still remain,
Offline paths keep local gain.
Concrete config now takes flight.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preferring exact releases when pinning with mise use.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR updates effective mise use pinning to verify exact release availability before reusing an installed fuzzy match, while preserving fuzzy, prefix, lockfile, and offline behavior.

• Adds an exact-release preference to resolution options used by effective pinning.
• Uses remote version enumeration to distinguish available exact releases from syntax-only exact selectors.
• Adds focused end-to-end coverage and updates generated CLI documentation.

Confidence Score: 5/5

The PR appears safe to merge.

The previously reported syntax-validation bypass is fixed because pinning now verifies the requested literal against remotely enumerated releases before accepting it, and no blocking failure remains.

Important Files Changed

Filename	Overview
src/toolset/tool_version.rs	The resolver now verifies exact release existence through backend version enumeration before accepting the literal; the previously reported syntax-validation bypass is no longer reachable.
src/cli/use.rs	Effective pinning is computed before resolution and correctly enables the new exact-release preference while allowing --fuzzy to override settings-based pinning.
e2e/cli/test_use_pin_exact	Adds coverage for exact availability, absent releases, settings-based pinning, fuzzy overrides, offline behavior, lookup failures, and syntax-only backend resolvers.
mise.usage.kdl	Clarifies that pinning saves the resolved concrete version and documents explicit prefix matching.
docs/cli/use.md	Regenerates user-facing documentation for the revised pinning semantics.

_{Reviews (4): Last reviewed commit: "fix(use): prefer exact releases when pin..." | Re-trigger Greptile}

[github-actions]

This PR currently has failing checks. If this continues for 7 days, it will be closed automatically.

This is warning day 1 of 7.

Please update the PR when you have a chance. Feel free to reopen or create a new PR if it is closed and you'd like to continue working on it.

This comment was generated by an automated workflow.