From 7c371e653d93f8a4008644237a7e56998f96112b Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Mon, 6 Jan 2025 21:30:52 -0500 Subject: [PATCH] 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 4a9a40244..b8b9e3a84 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.