docs: clarify common sources of confusion from GitHub discussions by jdx · Pull Request #8927 · jdx/mise

jdx · 2026-04-05T18:14:01Z

Summary

Fixes several documentation gaps identified from recent GitHub discussions where users were confused:

Task timeout precedence (Confusing task `timeout` precedence #8858): Clarify that the shorter of global task.timeout and per-task timeout always wins — a per-task timeout cannot extend the global one
confirm vs depends order (Run task's `confirm` before `depends` #8907): Document that confirm only guards the task's own run command; dependencies execute before the prompt appears
Shell aliases not available in tasks (Can't access `shell_alias` commands inside of TOML tasks #8461): Add a "Limitations" section noting that [shell_alias] entries are only active in interactive shells, not in task run blocks
locked setting is global (warnings for global tools on every mise call when locked=true #8663): Add warning that locked = true in a project's mise.toml applies to all tool resolution including global config tools
PATH overwritten after mise activate (path broken after cd into directory #7043): Add FAQ warning that custom PATH modifications after mise activate get overwritten by hook-env on prompt refresh
Install script auto-adds activate (Mise install adds activate to bashrc, whether you want it or not. #8870): Note that curl mise.run | sh automatically adds mise activate to the shell rc file

Test plan

Verify docs build successfully with mise run docs:build
Review rendered docs for each changed page

🤖 Generated with Claude Code

Note

Low Risk
Docs-only clarifications plus minor schema/settings description updates; no runtime behavior changes, so risk is low and limited to potential documentation accuracy/regeneration impacts.

Overview
Clarifies several commonly confusing behaviors in the docs: strict lockfile mode (locked) being global-scope (and how to generate a global lockfile), shell alias availability limits (interactive shells only, not tasks), and the order/coverage of task confirm vs depends.

Adds a shell feature compatibility matrix to getting-started, and expands task.timeout documentation (and schema/setting descriptions) to state that the effective timeout is the minimum of global and per-task values, with --timeout overriding the global default.

^{Reviewed by Cursor Bugbot for commit 58c94d0. Bugbot is set up for automated code reviews on this repo. Configure here.}

- task timeout precedence: shorter of global/per-task wins (#8858) - confirm runs after depends, not before (#8907) - shell aliases not available in task run blocks (#8461) - locked setting is global, affects global config tools (#8663) - PATH modifications after mise activate get overwritten (#7043) - install script auto-adds activate to shell rc (#8870) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

gemini-code-assist

Code Review

This pull request enhances the documentation by adding warnings and tips regarding lockfile settings, shell activation, PATH management, and task configurations. Specifically, it clarifies how the locked setting affects tool resolution, warns about PATH overwrites by hook-env, and explains the limitations of shell aliases and the confirm task property. Additionally, it provides detailed documentation on task timeout precedence in settings.toml. A review comment correctly identifies a technical inaccuracy regarding the scope of mise settings and provides a suggestion for more precise wording.

gemini-code-assist · 2026-04-05T18:15:44Z

 ```

+::: warning
+All mise settings are global in scope. Setting `locked = true` in a project's `mise.toml` applies to **all** tool resolution, including tools from your global `~/.config/mise/config.toml`. If you see warnings about global tools missing from the lockfile, run `mise lock -g` to generate a global lockfile, or pin global tools to specific versions.


The statement "All mise settings are global in scope" is technically inaccurate and potentially confusing. Mise settings are hierarchical; settings defined in a project's mise.toml are scoped to that project and its subdirectories. The intended point is that the locked setting, once resolved, affects all tool resolution in the current context (including tools inherited from the global configuration). Rephrasing this to focus on the context-wide impact would be more precise.

Suggested change

All mise settings are global in scope. Setting `locked = true` in a project's `mise.toml` applies to **all** tool resolution, including tools from your global `~/.config/mise/config.toml`. If you see warnings about global tools missing from the lockfile, run `mise lock -g` to generate a global lockfile, or pin global tools to specific versions.

Setting locked = true in a project's mise.toml applies to all tool resolution in that context, including tools inherited from your global ~/.config/mise/config.toml. If you see warnings about global tools missing from the lockfile, run mise lock -g to generate a global lockfile, or pin global tools to specific versions.

greptile-apps · 2026-04-05T18:18:44Z

Greptile Summary

This documentation-only PR clarifies several sources of user confusion identified from GitHub discussions: task confirm vs depends execution order, locked = true global scope, shell alias limitations, and the task.timeout global default behavior.

docs/getting-started.md: Adds a "Shell Feature Compatibility" matrix — but xonsh is incorrectly marked Yes for shell aliases; only bash, zsh, and fish implement set_alias/unset_alias in the source
docs/shell-aliases.md: Adds a Limitations section with the same xonsh error, contradicting the existing "Supported Shells" section in the same file
docs/tasks/task-configuration.md: Correctly documents that confirm only guards the task's own run block; dependencies run before the prompt appears
docs/dev-tools/mise-lock.md: Adds a useful warning that locked = true is global in scope and may affect global config tools
settings.toml / schema/mise.json: Expands task.timeout description; note that the "shorter wins" claim for global vs per-task timeout was flagged as potentially inaccurate in a prior review thread (the global timeout wraps the entire run, not individual tasks)

Confidence Score: 4/5

Safe to merge after correcting the xonsh shell alias support claims in two files

Two P1 factual errors introduced: xonsh is listed as supporting shell aliases in both the new compatibility table (getting-started.md:234) and the new Limitations bullet (shell-aliases.md:108), but the source code (src/shell/xonsh.rs has no set_alias override) and the pre-existing Supported Shells section both confirm xonsh is not supported. All other documentation changes are accurate and helpful, so this scores 4 rather than lower.

docs/getting-started.md (line 234) and docs/shell-aliases.md (line 108) both incorrectly claim xonsh supports shell aliases

Important Files Changed

Filename	Overview
docs/getting-started.md	Adds shell feature compatibility matrix; xonsh incorrectly listed as supporting shell aliases (source: only bash/zsh/fish implement set_alias)
docs/shell-aliases.md	Adds Limitations section; xonsh incorrectly included as a supported shell, contradicting the existing Supported Shells section and source code
docs/tasks/task-configuration.md	Clarifies that confirm only guards the task's own run block; dependencies execute before the confirmation prompt — accurate per task_executor.rs
docs/dev-tools/mise-lock.md	Adds warning clarifying that locked=true in a project config applies globally to all tool resolution
schema/mise.json	Simplifies task.timeout description by removing the override clause
settings.toml	Expands task.timeout docs with 'shorter wins' semantics; accuracy of global vs per-task interaction was questioned in a prior thread

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[mise run task] --> B{Has depends?}
    B -- Yes --> C[Execute dependency tasks]
    C --> D{Has confirm?}
    B -- No --> D
    D -- Yes --> E[Show confirmation prompt]
    E -- Confirmed --> F[Execute task's own run block]
    E -- Rejected --> G[Abort]
    D -- No --> F

_{Reviews (4): Last reviewed commit: "docs: remove mise deactivate from shell ..." | Re-trigger Greptile}

- Remove false claim about PATH being overwritten after mise activate - Remove false claim about install script auto-adding activate - Remove "pin global tools" suggestion for locked setting - Fix markdown lint (consecutive blank lines) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Shows which features (activate, shell, deactivate, aliases, chpwd) are supported in each shell (bash, zsh, fish, nushell, elvish, xonsh, powershell). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

It's part of mise activate, not a separate feature. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-04-05T19:06:08Z

Hyperfine Performance

`mise x -- echo`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2026.4.4 x -- echo`	23.5 ± 1.3	21.6	35.4	1.01 ± 0.07
`mise x -- echo`	23.2 ± 0.9	21.9	25.4	1.00

`mise env`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2026.4.4 env`	22.2 ± 0.8	21.1	28.2	1.00
`mise env`	22.4 ± 0.7	21.6	32.8	1.01 ± 0.05

`mise hook-env`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2026.4.4 hook-env`	22.8 ± 0.5	21.9	24.7	1.00
`mise hook-env`	23.5 ± 0.8	22.4	31.8	1.03 ± 0.04

`mise ls`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2026.4.4 ls`	19.8 ± 0.3	19.1	21.4	1.00
`mise ls`	20.2 ± 0.3	19.5	23.0	1.02 ± 0.02

`xtasks/test/perf`

Command	mise-2026.4.4	mise	Variance
install (cached)	150ms	149ms	+0%
ls (cached)	79ms	78ms	+1%
bin-paths (cached)	83ms	82ms	+1%
task-ls (cached)	803ms	800ms	+0%

@SamSoldatenko

### 🚀 Features - **(config)** report env files in config ls and doctor output by @SamSoldatenko in [#8853](#8853) - add support for token sources in GitLab and Forgejo by @roele in [#8868](#8868) ### 🐛 Bug Fixes - **(aqua)** prevent double .exe extension when Windows override URL already ends in .exe by @yusei-wy in [#8863](#8863) - **(bash)** avoid duplicate trust warning after cd by @timothysparg in [#8920](#8920) - **(env)** prevent config root injection into PATH via _.source by @jdx in [#8936](#8936) - **(install)** suppress spurious dependency warning when tool is configured by @jdx in [#8923](#8923) ### 📚 Documentation - **(node)** add section on pinning npm version by @jdx in [#8925](#8925) - add Windows default paths and mise.toml examples alongside CLI commands by @jdx in [#8926](#8926) - clarify common sources of confusion from GitHub discussions by @jdx in [#8927](#8927) - clarify Python venv mechanisms, JAVA_HOME behavior, and activation performance by @jdx in [#8928](#8928) - add FAQ and troubleshooting entries based on common Discord questions by @jdx in [#8930](#8930) ### New Contributors - @SamSoldatenko made their first contribution in [#8853](#8853) - @yusei-wy made their first contribution in [#8863](#8863)

gemini-code-assist Bot reviewed Apr 5, 2026

View reviewed changes

[autofix.ci] apply automated fixes

f6f517a

greptile-apps Bot reviewed Apr 5, 2026

View reviewed changes

Comment thread settings.toml

Comment thread docs/shell-aliases.md Outdated

jdx and others added 4 commits April 5, 2026 18:19

docs: add shell feature compatibility matrix

849d13e

Shows which features (activate, shell, deactivate, aliases, chpwd) are supported in each shell (bash, zsh, fish, nushell, elvish, xonsh, powershell). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: move shell feature matrix to getting-started page

cc5c0d5

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: remove mise deactivate from shell feature matrix

58c94d0

It's part of mise activate, not a separate feature. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

jdx enabled auto-merge (squash) April 5, 2026 18:47

jdx merged commit 7324ba8 into main Apr 5, 2026
37 checks passed

jdx deleted the docs/fix-common-issues branch April 5, 2026 19:04

mise-en-dev mentioned this pull request Apr 5, 2026

chore: release 2026.4.5 #8921

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: clarify common sources of confusion from GitHub discussions#8927

docs: clarify common sources of confusion from GitHub discussions#8927
jdx merged 6 commits intomainfrom
docs/fix-common-issues

jdx commented Apr 5, 2026 •

edited by cursor Bot

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Apr 5, 2026

Uh oh!

greptile-apps Bot commented Apr 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	All mise settings are global in scope. Setting `locked = true` in a project's `mise.toml` applies to all tool resolution, including tools from your global `~/.config/mise/config.toml`. If you see warnings about global tools missing from the lockfile, run `mise lock -g` to generate a global lockfile, or pin global tools to specific versions.
	Setting locked = true in a project's mise.toml applies to all tool resolution in that context, including tools inherited from your global ~/.config/mise/config.toml. If you see warnings about global tools missing from the lockfile, run mise lock -g to generate a global lockfile, or pin global tools to specific versions.

Uh oh!

Conversation

jdx commented Apr 5, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Flowchart

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 5, 2026

Hyperfine Performance

mise x -- echo

mise env

mise hook-env

mise ls

xtasks/test/perf

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jdx commented Apr 5, 2026 •

edited by cursor Bot

Loading

greptile-apps Bot commented Apr 5, 2026 •

edited

Loading

`mise x -- echo`

`mise env`

`mise hook-env`

`mise ls`

`xtasks/test/perf`