Documentation clarification request

[brandondrew]

Is your feature request related to a problem? Please describe.

It's related to an unclear portion of the documentation.

Describe the solution you'd like

On https://github.com/asdf-vm/asdf/edit/master/docs/core-configuration.md there is the following information:

legacy_version_file - defaults to no. If set to yes it will cause plugins that support this feature to read the version files used by other version managers (e.g. .ruby-version in the case of Ruby’s rbenv).

However, it is unclear if this means it will exclusively read the legacy files, or whether it will additionally read the legacy files. It's also unclear which would take precedence (though I would guess it would be .tool-versions).

I would like to use the .tool-versions file in my $HOME, but continue to use .ruby-version in repos, since it does not seem polite to require other developers to immediately switch.

Basically in a nutshell, I'm hoping I can use asdf's default (and better) file whenever it exists, but still support legacy files otherwise. The reason for this is that it would be a huge pain to have to change files for all repos and for all languages globally at the same time, and do this for all developers across an organization..

(This is a documentation clarification request, but if the clarification is that this is not currently possible, then my next step will be to create a feature request 😉.)

[jthegedus]

I believe when legacy_version_file = yes and you have a .ruby-version present it will use the .ruby-version before falling back to the .tool-versions.

Ie: .ruby-version > .tool-versions

Notably, it relies on the plugin to support this:

set to yes it will cause plugins that support this feature

and the version of the tool in .ruby-version needs to be installed with asdf.

You should be able to have a .tool-versions in your repo alongside a legacy version file like .ruby-version and asdf will respect that. This should allow, per-tool migration in a single project.