Skip to content

docs(lockfile): update documentation for recent lockfile changes #7107

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jdx merged 1 commit into from
Nov 28, 2025
Merged

docs(lockfile): update documentation for recent lockfile changes #7107

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 84 additions & 20 deletions docs/dev-tools/mise-lock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ lockfile = true

```toml
# Example mise.lock
[tools.node]
[[tools.node]]
version = "20.11.0"
backend = "core:node"

Expand All @@ -45,21 +45,28 @@ checksum = "sha256:a6c213b7a2c3b8b9c0aaf8d7f5b3a5c8d4e2f4a5b6c7d8e9f0a1b2c3d4e5f
size = 23456789
url = "https://nodejs.org/dist/v20.11.0/node-v20.11.0-linux-x64.tar.xz"

[tools.python]
[[tools.python]]
version = "3.11.7"
backend = "core:python"

[tools.python.platforms.linux-x64]
checksum = "sha256:def456..."
size = 12345678

[tools.ripgrep]
# Tool with backend-specific options
[[tools.ripgrep]]
version = "14.1.1"
backend = "aqua:BurntSushi/ripgrep"
options = { exe = "rg" }

[tools.ripgrep.platforms.linux-x64]
checksum = "sha256:4cf9f2741e6c465ffdb7c26f38056a59e2a2544b51f7cc128ef28337eeae4d8e"
size = 1234567

# Environment-specific version (only used when MISE_ENV=test)
[[tools.tiny]]
version = "2.1.0"
env = ["test"]
```

### Platform Information
Expand All @@ -70,6 +77,16 @@ Each platform in a tool's `[tools.name.platforms]` section uses a key format lik
- **`size`** (optional): File size in bytes for download validation
- **`url`** (optional): Original download URL for reference or re-downloading

### Tool Entry Fields

Each tool entry (`[[tools.name]]`) can contain:

- **`version`** (required): The exact version of the tool
- **`backend`** (optional): The backend used to install the tool (e.g., `core:node`, `aqua:BurntSushi/ripgrep`)
- **`options`** (optional): Backend-specific options that identify the artifact (e.g., `{exe = "rg", matching = "musl"}`)
- **`env`** (optional): List of environment names this version applies to (e.g., `["test", "staging"]`)
- **`platforms`** (optional): Platform-specific metadata (checksums, URLs, sizes)

### Platform Keys

The platform key format is generally `os-arch` but can be customized by backends:
Expand All @@ -78,9 +95,71 @@ The platform key format is generally `os-arch` but can be customized by backends
- **Backend-specific**: Some backends like Java may use more specific platform identifiers
- **Tool-specific**: Backends like `ubi` may include additional tool-specific information in the platform key

### Legacy Format Migration
## Environment-Specific Versions

When using [environment-specific configuration files](/configuration/environments) (e.g., `mise.test.toml`), tools from those files are tagged with an `env` field in the lockfile:

```toml
# mise.test.toml
[tools]
tiny = "2"
```

When you run `MISE_ENV=test mise use tiny@2`, the lockfile will include:
Copy link

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The command example mise use tiny@2 doesn't match the context. Based on the example at line 105 showing tiny = "2" in mise.test.toml, the command should be mise use tiny@2 --env test or the description should clarify that the tool is being added to the test environment config file.

Suggested change
When you run `MISE_ENV=test mise use tiny@2`, the lockfile will include:
When you run `mise use tiny@2 --env test`, the lockfile will include:

Copilot uses AI. Check for mistakes.

```toml
[[tools.tiny]]
version = "2.1.0"
env = ["test"]
```

**Resolution priority**: When resolving versions, mise checks in order:

1. Entry with matching `env` for the current `MISE_ENV`
2. Base entry (no `env` field)
3. First available entry

This allows different environments to use different tool versions while sharing the same lockfile.

## Local Lockfiles

Tools defined in `mise.local.toml` (which is typically gitignored) use a separate `mise.local.lock` file. This keeps local tool configurations separate from the committed lockfile.

```sh
# mise.local.toml tools go to mise.local.lock
mise use --path mise.local.toml node@22

# Regular mise.toml tools go to mise.lock
mise use --path mise.toml node@20
```

Use `mise lock --local` to update the local lockfile for all platforms:

```sh
mise lock --local # update mise.local.lock
mise lock --local node python # update specific tools in mise.local.lock
```

## Strict Lockfile Mode

Older lockfiles with separate `[tools.name.assets]` and `[tools.name.checksums]` sections are automatically migrated to the new platform-based `[tools.name.platforms]` format when read. The migration is seamless and maintains all existing functionality.
The `locked` setting enforces that all tools have pre-resolved URLs in the lockfile before installation. This prevents API calls to GitHub, aqua registry, etc., ensuring fully reproducible installations.

```sh
# Enable strict mode
mise settings locked=true

# Or via environment variable
MISE_LOCKED=1 mise install
```

When enabled, `mise install` will fail if a tool doesn't have a URL for the current platform in the lockfile. To fix this, first populate the lockfile with URLs:

```sh
mise lock # generate URLs for all platforms
mise lock --platform linux-x64,macos-arm64 # or specific platforms
```

This is useful for CI environments where you want to guarantee reproducible builds without any external API dependencies.

## Workflow

Expand Down Expand Up @@ -213,21 +292,6 @@ mise settings experimental=true
mise settings lockfile=true
```

## Benefits of the New Format

The platform-based format provides several advantages:

1. **Organized Structure**: Platform information is logically grouped by operating system and architecture
2. **Cross-platform Support**: Each tool can have different assets for different platforms in the same lockfile
3. **Reduced Duplication**: Platform-specific checksums and sizes are consolidated per platform
4. **Extended Metadata**: Support for file sizes and download URLs per platform
5. **Better Maintainability**: Clear separation of tool versions and their platform-specific assets
6. **Easier Navigation**: Platform-specific assets are easier to locate and manage by os-arch keys
7. **Full Traceability**: URLs provide complete audit trail of asset sources per platform
8. **Enhanced Security**: Better compliance and security auditing capabilities across platforms
9. **Avoids Rate Limits**: By storing URLs, future installs do not need to make API calls to GitHub or other providers, reducing the risk of hitting rate limits and removing the need for `GITHUB_TOKEN` in simple workflows
10. **Backend Flexibility**: Backends can customize platform keys for tool-specific requirements (e.g., Java's detailed platform specifications)

## See Also

- [Configuration Settings](/configuration/settings) - All available settings
Expand Down
Loading