diff --git a/docs/manage/configuration.md b/docs/manage/configuration.md index 1c8338ab..4130c992 100644 --- a/docs/manage/configuration.md +++ b/docs/manage/configuration.md @@ -7,7 +7,9 @@ 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: @@ -57,6 +59,7 @@ legacy_version_file = no use_release_candidates = no always_keep_download = no plugin_repository_last_check_duration = 60 +disable_plugin_short_name_repository = no ``` ### `legacy_version_file` @@ -88,7 +91,7 @@ Configure the `asdf install` command to keep or delete the source code or binary ### `plugin_repository_last_check_duration` -Configure the duration since the last asdf plugin repository sync to the next. Commands `asdf plugin add ` or `asdf plugin list all` will trigger a check of the duration, if the duration has passed then a sync occurs. +Configure the duration since the last asdf plugin repository sync to the next. Sync events will trigger a check of the duration, if the duration has passed then a sync occurs. | Options | Description | | :------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------- | @@ -96,6 +99,35 @@ Configure the duration since the last asdf plugin repository sync to the next. C | `0` | Sync on each trigger event | | `never` | Never sync | +Sync events occur when the following commands are executed: + +- `asdf plugin add ` +- `asdf plugin list all` + +`asdf plugin add ` does NOT trigger a plugin sync. + +### `disable_plugin_short_name_repository` + +Disable synchronization of the asdf plugin short-name repository. Sync events will exit early if the short-name repository is disabled. + +| Options | Description | +| :--------------------------------------------------------- | :-------------------------------------------------------- | +| `no` | Clone or update the asdf plugin repository on sync events | +| `yes` | Disable short-name plugin repository | + +Sync events occur when the following commands are executed: + +- `asdf plugin add ` +- `asdf plugin list all` + +`asdf plugin add ` does NOT trigger a plugin sync. + +::: warning Note + +Disabling the plugin short-name repository does not remove plugins previously installed from this source. Plugins can be removed with `asdf plugin remove `. Removing a plugin will remove all installed versions of the managed tool. + +::: + ## Environment Variables - `ASDF_CONFIG_FILE` - Defaults to `~/.asdfrc` as described above. Can be set to any location. diff --git a/docs/manage/plugins.md b/docs/manage/plugins.md index 011586ff..9e63bfeb 100644 --- a/docs/manage/plugins.md +++ b/docs/manage/plugins.md @@ -21,7 +21,9 @@ asdf plugin add ``` ::: tip Recommendation + Prefer the longer `git-url` method as it is independent of the short-name repo. + ::: ## List Installed @@ -72,10 +74,13 @@ asdf plugin remove Removing a plugin will remove all installations of the tool made with the plugin. This can be used as a shorthand for cleaning/pruning many unused versions of a tool. -## Syncing the Short-name Repository +## Syncing the asdf Short-name Repository -The short-name repo is synced to your local machine and periodically refreshed. This period is determined by the following method: +The short-name repo is synced to your local machine and periodically refreshed. This method to determine a sync is as follows: -- commands `asdf plugin add ` or `asdf plugin list all` can trigger a sync -- a sync occurs if there has not been one in the last `X` minutes -- `X` defaults to `60`, but can be configured in your `.asdfrc` via the `plugin_repository_last_check_duration` option. See the [asdf config docs](/manage/configuration.md) for more. +- sync events are triggered by commands: + - `asdf plugin add ` + - `asdf plugin list all` +- if configuration option `disable_plugin_short_name_repository` is set to `yes`, then sync is aborted early. See the [asdf config docs](/manage/configuration.md) for more. +- if there has not been a synchroniztion in the last `X` minutes then the sync will occur. + - `X` defaults to `60`, but can be configured in your `.asdfrc` via the `plugin_repository_last_check_duration` option. See the [asdf config docs](/manage/configuration.md) for more. diff --git a/lib/utils.bash b/lib/utils.bash index 1d3a72a7..941d7bca 100644 --- a/lib/utils.bash +++ b/lib/utils.bash @@ -412,6 +412,12 @@ initialize_or_update_repository() { local repository_url local repository_path + disable_plugin_short_name_repo="$(get_asdf_config_value "disable_plugin_short_name_repository")" + if [ "yes" == "$disable_plugin_short_name_repo" ]; then + printf "Short-name plugin repository is disabled\\n" >&2 + exit 1 + fi + repository_url=$(asdf_repository_url) repository_path=$(asdf_data_dir)/repository diff --git a/test/plugin_add_command.bats b/test/plugin_add_command.bats index da90e8cf..ae14df21 100644 --- a/test/plugin_add_command.bats +++ b/test/plugin_add_command.bats @@ -16,7 +16,7 @@ teardown() { run asdf plugin add "plugin_with-all-valid-CHARS-123" "${BASE_DIR}/repo-plugin_with-all-valid-CHARS-123" [ "$status" -eq 0 ] - run asdf plugin-list + run asdf plugin list [ "$output" = "plugin_with-all-valid-CHARS-123" ] } @@ -52,18 +52,39 @@ teardown() { run asdf plugin add "elixir" [ "$status" -eq 0 ] - run asdf plugin-list - # whitespace between 'elixir' and url is from printf %-15s %s format + run asdf plugin list [ "$output" = "elixir" ] } +@test "plugin_add command with no URL specified adds a plugin when short name repository is enabled" { + export ASDF_CONFIG_DEFAULT_FILE=$HOME/.asdfrc + echo "disable_plugin_short_name_repository=no" >$ASDF_CONFIG_DEFAULT_FILE + + run asdf plugin add "elixir" + [ "$status" -eq 0 ] + + local expected="elixir" + run asdf plugin list + [ "$output" = "$expected" ] +} + +@test "plugin_add command with no URL specified fails to add a plugin when disabled" { + export ASDF_CONFIG_DEFAULT_FILE=$HOME/.asdfrc + echo "disable_plugin_short_name_repository=yes" >$ASDF_CONFIG_DEFAULT_FILE + local expected="Short-name plugin repository is disabled" + + run asdf plugin add "elixir" + [ "$status" -eq 1 ] + [ "$output" = "$expected" ] +} + @test "plugin_add command with URL specified adds a plugin using repo" { install_mock_plugin_repo "dummy" run asdf plugin add "dummy" "${BASE_DIR}/repo-dummy" [ "$status" -eq 0 ] - run asdf plugin-list + run asdf plugin list # whitespace between 'elixir' and url is from printf %-15s %s format [ "$output" = "dummy" ] } diff --git a/test/plugin_list_all_command.bats b/test/plugin_list_all_command.bats index 25ba09f3..113289ee 100644 --- a/test/plugin_list_all_command.bats +++ b/test/plugin_list_all_command.bats @@ -12,51 +12,64 @@ teardown() { clean_asdf_dir } +@test "plugin_list_all should exit before syncing the plugin repo if disabled" { + export ASDF_CONFIG_DEFAULT_FILE=$HOME/.asdfrc + echo 'disable_plugin_short_name_repository=yes' >$ASDF_CONFIG_DEFAULT_FILE + local expected="Short-name plugin repository is disabled" + + run asdf plugin list all + [ "$status" -eq 1 ] + [ "$output" = "$expected" ] +} + @test "plugin_list_all should sync repo when check_duration set to 0" { - echo 'plugin_repository_last_check_duration = 0' >$HOME/.asdfrc - run asdf plugin-list-all + export ASDF_CONFIG_DEFAULT_FILE=$HOME/.asdfrc + echo 'plugin_repository_last_check_duration = 0' >$ASDF_CONFIG_DEFAULT_FILE local expected_plugin_repo_sync="updating plugin repository..." local expected_plugins_list="\ bar http://example.com/bar dummy *http://example.com/dummy foo http://example.com/foo" + run asdf plugin list all [ "$status" -eq 0 ] [[ "$output" =~ "$expected_plugin_repo_sync" ]] [[ "$output" =~ "$expected_plugins_list" ]] } @test "plugin_list_all no immediate repo sync expected because check_duration is greater than 0" { - echo 'plugin_repository_last_check_duration = 10' >$HOME/.asdfrc - run asdf plugin-list-all + export ASDF_CONFIG_DEFAULT_FILE=$HOME/.asdfrc + echo 'plugin_repository_last_check_duration = 10' >$ASDF_CONFIG_DEFAULT_FILE local expected="\ bar http://example.com/bar dummy *http://example.com/dummy foo http://example.com/foo" + run asdf plugin list all [ "$status" -eq 0 ] [ "$output" = "$expected" ] } @test "plugin_list_all skips repo sync because check_duration is set to never" { - echo 'plugin_repository_last_check_duration = never' >$HOME/.asdfrc - run asdf plugin-list-all + export ASDF_CONFIG_DEFAULT_FILE=$HOME/.asdfrc + echo 'plugin_repository_last_check_duration = never' >$ASDF_CONFIG_DEFAULT_FILE local expected="\ bar http://example.com/bar dummy *http://example.com/dummy foo http://example.com/foo" + run asdf plugin list all [ "$status" -eq 0 ] [ "$output" = "$expected" ] } @test "plugin_list_all list all plugins in the repository" { - run asdf plugin-list-all local expected="\ bar http://example.com/bar dummy *http://example.com/dummy foo http://example.com/foo" + run asdf plugin list all [ "$status" -eq 0 ] [ "$output" = "$expected" ] }