From a5beedf30d115fdbdf4feb2925c6d15a943df119 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Wed, 18 Dec 2024 16:08:35 -0500 Subject: [PATCH 01/10] docs(golang-rewrite): add sidebar link for 0.16.0 upgrade guide --- docs/.vitepress/sidebars.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/.vitepress/sidebars.ts b/docs/.vitepress/sidebars.ts index 1366590e9..9127e83ef 100644 --- a/docs/.vitepress/sidebars.ts +++ b/docs/.vitepress/sidebars.ts @@ -5,6 +5,8 @@ const en = [ items: [ { text: "What is asdf?", link: "/guide/introduction" }, { text: "Getting Started", link: "/guide/getting-started" }, + { text: "Upgrading to 0.16.0", link: "/guide/upgrading-from-v0-15-to-v0-16" }, + ], }, { From ffd66381a8431f64df8061a9e750c7158d185e03 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Tue, 24 Dec 2024 13:24:30 -0500 Subject: [PATCH 02/10] chore(docs): rename 0.16.0 upgrade guide page --- docs/.vitepress/sidebars.ts | 2 +- ...0-15-to-v0-16.md => upgrading-to-v0-16.md} | 146 +++++++++--------- 2 files changed, 76 insertions(+), 72 deletions(-) rename docs/guide/{upgrading-from-v0-15-to-v0-16.md => upgrading-to-v0-16.md} (90%) diff --git a/docs/.vitepress/sidebars.ts b/docs/.vitepress/sidebars.ts index 9127e83ef..262bbd8e7 100644 --- a/docs/.vitepress/sidebars.ts +++ b/docs/.vitepress/sidebars.ts @@ -5,7 +5,7 @@ const en = [ items: [ { text: "What is asdf?", link: "/guide/introduction" }, { text: "Getting Started", link: "/guide/getting-started" }, - { text: "Upgrading to 0.16.0", link: "/guide/upgrading-from-v0-15-to-v0-16" }, + { text: "Upgrading to 0.16.0", link: "/guide/upgrading-to-v0-16" }, ], }, diff --git a/docs/guide/upgrading-from-v0-15-to-v0-16.md b/docs/guide/upgrading-to-v0-16.md similarity index 90% rename from docs/guide/upgrading-from-v0-15-to-v0-16.md rename to docs/guide/upgrading-to-v0-16.md index 8b1bbccf8..cca671058 100644 --- a/docs/guide/upgrading-from-v0-15-to-v0-16.md +++ b/docs/guide/upgrading-to-v0-16.md @@ -1,17 +1,85 @@ -# Upgrading From Version 0.15.x to 0.16.0 +# 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.15.0 is a complete rewrite of asdf in Go. Since it is a complete rewrite -there are a number of breaking changes and it is now distributed as a binary -rather than a set of scripts. +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 is much simpler than previous versions of asdf. +It's just three steps: + +* Download the appropriate `asdf` binary for your operating system/architecture combo and place it in a directory on your `$PATH` +* 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 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" +``` + +### 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 breaks things for you simply remove the lines you added to your shell +RC file. ## 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.15.0 only the 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` @@ -40,7 +108,7 @@ resolves versions and provide equivalent functionality. 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.15.0 because +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`.** @@ -124,7 +192,7 @@ $ asdf cmd foo bat man # same as running `$ASDF_DATA_DIR/plugins/foo/lib/command 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.15.x +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. @@ -142,67 +210,3 @@ executed contain code that is suitable for evaluation by a particular program 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). - -## Installation - -Installation of version 0.15.0 is much simpler than previous versions of asdf. It's just three steps: - -* Download the appropriate `asdf` binary for your operating system/architecture combo and place it in a directory on your `$PATH` -* Set `ASDF_DATA_DIR` to the directory you'd like asdf to install plugins, versions, and shims. -* Add `$ASDF_DATA_DIR/shims` to the front of your `$PATH. - -If your operating system's package manager already offers asdf 0.15.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 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" -``` - -### Testing - -If you aren't sure if the upgrade to 0.15.0 will break things for you can you -can test by installing 0.15.0 in addition to your existing version as described -above in "Upgrading Without Losing Data". If it turns out that the upgrade to -0.15.0 breaks things for you simply remove the lines you added to your shell -RC file. From a4406bb0a2b109cb211ffd7965c2571a7e21b173 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Wed, 25 Dec 2024 09:17:05 -0500 Subject: [PATCH 03/10] chore(docs): add legacy getting started guide --- docs/.vitepress/sidebars.ts | 1 + docs/guide/getting-started-legacy.md | 474 +++++++++++++++++++++++++++ 2 files changed, 475 insertions(+) create mode 100644 docs/guide/getting-started-legacy.md diff --git a/docs/.vitepress/sidebars.ts b/docs/.vitepress/sidebars.ts index 262bbd8e7..48377a315 100644 --- a/docs/.vitepress/sidebars.ts +++ b/docs/.vitepress/sidebars.ts @@ -5,6 +5,7 @@ const en = [ items: [ { text: "What is asdf?", link: "/guide/introduction" }, { text: "Getting Started", link: "/guide/getting-started" }, + { text: "Getting Started (pre-0.16.0)", link: "/guide/getting-started-legacy" }, { text: "Upgrading to 0.16.0", link: "/guide/upgrading-to-v0-16" }, ], diff --git a/docs/guide/getting-started-legacy.md b/docs/guide/getting-started-legacy.md new file mode 100644 index 000000000..b775537af --- /dev/null +++ b/docs/guide/getting-started-legacy.md @@ -0,0 +1,474 @@ +# 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 + +**Warning** + +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](https://github.com/ohmyzsh/ohmyzsh/pull/8837). +::: + +::: 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`. The Oh-My-ZSH asdf plugin is yet to be updated, see [ohmyzsh/ohmyzsh#8837](https://github.com/ohmyzsh/ohmyzsh/pull/8837). +::: + +::: 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) From b341db19799a9a2d4ae0ef7365d4512a6f7b1fa8 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Wed, 25 Dec 2024 10:31:24 -0500 Subject: [PATCH 04/10] chore(docs): update installation instructions --- docs/guide/getting-started.md | 265 +++++++--------------------------- 1 file changed, 51 insertions(+), 214 deletions(-) diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 7dc2391b1..c630ea49b 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -1,26 +1,17 @@ # 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). +asdf primarily requires `git`. 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` | +| 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 Note @@ -28,115 +19,77 @@ asdf primarily requires `git` & `curl`. Here is a _non-exhaustive_ list of comma ::: -## 2. Download asdf - -### Official Download - - - - -```shell -git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.15.0 - -``` - - +## 2. Install asdf -### Community Supported Download Methods +asdf can be installed in several different ways: -We highly recommend using the official `git` method. +::: details With Package Manager - **Recommended** -| Method | Command | +| Package Manager | 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) +::: details Download Pre-Compiled Binary - **Easy** -If using **macOS Catalina or newer**, the default shell has changed to **ZSH**. Unless changing back to Bash, follow the ZSH instructions. +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. -Add the following to `~/.bash_profile`: - -```shell -. "$HOME/.asdf/asdf.sh" -``` +::: -Completions must be configured manually with the following entry in your `.bash_profile`: +::: details With `go install` -```shell -. "$HOME/.asdf/completions/asdf.bash" -``` + +1. [Install Go](https://go.dev/doc/install) +2. Run `go install github.com/asdf-vm/asdf@v0.16.0` + ::: -::: details Bash & Homebrew - -Add `asdf.sh` to your `~/.bashrc` with: +::: details Build from Source -```shell -echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bashrc -``` + +1. Clone the asdf repository: + ```shell + git clone https://github.com/asdf-vm/asdf.git --branch v0.16.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. -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 -``` +## 3. Set up completions -::: +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 & Homebrew (macOS) +**macOS users, be sure to read the warning about `path_helper` at the end of this section.** -If using **macOS Catalina or newer**, the default shell has changed to **ZSH**. Unless changing back to Bash, follow the ZSH instructions. +::: details Bash -Add `asdf.sh` to your `~/.bash_profile` with: +**macOS Catalina or newer**: The default shell has changed to **ZSH**. Unless changing back to Bash, follow the ZSH instructions. -```shell -echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bash_profile -``` +**Pacman**: [`bash-completion`](https://wiki.archlinux.org/title/bash#Common_programs_and_options) needs to be installed for the completions to work. -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: +Add the following to `~/.bashrc`: ```shell -echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bash_profile +. "$HOME/.asdf/asdf.sh" ``` -::: - -::: details Bash & Pacman - -Add the following to `~/.bashrc`: +Completions must be configured by adding the following to your `.bashrc`: ```shell -. /opt/asdf-vm/asdf.sh +. "$HOME/.asdf/completions/asdf.bash" ``` -[`bash-completion`](https://wiki.archlinux.org/title/bash#Common_programs_and_options) needs to be installed for the completions to work. ::: -::: details Fish & Git +::: details Fish Add the following to `~/.config/fish/config.fish`: @@ -150,31 +103,12 @@ Completions must be configured manually with the following command: 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 -``` +Pacman: Completions are automatically configured on installation by the AUR package. ::: -::: details Elvish & Git +::: details Elvish Add `asdf.elv` to your `~/.config/elvish/rc.elv` with: @@ -188,33 +122,7 @@ 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 +::: details ZSH Add the following to `~/.zshrc`: @@ -249,20 +157,11 @@ 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`. The Oh-My-ZSH asdf plugin is yet to be updated, see [ohmyzsh/ohmyzsh#8837](https://github.com/ohmyzsh/ohmyzsh/pull/8837). -::: - -::: 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 +::: details PowerShell Core Add the following to `~/.config/powershell/profile.ps1`: @@ -272,27 +171,7 @@ Add the following to `~/.config/powershell/profile.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 +::: details Nushell Add `asdf.nu` to your `~/.config/nushell/config.nu` with: @@ -303,29 +182,7 @@ Add `asdf.nu` to your `~/.config/nushell/config.nu` with: 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 +::: details POSIX Shell Add the following to `~/.profile`: @@ -336,28 +193,6 @@ export ASDF_DIR="$HOME/.asdf" ::: -::: 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 @@ -418,6 +253,8 @@ asdf install nodejs latest 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. + ### Global Global defaults are managed in `$HOME/.tool-versions`. Set a global version with: From 6e6892c5339006bae22ae1a45883effdad5f98ec Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Wed, 25 Dec 2024 16:56:55 -0500 Subject: [PATCH 05/10] chore(docs): update Bash and Fish configuration instructions --- docs/guide/getting-started.md | 111 +++++++++++++++++++---------- docs/parts/install-dependencies.md | 18 +++++ 2 files changed, 90 insertions(+), 39 deletions(-) create mode 100644 docs/parts/install-dependencies.md diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index c630ea49b..0f3c0f7ce 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -1,25 +1,6 @@ # Getting Started -## 1. Install Dependencies - -asdf primarily requires `git`. 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 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 Note - -`sudo` may be required depending on your system configuration. - -::: - -## 2. Install asdf +## 1. Install asdf asdf can be installed in several different ways: @@ -32,24 +13,36 @@ asdf can be installed in several different ways: ::: -::: details Download Pre-Compiled Binary - **Easy** +:::: 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` +:::: details With `go install` + + + +##### Install asdf 1. [Install Go](https://go.dev/doc/install) 2. Run `go install github.com/asdf-vm/asdf@v0.16.0` -::: +:::: + +:::: details Build from Source + + -::: details Build from Source +##### Install asdf 1. Clone the asdf repository: @@ -61,9 +54,16 @@ asdf can be installed in several different ways: 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. -::: +:::: -## 3. Set up completions +## 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 too, 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. @@ -75,37 +75,71 @@ There are many different combinations of Shells, OSs & Installation methods all **Pacman**: [`bash-completion`](https://wiki.archlinux.org/title/bash#Common_programs_and_options) needs to be installed for the completions to work. -Add the following to `~/.bashrc`: +##### Add shims directory to path (required) +Add the following to `~/.bash_profile`: ```shell -. "$HOME/.asdf/asdf.sh" +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 shells completions (optional) + Completions must be configured by adding the following to your `.bashrc`: ```shell -. "$HOME/.asdf/completions/asdf.bash" +. <(asdf completion bash) ``` ::: ::: details Fish +##### Add shims directory to path (required) + Add the following to `~/.config/fish/config.fish`: ```shell -source ~/.asdf/asdf.fish +# 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 ``` -Completions must be configured manually with the following command: +###### 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 -mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions +set -gx --prepend ASDF_DATA_DIR "/your/custom/data/dir" ``` -Pacman: +##### Set up shells completions (optional) + +Completions must be configured manually with the following command: + +```shell +$ asdf completion fish > ~/.config/fish/completions/asdf.fish +``` -Completions are automatically configured on installation by the AUR package. ::: ::: details Elvish @@ -124,6 +158,8 @@ Completions are automatically configured. ::: 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 the following to `~/.zshrc`: ```shell @@ -154,11 +190,7 @@ Add `asdf.sh` to your `~/.zshrc` with: 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`. The Oh-My-ZSH asdf plugin is yet to be updated, see [ohmyzsh/ohmyzsh#8837](https://github.com/ohmyzsh/ohmyzsh/pull/8837). - -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 @@ -201,6 +233,7 @@ On macOS, starting a Bash or Zsh shell automatically calls a utility called `pat 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: diff --git a/docs/parts/install-dependencies.md b/docs/parts/install-dependencies.md new file mode 100644 index 000000000..369f9e84d --- /dev/null +++ b/docs/parts/install-dependencies.md @@ -0,0 +1,18 @@ +##### Install Dependencies + +asdf primarily requires `git`. 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 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 Note + +`sudo` may be required depending on your system configuration. + +::: From 6362c55919ec3b70e451274b6ecec5e28e611348 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Wed, 25 Dec 2024 20:05:06 -0500 Subject: [PATCH 06/10] fix(golang-rewrite): correct zsh completions code --- internal/completions/asdf.zsh | 5 ----- 1 file changed, 5 deletions(-) diff --git a/internal/completions/asdf.zsh b/internal/completions/asdf.zsh index c88accef5..f65733547 100755 --- a/internal/completions/asdf.zsh +++ b/internal/completions/asdf.zsh @@ -1,5 +1,4 @@ #compdef asdf -compdef _asdf asdf #description tool to manage versions of multiple runtimes local curcontext="$curcontext" state state_descr line subcmd @@ -91,7 +90,6 @@ _asdf__installed_versions_of_plus_system() { compadd -a versions } -_asdf() { local -i IntermediateCount=0 @@ -119,8 +117,6 @@ _asdf__dash_commands() { subcmd="${subcmd}-${words[2+IntermediateCount]}" fi } - - case "$subcmd" in (plugin|shim|list) _asdf__dash_commands @@ -224,4 +220,3 @@ case "$subcmd" in (( CURRENT == 3 )) && compadd -- --head ;; esac -} From 084dc97364e47ae4befbf0f4ffee1b4e506d3239 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Thu, 26 Dec 2024 09:06:21 -0500 Subject: [PATCH 07/10] chore(docs): update Nushell and POSIX shell configuration instructions --- docs/guide/getting-started.md | 147 +++++++++++++++++++++++++++++----- 1 file changed, 127 insertions(+), 20 deletions(-) diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 0f3c0f7ce..8dcaf3904 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -90,7 +90,7 @@ Add the following to `~/.bash_profile` above the line you added above: export ASDF_DATA_DIR="/your/custom/data/dir" ``` -##### Set up shells completions (optional) +##### Set up shell completions (optional) Completions must be configured by adding the following to your `.bashrc`: @@ -132,7 +132,7 @@ Add the following to `~/.config/fish/config.fish` above the lines you added abov set -gx --prepend ASDF_DATA_DIR "/your/custom/data/dir" ``` -##### Set up shells completions (optional) +##### Set up shell completions (optional) Completions must be configured manually with the following command: @@ -144,15 +144,36 @@ $ asdf completion fish > ~/.config/fish/completions/asdf.fish ::: details Elvish -Add `asdf.elv` to your `~/.config/elvish/rc.elv` with: +##### Add shims directory to path (required) + +Add the following to `~/.config/elvish/rc.elv`: ```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 +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' ``` -Completions are automatically configured. +##### 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 +``` ::: @@ -160,25 +181,42 @@ Completions are automatically configured. **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 the following to `~/.zshrc`: +##### 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 -. "$HOME/.asdf/asdf.sh" +export ASDF_DATA_DIR="/your/custom/data/dir" ``` -**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. +##### Set up shell completions (optional) -Completions are configured by either a ZSH Framework `asdf` plugin or by adding the following to your `.zshrc`: +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_DIR}/completions $fpath) +fpath=(${ASDF_DATA_DIR:-$HOME/.asdf}/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 +**Note** + +If you are using a custom `compinit` setup with a ZSH Framework, ensure `compinit` is below your sourcing of the framework ::: @@ -195,32 +233,101 @@ Completions are configured by either a ZSH Framework `asdf` or will need to be [ ::: 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 -. "$HOME/.asdf/asdf.ps1" +$env:ASDF_DATA_DIR = "/your/custom/data/dir" ``` +Shell completions not available for PowerShell + ::: ::: details Nushell -Add `asdf.nu` to your `~/.config/nushell/config.nu` with: +##### Add shims directory to path (required) + +Add the following to `~/.config/nushell/config.nu`: + +```shell +let shims_dir = ( + if ( $env | get --ignore-errors ASDF_DATA_DIR | is-empty ) { + $env.HOME | path join '.asdf' + } else { + $env.ASDF_DATA_DIR + } | path join 'shims' +) +$env.PATH = ( $env.PATH | split row (char esep) | where { |p| $p != $shims_dir } | prepend $shims_dir ) +``` + +###### Custom data directory (optional) + +Add the following to `~/.config/nushell/config.nu` above the line you added above: + +```shell +$env.ASDF_DATA_DIR = "/your/custom/data/dir" +``` + +##### Set up shell completions (optional) + +```shell +# If you've not customized the asdf data directory: +$ mkdir $"($env.HOME)/.asdf/completions" +$ asdf completion nushell | save $"($env.HOME)/.asdf/completions/nushell.nu" + +# If you have customized the data directory by setting ASDF_DATA_DIR: +$ mkdir $"($env.ASDF_DATA_DIR)/completions" +$ asdf completion nushell | save $"($env.ASDF_DATA_DIR)/completions/nushell.nu" +``` + +Then add the following to `~/.config/nushell/config.nu`: ```shell -"\n$env.ASDF_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path +let asdf_data_dir = ( + if ( $env | get --ignore-errors ASDF_DATA_DIR | is-empty ) { + $env.HOME | path join '.asdf' + } else { + $env.ASDF_DATA_DIR + } +) +. "$asdf_data_dir/completions/nushell.nu" ``` -Completions are automatically configured ::: ::: 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_DIR="$HOME/.asdf" -. "$HOME/.asdf/asdf.sh" +export ASDF_DATA_DIR="/your/custom/data/dir" ``` ::: From 2be8a50e79a3527bdb8a0c9afa7d5eb86781ea20 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Sat, 28 Dec 2024 09:05:06 -0500 Subject: [PATCH 08/10] chore(docs): remove warning about oh-my-zsh issue --- docs/guide/getting-started.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 8dcaf3904..df056ad21 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -218,16 +218,6 @@ autoload -Uz compinit && compinit 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 -``` - 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`. The Oh-My-ZSH asdf plugin is yet to be updated, see [ohmyzsh/ohmyzsh#8837](https://github.com/ohmyzsh/ohmyzsh/pull/8837). ::: From ae77c93bb26fac0fa888cdcf34445379a816ea67 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Sat, 28 Dec 2024 09:12:59 -0500 Subject: [PATCH 09/10] fixup! chore(docs): remove warning about oh-my-zsh issue --- docs/guide/getting-started-legacy.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/guide/getting-started-legacy.md b/docs/guide/getting-started-legacy.md index b775537af..7dc2391b1 100644 --- a/docs/guide/getting-started-legacy.md +++ b/docs/guide/getting-started-legacy.md @@ -236,9 +236,6 @@ 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 -**Warning** - -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](https://github.com/ohmyzsh/ohmyzsh/pull/8837). ::: ::: details ZSH & Homebrew From bafe0f90009284e58b80e9e9f76c6710ea483c5e Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Mon, 6 Jan 2025 21:30:52 -0500 Subject: [PATCH 10/10] chore(docs): update docs with details on new 'asdf set' command --- docs/guide/getting-started.md | 12 +++----- docs/manage/configuration.md | 8 +---- docs/manage/versions.md | 58 +++++++++++++++++++++++------------ docs/plugins/create.md | 3 +- 4 files changed, 44 insertions(+), 37 deletions(-) diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index df056ad21..0d8f94884 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -385,12 +385,10 @@ Without a version listed for a tool execution of the tool will **error**. `asdf 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. -### Global - -Global defaults are managed in `$HOME/.tool-versions`. Set a global version with: +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 global nodejs latest +asdf set -u nodejs 16.5.0 ``` `$HOME/.tool-versions` will then look like: @@ -401,12 +399,10 @@ 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: +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 local nodejs latest +asdf set nodejs 16.5.0 ``` `$PWD/.tool-versions` will then look like: diff --git a/docs/manage/configuration.md b/docs/manage/configuration.md index e54080825..3a283a447 100644 --- a/docs/manage/configuration.md +++ b/docs/manage/configuration.md @@ -6,12 +6,6 @@ Configuration of `asdf` encompasses both the sharable `.tool-versions` files as Whenever `.tool-versions` file is present in a directory, the tool versions it declares will be used in that directory and any subdirectories. -::: warning Note - -Global defaults can be set in the file `$HOME/.tool-versions` - -::: - This is what a `.tool-versions` file looks like: ``` @@ -48,7 +42,7 @@ To install all the tools defined in a `.tool-versions` file run `asdf install` w To install a single tool defined in a `.tool-versions` file run `asdf install ` in the directory containing the `.tool-versions` file. The tool will be installed at the version specified in the `.tool-versions` file. -Edit the file directly or use `asdf local` (or `asdf global`) which updates it. +Edit the file directly or use `asdf set` which updates it. ## `.asdfrc` diff --git a/docs/manage/versions.md b/docs/manage/versions.md index 8eea1fb93..2dea46e7b 100644 --- a/docs/manage/versions.md +++ b/docs/manage/versions.md @@ -65,35 +65,53 @@ asdf latest # asdf latest erlang 17 ``` -## Set Current Version +## Set Version + +#### Via `.tool-versions` file ```shell -asdf global [...] -asdf shell [...] -asdf local [...] -# asdf global elixir 1.2.4 +asdf set [flags] [...] +# asdf set elixir 1.2.4 # set in current dir +# asdf set -u elixir 1.2.4 # set in .tool-versions file in home directory +# asdf set -p elixir 1.2.4 # set in existing .tool-versions file in a parent dir -asdf global latest[:] -asdf local latest[:] -# asdf global elixir latest +asdf set latest[:] +# asdf set elixir latest ``` -`global` writes the version to `$HOME/.tool-versions`. +`asdf set` writes the version to a `.tool-versions` file in the current directory, +creating it if needed. It exists purely for convenience. You can think of it as +just doing `echo " " > .tool-versions`. + +With the `-u`/`--home` flag `asdf set` writes to the `.tool-versions` file in +your `$HOME` directory, creating the file if it does not exist. + +With the `-p`/`--parent` flag `asdf set` finds a `.tool-versions` file in the +closest parent directory of the current directory. + +#### Via Environment Variable + +When determining the version looks for an environment variable with the pattern +`ASDF_${TOOL}_VERSION`. The version format is the same supported by the +`.tool-versions` file. If set, the value of this environment variable overrides +any versions set in for the tool in any `.tool-versions` file. For example: + +```shell +export ASDF_ELIXIR_VERSION=1.18.1 +``` -`shell` sets the version to an environment variable named `ASDF_${TOOL}_VERSION`, for the current shell session only. +Will tell asdf to use Elixir `1.18.1` in the current shell session. -`local` writes the version to `$PWD/.tool-versions`, creating it if needed. +:::warning +Because this is an environment variable, it only takes effect where it is set. +Any other shell sessions that are running will still use to whatever version is +set in a `.tool-versions` file. See the `.tool-versions` [file in the Configuration section](/manage/configuration.md) for details. -:::warning Alternatively -If you want to set a version only for the current shell session -or for executing just a command under a particular tool version, you -can set an environment variable like `ASDF_${TOOL}_VERSION`. ::: The following example runs tests on an Elixir project with version `1.4.0`. -The version format is the same supported by the `.tool-versions` file. ```shell ASDF_ELIXIR_VERSION=1.4.0 mix test @@ -103,11 +121,11 @@ ASDF_ELIXIR_VERSION=1.4.0 mix test To use the system version of tool `` instead of an asdf managed version you can set the version for the tool to `system`. -Set system with either `global`, `local` or `shell` as outlined in [Set Current Version](#set-current-version) section above. +Set system with either `asdf set` or via environment variable as outlined in [Set Current Version](#set-current-version) section above. ```shell -asdf local system -# asdf local python system +asdf set system +# asdf set python system ``` ## View Current Version @@ -136,7 +154,7 @@ When asdf installs a package it creates shims for every executable program in th The shims themselves are really simple wrappers that `exec` a helper program `asdf exec` passing it the name of the plugin and path to the executable in the installed package that the shim is wrapping. -The `asdf exec` helper determines the version of the package to use (as specified in `.tool-versions` file, selected by `asdf local ...` or `asdf global ...`), the final path to the executable in the package installation directory (this can be manipulated by the `exec-path` callback in the plugin) and the environment to execute in (also provided by the plugin - `exec-env` script), and finally it executes it. +The `asdf exec` helper determines the version of the package to use (as specified in `.tool-versions` file or environment variable), the final path to the executable in the package installation directory (this can be manipulated by the `exec-path` callback in the plugin) and the environment to execute in (also provided by the plugin - `exec-env` script), and finally it executes it. ::: warning Note Because this system uses `exec` calls, any scripts in the package that are meant to be sourced by the shell instead of executed need to be accessed directly instead of via the shim wrapper. The two `asdf` commands: `which` and `where` can help with this by returning the path to the installed package: diff --git a/docs/plugins/create.md b/docs/plugins/create.md index 7a34fa36f..84a0313ad 100644 --- a/docs/plugins/create.md +++ b/docs/plugins/create.md @@ -267,8 +267,7 @@ Determine the latest stable version of a tool. If absent, the asdf core will `ta **Commands that invoke this script** -- `asdf global latest`: set the global version of a tool to the latest stable version for that tool. -- `asdf local latest`: set the local version of a tool to the latest stable version for that tool. +- `asdf set latest`: set the global version of a tool to the latest stable version for that tool. - `asdf install latest`: installs the latest version of a tool. - `asdf latest []`: outputs the latest version of a tool based on the optional filter. - `asdf latest --all`: outputs the latest version of all tools managed by asdf and whether they are installed.