ASDF global file example and improvements to its KB article

examples/.tool-versions

@@ -0,0 +1,19 @@
+################################################################################
+## ~/.tool-versions
+##
+## Only versions or "system" are supported here, not "latest".
+## Put the version to use as default first, followed by all fallback versions
+## in order.
+##
+## Sources:
+## - https://asdf-vm.com/manage/configuration.html#tool-versions
+################################################################################
+
+python 3.11.0 system 3.10.7 3.9.7
+ruby 2.7.7 system
+
+azure-cli system 2.40.0
+terraform 1.2.9 1.3.7 system
+
+hadolint 2.12.0
+shellcheck 0.8.0

knowledge base/asdf.md

@@ -2,6 +2,14 @@
 
 `asdf` is a CLI tool to manage multiple language runtime versions on a per-project basis. It works like `gvm`, `nvm`, `rbenv` and `pyenv` (and more) all in one.
 
+1. [TL;DR](#tldr)
+2. [Installation](#installation)
+3. [Plugins management](#plugins-management)
+   1. [Plugins gotchas](#plugins-gotchas)
+4. [Versions management](#versions-management)
+   1. [The `.tool-versions` file](#the-tool-versions-file)
+5. [Further readings](#further-readings)
+
 ## TL;DR
 
 ```sh
@@ -27,10 +35,13 @@ asdf list elixir
 # list available versions
 asdf list all elixir
 
-# install a version
+# install a specific version
 asdf install erlang latest
 asdf install terraform 1.1.1
 
+# install all versions specified in the '.tool-versions' file
+asdf install
+
 # set a specific installed version to use
 asdf global helm 3.3 3.2
 asdf shell erlang latest
@@ -113,12 +124,34 @@ asdf local python system
 asdf uninstall helm 3.3
 ```
 
+### The `.tool-versions` file
+
+Stores the global (`~/.tool-versions`) or local (`./.tool-versions`) settings for ASDF.
+
+```txt
+# Multiple versions can be set by separating them with a space.
+# plugin_name  default_version  first_fallback_version ... nth_fallback_version
+python system 3.11.0 3.10.9 3.9.7 
+```
+
+The versions listed in such file can be:
+
+- an actual version, like `3.10.9`; plugins that support downloading binaries, will download that versions' binaries
+- a git reference, like `ref:v1.0.2-a` or `ref:39cb398vb39`; plugins will download the given tag/commit/branch from github and compile the executable file
+- a path, like `path:~/src/elixir`; plugins will reference this path to a (custom, compiled) version of the executable
+- the `system` keyword; this causes asdf to passthrough to the version of the tool present on the host system and avoid those which are managed by asdf
+
 ## Further readings
 
 - the project's [homepage]
 - the project's [github] page
 - [plugins list]
+- [`.tool-versions` example][.tool-versions example]
 
+<!-- project's references -->
 [github]: https://github.com/asdf-vm/asdf
 [homepage]: https://asdf-vm.com/
 [plugins list]: https://github.com/asdf-vm/asdf-plugins
+
+<!-- internal references -->
+[.tool-versions example]: ../examples/.tool-versions