docs: rename legacy version files to idiomatic version files

.prettierignore

@@ -1,6 +1,6 @@
 CHANGELOG.md
 .venv
-registry/
+aqua-registry/
 docs/cli
 docs/environments.md
 docs/registry.md

docs/cache-behavior.md

@@ -10,7 +10,7 @@ to be updating, this is a good place to start.
 ## Plugin/Runtime Cache
 
 Each plugin has a cache that's stored in `~/$MISE_CACHE_DIR/<PLUGIN>`. It stores
-the list of versions available for that plugin (`mise ls-remote <PLUGIN>`), the legacy filenames (see below),
+the list of versions available for that plugin (`mise ls-remote <PLUGIN>`), the idiomatic filenames (see below),
 the list of aliases, the bin directories within each runtime installation, and the result of
 running `exec-env` after the runtime was installed.
 

docs/cli/direnv.md

@@ -7,9 +7,9 @@ Output direnv function to use mise inside direnv
 
 See <https://mise.jdx.dev/direnv.html> for more information
 
-Because this generates the legacy files based on currently installed plugins,
+Because this generates the idiomatic files based on currently installed plugins,
 you should run this command after installing new plugins. Otherwise
-direnv may not know to update environment variables when legacy file versions change.
+direnv may not know to update environment variables when idiomatic file versions change.
 
 ## Subcommands
 

docs/cli/direnv/activate.md

@@ -7,9 +7,9 @@ Output direnv function to use mise inside direnv
 
 See <https://mise.jdx.dev/direnv.html> for more information
 
-Because this generates the legacy files based on currently installed plugins,
+Because this generates the idiomatic files based on currently installed plugins,
 you should run this command after installing new plugins. Otherwise
-direnv may not know to update environment variables when legacy file versions change.
+direnv may not know to update environment variables when idiomatic file versions change.
 
 Examples:
 

docs/cli/settings/get.md

@@ -24,5 +24,5 @@ Use the local config file instead of the global one
 
 Examples:
 
-    $ mise settings get legacy_version_file
+    $ mise settings get idiomatic_version_file
     true

docs/cli/settings/ls.md

@@ -30,7 +30,7 @@ Only display key names for each setting
 Examples:
 
     $ mise settings ls
-    legacy_version_file = false
+    idiomatic_version_file = false
     ...
 
     $ mise settings ls python

docs/cli/settings/set.md

@@ -26,4 +26,4 @@ Use the local config file instead of the global one
 
 Examples:
 
-    mise settings legacy_version_file=true
+    mise settings idiomatic_version_file=true

docs/cli/settings/unset.md

@@ -22,4 +22,4 @@ Use the local config file instead of the global one
 
 Examples:
 
-    mise settings unset legacy_version_file
+    mise settings unset idiomatic_version_file

docs/configuration.md

@@ -157,8 +157,8 @@ python = ['3.10', '3.11']
 [settings]
 # plugins can read the versions files used by other version managers (if enabled by the plugin)
 # for example, .nvmrc in the case of node's nvm
-legacy_version_file = true                     # enabled by default (unlike asdf)
-legacy_version_file_disable_tools = ['python'] # disable for specific tools
+idiomatic_version_file = true                     # enabled by default (unlike asdf)
+idiomatic_version_file_disable_tools = ['python'] # disable for specific tools
 
 # configure `mise install` to always keep the downloaded archive
 always_keep_download = false        # deleted after install by default
@@ -240,38 +240,38 @@ Both `.mise.toml` and `.tool-versions` support "scopes" which modify the behavio
   be used to express something like "2 versions behind lts" such as `sub-2:lts`. Or 1 minor
   version behind the latest version: `sub-0.1:latest`.
 
-## Legacy version files
+## Idiomatic version files
 
-mise supports "legacy version files" just like asdf. They're language-specific files
+mise supports "idiomatic version files" just like asdf. They're language-specific files
 like `.node-version`
 and `.python-version`. These are ideal for setting the runtime version of a project without forcing
 other developers to use a specific tool like mise/asdf.
 
 They support aliases, which means you can have an `.nvmrc` file with `lts/hydrogen` and it will work
-in mise and nvm. Here are some of the supported legacy version files:
+in mise and nvm. Here are some of the supported idiomatic version files:
 
-| Plugin    | "Legacy" (Idiomatic) Files                         |
+| Plugin    | Idiomatic Files                                    |
 | --------- | -------------------------------------------------- |
 | crystal   | `.crystal-version`                                 |
 | elixir    | `.exenv-version`                                   |
 | go        | `.go-version`, `go.mod`                            |
 | java      | `.java-version`, `.sdkmanrc`                       |
 | node      | `.nvmrc`, `.node-version`                          |
-| python    | `.python-version`                                  |
+| python    | `.python-version`, `.python-versions`              |
 | ruby      | `.ruby-version`, `Gemfile`                         |
 | terraform | `.terraform-version`, `.packer-version`, `main.tf` |
 | yarn      | `.yarnrc`                                          |
 
 In mise these are enabled by default. You can disable them
-with `mise settings legacy_version_file=false`.
+with `mise settings idiomatic_version_file=false`.
 There is a performance cost to having these when they're parsed as it's performed by the plugin in
-`bin/parse-version-file`. However these are [cached](/cache-behavior) so it's not a huge deal.
+`bin/parse-version-file`. However, these are [cached](/cache-behavior) so it's not a huge deal.
 You may not even notice.
 
 ::: info
-asdf calls these "legacy version files" so we do too. I think this is a bad name since it implies
+asdf called these "legacy version files". I think this was a bad name since it implies
 that they shouldn't be used—which is definitely not the case IMO. I prefer the term "idiomatic"
-version files since they're version files not specific to asdf/mise and can be used by other tools.
+version files since they are version files not specific to asdf/mise and can be used by other tools.
 (`.nvmrc` being a notable exception, which is tied to a specific tool.)
 :::
 

docs/lang/java.md

@@ -58,9 +58,9 @@ sudo ln -s ~/.local/share/mise/installs/java/openjdk-21/Contents /Library/Java/J
 
 > Note: Not all distributions of the Java SDK support this integration (e.g liberica).
 
-## Legacy version files
+## Idiomatic version files
 
-The Java core plugin supports the legacy version files `.java-version` and `.sdkmanrc`.
+The Java core plugin supports the idiomatic version files `.java-version` and `.sdkmanrc`.
 
 For `.sdkmanrc` files, mise will try to map the vendor and version to the appropriate version
 string. For example, the version `20.0.2-tem` will be mapped to `temurin-20.0.2`. Due to Azul's Zulu

docs/mise.usage.kdl

@@ -227,7 +227,7 @@ cmd "direnv" help="Output direnv function to use mise inside direnv" {
 
 See https://mise.jdx.dev/direnv.html for more information
 
-Because this generates the legacy files based on currently installed plugins,
+Because this generates the idiomatic files based on currently installed plugins,
 you should run this command after installing new plugins. Otherwise
 direnv may not know to update environment variables when legacy file versions change."
     cmd "envrc" hide=true help="[internal] This is an internal command that writes an envrc file\nfor direnv to consume."

mise.usage.kdl

@@ -291,19 +291,19 @@ cmd "direnv" help="Output direnv function to use mise inside direnv" {
 
 See https://mise.jdx.dev/direnv.html for more information
 
-Because this generates the legacy files based on currently installed plugins,
+Because this generates the idiomatic files based on currently installed plugins,
 you should run this command after installing new plugins. Otherwise
-direnv may not know to update environment variables when legacy file versions change."
+direnv may not know to update environment variables when idiomatic file versions change."
     cmd "envrc" hide=true help="[internal] This is an internal command that writes an envrc file\nfor direnv to consume."
     cmd "exec" hide=true help="[internal] This is an internal command that writes an envrc file\nfor direnv to consume."
     cmd "activate" help="Output direnv function to use mise inside direnv" {
         long_help r"Output direnv function to use mise inside direnv
 
 See https://mise.jdx.dev/direnv.html for more information
 
-Because this generates the legacy files based on currently installed plugins,
+Because this generates the idiomatic files based on currently installed plugins,
 you should run this command after installing new plugins. Otherwise
-direnv may not know to update environment variables when legacy file versions change."
+direnv may not know to update environment variables when idiomatic file versions change."
         after_long_help r"Examples:
 
     $ mise direnv activate > ~/.config/direnv/lib/use_mise.sh
@@ -1030,7 +1030,7 @@ Note that aliases are also stored in this file
 but managed separately with `mise aliases get`"
         after_long_help r"Examples:
 
-    $ mise settings get legacy_version_file
+    $ mise settings get idiomatic_version_file
     true
 "
         flag "-l --local" help="Use the local config file instead of the global one"
@@ -1047,7 +1047,7 @@ but managed separately with `mise aliases`"
         after_long_help r#"Examples:
 
     $ mise settings ls
-    legacy_version_file = false
+    idiomatic_version_file = false
     ...
 
     $ mise settings ls python
@@ -1065,7 +1065,7 @@ but managed separately with `mise aliases`"
 This modifies the contents of ~/.config/mise/config.toml"
         after_long_help r"Examples:
 
-    $ mise settings legacy_version_file=true
+    $ mise settings idiomatic_version_file=true
 "
         flag "-l --local" help="Use the local config file instead of the global one"
         arg "<KEY>" help="The setting to set"
@@ -1078,7 +1078,7 @@ This modifies the contents of ~/.config/mise/config.toml"
 This modifies the contents of ~/.config/mise/config.toml"
         after_long_help r"Examples:
 
-    $ mise settings unset legacy_version_file
+    $ mise settings unset idiomatic_version_file
 "
         flag "-l --local" help="Use the local config file instead of the global one"
         arg "<KEY>" help="The setting to remove"

schema/mise.json

@@ -285,6 +285,19 @@
           "description": "Timeout in seconds for all HTTP requests in mise.",
           "type": "string"
         },
+        "idiomatic_version_file": {
+          "default": true,
+          "description": "Set to false to disable the idiomatic version files such as .node-version, .ruby-version, etc.",
+          "type": "boolean"
+        },
+        "idiomatic_version_file_disable_tools": {
+          "default": [],
+          "description": "Specific tools to disable idiomatic version files for.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
         "ignored_config_paths": {
           "default": [],
           "description": "This is a list of config paths that mise will ignore.",
@@ -301,11 +314,13 @@
         "legacy_version_file": {
           "default": true,
           "description": "Set to false to disable the idiomatic version files such as .node-version, .ruby-version, etc.",
+          "deprecated": "Use idiomatic_version_file instead.",
           "type": "boolean"
         },
         "legacy_version_file_disable_tools": {
           "default": [],
           "description": "Specific tools to disable idiomatic version files for.",
+          "deprecated": "Use idiomatic_version_file_disable_tools instead.",
           "type": "array",
           "items": {
             "type": "string"

schema/mise.plugin.json

@@ -23,7 +23,7 @@
       "additionalProperties": false,
       "properties": {
         "data": {
-          "description": "list of legacy filenames to check for",
+          "description": "list of idiomatic filenames to check for",
           "type": "string"
         }
       }

settings.toml

@@ -315,6 +315,28 @@ type = "Duration"
 default = "30s"
 description = "Timeout in seconds for all HTTP requests in mise."
 
+[idiomatic_version_file]
+env = "MISE_IDIOMATIC_VERSION_FILE"
+type = "Bool"
+default = true
+description = "Set to false to disable the idiomatic version files such as .node-version, .ruby-version, etc."
+docs = """
+Plugins can read the versions files used by other version managers (if enabled by the plugin)
+for example, `.nvmrc` in the case of node's nvm. See [idiomatic version files](#idiomatic-version-files)
+for more
+information.
+
+Set to "false" to disable idiomatic version file parsing.
+"""
+
+[idiomatic_version_file_disable_tools]
+env = "MISE_IDIOMATIC_VERSION_FILE_DISABLE_TOOLS"
+type = "ListString"
+rust_type = "BTreeSet<String>"
+default = []
+parse_env = "list_by_comma"
+description = "Specific tools to disable idiomatic version files for."
+
 [ignored_config_paths]
 env = "MISE_IGNORED_CONFIG_PATHS"
 type = "ListPath"
@@ -330,28 +352,23 @@ rust_type = "usize"
 default = 4
 description = "How many jobs to run concurrently such as tool installs."
 
-# TODO: rename to "idiomatic_version_file"
 [legacy_version_file]
 env = "MISE_LEGACY_VERSION_FILE"
 type = "Bool"
 default = true
+deprecated = "Use idiomatic_version_file instead."
 description = "Set to false to disable the idiomatic version files such as .node-version, .ruby-version, etc."
-docs = """
-Plugins can read the versions files used by other version managers (if enabled by the plugin)
-for example, `.nvmrc` in the case of node's nvm. See [legacy version files](#legacy-version-files)
-for more
-information.
-
-Set to "false" to disable legacy version file parsing.
-"""
+hide = true
 
 [legacy_version_file_disable_tools]
 env = "MISE_LEGACY_VERSION_FILE_DISABLE_TOOLS"
 type = "ListString"
 rust_type = "BTreeSet<String>"
 default = []
 parse_env = "list_by_comma"
+deprecated = "Use idiomatic_version_file_disable_tools instead."
 description = "Specific tools to disable idiomatic version files for."
+hide = true
 
 [libgit2]
 env = "MISE_LIBGIT2"