## File: README.md # asdf [](https://github.com/asdf-vm/asdf/actions/workflows/lint.yml) [](https://github.com/asdf-vm/asdf/actions/workflows/tests.yml) **Manage multiple runtime versions with a single CLI tool, extendable via plugins** - [docs at asdf-vm.com](https://asdf-vm.com/) asdf is a CLI tool that can manage multiple language runtime versions on a per-project basis. It is like `gvm`, `nvm`, `rbenv` & `pyenv` (and more) all in one! Simply install your language's plugin! ## Why use asdf? - single CLI for multiple languages - consistent commands to manage all your languages - single global config keeping defaults in one place - single `.tool-versions` config file per project - support for existing config files `.node-version`, `.nvmrc`, `.ruby-version` for easy migration - automatically switches runtime versions as you traverse your directories - simple plugin system to add support for your language of choice - shell completion available for common shells (Bash, Zsh, Fish, Elvish) ## Documentation [Please head over to the documentation site for more information](https://asdf-vm.com/)! - [Getting Started](https://asdf-vm.com/guide/getting-started.html) - [All Commands](https://asdf-vm.com/manage/commands.html) - [All Plugins](https://github.com/asdf-vm/asdf-plugins) - [Create a Plugin](https://asdf-vm.com/plugins/create.html) with our [asdf-plugin-template](https://github.com/asdf-vm/asdf-plugin-template) - [asdf GitHub Actions](https://github.com/asdf-vm/actions) ## Contributing See [CONTRIBUTING.md in the repo](https://github.com/asdf-vm/asdf/blob/master/CONTRIBUTING.md) or the [Contributing section on the docs site](http://asdf-vm.com/contribute/core.html#initial-setup). ## Community & Questions - [FAQ](https://asdf-vm.com/more/faq.html) - [ GitHub Issues](https://github.com/asdf-vm/asdf/issues): report a bug or raise a feature request to the `asdf` core team - [ StackOverflow Tag](https://stackoverflow.com/questions/tagged/asdf-vm): see existing Q&A for `asdf`. Some of the core team watch this tag in addition to our helpful community ## Ballad of asdf > Once upon a time there was a programming language > There were many versions of it > So people wrote a version manager for it > To switch between versions for projects > Different, old, new. > > Then there came more programming languages > So there came more version managers > And many commands for them > > I installed a lot of them > I learnt a lot of commands > > Then I said, just one more version manager > Which I will write instead > > So, there came another version manager > **asdf version manager** - > > A version manager so extendable > for which anyone can create a plugin > To support their favourite language > No more installing more version managers > Or learning more commands ---
This was the mail I wrote to a few friends to tell them about the project. Thanks to [@roshanvid](https://twitter.com/roshanvid) for suggesting that this go into the readme
[@HashNuke](https://github.com/HashNuke)
--- ## File: docs/contribute/core.md # asdf `asdf` core contribution guide. ## Initial Setup Fork `asdf` on GitHub and/or Git clone the default branch: ```shell # clone your fork git clone https://github.com//asdf.git # or clone asdf git clone https://github.com/asdf-vm/asdf.git ``` The tools for core development are in this repo's `.tool-versions`. If you wish to manage with `asdf` itself, add the plugins: ```shell asdf plugin add bats https://github.com/timgluz/asdf-bats.git asdf plugin add shellcheck https://github.com/luizm/asdf-shellcheck.git asdf plugin add shfmt https://github.com/luizm/asdf-shfmt.git ``` Install the versions to develop `asdf` with: ```shell asdf install ``` It _may_ be useful to not use `asdf` to manage the tools during development on your local machine as you may need to break functionality which would then break your dev tooling. Here's the raw list of tools: - [bats-core](https://github.com/bats-core/bats-core): Bash Automated Testing System, for unit testing Bash or POSIX compliant scripts. - [shellcheck](https://github.com/koalaman/shellcheck): Static analysis tool for shell scripts. - [shfmt](https://github.com/mvdan/sh): A shell parser, formatter, and interpreter with bash support; includes shfmt ## Development If you want to try out your changes without making change to your installed `asdf`, you can set the `$ASDF_DIR` variable to the path where you cloned the repository, and temporarily prepend the `bin` and `shims` directory of the directory to your path. It is best to format, lint and test your code locally before you commit or push to the remote. Use the following scripts/commands: ```shell # Lint ./scripts/lint.bash --check # Fix & Format ./scripts/lint.bash --fix # Test: all tests ./scripts/test.bash # Test: for specific command bats test/list_commands.bash ``` ::: tip **Add tests!** - Tests are **required** for new features and speed up review of bug fixes. Please cover new code paths before you create a Pull Request. See [bats-core documentation](https://bats-core.readthedocs.io/en/stable/index.html) ::: ### Gitignore The following is the `.gitignore` file in the `asdf-vm/asdf` repository. We ignore project-specific files. Files specific to your OS, tools or workflows should be ignored in your global `.gitignore` configuration, [see here](http://stratus3d.com/blog/2018/06/03/stop-excluding-editor-temp-files-in-gitignore/) for more details. <<< @/../.gitignore ### `.git-blame-ignore-revs` `asdf` uses a `.git-blame-ignore-revs` to reduce noise when running a blame. See the [git blame documentation](https://git-scm.com/docs/git-blame) for more information. Use the file with `git blame` like so: ```sh git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats ``` Optionally, configure to use the file on every invocation of `blame` without manually supplying it: ```sh git config blame.ignoreRevsFile .git-blame-ignore-revs ``` It is possible to configure IDEs to use this file. For example, when using VSCode (with [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)), write the following to `.vscode/settings.json`: ```json { "gitlens.advanced.blame.customArguments": [ "--ignore-revs-file", ".git-blame-ignore-revs" ] } ``` ## Bats Testing Execute tests locally with: ```shell ./scripts/test.bash ``` Before writing tests **please read**: - existing tests in `test/` - [bats-core documentation](https://bats-core.readthedocs.io/en/stable/index.html) - existing Bats settings used in `scripts/test.bash` ### Bats Tips Bats debugging can be difficult at times. Using the TAP output with `-t` flag will enable you to print outputs with the special file descriptor `>&3` during test execution, simplifying debugging. As an example: ```shell # test/some_tests.bats printf "%s\n" "Will not be printed during bats test/some_tests.bats" printf "%s\n" "Will be printed during bats -t test/some_tests.bats" >&3 ``` This is further documented in bats-core [Printing to the Terminal](https://bats-core.readthedocs.io/en/stable/writing-tests.html#printing-to-the-terminal). ## Pull Requests, Releases & Conventional Commits `asdf` is using an automated release tool called [Release Please](https://github.com/googleapis/release-please) to automatically bump the [SemVer](https://semver.org/) version and generate the [Changelog](https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md). This information is determined by reading the commit history since the last release. [Conventional Commit messages](https://www.conventionalcommits.org/) define the format of the Pull Request Title which becomes the commit message format on the default branch. This is enforced with GitHub Action [`amannn/action-semantic-pull-request`](https://github.com/amannn/action-semantic-pull-request). Conventional Commit follows this format: ``` [optional scope][optional !]: fix: some fix feat: a new feature docs: some documentation update docs(website): some change for the website feat!: feature with breaking change ``` The full list of `` are: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. - `!`: indicates a breaking change - `fix`: will create a new SemVer `patch` - `feat`: will create a new SemVer `minor` - `!`: will create a new SemVer `major` The Pull Request Title must follow this format. ::: tip Use Conventional Commit message format for your Pull Request Title. ::: ## Docker Images The [asdf-alpine](https://github.com/vic/asdf-alpine) and [asdf-ubuntu](https://github.com/vic/asdf-ubuntu) projects are an ongoing effort to provide Dockerized images of some asdf tools. You can use these docker images as base for your development servers, or for running your production apps. --- ## File: docs/contribute/documentation.md # Docs & Site Documentation & site contribution guide. ## Initial Setup Fork `asdf` on GitHub and/or Git clone the default branch: ```shell # clone your fork git clone https://github.com//asdf.git # or clone asdf git clone https://github.com/asdf-vm/asdf.git ``` The tools for Docs site development are managed with `asdf` in the `docs/.tool-versions`. Add the plugins with: ```shell asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs ``` Install the tool version(s) with: ```shell asdf install ``` - [Node.js](https://nodejs.org): JavaScript runtime built on Chrome's V8 JavaScript engine. Install Node.js dependencies from `docs/package.json`: ```shell npm install ``` ## Development [VitePress (v2)](https://vitepress.dev/) is the Static Site Generator (SSG) we use to build the asdf documentation site. It was chosen to replace [Docsify.js](https://docsify.js.org/) and subsequently VuePress as we would like to support an HTML only fallback when users do not have JavaScript available or enabled. This was not possible with Docsify & VitePress quickly supplanted VuePress. Other than this, the feature-set is largely the same, with the focus on writing Markdown files with minimal configuration. `package.json` contains the scripts required for development: @[code json{3-5}](../package.json) To start the local development server: ```shell npm run dev ``` Format the code before committing: ```shell npm run fmt ``` ## Pull Requests, Releases & Conventional Commits `asdf` is using an automated release pipeline which relies on Conventional Commits in PR titles. Detailed documentation found in the [core contribution guide](./core.md). When creating a PR for documentation changes please make the PR title with the Conventional Commit type `docs` in the format `docs: `. ## Vitepress Configuration of the site is contained within a few TypeScript files with JS Objects used to represent the config. They are: - `docs/.vitepress/config.js`: the root config file for the site. Read the [VitePress documentation](https://vitepress.dev/reference/site-config) for it's spec. To simplify the root config, the larger JS Objects representing the _navbar_ and _sidebar_ configuration have been extracted and separated by their locale. See both in: - `docs/.vitepress/navbars.js` - `docs/.vitepress/sidebars.js` With the official documentation for these configs living in the [Default Theme Reference](https://vitepress.dev/reference/default-theme-config). ## I18n VitePress has first-class support for internationalization. The root config `docs/.vitepress/config.js` defines the supported locales with their URL, title in the selection dropdown menu and navbar/sidebar configs references. The navbar/sidebar configs are captured in the aforementioned config files, separated by locale and exported individually. The markdown content for each locale must fall under a folder with the same name as the keys for `locales` in the root config. That is: ```js // docs/.vitepress/config.js export default defineConfig({ ... locales: { root: { label: "English", lang: "en-US", themeConfig: { nav: navbars.en, sidebar: sidebars.en, }, }, "pt-br": { label: "Brazilian Portuguese", lang: "pr-br", themeConfig: { nav: navbars.pt_br, sidebar: sidebars.pt_br, }, }, "zh-hans": { label: "简体中文", lang: "zh-hans", themeConfig: { nav: navbars.zh_hans, sidebar: sidebars.zh_hans, }, }, }, }) ``` `/pt-BR/` will require the same set of markdown files located under `docs/pt-BR/`, like so: ```shell docs ├─ README.md ├─ foo.md ├─ nested │ └─ README.md └─ pt-BR ├─ README.md ├─ foo.md └─ nested └─ README.md ``` The [official VitePress i18n documentation](https://vitepress.dev/guide/i18n) goes into more detail. --- ## File: docs/contribute/first-party-plugins.md # First-Party Plugins The asdf core team has authored some plugins relevant to their daily work life. Help is always welcome in maintaining and improving these plugins. See the associated repo for each linked below: - [Elixir](https://github.com/asdf-vm/asdf-elixir) - [Erlang](https://github.com/asdf-vm/asdf-erlang) - [Node.js](https://github.com/asdf-vm/asdf-nodejs) - [Ruby](https://github.com/asdf-vm/asdf-ruby) For community plugins, see: - [`asdf-community` organisation](https://github.com/asdf-community): A collaborative, community-driven project for long-term maintenance of `asdf` plugins. - [`asdf-plugins` shortname repo](https://github.com/asdf-vm/asdf-plugins): Short-name list used by `asdf` core to lookup popular `asdf` plugins. - [GitHub `asdf-plugin` topic search](https://github.com/topics/asdf-plugin) --- ## File: docs/contribute/github-actions.md # GitHub Actions Thanks for your interest, please see the [asdf actions repo](https://github.com/asdf-vm/actions) for their existing Issues, conversations and Contributing Guidelines. --- ## File: docs/guide/getting-started.md # Getting Started ## 1. Install asdf asdf can be installed in several different ways: ::: details With Package Manager - **Recommended** | Package Manager | Command | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Homebrew | `brew install asdf` | | Zypper | `zypper install asdf` | | Pacman | `git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si` or use your preferred [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) | ::: :::: details Download Pre-Compiled Binary - **Easy** ##### Install asdf 1. Visit https://github.com/asdf-vm/asdf/releases and download the appropriate archive for your operating system/architecture combination. 2. Extract the `asdf` binary in the archive into a directory on your `$PATH`. 3. Verify `asdf` is on your shell's `$PATH` by running `type -a asdf`. The directory you placed the `asdf` binary in should be listed on the first line of the output from `type`. If it is not that means step #2 was not completed correctly. :::: :::: details With `go install` ##### Install asdf 1. [Install Go](https://go.dev/doc/install) 2. Run `go install github.com/asdf-vm/asdf/cmd/asdf@v0.20.0` :::: :::: details Build from Source ##### Install asdf 1. Clone the asdf repository: ```shell git clone https://github.com/asdf-vm/asdf.git --branch v0.20.0 ``` 2. Run `make` 3. Copy the `asdf` binary into a directory on your `$PATH`. 4. Verify `asdf` is on your shell's `$PATH` by running `type -a asdf`. The directory you placed the `asdf` binary in should be listed on the first line of the output from `type`. If it is not that means step #3 was not completed correctly. :::: ## 2. Configure asdf ::: tip Note Most users **DO NOT** need to customize the location that asdf writes plugin, install, and shim data to. However, if `$HOME/.asdf` isn't the directory you want asdf writing to, you can change it. Specify the directory by exporting a variable named `ASDF_DATA_DIR` in your shell's RC file. ::: There are many different combinations of Shells, OSs & Installation methods all of which affect the configuration here. Expand the selection below that best matches your system. ::: details Bash **macOS Catalina or newer**: The default shell has changed to **ZSH**. Unless changing back to Bash, follow the ZSH instructions. **Pacman**: [`bash-completion`](https://wiki.archlinux.org/title/bash#Common_programs_and_options) needs to be installed for the completions to work. ##### Add shims directory to path (required) Add the following to `~/.bash_profile`: ```shell export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH" ``` ###### Custom data directory (optional) Add the following to `~/.bash_profile` above the line you added above: ```shell export ASDF_DATA_DIR="/your/custom/data/dir" ``` ##### Set up shell completions (optional) Completions must be configured by adding the following to your `.bashrc`: ```shell . <(asdf completion bash) ``` ::: ::: details Fish ##### Add shims directory to path (required) Add the following to `~/.config/fish/config.fish`: ```shell # ASDF configuration code if test -z $ASDF_DATA_DIR set _asdf_shims "$HOME/.asdf/shims" else set _asdf_shims "$ASDF_DATA_DIR/shims" end # Do not use fish_add_path (added in Fish 3.2) because it # potentially changes the order of items in PATH if not contains $_asdf_shims $PATH set -gx --prepend PATH $_asdf_shims end set --erase _asdf_shims ``` ###### Custom data directory (optional) **Pacman**: Completions are automatically configured on installation by the AUR package. Add the following to `~/.config/fish/config.fish` above the lines you added above: ```shell set -gx --prepend ASDF_DATA_DIR "/your/custom/data/dir" ``` ##### Set up shell completions (optional) Completions must be configured manually with the following command: ```shell $ asdf completion fish > ~/.config/fish/completions/asdf.fish ``` ::: ::: details Elvish ##### Add shims directory to path (required) Add the following to `~/.config/elvish/rc.elv`: ```shell var asdf_data_dir = ~'/.asdf' if (and (has-env ASDF_DATA_DIR) (!=s $E:ASDF_DATA_DIR '')) { set asdf_data_dir = $E:ASDF_DATA_DIR } if (not (has-value $paths $asdf_data_dir'/shims')) { set paths = [$path $@paths] } ``` ###### Custom data directory (optional) Change the following line in the above snippet to set a custom data directory: ```diff -var asdf_data_dir = ~'/.asdf' +var asdf_data_dir = '/your/custom/data/dir' ``` ##### Set up shell completions (optional) ```shell $ asdf completion elvish >> ~/.config/elvish/rc.elv $ echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv ``` ::: ::: details ZSH **Pacman**: Completions are placed in a ZSH friendly location, but [ZSH must be configured to use the autocompletions](https://wiki.archlinux.org/index.php/zsh#Command_completion). ##### Add shims directory to path (required) Add the following to `~/.zshrc`: ```shell export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH" ``` ###### Custom data directory (optional) Add the following to `~/.zshrc` above the line you added above: ```shell export ASDF_DATA_DIR="/your/custom/data/dir" ``` ##### Set up shell completions (optional) Completions are configured by either a ZSH Framework `asdf` plugin (like [asdf for oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf)) or by doing the following: ```shell $ mkdir -p "${ASDF_DATA_DIR:-$HOME/.asdf}/completions" $ asdf completion zsh > "${ASDF_DATA_DIR:-$HOME/.asdf}/completions/_asdf" ``` Then add the following to your `.zshrc`: ```shell # append completions to fpath fpath=(${ASDF_DATA_DIR:-$HOME/.asdf}/completions $fpath) # initialise completions with ZSH's compinit autoload -Uz compinit && compinit ``` **Note** If you are using a custom `compinit` setup with a ZSH Framework, ensure `compinit` is below your sourcing of the framework Completions are configured by either a ZSH Framework `asdf` or will need to be [configured as per Homebrew's instructions](https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh). If you are using a ZSH Framework the associated plugin for asdf may need to be updated to use the new ZSH completions properly via `fpath`. ::: ::: details PowerShell Core ##### Add shims directory to path (required) Add the following to `~/.config/powershell/profile.ps1`: ```shell # Determine the location of the shims directory if ($null -eq $ASDF_DATA_DIR -or $ASDF_DATA_DIR -eq '') { $_asdf_shims = "${env:HOME}/.asdf/shims" } else { $_asdf_shims = "$ASDF_DATA_DIR/shims" } # Then add it to path $env:PATH = "${_asdf_shims}:${env:PATH}" ``` ###### Custom data directory (optional) Add the following to `~/.config/powershell/profile.ps1` above the snippet you added above: ```shell $env:ASDF_DATA_DIR = "/your/custom/data/dir" ``` Shell completions not available for PowerShell ::: ::: details Nushell ##### Add shims directory to path (required) Add the following to `~/.config/nushell/config.nu`: ```shell const asdf_data_dir = '~/.asdf' | path expand # or wherever you like const asdf_shims = [$asdf_data_dir shims] | path join $env.PATH = $env.PATH | where {$in != $asdf_shims} | prepend $asdf_shims ``` ###### Custom data directory (required when $asdf_data_dir != '~/.asdf') If you set $asdf_data_dir to something different than the default `~/.asdf` then you must add the following to `~/.config/nushell/config.nu`: ```shell $env.ASDF_DATA_DIR = $asdf_data_dir ``` ##### Set up shell completions (optional) Add the following to `~/.config/nushell/config.nu`, after the required setup: ```shell const asdf_cmp = [$asdf_data_dir completions nushell.nu] | path join mkdir ($asdf_cmp | path dirname) asdf completion nushell | save -f $asdf_cmp source $asdf_cmp ``` ::: ::: details POSIX Shell ##### Add shims directory to path (required) Add the following to `~/.profile`: ```shell export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH" ``` ###### Custom data directory (optional) Add the following to `~/.profile` above the line you added above: ```shell export ASDF_DATA_DIR="/your/custom/data/dir" ``` ::: `asdf` scripts need to be sourced **after** you have set your `$PATH` and **after** you have sourced your framework (oh-my-zsh etc). Restart your shell so that `PATH` changes take effect. Opening a new terminal tab will usually do it. ## Core Installation Complete! This completes the installation of the `asdf` core :tada: `asdf` is only useful once you install a **plugin**, install a **tool** and manage its **versions**. Continue the guide below to learn how to do this. ## 4. Install a Plugin For demonstration purposes we will install & set [Node.js](https://nodejs.org/) via the [`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/) plugin. ### Plugin Dependencies Each plugin has dependencies so we need to check the plugin repo where they should be listed. For `asdf-nodejs` they are: | OS | Dependency Installation | | ------------------------------ | --------------------------------------- | | Debian | `apt-get install dirmngr gpg curl gawk` | | CentOS/ Rocky Linux/ AlmaLinux | `yum install gnupg2 curl gawk` | | macOS | `brew install gpg gawk` | We should install dependencies first as some Plugins have post-install hooks. ### Install the Plugin ```shell asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git ``` ## 5. Install a Version Now we have a plugin for Node.js we can install a version of the tool. We can see which versions are available with `asdf list all nodejs` or a subset of versions with `asdf list all nodejs 14`. We will just install the `latest` available version: ```shell asdf install nodejs latest ``` ::: tip Note `asdf` enforces exact versions. `latest` is a helper throughout `asdf` that will resolve to the actual version number at the time of execution. ::: ## 6. Set a Version `asdf` performs a version lookup of a tool in all `.tool-versions` files from the current working directory up to the `$HOME` directory. The lookup occurs just-in-time when you execute a tool that `asdf` manages. ::: warning Without a version listed for a tool execution of the tool will **error**. `asdf current` will show you the tool & version resolution, or absence of, from your current directory so you can observe which tools will fail to execute. ::: Because asdf looks for a `.tool-versions` file in the current directory first, and if the file is not found it then climbs up the file tree looking for a `.tool-versions` in a parent directory until it finds one. If no `.tool-versions` file is found the version resolution process will fail and an error will be printed. If you want to set a default version that will apply to all directories you work in you can set a version in `$HOME/.tool-versions`. Any directory under your home directory will have that same version set, unless a particular directory sets another version. ```shell asdf set -u nodejs 16.5.0 ``` `$HOME/.tool-versions` will then look like: ``` nodejs 16.5.0 ``` Some OSs already have tools installed that are managed by the system and not `asdf`, `python` is a common example. You need to tell `asdf` to pass the management back to the system. The [Versions reference section](/manage/versions.md) will guide you. The first place asdf looks for a version is your current working directory (`$PWD/.tool-versions`). This may be a directory containing a source code or Git repository for a project. When in your desired directory execute you can use `asdf set` to set the version: ```shell asdf set nodejs 16.5.0 ``` `$PWD/.tool-versions` will then look like: ``` nodejs 16.5.0 ``` ### Using Existing Tool Version Files `asdf` supports the migration from existing version files from other version managers. Eg: `.ruby-version` for the case of `rbenv`. This is supported on a per-plugin basis. [`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/) supports this via both `.nvmrc` and `.node-version` files. To enable this, add the following to your `asdf` configuration file `$HOME/.asdfrc`: ``` legacy_version_file = yes ``` See the [configuration](/manage/configuration.md) reference page for more config options. ## Guide Complete! That completes the Getting Started guide for `asdf` :tada: You can now manage `nodejs` versions for your project. Follow similar steps for each type of tool in your project! `asdf` has many more commands to become familiar with, you can see them all by running `asdf --help` or `asdf`. The core of the commands are broken into three categories: - [core `asdf`](/manage/core.md) - [plugins](/manage/plugins.md) - [versions (of tools)](/manage/versions.md) --- ## File: docs/guide/getting-started-legacy.md # Getting Started `asdf` installation involves: 1. Installing dependencies 2. Downloading `asdf` core 3. Installing `asdf` 4. Installing a plugin for each tool/runtime you wish to manage 5. Installing a version of the tool/runtime 6. Setting global and project versions via `.tool-versions` config files ## 1. Install Dependencies asdf primarily requires `git` & `curl`. Here is a _non-exhaustive_ list of commands to run for _your_ package manager (some might automatically install these tools in later steps). | OS | Package Manager | Command | | ----- | --------------- | ---------------------------------- | | linux | Aptitude | `apt install curl git` | | linux | DNF | `dnf install curl git` | | linux | Pacman | `pacman -S curl git` | | linux | Zypper | `zypper install curl git` | | macOS | Homebrew | `brew install coreutils curl git` | | macOS | Spack | `spack install coreutils curl git` | ::: tip Note `sudo` may be required depending on your system configuration. ::: ## 2. Download asdf ### Official Download ```shell git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.15.0 ``` ### Community Supported Download Methods We highly recommend using the official `git` method. | Method | Command | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Homebrew | `brew install asdf` | | Pacman | `git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si` or use your preferred [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) | ## 3. Install asdf There are many different combinations of Shells, OSs & Installation methods all of which affect the configuration here. Expand the selection below that best matches your system. **macOS users, be sure to read the warning about `path_helper` at the end of this section.** ::: details Bash & Git Add the following to `~/.bashrc`: ```shell . "$HOME/.asdf/asdf.sh" ``` Completions must be configured by adding the following to your `.bashrc`: ```shell . "$HOME/.asdf/completions/asdf.bash" ``` ::: ::: details Bash & Git (macOS) If using **macOS Catalina or newer**, the default shell has changed to **ZSH**. Unless changing back to Bash, follow the ZSH instructions. Add the following to `~/.bash_profile`: ```shell . "$HOME/.asdf/asdf.sh" ``` Completions must be configured manually with the following entry in your `.bash_profile`: ```shell . "$HOME/.asdf/completions/asdf.bash" ``` ::: ::: details Bash & Homebrew Add `asdf.sh` to your `~/.bashrc` with: ```shell echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bashrc ``` Completions will need to be [configured as per Homebrew's instructions](https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash) or with the following: ```shell echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bashrc ``` ::: ::: details Bash & Homebrew (macOS) If using **macOS Catalina or newer**, the default shell has changed to **ZSH**. Unless changing back to Bash, follow the ZSH instructions. Add `asdf.sh` to your `~/.bash_profile` with: ```shell echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bash_profile ``` Completions will need to be [configured as per Homebrew's instructions](https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash) or with the following: ```shell echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bash_profile ``` ::: ::: details Bash & Pacman Add the following to `~/.bashrc`: ```shell . /opt/asdf-vm/asdf.sh ``` [`bash-completion`](https://wiki.archlinux.org/title/bash#Common_programs_and_options) needs to be installed for the completions to work. ::: ::: details Fish & Git Add the following to `~/.config/fish/config.fish`: ```shell source ~/.asdf/asdf.fish ``` Completions must be configured manually with the following command: ```shell mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions ``` ::: ::: details Fish & Homebrew Add `asdf.fish` to your `~/.config/fish/config.fish` with: ```shell echo -e "\nsource "(brew --prefix asdf)"/libexec/asdf.fish" >> ~/.config/fish/config.fish ``` Completions are [handled by Homebrew for the Fish shell](https://docs.brew.sh/Shell-Completion#configuring-completions-in-fish). Friendly! ::: ::: details Fish & Pacman Add the following to `~/.config/fish/config.fish`: ```shell source /opt/asdf-vm/asdf.fish ``` Completions are automatically configured on installation by the AUR package. ::: ::: details Elvish & Git Add `asdf.elv` to your `~/.config/elvish/rc.elv` with: ```shell mkdir -p ~/.config/elvish/lib; ln -s ~/.asdf/asdf.elv ~/.config/elvish/lib/asdf.elv echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv ``` Completions are automatically configured. ::: ::: details Elvish & Homebrew Add `asdf.elv` to your `~/.config/elvish/rc.elv` with: ```shell mkdir -p ~/.config/elvish/lib; ln -s (brew --prefix asdf)/libexec/asdf.elv ~/.config/elvish/lib/asdf.elv echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv ``` Completions are automatically configured. ::: ::: details Elvish & Pacman Add `asdf.elv` to your `~/.config/elvish/rc.elv` with: ```shell mkdir -p ~/.config/elvish/lib; ln -s /opt/asdf-vm/asdf.elv ~/.config/elvish/lib/asdf.elv echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv ``` Completions are automatically configured. ::: ::: details ZSH & Git Add the following to `~/.zshrc`: ```shell . "$HOME/.asdf/asdf.sh" ``` **OR** use a ZSH Framework plugin like [asdf for oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) which will source this script and setup completions. Completions are configured by either a ZSH Framework `asdf` plugin or by adding the following to your `.zshrc`: ```shell # append completions to fpath fpath=(${ASDF_DIR}/completions $fpath) # initialise completions with ZSH's compinit autoload -Uz compinit && compinit ``` - if you are using a custom `compinit` setup, ensure `compinit` is below your sourcing of `asdf.sh` - if you are using a custom `compinit` setup with a ZSH Framework, ensure `compinit` is below your sourcing of the framework ::: ::: details ZSH & Homebrew Add `asdf.sh` to your `~/.zshrc` with: ```shell echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc ``` **OR** use a ZSH Framework plugin like [asdf for oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) which will source this script and setup completions. Completions are configured by either a ZSH Framework `asdf` or will need to be [configured as per Homebrew's instructions](https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh). If you are using a ZSH Framework the associated plugin for asdf may need to be updated to use the new ZSH completions properly via `fpath`. ::: ::: details ZSH & Pacman Add the following to `~/.zshrc`: ```shell . /opt/asdf-vm/asdf.sh ``` Completions are placed in a ZSH friendly location, but [ZSH must be configured to use the autocompletions](https://wiki.archlinux.org/index.php/zsh#Command_completion). ::: ::: details PowerShell Core & Git Add the following to `~/.config/powershell/profile.ps1`: ```shell . "$HOME/.asdf/asdf.ps1" ``` ::: ::: details PowerShell Core & Homebrew Add `asdf.sh` to your `~/.config/powershell/profile.ps1` with: ```shell echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.ps1\"" >> ~/.config/powershell/profile.ps1 ``` ::: ::: details PowerShell Core & Pacman Add the following to `~/.config/powershell/profile.ps1`: ```shell . /opt/asdf-vm/asdf.ps1 ``` ::: ::: details Nushell & Git Add `asdf.nu` to your `~/.config/nushell/config.nu` with: ```shell "\n$env.ASDF_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path ``` Completions are automatically configured ::: ::: details Nushell & Homebrew Add `asdf.nu` to your `~/.config/nushell/config.nu` with: ```shell "\n$env.ASDF_DIR = (brew --prefix asdf | str trim | into string | path join 'libexec')\n source " + (brew --prefix asdf | str trim | into string | path join 'libexec/asdf.nu') | save --append $nu.config-path ``` Completions are automatically configured ::: ::: details Nushell & Pacman Add `asdf.nu` to your `~/.config/nushell/config.nu` with: ```shell "\n$env.ASDF_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path ``` Completions are automatically configured. ::: ::: details POSIX Shell & Git Add the following to `~/.profile`: ```shell export ASDF_DIR="$HOME/.asdf" . "$HOME/.asdf/asdf.sh" ``` ::: ::: details POSIX Shell & Homebrew Add `asdf.sh` to your `~/.profile` with: ```shell echo -e "\nexport ASDF_DIR=\"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.profile echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.profile ``` ::: ::: details POSIX Shell & Pacman Add the following to `~/.profile`: ```shell export ASDF_DIR="/opt/asdf-vm" . /opt/asdf-vm/asdf.sh ``` ::: `asdf` scripts need to be sourced **after** you have set your `$PATH` and **after** you have sourced your framework (oh-my-zsh etc). ::: warning On macOS, starting a Bash or Zsh shell automatically calls a utility called `path_helper`. `path_helper` can rearrange items in `PATH` (and `MANPATH`), causing inconsistent behavior for tools that require specific ordering. To workaround this, `asdf` on macOS defaults to forcibly adding its `PATH`-entries to the front (taking highest priority). This is controllable with the `ASDF_FORCE_PREPEND` variable. ::: Restart your shell so that `PATH` changes take effect. Opening a new terminal tab will usually do it. ## Core Installation Complete! This completes the installation of the `asdf` core :tada: `asdf` is only useful once you install a **plugin**, install a **tool** and manage its **versions**. Continue the guide below to learn how to do this. ## 4. Install a Plugin For demonstration purposes we will install & set [Node.js](https://nodejs.org/) via the [`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/) plugin. ### Plugin Dependencies Each plugin has dependencies so we need to check the plugin repo where they should be listed. For `asdf-nodejs` they are: | OS | Dependency Installation | | ------------------------------ | --------------------------------------- | | Debian | `apt-get install dirmngr gpg curl gawk` | | CentOS/ Rocky Linux/ AlmaLinux | `yum install gnupg2 curl gawk` | | macOS | `brew install gpg gawk` | We should install dependencies first as some Plugins have post-install hooks. ### Install the Plugin ```shell asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git ``` ## 5. Install a Version Now we have a plugin for Node.js we can install a version of the tool. We can see which versions are available with `asdf list all nodejs` or a subset of versions with `asdf list all nodejs 14`. We will just install the `latest` available version: ```shell asdf install nodejs latest ``` ::: tip Note `asdf` enforces exact versions. `latest` is a helper throughout `asdf` that will resolve to the actual version number at the time of execution. ::: ## 6. Set a Version `asdf` performs a version lookup of a tool in all `.tool-versions` files from the current working directory up to the `$HOME` directory. The lookup occurs just-in-time when you execute a tool that `asdf` manages. ::: warning Without a version listed for a tool execution of the tool will **error**. `asdf current` will show you the tool & version resolution, or absence of, from your current directory so you can observe which tools will fail to execute. ::: ### Global Global defaults are managed in `$HOME/.tool-versions`. Set a global version with: ```shell asdf global nodejs latest ``` `$HOME/.tool-versions` will then look like: ``` nodejs 16.5.0 ``` Some OSs already have tools installed that are managed by the system and not `asdf`, `python` is a common example. You need to tell `asdf` to pass the management back to the system. The [Versions reference section](/manage/versions.md) will guide you. ### Local Local versions are defined in the `$PWD/.tool-versions` file (your current working directory). Usually, this will be the Git repository for a project. When in your desired directory execute: ```shell asdf local nodejs latest ``` `$PWD/.tool-versions` will then look like: ``` nodejs 16.5.0 ``` ### Using Existing Tool Version Files `asdf` supports the migration from existing version files from other version managers. Eg: `.ruby-version` for the case of `rbenv`. This is supported on a per-plugin basis. [`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/) supports this via both `.nvmrc` and `.node-version` files. To enable this, add the following to your `asdf` configuration file `$HOME/.asdfrc`: ``` legacy_version_file = yes ``` See the [configuration](/manage/configuration.md) reference page for more config options. ## Guide Complete! That completes the Getting Started guide for `asdf` :tada: You can now manage `nodejs` versions for your project. Follow similar steps for each type of tool in your project! `asdf` has many more commands to become familiar with, you can see them all by running `asdf --help` or `asdf`. The core of the commands are broken into three categories: - [core `asdf`](/manage/core.md) - [plugins](/manage/plugins.md) - [versions (of tools)](/manage/versions.md) --- ## File: docs/guide/introduction.md # Introduction `asdf` is a tool version manager. All tool version definitions are contained within one file (`.tool-versions`) which you can check in to your project's Git repository to share with your team, ensuring everyone is using the **exact** same versions of tools. The old way of working required multiple CLI version managers, each with their distinct API, configurations files and implementation (e.g. `$PATH` manipulation, shims, environment variables, etc...). `asdf` provides a single interface and configuration file to simplify development workflows, and can be extended to all tools and runtimes via a simple plugin interface. ## How It Works Once `asdf` core is set up with your Shell configuration, plugins are installed to manage particular tools. When a tool is installed by a plugin, the executables that are installed have [shims]() created for each of them. When you try and run one of these executables, the shim is run instead, allowing `asdf` to identify which version of the tool is set in `.tool-versions` and execute that version. ## Related Projects ### nvm / n / rbenv etc Tools like [nvm](https://github.com/nvm-sh/nvm), [n](https://github.com/tj/n) and [rbenv](https://github.com/rbenv/rbenv) are all written as Shell scripts which create shims for the executables installed by these tools. `asdf` is very similar and was built to compete in this space of tool/runtime version management. The differentiating factor for `asdf` is its plugin system which removes the need for a manager per tool/runtime, different commands per manager and different `*-version` files in your repo. ### direnv > augments existing shells with a new feature that can load and unload environment variables depending on the current directory. `asdf` does not manage Environment Variables, however there is a plugin [`asdf-direnv`](https://github.com/asdf-community/asdf-direnv) to integrate direnv behaviour with `asdf`. See [direnv docs](https://direnv.net/) for more. ### Homebrew > The Missing Package Manager for macOS (or Linux) Homebrew manages your packages and their upstream dependencies. `asdf` does not manage upstream dependencies, it is not a package manager, that burden is upon the user, though we try and keep the dependency list small. See [Homebrew docs](https://brew.sh/) for more. ### NixOS > Nix is a tool that takes a unique approach to package management and system configuration NixOS aims to build truly reproducible environments by managing exact versions of packages up the entire dependency tree of each tool, something `asdf` does not do. NixOS does this with its own programming language, many CLI tools and a package collection of over 60,000 packages. Again, `asdf` does not manage upstream dependencies and is not a package manager. See [NixOS docs](https://nixos.org/guides/how-nix-works.html) for more. ## Why use asdf? `asdf` ensures teams are using the **exact** same versions of tools, with support for **many** tools via a plugin system, and the _simplicity and familiarity_ of being a single **Shell** script you include in your Shell config. ::: tip Note `asdf` is not intended to be a system package manager. It is a tool version manager. Just because you can create a plugin for any tool and manage its versions with `asdf`, does not mean that is the best course of action for that specific tool. ::: --- ## File: docs/guide/upgrading-to-v0-16.md # Upgrading to 0.16.0 asdf versions 0.15.0 and older were written in Bash and distributed as a set of Bash scripts with the `asdf` function loaded into your shell. asdf version 0.16.0 is a complete rewrite of asdf in Go. Since it is a complete rewrite there are a [number of breaking](#breaking-changes) changes and it is now a binary rather than a set of scripts. ## Installation Installation of version 0.16.0 and newer is much simpler than previous versions of asdf. It's just three steps: * Download the appropriate `asdf` binary for your operating system/architecture combo via [any of the install methods available](/guide/getting-started.html#_1-install-asdf). If using a package manager verify it's installing version 0.16.0 or later. * Add `$ASDF_DATA_DIR/shims` to the front of your `$PATH`. * Optionally, if you previously had a customized location for asdf data, set `ASDF_DATA_DIR` to the directory you already had the old version installing plugins, versions, and shims. If your operating system's package manager already offers asdf 0.16.0 that is probably the best method for installing it. Upgrading asdf is now only possible via OS package managers and manual installation. There is no self-upgrade feature. ### Upgrading Without Losing Data You can upgrade to the latest version of asdf without losing your existing install data. It's the same sequence of steps as above. #### 1. Download the appropriate `asdf` binary for your operating system & architecture Download the binary from the [GitHub releases page](https://github.com/asdf-vm/asdf/releases) and place it in a directory on your path. I chose to place the asdf binary in `$HOME/bin` and then added `$HOME/bin` to the front of my `$PATH`: ``` # In .zshrc, .bashrc, etc... export PATH="$HOME/bin:$PATH" ``` #### 2. Set `ASDF_DATA_DIR` Run `asdf info` and copy the line containing the `ASDF_DATA_DIR` variable: ``` ... ASDF_DATA_DIR="/home/myuser/.asdf" ... ``` In your shell RC file (`.zshrc` if Zsh, `.bashrc` if Bash, etc...) add a line to the end setting `ASDF_DATA_DIR` to that same value: ```bash export ASDF_DATA_DIR="/home/myuser/.asdf" ``` #### 3. Add `$ASDF_DATA_DIR/shims` to the front of your `$PATH` In your shell RC file (same file as step #2) add `$ASDF_DATA_DIR/shims` to the front of your path: ```bash export ASDF_DATA_DIR="/home/myuser/.asdf" export PATH="$ASDF_DATA_DIR/shims:$PATH" ``` #### 4. Remove Old Config In your shells RC file you'll have the old code running the asdf shell script at startup. It'll probably look something like this: ``` . "$HOME/.asdf/asdf.sh" ``` Or this: ``` . /opt/homebrew/opt/asdf/libexec/asdf.sh ``` Comment out these lines or remove them entirely. If you are not using Zsh or Bash please see the legacy [Getting Started guide](https://asdf-vm.com/guide/getting-started-legacy.html#_3-install-asdf) for the code snippet you need to remove. #### 5. Regenerate Shims Verify that `asdf` command in your shell session is version 0.16.0+ by running `asdf --help`. If you still see an older version you will need to start a new shell session. Once you've verified the `asdf` command is the new version run `asdf reshim` to regenerate all shims. This is necessary as the old shims may still reference the old Bash version. ### Testing If you aren't sure if the upgrade to 0.16.0 will break things for you can you can test by installing 0.16.0 in addition to your existing version as described above in "Upgrading Without Losing Data". If it turns out that the upgrade to 0.16.0 or greater breaks things for you you can revert back to the older version. Remove the lines you added to your shell RC file, and add back in the lines you removed or commented out. ### Removing old files **Only do this after you've completed all the steps above and have verified your new asdf installation is working correctly!** After upgrade there are various files you can remove from the old Bash-script based versions of asdf. Most of the files in your data directory (typically `~/.asdf/`) can be removed. Note that you don't have to do this. There is no harm in keeping the files from old versions of asdf around. The only directories that must be **kept** are: * `downloads/` * `installs/` * `plugins/` * `shims/` The rest can be deleted. This can be done in one command with `find`: ``` find ${ASDF_DATA_DIR:-$HOME/.asdf}/ -maxdepth 1 -mindepth 1 -not -name downloads -not -name plugins -not -name installs -not -name shims -exec rm -r {} \; ``` ## Breaking Changes ### Hyphenated commands have been removed asdf version 0.15.0 and earlier supported by hyphenated and non-hyphenated versions of certain commands. With version 0.16.0 only the non-hyphenated versions are supported. The affected commands: * `asdf list-all` -> `asdf list all` * `asdf plugin-add` -> `asdf plugin add` * `asdf plugin-list` -> `asdf plugin list` * `asdf plugin-list-all` -> `asdf plugin list all` * `asdf plugin-update` -> `asdf plugin update` * `asdf plugin-remove` -> `asdf plugin remove` * `asdf plugin-test` -> `asdf plugin test` * `asdf shim-versions` -> `asdf shimversions` ### `asdf global` and `asdf local` commands have been replaced with `asdf set` `asdf global` and `asdf local` have been removed. The "global" and "local" terminology was wrong and also misleading. asdf doesn't actually support "global" versions that apply everywhere. Any version that was specified with `asdf global` could easily be overridden by a `.tool-versions` file in your current directory specifying a different version. This was confusing to users. The new `asdf set` behaves the same as `asdf local` by default, but also has flags for setting versions in the user's home directory (`--home`) and in an existing `.tool-versions` file in one of the parent directories (`--parent`). This new interface will hopefully convey a better understanding of how asdf resolves versions and provide equivalent functionality. ### `asdf update` command has been removed Updates can no longer be performed this way. Use your OS package manager or download the latest binary manually. Additionally, the `asdf update` command present in versions 0.15.0 and older cannot upgrade to version 0.16.0 because the install process has changed. **You cannot upgrade to the latest Go implementation using `asdf update`.** ### `asdf shell` command has been removed This command actually set an environment variable in the user's current shell session. It was able to do this because `asdf` was actually a shell function, not an executable. The new rewrite removes all shell code from asdf, and it is now a binary rather than a shell function, so setting environment variables directly in the shell is no longer possible. ### `asdf current` has changed Instead of three columns in the output, with the last being either the location the version is set or a suggested command that could be run to set or install a version. The third column has been split into two columns. The third column now only indicates the source of the version if it is set (typically either version file or environment variable) and the fourth is a boolean indicating whether the specified version is actually installed. If it is not installed, a suggested install command is shown. ### Plugin extension commands must now be prefixed with `cmd` Previously plugin extension commands could be run like this: ``` asdf nodejs nodebuild --version ``` Now they must be prefixed with `cmd` to avoid causing confusion with built-in commands: ``` asdf cmd nodejs nodebuild --version ``` ### Extension commands have been redesigned There are a number of breaking changes for plugin extension commands: * They must be runnable by `exec` syscall. If your extension commands are shell scripts in order to be run with `exec` they must start with a proper shebang line. * They can now be binaries or scripts in any language. It no longer makes sense to require a `.bash` extension as it is misleading. * They must have executable permission set. * They are no longer sourced by asdf as Bash scripts when they lack executable permission. Additionally, only the first argument after plugin name is used to determine the extension command to run. This means effectively there is the default `command` extension command that asdf defaults to when no command matching the first argument after plugin name is found. For example: ``` foo/ lib/commands/ command command-bar command-bat-man ``` Previously these scripts would work like this: ``` $ asdf cmd foo # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command` $ asdf cmd foo bar # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bar` $ asdf cmd foo bat man # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat-man` ``` Now: ``` $ asdf cmd foo # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command` $ asdf cmd foo bar # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bar` $ asdf cmd foo bat man # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat man` ``` ### Executables Shims Resolve to Must Runnable by `syscall.Exec` The most obvious example of this breaking change are scripts that lack a proper shebang line. asdf 0.15.0 and older were implemented in Bash, so as long it was an executable that could be executed with Bash it would run. This mean that scripts lacking a shebang could still be run by `asdf exec`. With asdf 0.16.x implemented in Go we now invoke executables via Go's `syscall.Exec` function, which cannot handle scripts lacking a shebang. In practice this isn't much of a problem. Most shell scripts DO contain a shebang line. If a tool managed by asdf provides scripts that don't have a shebang line one will need to be added to them. ### Custom shim templates are no longer supported This was a rarely used feature. The only plugin maintained by the core team that used it was the Elixir plugin, and it no longer needs it. This feature was originally added so that shim that get evaluated by a program rather than executed contain code that is suitable for evaluation by a particular program (in the case of Elixir this was the `iex` shell). Upon further investigation it seems this feature only exists because the `PATH` for executables was sometimes improperly set to include the **shims** rather than the other **executables** for the selected version(s). --- ## File: docs/ja-jp/guide/parts/install-dependencies.md ##### 依存関係のインストール asdfの動作には`git`が必要です。以下の表は、 _あなたが使用している_ パッケージマネージャで実行するコマンドの _一部例_ です(いくつかのツールは、後の手順で自動的にインストールされます)。 | OS | パッケージマネージャー | コマンド | | ----- | ------------------ | ----------------------------- | | linux | Aptitude | `apt install git` | | linux | DNF | `dnf install git` | | linux | Pacman | `pacman -S git` | | linux | Zypper | `zypper install git` | | macOS | Homebrew | `brew install coreutils git` | | macOS | Spack | `spack install coreutils git` | ::: tip 備考 お使いのシステムの構成によっては、`sudo`が必要となる場合があります。 :::