coredesktop/skills/sibling-project-updates.md

Skill: Supporting the updates.d Update Architecture in a Sibling Project

Overview

There are two ways for a sibling project to plug into CoreDesktop:

1. The sibling command (preferred). The user runs sibling and gives it the project's git URL. The repo is cloned into ~/.local/share/siblings/<name> and its install.sh (if any) is run once. On every update, updates.d/71-siblings.sh pulls each sibling and runs its update.sh (if any). The sibling only needs those two optional scripts.
2. A custom hook. CoreDesktop's update script sources every *.sh file found in ~/.local/share/coredesktop/updates.d/ in filename order. A sibling project can install its own numbered shell script into that directory during its own install step, for full control over how and when it updates.

Using the sibling Command

See sibling-project-format.md for the full rules, templates and testing. In short, give the repo these optional files at its top level:

File	When it runs
install.sh	Once, from the repo folder, when the user runs sibling add (and again if they re-run it)
update.sh	On every update, from the repo folder, after the repo has been pulled

Both run with bash, and a non-zero exit is reported as a failure. update.sh should be idempotent. If you have no update.sh, update just pulls the repo.

Commands:

sibling                 # asks for the git URL
sibling add <url>       # same, without the prompt
sibling list            # installed siblings, their version and URL
sibling check           # which siblings have a newer version
sibling update [name]   # update the named siblings, or all of them
sibling remove <name>   # deletes ~/.local/share/siblings/<name>

The rest of this document covers the custom-hook approach.

How It Works

When a user runs update:

1. The coredesktop repo at ~/.local/share/coredesktop is pulled.
2. All *.sh files in updates.d/ are sourced, each in its own subshell, in lexicographic order.
3. Each script can see $COREDESKTOP, but nothing defined by earlier hooks — source utils.sh yourself if you need its helpers. A cd, set -e or exit in one hook can't affect the others.
4. A hook that exits non-zero is listed in the summary at the end of update.

Because the scripts are sourced from within the cloned repo directory, any file placed there by a sibling project's installer will survive git pull — git does not delete untracked files on pull.

Naming Convention

Existing coredesktop hooks use a numeric prefix to control execution order:

File	Purpose
09-snapshot.sh	Snapper snapshot of / (btrfs only)
10-pacman.sh	Arch system update
12-migrations.sh	One-time migrations from migrations/
15-services.sh	Enable new systemd services
20-aur.sh	AUR packages
30-flatpak.sh	Flatpak apps
40-mise.sh	languages installed with mise, Rails
45-tmux.sh	TPM and tmux plugins
46-neovim.sh	Neovim plugins
50-bitwarden.sh	Bitwarden SSH agent
60-pipx.sh	pipx packages
70-claude.sh	Claude Code setup
71-siblings.sh	Projects installed with sibling
80-gnome-extensions.sh	GNOME extensions
85-gnome-settings.sh	GNOME extension settings
90-firmware.sh	Firmware update check
95-cleanup.sh	Flatpak/pacman cache cleanup
99-reboot-check.sh	Reboot-needed notice

Sibling projects should use an unused number from 72–79 so they run after the core updates but before coredesktop's end-of-run hooks (80+).

What to Add to a Sibling Project

1. Create the hook script

Add a file like updates.d/72-myproject.sh to the sibling repo:

#!/bin/bash

echo "Updating MyProject..."
git -C "$HOME/.local/share/myproject" pull

# Optional: use coredesktop helpers if needed
# source "$COREDESKTOP/utils.sh"
# install_packages "${MY_PACKAGES[@]}"

2. Install the hook during the sibling's install step

In the sibling's install.sh, copy the hook into coredesktop's updates.d/:

echo "Registering MyProject update hook..."
cp updates.d/72-myproject.sh ~/.local/share/coredesktop/updates.d/

This is a one-time step that wires the sibling into every future update run on the machine.

Optional: only update when installed

Instead of running code at the top level, a hook can define run_update and, optionally, is_installed. update calls run_update only when is_installed is missing or returns true, so the hook is skipped on machines where the project isn't installed. Return non-zero from run_update to report a failure:

#!/bin/bash

is_installed() {
  [ -d "$HOME/.local/share/myproject" ]
}

run_update() {
  echo "Updating MyProject..."
  git -C "$HOME/.local/share/myproject" pull --ff-only
}

Available Helpers

Hooks don't inherit functions from earlier hooks, so source utils.sh for its helpers. Do this before defining your own is_installed, because utils.sh has a pacman-specific function with the same name:

source "$COREDESKTOP/utils.sh"

# Install pacman packages (skips already-installed ones)
install_packages "${MY_PACMAN_PACKAGES[@]}"

# Remove packages
remove_packages "${MY_REMOVE_PACKAGES[@]}"

Checklist for Sibling Project Authors

• Create updates.d/7X-<project>.sh in the sibling repo
• Hook script echoes its name so progress is visible during update
• Install step copies the hook to ~/.local/share/coredesktop/updates.d/
• Numeric prefix is an unused number in 72–79
• Script is idempotent — safe to run multiple times without side effects