chore(docs): update docs with details on new 'asdf set' command

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:

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 <name>` 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`
 

docs/manage/versions.md

@@ -65,35 +65,53 @@ asdf latest <name> <version>
 # asdf latest erlang 17
 ```
 
-## Set Current Version
+## Set Version
+
+#### Via `.tool-versions` file
 
 ```shell
-asdf global <name> <version> [<version>...]
-asdf shell <name> <version> [<version>...]
-asdf local <name> <version> [<version>...]
-# asdf global elixir 1.2.4
+asdf set [flags] <name> <version> [<version>...]
+# 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 <name> latest[:<version>]
-asdf local <name> latest[:<version>]
-# asdf global elixir latest
+asdf set <name> latest[:<version>]
+# 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> <version>" > .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 `<name>` 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 <name> system
-# asdf local python system
+asdf set <name> 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:

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 <tool> latest`: set the global version of a tool to the latest stable version for that tool.
-- `asdf local <name> latest`: set the local version of a tool to the latest stable version for that tool.
+- `asdf set <tool> latest`: set the global version of a tool to the latest stable version for that tool.
 - `asdf install <tool> latest`: installs the latest version of a tool.
 - `asdf latest <tool> [<version>]`: 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.