From eeab51965c91d46de9597b9f0f3e83b3834a109c Mon Sep 17 00:00:00 2001
From: James Hegedus <jthegedus@hey.com>
Date: Fri, 4 Jun 2021 08:26:46 +1000
Subject: [PATCH] docs: explain plugin repo sync details (#965)

---
 docs/core-manage-plugins.md | 43 +++++++++++++++++++++++++++----------
 1 file changed, 32 insertions(+), 11 deletions(-)

diff --git a/docs/core-manage-plugins.md b/docs/core-manage-plugins.md
index f3b5d58f..a2c0b10b 100644
--- a/docs/core-manage-plugins.md
+++ b/docs/core-manage-plugins.md
@@ -1,23 +1,24 @@
-Plugins are how asdf understands handling different packages.
+Plugins are how asdf knows how to handle different tools like Node.js, Ruby, Elixir etc.
 
-See [All plugins](plugins-all) for the plugins repository which lists all asdf plugins we know.
-
-See [Creating Plugins](plugins-create) for the super-simple API for supporting more languages.
+See [Creating Plugins](plugins-create) for the plugin API used to support more tools.
 
 ## Add
 
+Add plugins via their Git URL:
+
+```shell
+asdf plugin add <name> <git-url>
+# asdf plugin add elm https://github.com/vic/asdf-elm
+```
+
+or via the short-name association in the plugins repository:
+
 ```shell
 asdf plugin add <name>
 # asdf plugin add erlang
 ```
 
-If the plugin you want to install is not part of the plugins repository, you
-can add it using its repository URL:
-
-```shell
-asdf plugin add <name> <git-url>
-# asdf plugin add elm https://github.com/vic/asdf-elm
-```
+When scripting, prefer the longer `git-url` method as it is independent of the short-name repo.
 
 ## List Installed
 
@@ -35,6 +36,14 @@ asdf plugin list --urls
 # nodejs          https://github.com/asdf-vm/asdf-nodejs.git
 ```
 
+## List All in Short-name Repository
+
+```shell
+asdf plugin list all
+```
+
+See [All plugins](plugins-all) for the short-name list of plugins.
+
 ## Update
 
 ```shell
@@ -48,9 +57,21 @@ asdf plugin update <name>
 # asdf plugin update erlang
 ```
 
+This update will fetch the *latest commit* on the *default branch* of the *origin* of the plugin repository. Versioned plugins and updates are currently being developed - https://github.com/asdf-vm/asdf/pull/916
+
 ## Remove
 
 ```bash
 asdf plugin remove <name>
 # asdf plugin remove erlang
 ```
+
+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
+
+The short-name repo is synced to your local machine and periodically refreshed. This period is determined by the following method:
+
+- commands `asdf plugin add <name>` 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](core-configuration) for more.