asdf: Скилл для управления версиями окружений

--- name: asdf description: Use this skill whenever the user wants to install, configure, or use asdf (asdf-vm), the universal version manager. Trigger for any mention of asdf, .tool-versions files, managing runtime versions, switching between versions of Node.js, Python, Ruby, Go, Terraform, kubectl, Java, Erlang, Elixir, or any other tool managed by asdf. Also trigger when migrating from nvm, pyenv, rbenv, goenv, tfenv, or similar single-language version managers. Use this skill for help with asdf plugins, asdf install, asdf set/global/local, troubleshooting shims, Fish/Bash/Zsh shell configuration, and multi-project version isolation workflows. license: MIT compatibility: opencode --- # asdf Version Manager Skill asdf is a universal CLI version manager — one tool to replace nvm, pyenv, rbenv, tfenv, goenv and more. It manages per-project versions via `.tool-versions` files and switches versions automatically as you navigate directories. --- ## When to Use This Skill Use this skill when the user is: - **Installing or setting up asdf** on a new machine (any OS, any shell) - **Adding plugins** for a language or tool (Node.js, Python, Go, Terraform, kubectl, Helm, etc.) - **Installing or switching versions** of any tool managed by asdf - **Managing `.tool-versions` files** — creating, editing, or understanding version resolution - **Migrating from single-language version managers** like nvm, pyenv, rbenv, goenv, tfenv, or sdkman - **Configuring shell integration** for Bash, Zsh, Fish, or Elvish - **Debugging version resolution** — wrong version active, shims not working, `command not found` errors - **Onboarding to a project** that uses `.tool-versions` for reproducible environments - **Setting up CI/CD pipelines** that need deterministic tool versions via asdf - **Configuring `.asdfrc`** for legacy file support, concurrency, or plugin repository settings --- ## Core Concepts - **Plugin**: Adapter for a specific tool (nodejs, python, terraform, kubectl, etc.) - **Tool**: The actual runtime/binary managed (e.g., Node.js 20.11.0) - **.tool-versions**: Project-level file declaring exact versions; asdf resolves it by traversing up the directory tree to `$HOME` - **Shims**: Lightweight wrappers in `~/.asdf/shims/` that intercept tool invocations and dispatch to the right version - **Version scopes**: project (`.tool-versions` in cwd) → parent dirs → `$HOME/.tool-versions` → env var `ASDF_${TOOL}_VERSION` --- ## Installation ### Dependencies (all platforms) ```bash # Debian/Ubuntu sudo apt install -y git curl # macOS brew install git curl ``` ### Install asdf binary (recommended: binary download) ```bash # Download latest release from https://github.com/asdf-vm/asdf/releases # Or via git clone (classic method): git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.16.7 ``` ### Shell Configuration **Fish shell** (Jean-Jacques' setup): ```fish # Add to ~/.config/fish/config.fish source ~/.asdf/asdf.fish # Install completions mkdir -p ~/.config/fish/completions ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions/asdf.fish ``` **Bash**: ```bash # Add to ~/.bashrc or ~/.bash_profile . "$HOME/.asdf/asdf.sh" . "$HOME/.asdf/completions/asdf.bash" ``` **Zsh**: ```zsh # Add to ~/.zshrc . "$HOME/.asdf/asdf.sh" ``` After configuration, restart shell or `source` the config file. --- ## Essential Commands ### Plugin Management ```bash asdf plugin list all # Browse all available plugins asdf plugin list all | grep terra # Search for specific plugins asdf plugin add nodejs # Add plugin by shortname (from registry) asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git # Add by URL asdf plugin list # List installed plugins asdf plugin update nodejs # Update a plugin asdf plugin update --all # Update all plugins asdf plugin remove nodejs # Remove plugin + all its installs ``` ### Version Management ```bash asdf list all nodejs # List all installable versions asdf list all nodejs 20 # List versions matching prefix asdf install nodejs latest # Install latest version asdf install nodejs 20.11.0 # Install specific version asdf install # Install all versions in .tool-versions asdf list nodejs # List installed versions asdf uninstall nodejs 18.0.0 # Remove a version ``` ### Setting Versions ```bash asdf set nodejs 20.11.0 # Set version in ./.tool-versions (project) asdf set -u nodejs 20.11.0 # Set version in ~/.tool-versions (global/user default) asdf set -p nodejs 20.11.0 # Set in nearest parent .tool-versions asdf set nodejs latest # Resolve and write latest version asdf current # Show active version for all tools in cwd asdf current nodejs # Show active version for one tool asdf where nodejs # Show install path for active version asdf which node # Show shim path for a command ``` > **Note**: `asdf set` replaced the older `asdf local` / `asdf global` commands in asdf v0.15+. Both still work but `asdf set` is the modern API. ### Environment Variable Override ```bash # Temporarily override without editing .tool-versions ASDF_NODEJS_VERSION=18.0.0 node --version ``` --- ## .tool-versions Format ``` nodejs 20.11.0 python 3.12.2 terraform 1.7.4 kubectl 1.29.2 golang 1.22.1 ``` - One tool per line, `<name> <version>` - Multiple versions separated by spaces (fallback chain): `python 3.12.2 2.7.18` - Special keywords: `system` (use OS-installed version), `path:~/my/custom/build` - Commit to version control — this is the contract for the project's tool versions --- ## .asdfrc Configuration Located at `~/.asdfrc`: ```ini # Support .nvmrc, .ruby-version, etc. (per-plugin support required) legacy_version_file = yes # Keep downloaded archives (useful for slow connections) always_keep_download = no # Concurrency for parallel installs concurrency = auto # Plugin repository refresh interval in minutes plugin_repository_last_check_duration = 60 ``` --- ## Common Plugins for DevOps/Cloud (Jean-Jacques' stack) | Tool | Plugin add command | |------|-------------------| | Node.js | `asdf plugin add nodejs` | | Python | `asdf plugin add python` | | Go | `asdf plugin add golang` | | Terraform | `asdf plugin add terraform` | | kubectl | `asdf plugin add kubectl` | | Helm | `asdf plugin add helm` | | gcloud CLI | `asdf plugin add gcloud` | | Skaffold | `asdf plugin add skaffold` | | Java | `asdf plugin add java` | | Ruby | `asdf plugin add ruby` | | Erlang | `asdf plugin add erlang` | | Elixir | `asdf plugin add elixir` | Many plugins may require system dependencies — always check the plugin's README before installing. --- ## Migration from Other Version Managers Enable legacy file support in `~/.asdfrc`: ```ini legacy_version_file = yes ``` | Old file | Tool | |----------|------| | `.nvmrc` | nodejs (via asdf-nodejs) | | `.node-version` | nodejs | | `.ruby-version` | ruby (via asdf-ruby) | | `.python-version` | python (via asdf-python) | --- ## Troubleshooting ### Shims not working / command not found ```bash asdf reshim nodejs # Regenerate shims for a plugin asdf reshim # Regenerate all shims echo $PATH # Verify ~/.asdf/shims is early in PATH type -a node # Fish: check which binary is resolved ``` ### Version not being picked up ```bash asdf current # See what version is resolved and from where # Look for "No version set" warnings # Check .tool-versions exists in project dir or a parent ``` ### Plugin install failures - Check plugin README for system dependency requirements - Ensure git is installed and accessible - For nodejs: may need `gnupg` for keyring verification ### Data directory Default: `~/.asdf/` — override with `export ASDF_DATA_DIR=/custom/path` in shell config. --- ## Typical Project Onboarding Workflow ```bash # 1. Clone project git clone <repo> && cd <repo> # 2. Add plugins for each tool in .tool-versions (if not already added) asdf plugin add nodejs asdf plugin add python # 3. Install all versions specified in .tool-versions asdf install # 4. Verify asdf current ``` --- ## Reference - Full docs: https://asdf-vm.com/ - Plugin list: https://github.com/asdf-vm/asdf-plugins - All commands: `asdf --help` or `asdf <command> --help`