asdf-community / asdf-plugin-manager

A plugin manager for the asdf version manager

ASDF Plugin Manager

Let the Kraken manage your asdf plugins securely and declaratively!

Overview

ASDF Plugin Manager allows you to pin asdf plugin info like Git URL and ref for security and integrity. So, it's the only plugin you need to validate manually, and the .plugin-versions file will be the source of truth for all other asdf plugins. Check the example for more details.

Contents

• Overview
• Why?
• Dependencies
• Install
• Example
• Parameters
• Contributing
• License

Why?

Asdf is a great universal version manager. However, it lacks a secure and declarative method to manage its plugins. For example, you cannot pin a specific asdf plugin version, which means you will be easily hacked if one of the asdf plugins you use is compromised!

Many exist requests asking to fix that, but no solution has been proposed in asdf upstream yet! (Last check: Jan 2024)

Hence, asdf-plugin-manager fills the gap to manage asdf plugins securely and declaratively via .plugin-versions file.

Dependencies

• asdf-vm: Tested with v0.12.0 but probably will work with older versions.
• bash, cat, grep, tr, cut, column, sed, git: Generic utilities.
• ASDF_PLUGIN_MANAGER_PLUGIN_VERSIONS_FILENAME: Set the default name for the file with the list of managed plugins. Default: .plugin-versions.

Install

Note

Remember, asdf-plugin-manager is a plugin for asdf and also the actual CLI which actually used to interact with .plugin-versions file.

First, setup asdf-plugin-manager as asdf plugin in asdf:

asdf plugin add asdf-plugin-manager https://github.com/asdf-community/asdf-plugin-manager.git
# Pin the asdf-plugin-manager version using git tag or even better using git hash which is immutable.
asdf plugin update asdf-plugin-manager v1.3.1

Then, install the actual asdf-plugin-manager CLI:

# Install specific version
asdf install asdf-plugin-manager 1.3.1

# Set a version globally (on your ~/.tool-versions file)
asdf global asdf-plugin-manager 1.3.1

# Now asdf-plugin-manager command is available
asdf-plugin-manager version

Example

Using asdf-plugin-manager, the .plugin-versions file will be the source of truth for asdf plugins. Its syntax is as follows:

# plugin-name  git-url                                               git-ref (hash, tag, or branch)
golang         https://github.com/asdf-community/asdf-golang.git     d8dec15
terraform      https://github.com/asdf-community/asdf-hashicorp.git  c048526

You can also export the currently added plugins to be managed by asdf-plugin-manager:

asdf-plugin-manager export > .plugin-versions

From now on, you can use .plugin-versions to manage asdf plugins.

# Add all plugins according to .plugin-versions file
asdf-plugin-manager add-all

Or

# Add named plugin according to .plugin-versions file
asdf-plugin-manager add golang

Parameters

The following are all asdf-plugin-manager parameters:

asdf-plugin-manager help                 : Print this help message
asdf-plugin-manager version              : Print asdf-plugin-manager current version
asdf-plugin-manager export               : List currently installed plugins to be used in .plugin-versions
asdf-plugin-manager list                 : List plugins in .plugin-versions file
asdf-plugin-manager add <plugin-name>    : Add named plugin according to .plugin-versions file
asdf-plugin-manager add-all              : Add all plugins according to .plugin-versions file
asdf-plugin-manager update <plugin-name> : Update named plugin to latest in the system and in the .plugin-versions file
asdf-plugin-manager update-all           : Update all plugins to latest in the system and in the .plugin-versions file
asdf-plugin-manager remove <plugin-name> : Remove named plugin according to .plugin-versions file
asdf-plugin-manager remove-all           : Remove all plugins according to .plugin-versions file

Contributing

Contributions of any kind are welcome! See the contributing guide.

Thanks go to these contributors!

License

This project is by DevOps Hive and licensed under an open-source license. For more details, check LICENSE.

asdf-plugin-manager's Issues

update-all doesn't work if one plugin don't need update, add-all doesn't work if one plugin already installed

Describe the bug

When using asdf-plugin-manager update-all if one of the plugins doesn't need update, the script stop with return code 0 without testing other dependencies

Steps to reproduce

Using the following .plugin-versions file

alias                https://github.com/andrewthauer/asdf-alias.git             1209ad5
gcloud               https://github.com/jthegedus/asdf-gcloud.git                   14d1c0d
golang               https://github.com/kennyp/asdf-golang.git                  f006a12
helm                 https://github.com/Antiarchitect/asdf-helm.git             a39e17b

use asdf-plugin-manager update-all

The output is

[INFO] Updating: alias https://github.com/andrewthauer/asdf-alias.git 1209ad5 to HEAD
Updating alias to main
Already on 'main'
Your branch is up to date with 'origin/main'.
[INFO] The plugin "alias" with git-ref "1209ad5" is already up-to-date.

execute

asdf-plugin-manager add alias #add one of the plugin already
asdf-plugin-manager add-all

The output is

[INFO] Adding: alias https://github.com/andrewthauer/asdf-alias.git 1209ad5
Plugin named alias already added

Expected behavior

The update-all command should try to update all plugins.
The add-all command should try to install all the plugins even if one is already installed

Additional context

add-all is modifying my git repo

Describe the bug

example repo: https://github.com/airtonix/broken-asdf-plugin-manager-1-3-1

I've been using the ./setup.sh in lots of projects for my team members to faceroll all day long.

test on git master 
> ./setup.sh 

🍙  Installing/Updating ASDF  


🍙  Updating asdf...  

HEAD is now at ccdd47d chore(master): release 0.14.0 (#1641)
Updated asdf to release v0.14.0

🍙  Installing ASDF Plugin Manager 1.3.1  

Plugin named asdf-plugin-manager already added
Location of asdf-plugin-manager plugin: /home/zenobius/.asdf/plugins/asdf-plugin-manager
Updating asdf-plugin-manager to v1.3.1
warning: refname 'v1.3.1' is ambiguous.
warning: refname 'v1.3.1' is ambiguous.
Already on 'v1.3.1'
asdf-plugin-manager 1.3.1 is already installed

🍙  Installing .plugin-versions  

[INFO] Adding: asdf-plugin-manager https://github.com/asdf-community/asdf-plugin-manager.git 6fc3faa
Plugin named asdf-plugin-manager already added
error: Your local changes to the following files would be overwritten by checkout:
        README.md
Please commit your changes or stash them before you switch branches.
Aborting

Steps to reproduce

git clone [email protected]:airtonix/broken-asdf-plugin-manager-1-3-1.git
cd broken-asdf-plugin-manager-1-3-1
./setup.sh

Expected behavior

don't run git in my repo

Additional context

it's most likely checkout_plugin_ref causing the issue

[BUG] Fails with invalid name when installing asdf-nodejs plugin

Describe the bug

When adding nodjs plugin it fails saying the name doesn’t flow rules regarding name case and the use of underline and hyphen.
I cannot see anything wrong with the name compared to others.

Steps to reproduce

> cat  .plugin-versions
asdf-plugin-manager  https://github.com/asdf-community/asdf-plugin-manager.git  07a8a5a
direnv               https://github.com/asdf-community/asdf-direnv.git          2b649c8
lua                  https://github.com/Stratus3D/asdf-lua.git                  36fae6e
luajit               https://github.com/smashedtoatoms/asdf-luaJIT.git          bbfe3cd
nodejs               https://github.com/asdf-vm/asdf-nodejs.git                 9c4e0f2
python               https://github.com/danhper/asdf-python.git                 5e277e2

asdf-plugin-manager add nodejs
[INFO] Adding:
 is invalid. Name may only contain lowercase letters, numbers, '_', and ‘-'

Expected behavior

install the nodejs plugin

Screenshots
Additional context

output has been posted above

[Bug] Looking up git refs fails.

Describe the bug

All the git refs fail and cannot be found. These were all install fresh today

Steps to reproduce

asdf plugin add XXX
asdf-plugin-manager export > .plugin-versions 
asdf-plugin-manager add-all

Expected behavior

To check all the git refs

Screenshots
Additional context

> asdf-plugin-manager list
asdf-plugin-manager  https://github.com/asdf-community/asdf-plugin-manager.git  07a8a5a
direnv               https://github.com/asdf-community/asdf-direnv.git          2b649c8
lua                  https://github.com/Stratus3D/asdf-lua.git                  36fae6e
luajit               https://github.com/smashedtoatoms/asdf-luaJIT.git          bbfe3cd
python               https://github.com/danhper/asdf-python.git                 5e277e2

> asdf-plugin-manager add-all
[INFO] Adding: asdf-plugin-manager https://github.com/asdf-community/asdf-plugin-manager.git 07a8a5a
Plugin named asdf-plugin-manager already added
Location of asdf-plugin-manager plugin: /Users/XXXXX/.local/share/asdf/plugins/asdf-plugin-manager
Updating asdf-plugin-manager to 07a8a5a
fatal: couldn't find remote ref 07a8a5a
HEAD is now at 07a8a5a chore(deps): bump asdf-vm/actions from 2 to 3 (#30)
[INFO] Done.
[INFO] Adding: direnv https://github.com/asdf-community/asdf-direnv.git 2b649c8
Plugin named direnv already added
Location of direnv plugin: /Users/XXXXX/.local/share/asdf/plugins/direnv
Updating direnv to 2b649c8
fatal: couldn't find remote ref 2b649c8
HEAD is now at 2b649c8 Bump asdf-vm/actions from 2 to 3
[INFO] Done.
[INFO] Adding: lua https://github.com/Stratus3D/asdf-lua.git 36fae6e
Plugin named lua already added
Location of lua plugin: /Users/XXXXX/.local/share/asdf/plugins/lua
Updating lua to 36fae6e
fatal: couldn't find remote ref 36fae6e
HEAD is now at 36fae6e Add Lua 5.4.5 and 5.4.6 (#32)
[INFO] Done.
[INFO] Adding: luajit https://github.com/smashedtoatoms/asdf-luaJIT.git bbfe3cd
Plugin named luajit already added
Location of luajit plugin: /Users/XXXXX/.local/share/asdf/plugins/luajit
Updating luajit to bbfe3cd
fatal: couldn't find remote ref bbfe3cd
HEAD is now at bbfe3cd Attempting to fix missing luarocks.cfg
[INFO] Done.
[INFO] Adding: python https://github.com/danhper/asdf-python.git 5e277e2
Plugin named python already added
Location of python plugin: /Users/XXXXX/.local/share/asdf/plugins/python
Updating python to 5e277e2
fatal: couldn't find remote ref 5e277e2
HEAD is now at 5e277e2 Merge pull request #169 from asdf-community/renovate/configure
[INFO] Done.

Plugin using a different remote should create a warning

Describe the bug

When adding a plugin that is already added but has a different remote, not action are taken until ASDF_PLUGIN_MANAGER_ADD_CLEAN is true. Maybe a warning should be issued if plugins remote URLs are different.

Steps to reproduce

From a container with asdf and asdf-plugin-manager installed (source available)

node@79423a9cc918:/demo$ asdf plugin-add sops https://github.com/sylvainmetayer/asdf-sops-evil
node@79423a9cc918:/demo$ asdf install sops latest
redirect url: https://github.com/getsops/sops/releases/tag/v3.8.1
sops 3.8.1 installation was successful!
node@79423a9cc918:/demo$ cd plugin-manager/
# Evil sops version, not valid Git remote. This should be fixed by using .plugin-versions and official git remote
node@79423a9cc918:/demo/plugin-manager$ sops
Vous pensiez utiliser sops ?
Dommage, vous venez de faire fuire toutes vos clés SSH vers un serveur mailveillant ! 😈
node@79423a9cc918:/demo/plugin-manager$ asdf global asdf-plugin-manager 1.3.1
node@79423a9cc918:/demo/plugin-manager$ asdf-plugin-manager version
1.3.1
# We can see below that currently installed version is not valid
node@79423a9cc918:/demo/plugin-manager$ asdf-plugin-manager export
asdf-plugin-manager  https://github.com/asdf-community/asdf-plugin-manager.git  54ac342
nodejs               https://github.com/asdf-vm/asdf-nodejs.git                 c5b7c40
sops                 https://github.com/sylvainmetayer/asdf-sops-evil           b7bb9cd
node@79423a9cc918:/demo/plugin-manager$ bat .plugin-versions
# shortened output
   1    # plugin-name  git-url                               git-ref (hash, tag, or branch)
   2    sops           https://github.com/feniix/asdf-sops   master

# I expected that any of "add-all / update-all / add sops / update sops" commands would fix the git remote, or at least
# show a warning  

node@79423a9cc918:/demo/plugin-manager$ asdf-plugin-manager add-all
[INFO] Adding: sops https://github.com/feniix/asdf-sops master
Plugin named sops already added
error: pathspec 'master' did not match any file(s) known to git

node@79423a9cc918:/demo/plugin-manager$ asdf-plugin-manager add sops
[INFO] Adding: sops https://github.com/feniix/asdf-sops master
Plugin named sops already added
error: pathspec 'master' did not match any file(s) known to git

node@79423a9cc918:/demo/plugin-manager$ asdf-plugin-manager update-all
[INFO] Updating: sops https://github.com/feniix/asdf-sops master to HEAD
Location of sops plugin: /home/node/.asdf/plugins/sops
Updating sops to main
Already on 'main'
Your branch is up to date with 'origin/main'.
[INFO] The plugin "sops" with git-ref "master" is already up-to-date.

node@79423a9cc918:/demo/plugin-manager$ asdf-plugin-manager export
asdf-plugin-manager  https://github.com/asdf-community/asdf-plugin-manager.git  54ac342
nodejs               https://github.com/asdf-vm/asdf-nodejs.git                 c5b7c40
sops                 https://github.com/sylvainmetayer/asdf-sops-evil           b7bb9cd

node@79423a9cc918:/demo/plugin-manager$ asdf-plugin-manager update sops
[INFO] Updating: sops https://github.com/feniix/asdf-sops master to HEAD
Location of sops plugin: /home/node/.asdf/plugins/sops
Updating sops to main
Already on 'main'
Your branch is up to date with 'origin/main'.
[INFO] The plugin "sops" with git-ref "master" is already up-to-date.

# With this variable, the plugin is uninstalled before. This ensure the new remote is installed.
node@79423a9cc918:/demo/plugin-manager$ export ASDF_PLUGIN_MANAGER_ADD_CLEAN=true

# However, this does not seems to work with the "update" option
node@79423a9cc918:/demo/plugin-manager$ asdf-plugin-manager update sops
[INFO] Updating: sops https://github.com/feniix/asdf-sops master to HEAD
Location of sops plugin: /home/node/.asdf/plugins/sops
Updating sops to main
Already on 'main'
Your branch is up to date with 'origin/main'.
[INFO] The plugin "sops" with git-ref "master" is already up-to-date.

node@79423a9cc918:/demo/plugin-manager$ asdf-plugin-manager export
asdf-plugin-manager  https://github.com/asdf-community/asdf-plugin-manager.git  54ac342
nodejs               https://github.com/asdf-vm/asdf-nodejs.git                 c5b7c40
sops                 https://github.com/sylvainmetayer/asdf-sops-evil           b7bb9cd

node@79423a9cc918:/demo/plugin-manager$ asdf-plugin-manager add sops
[INFO] Adding: sops https://github.com/feniix/asdf-sops master
[INFO] Removing: sops
[INFO] Done.

node@79423a9cc918:/demo/plugin-manager$ asdf install sops latest 
Downloading sops from https://github.com/getsops/sops/releases/download/v3.8.1/sops-v3.8.1.linux.amd64
asdf: Warn: You have configured asdf to preserve downloaded files (with always_keep_download=yes or --keep-download). But
asdf: Warn: the current plugin (sops) does not support that. Downloaded files will not be preserved.

# Valid SOPS version
node@79423a9cc918:/demo/plugin-manager$ sops
Error: no file specified

Expected behavior

When using different remote URLs for a plugin, a warning should be issued. If the ASDF_PLUGIN_MANAGER_ADD_CLEAN variable is present, the plugin is (except for the update command) uninstalled and reinstalled with the correct git remote.

Screenshots

N/A

Additional context

Thanks a lot for asdf that I use on a daily basis and for this plugin ! I'm preparing a talk on asdf and want to speak about this plugin, that solve an issue we have in our team and ensure consistency in our plugins URLs/tags accross team members.

My demo use case is maybe an edge case as we often use "official" plugins, but I was surprised that no warning would be issued.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

asdf

.tool-versions

• shellcheck 0.9.0
• shfmt 3.7.0

github-actions

.github/workflows/build.yml

• asdf-vm/actions v3
• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11

.github/workflows/lint.yml

• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• asdf-vm/actions v3
• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• rhysd/actionlint 1.6.26

.github/workflows/release.yml

• GoogleCloudPlatform/release-please-action v4
• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11

.github/workflows/semantic-pr.yml

• amannn/action-semantic-pull-request v5.4.0

---

• Check this box to trigger a request for Renovate to run again on this repository