fix: deprecate mise local|global (#3350)

It has long been the case that these commands lack functionality that `mise use` provides and they have been hidden for over a year. They exist just for users coming from asdf but have been discouraged since almost the beginning of rtx.

docs/cli/use.md

@@ -42,15 +42,15 @@ 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`
 
 Use the global config file (`~/.config/mise/config.toml`) instead of the local one
 
 ### `-e --env <ENV>`
 
-Modify an environment-specific config file like .mise.&lt;env>.toml
+Create/modify an environment-specific config file like .mise.&lt;env>.toml
 
 ### `-j --jobs <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:
+<https://mise.jdx.dev/configuration/settings.html#lockfile>
 
 Examples:
 

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 <node@20.x> 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

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` <Badge type="danger" text="not recommended" />
-
-`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

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?
 

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.<env>.toml" {
+    flag "-e --env" help="Create/modify an environment-specific config file like .mise.<env>.toml" {
         arg "<ENV>"
     }
     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 "<PLUGIN>"
     }
     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 "<PATH>"
     }
-    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" {

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.

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 {

src/cli/use.rs

@@ -55,15 +55,15 @@ 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,
 
     /// Use the global config file (`~/.config/mise/config.toml`) instead of the local one
     #[clap(short, long, overrides_with_all = & ["path", "env"])]
     global: bool,
 
-    /// Modify an environment-specific config file like .mise.<env>.toml
+    /// Create/modify an environment-specific config file like .mise.<env>.toml
     #[clap(long, short, overrides_with_all = & ["global", "path"])]
     env: Option<String>,
 
@@ -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<PathBuf>,
 
     /// 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,
 }

xtasks/fig/src/mise.ts

@@ -2931,7 +2931,7 @@ const completionSpec: Fig.Spec = {
                         "-e",
                         "--env"
                     ],
-                    "description": "Modify an environment-specific config file like .mise.<env>.toml",
+                    "description": "Create/modify an environment-specific config file like .mise.<env>.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
                 }
             ],