diff --git a/docs/plugins-create.md b/docs/plugins-create.md
index 13d103e76..b74876439 100644
--- a/docs/plugins-create.md
+++ b/docs/plugins-create.md
@@ -57,6 +57,19 @@ If possible the script should only place files in the `ASDF_INSTALL_PATH` direct
## Optional Scripts
+#### bin/help scripts
+
+This is not one callback script but rather a set of callback scripts that each print different documentation to STDOUT. The possible callback scripts are listed below. Note that `bin/help.overview` is a special case as it must be present for any help output to be displayed for the script.
+
+* `bin/help.overview` - This script should output a general description about the plugin and the tool being managed. No heading should be printed as asdf will print headings. Output may be free-form text but ideally only one short paragraph. This script must be present if you want asdf to provide help information for your plugin. All other help callback scripts are optional.
+* `bin/help.deps` - This script should output the list of dependencies tailored to the operating system. One dependency per line.
+* `bin/help.config` - This script should print any required or optional configuration that may be available for the plugin and tool. Any environment variables or other flags needed to install or compile the tool (for the users operating system when possible). Output can be free-form text.
+* `bin/help.links` - This should be a list of links relevant to the plugin and tool (again, tailored to the current operating system when possible). One link per line. Lines may be in the format `
: ` or just ``.
+
+Each of these scripts should tailor their output to the current operating system. For example, when on Ubuntu the deps script could output the dependencies as apt-get packages that must be installed. The script should also tailor its output to the value of `ASDF_INSTALL_VERSION` and `ASDF_INSTALL_TYPE` when the variables are set. They are optional and will not always be set.
+
+The help callback script MUST NOT output any information that is already covered in the core asdf-vm documentation. General asdf usage information must not be present.
+
#### bin/list-bin-paths
List executables for the specified version of the tool. Must print a string with a space-separated list of dir paths that contain executables. The paths must be relative to the install path passed. Example output would be:
diff --git a/help.txt b/help.txt
index c70225d89..f318dbd04 100644
--- a/help.txt
+++ b/help.txt
@@ -37,6 +37,7 @@ asdf latest [] Show latest stable version of a package
asdf list List installed versions of a package
asdf list all [] List all versions of a package and
optionally filter the returned versions
+asdf help [] Output documentation for plugin and tool
UTILS
diff --git a/lib/commands/command-help.bash b/lib/commands/command-help.bash
index fcb8d4832..4313afc4e 100644
--- a/lib/commands/command-help.bash
+++ b/lib/commands/command-help.bash
@@ -31,9 +31,84 @@ asdf_extension_cmds() {
}
help_command() {
- asdf_help
- asdf_extension_cmds
- asdf_moto
+ local plugin_name="$1"
+ local tool_version="$2"
+ local plugin_path
+
+ # If plugin name is present as first argument output plugin help info
+ if [ -n "$plugin_name" ]; then
+ plugin_path=$(get_plugin_path "$plugin_name")
+
+ if [ -d "$plugin_path" ]; then
+ if [ -f "${plugin_path}/bin/help.overview" ]; then
+ if [ -n "$tool_version" ]; then
+
+ # TODO: Refactor this code out into helper functions in utils.bash
+ IFS=':' read -r -a version_info <<<"$tool_version"
+ if [ "${version_info[0]}" = "ref" ]; then
+ local install_type="${version_info[0]}"
+ local version="${version_info[1]}"
+ else
+ local install_type="version"
+
+ if [ "${version_info[0]}" = "latest" ]; then
+ local version
+ version=$(asdf latest "$plugin_name" "${version_info[1]}")
+ else
+ local version="${version_info[0]}"
+ fi
+ fi
+
+ local install_path
+ install_path=$(get_install_path "$plugin_name" "$install_type" "$version")
+
+ (
+ # shellcheck disable=SC2031
+ export ASDF_INSTALL_TYPE=$install_type
+ # shellcheck disable=SC2031
+ export ASDF_INSTALL_VERSION=$version
+ # shellcheck disable=SC2031
+ export ASDF_INSTALL_PATH=$install_path
+
+ print_plugin_help "$plugin_path"
+ )
+ else
+ (print_plugin_help "$plugin_path")
+ fi
+ else
+ echo "No documentation for plugin $plugin_name" >&2
+ exit 1
+ fi
+ else
+ echo "No plugin named $plugin_name" >&2
+ exit 1
+ fi
+ else
+ # Otherwise output general asdf help
+ asdf_help
+ asdf_extension_cmds
+ asdf_moto
+ fi
+}
+
+print_plugin_help() {
+ local plugin_path=$1
+
+ # Eventually @jthegedus or someone else will format the output from these
+ # scripts in a certain way.
+ bash "${plugin_path}"/bin/help.overview
+
+ if [ -f "${plugin_path}"/bin/help.deps ]; then
+ bash "${plugin_path}"/bin/help.deps
+ fi
+
+ if [ -f "${plugin_path}"/bin/help.config ]; then
+ bash "${plugin_path}"/bin/help.config
+ fi
+
+ if [ -f "${plugin_path}"/bin/help.links ]; then
+ bash "${plugin_path}"/bin/help.links
+ fi
}
help_command "$@"
diff --git a/test/fixtures/dummy_plugin/bin/help.overview b/test/fixtures/dummy_plugin/bin/help.overview
new file mode 100644
index 000000000..746761d5a
--- /dev/null
+++ b/test/fixtures/dummy_plugin/bin/help.overview
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+echo "Dummy plugin documentation"
+echo
+echo "Dummy plugin is a plugin only used for unit tests"
+
+if [ -n "$ASDF_INSTALL_VERSION" ]; then
+ echo
+ echo "Details specific for version $ASDF_INSTALL_VERSION"
+fi
diff --git a/test/help_command.bats b/test/help_command.bats
new file mode 100644
index 000000000..a0d9a9a97
--- /dev/null
+++ b/test/help_command.bats
@@ -0,0 +1,76 @@
+#!/usr/bin/env bats
+
+load test_helpers
+
+setup() {
+ setup_asdf_dir
+ install_dummy_plugin
+ install_dummy_legacy_plugin
+ run asdf install dummy 1.0
+ run asdf install dummy 1.1
+
+ PROJECT_DIR=$HOME/project
+ mkdir $PROJECT_DIR
+}
+
+teardown() {
+ clean_asdf_dir
+}
+
+@test "help should show dummy plugin help" {
+ cd $PROJECT_DIR
+
+ run asdf help "dummy"
+
+ expected_output="$(cat <