diff --git a/docs/cli/use.md b/docs/cli/use.md index 848206495..dce8b5529 100644 --- a/docs/cli/use.md +++ b/docs/cli/use.md @@ -42,7 +42,7 @@ Force reinstall even if already installed Save fuzzy version to config file e.g.: `mise use --fuzzy node@20` will save 20 as the version -this is the default behavior unless `MISE_PIN=1` or `MISE_ASDF_COMPAT=1` +this is the default behavior unless `MISE_PIN=1` ### `-g --global` @@ -50,7 +50,7 @@ Use the global config file (`~/.config/mise/config.toml`) instead of the local o ### `-e --env ` -Modify an environment-specific config file like .mise.<env>.toml +Create/modify an environment-specific config file like .mise.<env>.toml ### `-j --jobs ` @@ -69,13 +69,16 @@ Remove the plugin(s) from config file Specify a path to a config file or directory -If a directory is specified, it will look for `mise.toml` (default) or `.tool-versions` if `MISE_ASDF_COMPAT=1` +If a directory is specified, it will look for a config file in that directory following the rules above. ### `--pin` Save exact version to config file e.g.: `mise use --pin node@20` will save 20.0.0 as the version -Set `MISE_PIN=1` or `MISE_ASDF_COMPAT=1` to make this the default behavior +Set `MISE_PIN=1` to make this the default behavior + +Consider using mise.lock as a better alternative to pinning in mise.toml: + Examples: diff --git a/docs/configuration.md b/docs/configuration.md index 636113abd..89393f5e4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -183,7 +183,6 @@ trusted_config_paths = [ ] verbose = false # set to true to see full installation output, see `MISE_VERBOSE` -asdf_compat = false # set to true to ensure .tool-versions will be compatible with asdf, see `MISE_ASDF_COMPAT` http_timeout = "30s" # set the timeout for http requests as duration string, see `MISE_HTTP_TIMEOUT` jobs = 4 # number of plugins or runtimes to install in parallel. The default is `4`. raw = false # set to true to directly pipe plugins to stdin/stdout/stderr @@ -352,13 +351,6 @@ Uses [dotenvy](https://crates.io/crates/dotenvy) under the hood. Set the version for a runtime. For example, `MISE_NODE_VERSION=20` will use regardless of what is set in `.tool-versions`/`.mise.toml`. -### `MISE_USE_TOML=1` - -Set to `0` to default to using `.tool-versions` in `mise local` instead of `mise.toml` for -configuration. - -This is not used by `mise use` which will only use `mise.toml` unless `--path` is specified. - ### `MISE_TRUSTED_CONFIG_PATHS` This is a list of paths that mise will automatically mark as diff --git a/docs/dev-tools/index.md b/docs/dev-tools/index.md index f33f45fcc..314ea9aee 100644 --- a/docs/dev-tools/index.md +++ b/docs/dev-tools/index.md @@ -103,14 +103,6 @@ There are many ways it can be used: .tool-versions/.mise.toml - `mise install` - install all plugins and tools -### `mise local|global` - -`mise local` and `mise global` are command which only modify the `.tool-versions` or `.mise.toml` -files. -These are hidden from the CLI help and remain for asdf-compatibility. The recommended approach is -to use `mise use` instead because that will do the same thing but also install the tool if it does -not already exists. - ### [`mise exec`|`mise x`](/cli/exec) `mise x` can be used for one-off commands using specific tools. e.g.: if you want to run a script diff --git a/docs/faq.md b/docs/faq.md index 5bc2c6982..b18d85c7f 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -125,18 +125,9 @@ wouldn't want to install a version that is already installed. ## How do I migrate from asdf? -First, just install mise with `mise activate` like in the getting started guide and remove asdf from -your -shell rc file. - -Then you can just run `mise install` in a directory with an asdf `.tool-versions` file and it will -install the runtimes. You could attempt to avoid this by copying the internal directory from asdf -over -to mise with `cp -r ~/.asdf ~/.local/share/mise`. That _should_ work because they use the same -structure, -however this isn't officially supported or regularly tested. Alternatively you can -set `MISE_DATA_DIR=~/.asdf` -and see what happens. +First, just install mise with `mise activate` as described in the [getting started guide](/getting-started) +and remove asdf from your shell rc file. Then run `mise install` in a directory with an asdf `.tool-versions` file +and mise will install the tools. ## How compatible is mise with asdf? @@ -154,11 +145,11 @@ we should attempt to make things as consistent as possible. This isn't important for usability reasons so much as making it so plugins continue to work that call asdf commands. -If you need to switch to/from asdf or work in a project with asdf users, you can set -[`MISE_ASDF_COMPAT=1`](/configuration#mise_asdf_compat1). That prevents -mise from writing `.tool-versions` files that will not be -compatible with asdf. Also consider using `mise.toml` instead which won't conflict with asdf -setups. +Using commands like `mise use` may output `.tool-versions` files that are not compatible with asdf, +such as using fuzzy versions. You can set `MISE_PIN=1` to make it output asdf-compatible versions. +That said, in general compatibility with asdf is no longer a design goal. It's long been the case +that there is no reason to prefer asdf to mise so users should migrate. While plenty of users have +teams which use both in tandem, issues with such a setup are unlikely to be prioritized. ## How do I disable/force CLI color output? diff --git a/mise.usage.kdl b/mise.usage.kdl index cd49f0b76..f8992ff76 100644 --- a/mise.usage.kdl +++ b/mise.usage.kdl @@ -1556,10 +1556,10 @@ Use the `--global` flag to use the global config file instead."# " flag "-f --force" help="Force reinstall even if already installed" flag "--fuzzy" help="Save fuzzy version to config file" { - long_help "Save fuzzy version to config file\n\ne.g.: `mise use --fuzzy node@20` will save 20 as the version\nthis is the default behavior unless `MISE_PIN=1` or `MISE_ASDF_COMPAT=1`" + long_help "Save fuzzy version to config file\n\ne.g.: `mise use --fuzzy node@20` will save 20 as the version\nthis is the default behavior unless `MISE_PIN=1`" } flag "-g --global" help="Use the global config file (`~/.config/mise/config.toml`) instead of the local one" - flag "-e --env" help="Modify an environment-specific config file like .mise..toml" { + flag "-e --env" help="Create/modify an environment-specific config file like .mise..toml" { arg "" } flag "-j --jobs" help="Number of jobs to run in parallel\n[default: 4]" { @@ -1570,10 +1570,12 @@ Use the `--global` flag to use the global config file instead."# arg "" } flag "-p --path" help="Specify a path to a config file or directory" { - long_help "Specify a path to a config file or directory\n\nIf a directory is specified, it will look for `mise.toml` (default) or `.tool-versions` if `MISE_ASDF_COMPAT=1`" + long_help "Specify a path to a config file or directory\n\nIf a directory is specified, it will look for a config file in that directory following the rules above." arg "" } - flag "--pin" help="Save exact version to config file\ne.g.: `mise use --pin node@20` will save 20.0.0 as the version\nSet `MISE_PIN=1` or `MISE_ASDF_COMPAT=1` to make this the default behavior" + flag "--pin" help="Save exact version to config file\ne.g.: `mise use --pin node@20` will save 20.0.0 as the version\nSet `MISE_PIN=1` to make this the default behavior" { + long_help "Save exact version to config file\ne.g.: `mise use --pin node@20` will save 20.0.0 as the version\nSet `MISE_PIN=1` to make this the default behavior\n\nConsider using mise.lock as a better alternative to pinning in mise.toml:\nhttps://mise.jdx.dev/configuration/settings.html#lockfile" + } arg "[TOOL@VERSION]..." help="Tool(s) to add to config file" help_long="Tool(s) to add to config file\n\ne.g.: node@20, cargo:ripgrep@latest npm:prettier@3\nIf no version is specified, it will default to @latest\n\nTool options can be set with this syntax:\n\n mise use ubi:BurntSushi/ripgrep[exe=rg]" var=true } cmd "version" help="Display the version of mise" { diff --git a/settings.toml b/settings.toml index 677dcfd90..7b2a6a172 100644 --- a/settings.toml +++ b/settings.toml @@ -96,6 +96,7 @@ default to using an asdf plugin for cmake. [asdf_compat] env = "MISE_ASDF_COMPAT" type = "Bool" +hide = true description = "set to true to ensure .tool-versions will be compatible with asdf" docs = """ Only output `.tool-versions` files in `mise local|global` which will be usable by asdf. diff --git a/src/cli/local.rs b/src/cli/local.rs index ac8692dd7..e4827efd1 100644 --- a/src/cli/local.rs +++ b/src/cli/local.rs @@ -102,6 +102,10 @@ pub fn local( fuzzy: bool, show_path: bool, ) -> Result<()> { + deprecated!( + "local", + "mise local/global are deprecated. Use `mise use` instead." + ); let settings = Settings::try_get()?; let mut cf = config_file::parse_or_init(path)?; if show_path { diff --git a/src/cli/use.rs b/src/cli/use.rs index b987b008b..6ea13e29f 100644 --- a/src/cli/use.rs +++ b/src/cli/use.rs @@ -55,7 +55,7 @@ pub struct Use { /// Save fuzzy version to config file /// /// e.g.: `mise use --fuzzy node@20` will save 20 as the version - /// this is the default behavior unless `MISE_PIN=1` or `MISE_ASDF_COMPAT=1` + /// this is the default behavior unless `MISE_PIN=1` #[clap(long, verbatim_doc_comment, overrides_with = "pin")] fuzzy: bool, @@ -63,7 +63,7 @@ pub struct Use { #[clap(short, long, overrides_with_all = & ["path", "env"])] global: bool, - /// Modify an environment-specific config file like .mise..toml + /// Create/modify an environment-specific config file like .mise..toml #[clap(long, short, overrides_with_all = & ["global", "path"])] env: Option, @@ -83,15 +83,17 @@ pub struct Use { /// Specify a path to a config file or directory /// - /// If a directory is specified, it will look for `mise.toml` (default) or `.tool-versions` if - /// `MISE_ASDF_COMPAT=1` - #[clap(short, long, overrides_with_all = & ["global", "env"], value_hint = clap::ValueHint::FilePath - )] + /// If a directory is specified, it will look for a config file in that directory following + /// the rules above. + #[clap(short, long, overrides_with_all = & ["global", "env"], value_hint = clap::ValueHint::FilePath)] path: Option, /// Save exact version to config file /// e.g.: `mise use --pin node@20` will save 20.0.0 as the version - /// Set `MISE_PIN=1` or `MISE_ASDF_COMPAT=1` to make this the default behavior + /// Set `MISE_PIN=1` to make this the default behavior + /// + /// Consider using mise.lock as a better alternative to pinning in mise.toml: + /// https://mise.jdx.dev/configuration/settings.html#lockfile #[clap(long, verbatim_doc_comment, overrides_with = "fuzzy")] pin: bool, } diff --git a/xtasks/fig/src/mise.ts b/xtasks/fig/src/mise.ts index 1f88ce8b6..214400527 100644 --- a/xtasks/fig/src/mise.ts +++ b/xtasks/fig/src/mise.ts @@ -2931,7 +2931,7 @@ const completionSpec: Fig.Spec = { "-e", "--env" ], - "description": "Modify an environment-specific config file like .mise..toml", + "description": "Create/modify an environment-specific config file like .mise..toml", "isRepeatable": false, "args": { "name": "env", @@ -2990,7 +2990,7 @@ const completionSpec: Fig.Spec = { "name": [ "--pin" ], - "description": "Save exact version to config file\ne.g.: `mise use --pin node@20` will save 20.0.0 as the version\nSet `MISE_PIN=1` or `MISE_ASDF_COMPAT=1` to make this the default behavior", + "description": "Save exact version to config file\ne.g.: `mise use --pin node@20` will save 20.0.0 as the version\nSet `MISE_PIN=1` to make this the default behavior", "isRepeatable": false } ],