define/correct logic around .tool-versions/.mise.toml with mise use|global|local

[jdx]

This logic is in a bit of disarray and fairly complicated. This task is a bit of a placeholder to first figure out what exactly mise is doing around these files and then make any corrections necessary.

However in general this is what I think should happen (I think roughly 50% of this is current behavior):

• MISE_USE_TOML=1 means use .mise.toml always for writing
• MISE_USE_TOML=0 means always use .tool-versions for writing
• MISE_DEFAULT_TOOL_VERSIONS_FILENAME can be used to change the file to whatever
• mise use -g and mise global should use ~/.config/mise/config.toml if it exists, ~/.tool-versions otherwise if that exists, and default to creating ~/.config/mise/config.toml
• mise use should modify the nearest local config file with the plugin already specified, otherwise the nearest local file, otherwise use cwd. [^nearest]
• it should be possible to use mise use with legacy config files like .node-version—note that this would only be possible with plugin support. It's not possible for me to modify just any file correctly. (e.g.: Gemfile for ruby)

What I'm a little unsure about is mise local. Now, I don't really suggest that people use mise local|global and they're hidden from docs/CLI help. They're there for asdf compatibility. mise use should be thought of as the modern, better equivalent. However, people are going to keep using these probably forever. Should mise local behave more like asdf and default to .tool-versions? Or for consistency should it behave like mise use and default to .mise.toml?

Also from a higher level: what are your thoughts on .tool-versions generally? I kind of want to push people away from them. Part of the reason for this is actually asdf compatibility which might be surprising. If you use fuzzy versions in your .tool-versions file, then that config will break in asdf. Defaulting to a single config style like .mise.toml might provide more consistent behavior.

Of course, supporting .tool-versions files is a major feature of mise that will never go away for people coming from asdf. However what we could do is provide a way to create .mise.toml files out of .tool-versions—possibly automatically. I welcome thoughts either way here.

[^nearest]: this gets a little hairy, like imagine mise use [email protected] node@20 but python and node are currently in different files. I'm not sure, but I think it should update each file individually. Or I could make it "go to the nearest single file where the first is defined". I would need to be a little careful that in this case the priority load order is such that the newly "used" version is overridden.

[jdx]

note that this logic is solely around writing the config files, not reading. reading is actually easier since we just merge everything up but when we write we have to pick a specific location.

That said, if you are doing some things that are quite particular about where these files get written to (generally just in scripts), I would encourage you in the short term (within the next month) to consider being explicit with the path used mise use --path .mise.toml because the details around that may shift. It's not really possible for me to provide a decent deprecation/migration path for this breaking change unfortunately.

I've labeled this as a "breaking change"—but I suspect very few people would be hit by this logic changing. It's fairly minor details like mise use might use .tool-versions if that file exists where now it always uses .mise.toml.