Utilities and Siblings: sibling versions, sibling check and sibling update

content/siblings.md

@@ -4,7 +4,7 @@ description: "Sibling projects are git repositories that build on Federated Core
 sections:
   - type: hero
     compact: true
-    eyebrow: "sibling · sibling add · sibling list · sibling remove"
+    eyebrow: "sibling · sibling add · sibling list · sibling check · sibling update · sibling remove"
     title: "Build your own layer on top."
     subhead: "A sibling project is a git repository that builds on CoreDesktop. Install one with a single command, and every `update` keeps it current along with everything else."
     ctas:
@@ -25,7 +25,7 @@ sections:
       - tag: "Bin"
         text: "Installed ~/.local/bin/my-tools"
       - done: true
-        text: "my-tools installed. update keeps it current."
+        text: "my-tools v1.0.0 installed. update keeps it current."
 
   - type: text
     kicker: "What's a sibling?"
@@ -37,6 +37,8 @@ sections:
 
       A repository needs no special files to be installable. Without the scripts, `update` just keeps the clone up to date.
 
+      `version` lists the siblings you've installed with their versions, and offers to update any that have a newer one.
+
   - type: command
     id: install-a-sibling
     kicker: "Install one"
@@ -52,7 +54,9 @@ sections:
     rows:
       - ["`sibling`", "Asks for a git URL, then installs that project"]
       - ["`sibling add <url>`", "The same, without the prompt. Run it again to repair an install"]
-      - ["`sibling list`", "Shows the installed siblings, their URLs and current commits"]
+      - ["`sibling list`", "Shows the installed siblings, their versions and URLs"]
+      - ["`sibling check`", "Shows which siblings have a newer version"]
+      - ["`sibling update [name...]`", "Updates the named siblings now, or all of them, the way `update` does"]
       - ["`sibling remove <name>`", "Deletes `~/.local/share/siblings/<name>`. Anything its install.sh set up elsewhere stays"]
 
   - type: siblings
@@ -113,6 +117,8 @@ sections:
         body: "`update` pulls with `--ff-only` and never merges or resets. Never force-push the default branch, and never write into tracked files: put generated files and per-machine state in `~/.config/<name>/` or in paths listed in `.gitignore`."
       - label: "sudo works as normal"
         body: "`sudo` prompts for a password as usual. CoreDesktop doesn't give siblings passwordless sudo."
+      - label: "Versions come from git tags"
+        body: "Your project's version is its latest tag, such as `v1.4.0`, or `v1.4.0+3` three commits later. Without tags it's the latest commit's date and id. To release, tag the default branch and push the tag: `git tag v1.5.0 && git push origin v1.5.0`. Never move a tag once it's pushed. `update` always installs the newest commit, tagged or not."
 
   - type: table
     kicker: "Helpers"
@@ -194,8 +200,10 @@ sections:
       # Install
       bash "$HOME/.local/share/coredesktop/sibling" add /path/to/sibling-repo
 
-      # Commit a change in /path/to/sibling-repo, then run the update hook the way update does
-      ( source "$HOME/.local/share/coredesktop/updates.d/71-siblings.sh"; is_installed && run_update )
+      # Commit a change in /path/to/sibling-repo, check that it's seen as newer,
+      # then update the way update does
+      bash "$HOME/.local/share/coredesktop/sibling" check
+      bash "$HOME/.local/share/coredesktop/sibling" update
 
       # Re-run the install to check it's safe to repeat
       bash "$HOME/.local/share/coredesktop/sibling" add /path/to/sibling-repo
@@ -227,6 +235,7 @@ sections:
       - "`update.sh` (optional) is at the top level, idempotent, doesn't prompt, and prints what it's doing."
       - "Scripts find their own files relative to the script and set `COREDESKTOP=\"$HOME/.local/share/coredesktop\"` themselves."
       - "Nothing writes to tracked files in the clone, and the default branch is never force-pushed."
+      - "Releases are tagged on the default branch (optional), and pushed tags are never moved."
       - "The project doesn't also copy a hook into CoreDesktop's `updates.d/`."
       - "The README tells users to install with `sibling add <url>`."