os-mindset update: a plugin user guide

· 3 min read

os-mindset update from os-mindset updates every package manager on a macOS or Debian machine with one command. Each package manager is a plugin. This guide shows how to see which plugins run, turn them off, and add your own. If you want to know how the runner works inside, see the technical write-up.

See what will run

os-mindset update --list

On a Mac with sdkman and Homebrew installed:

sdkman               builtin  run          sdkman
brew                 builtin  run          brew update
os                   builtin  run          MacOS X software update

The columns are the plugin name, where the plugin comes from (builtin or user), its status, and its description. Rows are in run order. --list does not run any plugin.

The status tells you what a normal os-mindset update would do:

Status Meaning
run the plugin runs
skipped the name is in your skip list
disabled the plugin is opt-in, and you have not enabled it
not-selected left out by --only

Plugins for tools that are not installed are not shown at all. On a Mac without flatpak, the flatpak plugin does not appear.

The built-in plugins are sdkman and flatpak on every OS, brew, jetbrains and os (softwareupdate) on macOS, and jetbrains and os (aptitude, autoremove, and a git commit of /etc) on Debian.

os-mindset updates itself with git pull before every command. To skip that, for example when you only want --list, set OSMINDSET_AUTO_UPDATE=0.

Run only some plugins

os-mindset update --only brew sdkman

An unknown name is an error, and then nothing runs.

Skip plugins

To skip a plugin every time, put its name in ~/.os-mindset/update-skip, one per line. Lines that start with # are ignored:

echo os >> ~/.os-mindset/update-skip

To skip plugins for one run only:

OSM_UPDATE_SKIP="os jetbrains" os-mindset update

Enable opt-in plugins

Some plugins are off until you enable them. On Debian, jetbrains is one of them. To enable it, add its name to ~/.os-mindset/update-enable:

echo jetbrains >> ~/.os-mindset/update-enable

If JetBrains Toolbox is not in its default folder, set OSM_JBTOOLBOX_HOME.

Add your own plugin

Put a bash file in one of these folders:

  • ~/.os-mindset/update.d/common/ to run on every OS.
  • ~/.os-mindset/update.d/macosx/ or ~/.os-mindset/update.d/debian/ to run on one OS.
  • Any folder listed in OSM_UPDATE_PATH, separated by colons.

Name the file NN-name. The number sets where it runs among all plugins. The built-ins use 10 (sdkman), 20 (flatpak), 30 (brew), 50 (jetbrains) and 90 (os). For example, ~/.os-mindset/update.d/common/40-npm:

plugin_description="npm global packages"

function plugin_available() {
    command -v npm > /dev/null 2>&1
}

function plugin_run() {
    npm update -g
}
  • plugin_description is printed before the plugin runs.
  • plugin_available is optional. If it fails, the plugin is quietly left out. Without it, the plugin always runs.
  • plugin_run does the update. If it fails, the other plugins still run, and os-mindset update exits non-zero with a list of the failed plugins.
  • Add plugin_enabled_default=false to make your plugin opt-in.

You don’t need to make the file executable. The runner sources each plugin in its own subshell, so plugins can’t affect each other.

Replace a built-in plugin

Plugin names must be unique. If two plugins have the same name, os-mindset update stops with an error and runs nothing. This also applies to different numbers: 90-os and 95-os are both named os.

To replace a built-in plugin, skip it and add yours under a different name. For example, to use your own OS update on macOS:

echo os >> ~/.os-mindset/update-skip
mkdir -p ~/.os-mindset/update.d/macosx
cat > ~/.os-mindset/update.d/macosx/90-my-os <<'EOF'
plugin_description="my OS update"

function plugin_run() {
    softwareupdate -l
}
EOF

os-mindset update --list then shows os as skipped and my-os as run.

Coming from the old update

The os-update function override and the ~/.os-mindset/osupdate-skip file no longer work. To skip the OS update, add os to ~/.os-mindset/update-skip. To replace it, follow the steps above.