asdf core contribution guide.
Fork asdf on GitHub and/or Git clone the default branch:
# clone your fork
+git clone https://github.com/<GITHUB_USER>/asdf.git
+# or clone asdf
+git clone https://github.com/asdf-vm/asdf.gitThe tools for core development are in this repo's .tool-versions. If you wish to manage with asdf itself, add the plugins:
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.gitInstall the versions to develop asdf with:
asdf installIt 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:
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:
# 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.bashTIP
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
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 for more details.
/installs
+/downloads
+/plugins
+/shims
+repository
+.vagrant
+keyrings
+/tmp.git-blame-ignore-revs asdf uses a .git-blame-ignore-revs to reduce noise when running a blame. See the git blame documentation for more information.
Use the file with git blame like so:
git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.batsOptionally, configure to use the file on every invocation of blame without manually supplying it:
git config blame.ignoreRevsFile .git-blame-ignore-revsIt is possible to configure IDEs to use this file. For example, when using VSCode (with GitLens), write the following to .vscode/settings.json:
{
+ "gitlens.advanced.blame.customArguments": [
+ "--ignore-revs-file",
+ ".git-blame-ignore-revs"
+ ]
+}Execute tests locally with:
./scripts/test.bashBefore writing tests please read:
test/scripts/test.bashBats 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:
# 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" >&3This is further documented in bats-core Printing to the Terminal.
asdf is using an automated release tool called Release Please to automatically bump the SemVer version and generate the Changelog. This information is determined by reading the commit history since the last release.
Conventional Commit messages 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.
Conventional Commit follows this format:
<type>[optional scope][optional !]: <description>
+
+<!-- examples -->
+fix: some fix
+feat: a new feature
+docs: some documentation update
+docs(website): some change for the website
+feat!: feature with breaking changeThe full list of <types> are: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
!: indicates a breaking changefix: will create a new SemVer patchfeat: will create a new SemVer minor<type>!: will create a new SemVer majorThe Pull Request Title must follow this format.
TIP
Use Conventional Commit message format for your Pull Request Title.
The asdf-alpine and 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.
`,47)]))}const k=e(n,[["render",l]]);export{g as __pageData,k as default}; diff --git a/assets/contribute_core.md.BABeyVan.lean.js b/assets/contribute_core.md.BABeyVan.lean.js new file mode 100644 index 00000000..66d8cade --- /dev/null +++ b/assets/contribute_core.md.BABeyVan.lean.js @@ -0,0 +1,38 @@ +import{_ as e,c as a,a2 as i,o as t}from"./chunks/framework.C9NVOr0y.js";const g=JSON.parse('{"title":"asdf","description":"","frontmatter":{},"headers":[],"relativePath":"contribute/core.md","filePath":"contribute/core.md","lastUpdated":1728309110000}'),n={name:"contribute/core.md"};function l(o,s,p,r,h,d){return t(),a("div",null,s[0]||(s[0]=[i(`asdf core contribution guide.
Fork asdf on GitHub and/or Git clone the default branch:
# clone your fork
+git clone https://github.com/<GITHUB_USER>/asdf.git
+# or clone asdf
+git clone https://github.com/asdf-vm/asdf.gitThe tools for core development are in this repo's .tool-versions. If you wish to manage with asdf itself, add the plugins:
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.gitInstall the versions to develop asdf with:
asdf installIt 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:
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:
# 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.bashTIP
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
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 for more details.
/installs
+/downloads
+/plugins
+/shims
+repository
+.vagrant
+keyrings
+/tmp.git-blame-ignore-revs asdf uses a .git-blame-ignore-revs to reduce noise when running a blame. See the git blame documentation for more information.
Use the file with git blame like so:
git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.batsOptionally, configure to use the file on every invocation of blame without manually supplying it:
git config blame.ignoreRevsFile .git-blame-ignore-revsIt is possible to configure IDEs to use this file. For example, when using VSCode (with GitLens), write the following to .vscode/settings.json:
{
+ "gitlens.advanced.blame.customArguments": [
+ "--ignore-revs-file",
+ ".git-blame-ignore-revs"
+ ]
+}Execute tests locally with:
./scripts/test.bashBefore writing tests please read:
test/scripts/test.bashBats 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:
# 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" >&3This is further documented in bats-core Printing to the Terminal.
asdf is using an automated release tool called Release Please to automatically bump the SemVer version and generate the Changelog. This information is determined by reading the commit history since the last release.
Conventional Commit messages 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.
Conventional Commit follows this format:
<type>[optional scope][optional !]: <description>
+
+<!-- examples -->
+fix: some fix
+feat: a new feature
+docs: some documentation update
+docs(website): some change for the website
+feat!: feature with breaking changeThe full list of <types> are: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
!: indicates a breaking changefix: will create a new SemVer patchfeat: will create a new SemVer minor<type>!: will create a new SemVer majorThe Pull Request Title must follow this format.
TIP
Use Conventional Commit message format for your Pull Request Title.
The asdf-alpine and 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.
`,47)]))}const k=e(n,[["render",l]]);export{g as __pageData,k as default}; diff --git a/assets/contribute_documentation.md.BYyBOKz0.js b/assets/contribute_documentation.md.BYyBOKz0.js new file mode 100644 index 00000000..ff60ed67 --- /dev/null +++ b/assets/contribute_documentation.md.BYyBOKz0.js @@ -0,0 +1,42 @@ +import{_ as i,c as a,a2 as e,o as n}from"./chunks/framework.C9NVOr0y.js";const c=JSON.parse('{"title":"Docs & Site","description":"","frontmatter":{},"headers":[],"relativePath":"contribute/documentation.md","filePath":"contribute/documentation.md","lastUpdated":1687069487000}'),t={name:"contribute/documentation.md"};function l(p,s,h,o,r,d){return n(),a("div",null,s[0]||(s[0]=[e(`Documentation & site contribution guide.
Fork asdf on GitHub and/or Git clone the default branch:
# clone your fork
+git clone https://github.com/<GITHUB_USER>/asdf.git
+# or clone asdf
+git clone https://github.com/asdf-vm/asdf.gitThe tools for Docs site development are managed with asdf in the docs/.tool-versions. Add the plugins with:
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejsInstall the tool version(s) with:
asdf installInstall Node.js dependencies from docs/package.json:
npm installVitePress (v2) is the Static Site Generator (SSG) we use to build the asdf documentation site. It was chosen to replace Docsify.js 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 quicly 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:
To start the local development server:
npm run devFormat the code before committing:
npm run formatasdf is using an automated release pipeline which relies on Conventional Commits in PR titles. Detailed documentation found in the core contribution guide.
When creating a PR for documentation changes please make the PR title with the Conventional Commit type docs in the format docs: <description>.
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 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.jsdocs/.vitepress/sidebars.jsWith the official documentation for these configs living in the Default Theme Reference.
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:
// 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:
docs
+├─ README.md
+├─ foo.md
+├─ nested
+│ └─ README.md
+└─ pt-BR
+ ├─ README.md
+ ├─ foo.md
+ └─ nested
+ └─ README.mdThe official VitePress i18n documentation goes into more detail.
`,37)]))}const g=i(t,[["render",l]]);export{c as __pageData,g as default}; diff --git a/assets/contribute_documentation.md.BYyBOKz0.lean.js b/assets/contribute_documentation.md.BYyBOKz0.lean.js new file mode 100644 index 00000000..ff60ed67 --- /dev/null +++ b/assets/contribute_documentation.md.BYyBOKz0.lean.js @@ -0,0 +1,42 @@ +import{_ as i,c as a,a2 as e,o as n}from"./chunks/framework.C9NVOr0y.js";const c=JSON.parse('{"title":"Docs & Site","description":"","frontmatter":{},"headers":[],"relativePath":"contribute/documentation.md","filePath":"contribute/documentation.md","lastUpdated":1687069487000}'),t={name:"contribute/documentation.md"};function l(p,s,h,o,r,d){return n(),a("div",null,s[0]||(s[0]=[e(`Documentation & site contribution guide.
Fork asdf on GitHub and/or Git clone the default branch:
# clone your fork
+git clone https://github.com/<GITHUB_USER>/asdf.git
+# or clone asdf
+git clone https://github.com/asdf-vm/asdf.gitThe tools for Docs site development are managed with asdf in the docs/.tool-versions. Add the plugins with:
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejsInstall the tool version(s) with:
asdf installInstall Node.js dependencies from docs/package.json:
npm installVitePress (v2) is the Static Site Generator (SSG) we use to build the asdf documentation site. It was chosen to replace Docsify.js 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 quicly 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:
To start the local development server:
npm run devFormat the code before committing:
npm run formatasdf is using an automated release pipeline which relies on Conventional Commits in PR titles. Detailed documentation found in the core contribution guide.
When creating a PR for documentation changes please make the PR title with the Conventional Commit type docs in the format docs: <description>.
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 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.jsdocs/.vitepress/sidebars.jsWith the official documentation for these configs living in the Default Theme Reference.
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:
// 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:
docs
+├─ README.md
+├─ foo.md
+├─ nested
+│ └─ README.md
+└─ pt-BR
+ ├─ README.md
+ ├─ foo.md
+ └─ nested
+ └─ README.mdThe official VitePress i18n documentation goes into more detail.
`,37)]))}const g=i(t,[["render",l]]);export{c as __pageData,g as default}; diff --git a/assets/contribute_first-party-plugins.md.CpFWKmHh.js b/assets/contribute_first-party-plugins.md.CpFWKmHh.js new file mode 100644 index 00000000..e1a12f33 --- /dev/null +++ b/assets/contribute_first-party-plugins.md.CpFWKmHh.js @@ -0,0 +1 @@ +import{_ as r,c as t,a2 as a,o as i}from"./chunks/framework.C9NVOr0y.js";const u=JSON.parse('{"title":"First-Party Plugins","description":"","frontmatter":{},"headers":[],"relativePath":"contribute/first-party-plugins.md","filePath":"contribute/first-party-plugins.md","lastUpdated":1627017981000}'),o={name:"contribute/first-party-plugins.md"};function s(l,e,n,d,c,f){return i(),t("div",null,e[0]||(e[0]=[a('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:
For community plugins, see:
asdf-community organisation: A collaborative, community-driven project for long-term maintenance of asdf plugins.asdf-plugins shortname repo: Short-name list used by asdf core to lookup popular asdf plugins.asdf-plugin topic searchThe 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:
For community plugins, see:
asdf-community organisation: A collaborative, community-driven project for long-term maintenance of asdf plugins.asdf-plugins shortname repo: Short-name list used by asdf core to lookup popular asdf plugins.asdf-plugin topic searchasdf installation involves:
asdf coreasdf.tool-versions config filesasdf 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 |
Note
sudo may be required depending on your system configuration.
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.1We 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 |
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.
Add the following to ~/.bashrc:
. "$HOME/.asdf/asdf.sh"Completions must be configured by adding the following to your .bashrc:
. "$HOME/.asdf/completions/asdf.bash"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:
. "$HOME/.asdf/asdf.sh"Completions must be configured manually with the following entry in your .bash_profile:
. "$HOME/.asdf/completions/asdf.bash"Add asdf.sh to your ~/.bashrc with:
echo -e "\\n. \\"$(brew --prefix asdf)/libexec/asdf.sh\\"" >> ~/.bashrcCompletions will need to be configured as per Homebrew's instructions or with the following:
echo -e "\\n. \\"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\\"" >> ~/.bashrcIf 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:
echo -e "\\n. \\"$(brew --prefix asdf)/libexec/asdf.sh\\"" >> ~/.bash_profileCompletions will need to be configured as per Homebrew's instructions or with the following:
echo -e "\\n. \\"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\\"" >> ~/.bash_profileAdd the following to ~/.bashrc:
. /opt/asdf-vm/asdf.shbash-completion needs to be installed for the completions to work.
Add the following to ~/.config/fish/config.fish:
source ~/.asdf/asdf.fishCompletions must be configured manually with the following command:
mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completionsAdd asdf.fish to your ~/.config/fish/config.fish with:
echo -e "\\nsource "(brew --prefix asdf)"/libexec/asdf.fish" >> ~/.config/fish/config.fishCompletions are handled by Homebrew for the Fish shell. Friendly!
Add the following to ~/.config/fish/config.fish:
source /opt/asdf-vm/asdf.fishCompletions are automatically configured on installation by the AUR package.
Add asdf.elv to your ~/.config/elvish/rc.elv with:
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.elvCompletions are automatically configured.
Add asdf.elv to your ~/.config/elvish/rc.elv with:
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.elvCompletions are automatically configured.
Add asdf.elv to your ~/.config/elvish/rc.elv with:
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.elvCompletions are automatically configured.
Add the following to ~/.zshrc:
. "$HOME/.asdf/asdf.sh"OR use a ZSH Framework plugin like asdf for oh-my-zsh 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:
# append completions to fpath
+fpath=(\${ASDF_DIR}/completions $fpath)
+# initialise completions with ZSH's compinit
+autoload -Uz compinit && compinitcompinit setup, ensure compinit is below your sourcing of asdf.shcompinit setup with a ZSH Framework, ensure compinit is below your sourcing of the frameworkWarning
If you are using a ZSH Framework the associated asdf plugin may need to be updated to use the new ZSH completions properly via fpath. The Oh-My-ZSH asdf plugin is yet to be updated, see ohmyzsh/ohmyzsh#8837.
Add asdf.sh to your ~/.zshrc with:
echo -e "\\n. $(brew --prefix asdf)/libexec/asdf.sh" >> \${ZDOTDIR:-~}/.zshrcOR use a ZSH Framework plugin like asdf for oh-my-zsh 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. 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. The Oh-My-ZSH asdf plugin is yet to be updated, see ohmyzsh/ohmyzsh#8837.
Add the following to ~/.zshrc:
. /opt/asdf-vm/asdf.shCompletions are placed in a ZSH friendly location, but ZSH must be configured to use the autocompletions.
Add the following to ~/.config/powershell/profile.ps1:
. "$HOME/.asdf/asdf.ps1"Add asdf.sh to your ~/.config/powershell/profile.ps1 with:
echo -e "\\n. \\"$(brew --prefix asdf)/libexec/asdf.ps1\\"" >> ~/.config/powershell/profile.ps1Add the following to ~/.config/powershell/profile.ps1:
. /opt/asdf-vm/asdf.ps1Add asdf.nu to your ~/.config/nushell/config.nu with:
"\\n$env.ASDF_DIR = ($env.HOME | path join '.asdf')\\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-pathCompletions are automatically configured
Add asdf.nu to your ~/.config/nushell/config.nu with:
"\\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-pathCompletions are automatically configured
Add asdf.nu to your ~/.config/nushell/config.nu with:
"\\n$env.ASDF_DIR = '/opt/asdf-vm/'\\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-pathCompletions are automatically configured.
Add the following to ~/.profile:
export ASDF_DIR="$HOME/.asdf"
+. "$HOME/.asdf/asdf.sh"Add asdf.sh to your ~/.profile with:
echo -e "\\nexport ASDF_DIR=\\"$(brew --prefix asdf)/libexec/asdf.sh\\"" >> ~/.profile
+echo -e "\\n. \\"$(brew --prefix asdf)/libexec/asdf.sh\\"" >> ~/.profileAdd the following to ~/.profile:
export ASDF_DIR="/opt/asdf-vm"
+. /opt/asdf-vm/asdf.shasdf 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 forcily 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.
This completes the installation of the asdf core 🎉
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.
For demonstration purposes we will install & set Node.js via the asdf-nodejs plugin.
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.
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.gitNow 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:
asdf install nodejs latestNote
asdf enforces exact versions. latest is a helper throughout asdf that will resolve to the actual version number at the time of execution.
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 defaults are managed in $HOME/.tool-versions. Set a global version with:
asdf global nodejs latest$HOME/.tool-versions will then look like:
nodejs 16.5.0Some 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 will guide you.
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:
asdf local nodejs latest$PWD/.tool-versions will then look like:
nodejs 16.5.0asdf 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 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 = yesSee the configuration reference page for more config options.
That completes the Getting Started guide for asdf 🎉 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:
asdf installation involves:
asdf coreasdf.tool-versions config filesasdf 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 |
Note
sudo may be required depending on your system configuration.
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.1We 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 |
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.
Add the following to ~/.bashrc:
. "$HOME/.asdf/asdf.sh"Completions must be configured by adding the following to your .bashrc:
. "$HOME/.asdf/completions/asdf.bash"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:
. "$HOME/.asdf/asdf.sh"Completions must be configured manually with the following entry in your .bash_profile:
. "$HOME/.asdf/completions/asdf.bash"Add asdf.sh to your ~/.bashrc with:
echo -e "\\n. \\"$(brew --prefix asdf)/libexec/asdf.sh\\"" >> ~/.bashrcCompletions will need to be configured as per Homebrew's instructions or with the following:
echo -e "\\n. \\"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\\"" >> ~/.bashrcIf 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:
echo -e "\\n. \\"$(brew --prefix asdf)/libexec/asdf.sh\\"" >> ~/.bash_profileCompletions will need to be configured as per Homebrew's instructions or with the following:
echo -e "\\n. \\"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\\"" >> ~/.bash_profileAdd the following to ~/.bashrc:
. /opt/asdf-vm/asdf.shbash-completion needs to be installed for the completions to work.
Add the following to ~/.config/fish/config.fish:
source ~/.asdf/asdf.fishCompletions must be configured manually with the following command:
mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completionsAdd asdf.fish to your ~/.config/fish/config.fish with:
echo -e "\\nsource "(brew --prefix asdf)"/libexec/asdf.fish" >> ~/.config/fish/config.fishCompletions are handled by Homebrew for the Fish shell. Friendly!
Add the following to ~/.config/fish/config.fish:
source /opt/asdf-vm/asdf.fishCompletions are automatically configured on installation by the AUR package.
Add asdf.elv to your ~/.config/elvish/rc.elv with:
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.elvCompletions are automatically configured.
Add asdf.elv to your ~/.config/elvish/rc.elv with:
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.elvCompletions are automatically configured.
Add asdf.elv to your ~/.config/elvish/rc.elv with:
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.elvCompletions are automatically configured.
Add the following to ~/.zshrc:
. "$HOME/.asdf/asdf.sh"OR use a ZSH Framework plugin like asdf for oh-my-zsh 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:
# append completions to fpath
+fpath=(\${ASDF_DIR}/completions $fpath)
+# initialise completions with ZSH's compinit
+autoload -Uz compinit && compinitcompinit setup, ensure compinit is below your sourcing of asdf.shcompinit setup with a ZSH Framework, ensure compinit is below your sourcing of the frameworkWarning
If you are using a ZSH Framework the associated asdf plugin may need to be updated to use the new ZSH completions properly via fpath. The Oh-My-ZSH asdf plugin is yet to be updated, see ohmyzsh/ohmyzsh#8837.
Add asdf.sh to your ~/.zshrc with:
echo -e "\\n. $(brew --prefix asdf)/libexec/asdf.sh" >> \${ZDOTDIR:-~}/.zshrcOR use a ZSH Framework plugin like asdf for oh-my-zsh 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. 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. The Oh-My-ZSH asdf plugin is yet to be updated, see ohmyzsh/ohmyzsh#8837.
Add the following to ~/.zshrc:
. /opt/asdf-vm/asdf.shCompletions are placed in a ZSH friendly location, but ZSH must be configured to use the autocompletions.
Add the following to ~/.config/powershell/profile.ps1:
. "$HOME/.asdf/asdf.ps1"Add asdf.sh to your ~/.config/powershell/profile.ps1 with:
echo -e "\\n. \\"$(brew --prefix asdf)/libexec/asdf.ps1\\"" >> ~/.config/powershell/profile.ps1Add the following to ~/.config/powershell/profile.ps1:
. /opt/asdf-vm/asdf.ps1Add asdf.nu to your ~/.config/nushell/config.nu with:
"\\n$env.ASDF_DIR = ($env.HOME | path join '.asdf')\\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-pathCompletions are automatically configured
Add asdf.nu to your ~/.config/nushell/config.nu with:
"\\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-pathCompletions are automatically configured
Add asdf.nu to your ~/.config/nushell/config.nu with:
"\\n$env.ASDF_DIR = '/opt/asdf-vm/'\\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-pathCompletions are automatically configured.
Add the following to ~/.profile:
export ASDF_DIR="$HOME/.asdf"
+. "$HOME/.asdf/asdf.sh"Add asdf.sh to your ~/.profile with:
echo -e "\\nexport ASDF_DIR=\\"$(brew --prefix asdf)/libexec/asdf.sh\\"" >> ~/.profile
+echo -e "\\n. \\"$(brew --prefix asdf)/libexec/asdf.sh\\"" >> ~/.profileAdd the following to ~/.profile:
export ASDF_DIR="/opt/asdf-vm"
+. /opt/asdf-vm/asdf.shasdf 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 forcily 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.
This completes the installation of the asdf core 🎉
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.
For demonstration purposes we will install & set Node.js via the asdf-nodejs plugin.
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.
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.gitNow 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:
asdf install nodejs latestNote
asdf enforces exact versions. latest is a helper throughout asdf that will resolve to the actual version number at the time of execution.
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 defaults are managed in $HOME/.tool-versions. Set a global version with:
asdf global nodejs latest$HOME/.tool-versions will then look like:
nodejs 16.5.0Some 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 will guide you.
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:
asdf local nodejs latest$PWD/.tool-versions will then look like:
nodejs 16.5.0asdf 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 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 = yesSee the configuration reference page for more config options.
That completes the Getting Started guide for asdf 🎉 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:
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.
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.
Tools like nvm, n and 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.
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 to integrate direnv behaviour with asdf.
See direnv docs for more.
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 for more.
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 for more.
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.
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.
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.
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.
Tools like nvm, n and 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.
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 to integrate direnv behaviour with asdf.
See direnv docs for more.
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 for more.
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 for more.
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.
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.