kevin/asdf
1
Fork 0
mirror of https://github.com/asdf-vm/asdf.git synced 2024-12-24 12:25:28 -07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #75 from asdf-vm/tb/upgrade-doc

Browse Source 
feat(golang-rewrite): create version 0.14 to 0.15 upgrade guide
This commit is contained in:
Trevor Brown 2024-10-29 09:47:11 -04:00 committed by Trevor Brown
commit 3d4d4366ab
1 changed files with 108 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
docs/guide/upgrading-from-v0-14-to-v0-15.md Normal file
View File

@ -0,0 +1,108 @@
# Upgrading From Version 0.14.x to 0.15.0
asdf versions 0.14.1 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.
## Breaking Changes
### Hyphenated commands have been removed
asdf version 0.14.1 and earlier supported by hyphenated and non-hyphenated
versions of certain commands. With version 0.15.0 only the non-hyphenated
versions are supported. The affected commands:
* `asdf list-all` -> `asdf list all`
* `asdf plugin-add` -> `asdf plugin add`
* `asdf plugin-list` -> `asdf plugin list`
* `asdf plugin-list-all` -> `asdf plugin list all`
* `asdf plugin-update` -> `asdf plugin update`
* `asdf plugin-remove` -> `asdf plugin remove`
### `asdf global` and `asdf local` commands have been replaced by the `asdf set` command
`asdf global` and `asdf local` have been replaced by `asdf set`, which aims to
provide the same functionality while using terminology that is less likely to
mislead the user. TODO: Add more details here
### `asdf update` command has been removed
Updates can no longer be performed this way. Use your OS package manager or
download the latest binary manually. Additionally, the `asdf update` command
present in versions 0.14.1 and older cannot upgrade to version 0.15.0 because
the install process has changed. **You cannot upgrade to the latest Go
implementation using `asdf update`.**
### `asdf shell` command has been removed
This command actually set an environment variable in the user's current shell
session. It was able to do this because `asdf` was actually a shell function,
not an executable. The new rewrite removes all shell code from asdf, and it is
now a binary rather than a shell function, so setting environment variables
directly in the shell is no longer possible.
## 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.