boost-skill-cli 1.2.58__tar.gz → 1.2.60__tar.gz

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -34,6 +34,8 @@ config
 configs
 CPython
 CRM
+cron
+crontab
 cyclomatic
 Dependabot
 deps

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/CLAUDE.md

@@ -543,6 +543,41 @@ each agent's skills dir, and updating the lock file.
   by another key-holder; `scripts/publish_shards.py manifest` refuses to
   describe two spaces in one file.
 
+- **`sync` and `ingest` differ in which side is authoritative, and only one of
+  them survives a republish.** `shards.sync` takes this machine's commits as
+  given and asks whether a published shard happens to match — right on setup
+  day, wrong a week later, because the weekly run republishes against whatever
+  the registries moved to. So for most taps the answer becomes "no", and the
+  user is told their vectors are stale with no way to act on it but hours of
+  local CPU: `boost update` chases branch HEAD and `--force` chases it while
+  dropping the pin, neither of which can land on a commit a manifest names.
+  `shards.ingest` reads the manifest as the **target**: a row for a tap held at
+  another commit is a reason to move the tap (`registry.retarget` — checkout
+  then pin, never the reverse), and `boost update --shards` is the surface. Two
+  invariants are load-bearing. **Download and verify before moving**: a move
+  followed by a failed download leaves vectors stale but present, the failure
+  that looks like nothing at all — `retarget` is injected so the ordering is
+  testable without a git remote. **Skip on `built`, not on `commits`**:
+  `dense.tap_commits()` says which commit the *vectors* were built at, and a tap
+  matching on both is skipped without a download, which is the whole reason a
+  weekly cron line costs one manifest fetch. A registry that dropped out of the
+  manifest is left pinned where it sits — falling back to HEAD would invent a
+  target no published vectors describe. And a tap that moves invalidates more
+  than vectors: its catalog cache and the BM25 index name entries from the old
+  tree, so `catalog.rebuild_tap` and `rag.build` run for anything that moved.
+
+- **Search reads two mtimes and makes zero network calls, and cheapness is not
+  the argument.** The manifest is ~170 KB, so an inline check would be
+  affordable; acting on its answer means moving taps and downloading hundreds of
+  megabytes, which cannot happen inside a sub-second search. So the most an
+  inline check could ever produce is the one line `_hint_stale_shards` already
+  prints for one `stat` — at the price of a round trip per query and
+  unannounced egress. `paths.shard_sync_marker()` lives under `state/`, not
+  `cache/`, because `boost clean` sweeps `cache/*.json` and would delete it,
+  after which search would nag about vectors refreshed that morning. The shard
+  hint suppresses the tap-age hint when it fires: its remedy moves the taps too,
+  and two staleness lines under one result set is how a hint becomes noise.
+
 **Search has two engines**, both in `core/`: `rag.py` is the always-on,
 zero-dependency BM25 engine (full-content index, auto-builds on first
 search — this is what the required `eval` gate floors at recall@k ≥ 0.78).

{boost_skill_cli-1.2.58/boost_skill_cli.egg-info → boost_skill_cli-1.2.60}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.58
+Version: 1.2.60
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0
@@ -197,14 +197,34 @@ for every one that has a published shard.
 Already tapped? `boost reindex --fetch-shards` does the download half alone,
 and `boost reindex --dense` embeds locally whatever has no published shard.
 
+Vectors are republished weekly, and `boost update --shards` is the ingestion
+side of that. It reads the manifest as the *target* state: each tap is moved
+onto the commit its published vectors were built from, those vectors are
+imported, and the keyword index is rebuilt for anything that moved. A tap
+already sitting at the published commit with those vectors already built is
+skipped without downloading anything, so in a week where a registry did not
+move the command does nothing at all — which is what makes it safe to schedule:
+
+```bash
+# refresh prebuilt vectors every Monday at 09:00 — crontab -e
+0 9 * * 1 /full/path/to/boost update --shards >> ~/.boost/logs/shards.log 2>&1
+```
+
+Plain `boost update` moves each tap to its branch head; `--shards` moves each
+tap to the commit the published vectors describe. Two different targets, so
+they are separate modes rather than one pass, and `--shards --taps-only` is
+refused rather than silently picking one.
+
 Because vectors are keyed to a registry's commit, `quickstart` **pins** each tap
 it fetches vectors for, and `boost update` skips a pinned tap rather than moving
 it out from under them (`--force` moves it anyway and drops the pin). When a tap
 does move, boost checks whether a newer shard exists for the new commit and
 imports it; if none does, it says so instead of leaving stale vectors looking
-fresh. `boost search` never refreshes taps behind your back — it prints one line
-when they are more than two weeks old and leaves the fetching to
-`boost update --taps-only`.
+fresh. `boost search` never refreshes taps behind your back, and never checks
+the manifest either — acting on that answer means moving taps and downloading
+hundreds of megabytes, which cannot happen inside a sub-second search. It prints
+one line when the taps or the prebuilt vectors are more than two weeks old and
+leaves the fetching to `boost update --taps-only` or `boost update --shards`.
 Every download is checked against the sha256 in the manifest and refused on a
 mismatch, and shards for a registry that has moved since publication are
 refused rather than merged — stale vectors would otherwise look fresh forever.

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/README.md

@@ -155,14 +155,34 @@ for every one that has a published shard.
 Already tapped? `boost reindex --fetch-shards` does the download half alone,
 and `boost reindex --dense` embeds locally whatever has no published shard.
 
+Vectors are republished weekly, and `boost update --shards` is the ingestion
+side of that. It reads the manifest as the *target* state: each tap is moved
+onto the commit its published vectors were built from, those vectors are
+imported, and the keyword index is rebuilt for anything that moved. A tap
+already sitting at the published commit with those vectors already built is
+skipped without downloading anything, so in a week where a registry did not
+move the command does nothing at all — which is what makes it safe to schedule:
+
+```bash
+# refresh prebuilt vectors every Monday at 09:00 — crontab -e
+0 9 * * 1 /full/path/to/boost update --shards >> ~/.boost/logs/shards.log 2>&1
+```
+
+Plain `boost update` moves each tap to its branch head; `--shards` moves each
+tap to the commit the published vectors describe. Two different targets, so
+they are separate modes rather than one pass, and `--shards --taps-only` is
+refused rather than silently picking one.
+
 Because vectors are keyed to a registry's commit, `quickstart` **pins** each tap
 it fetches vectors for, and `boost update` skips a pinned tap rather than moving
 it out from under them (`--force` moves it anyway and drops the pin). When a tap
 does move, boost checks whether a newer shard exists for the new commit and
 imports it; if none does, it says so instead of leaving stale vectors looking
-fresh. `boost search` never refreshes taps behind your back — it prints one line
-when they are more than two weeks old and leaves the fetching to
-`boost update --taps-only`.
+fresh. `boost search` never refreshes taps behind your back, and never checks
+the manifest either — acting on that answer means moving taps and downloading
+hundreds of megabytes, which cannot happen inside a sub-second search. It prints
+one line when the taps or the prebuilt vectors are more than two weeks old and
+leaves the fetching to `boost update --taps-only` or `boost update --shards`.
 Every download is checked against the sha256 in the manifest and refused on a
 mismatch, and shards for a registry that has moved since publication are
 refused rather than merged — stale vectors would otherwise look fresh forever.

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.58'
-__version_tuple__ = version_tuple = (1, 2, 58)
+__version__ = version = '1.2.60'
+__version_tuple__ = version_tuple = (1, 2, 60)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/boost_cli/commands/discovery.py

@@ -218,6 +218,8 @@ def _hint_stale_taps() -> None:
     price of one stat, and a machine that has never refreshed says nothing at
     all rather than inventing an age.
     """
+    if _hint_stale_shards():
+        return
     age = registry.refresh_age_days()
     if age is None or age < registry.STALE_TAPS_DAYS:
         return
@@ -226,6 +228,37 @@ def _hint_stale_taps() -> None:
         % int(age), "muted"))
 
 
+def _hint_stale_shards() -> bool:
+    """Mention un-ingested published vectors. One `stat`, and never a network call.
+
+    The published manifest is ~170 KB, so checking it inline would be cheap —
+    and cheapness is not the argument. Acting on the answer means moving taps
+    and downloading hundreds of megabytes, which cannot happen inside a
+    sub-second search, so the most an inline check could ever produce is this
+    one line: the same line, for the price of a network round trip on every
+    query and unannounced egress at that. The marker's mtime answers it for
+    free, and a machine that has never ingested a shard says nothing rather
+    than inventing an age.
+
+    Returns True when it printed, so the tap-age hint stays quiet. The remedy
+    named here moves the taps as well, and two staleness lines under one set of
+    results is how a hint turns into noise.
+    """
+    from ..core import shards
+    age = shards.sync_age_days()
+    if age is None or age < shards.STALE_SHARDS_DAYS:
+        return False
+    from ..core import dense
+    if not dense.status().get("ready"):
+        # Vectors that are not serving queries cannot be stale in a way the
+        # user can act on; `_hint_semantic_search` owns that conversation.
+        return False
+    out.info(out.role(
+        "prebuilt vectors last refreshed %d days ago — `boost update --shards`"
+        % int(age), "muted"))
+    return True
+
+
 def _hint_semantic_search(engine: str) -> None:
     """Say that a better engine exists, when BM25 answered alone.
 
@@ -315,8 +348,12 @@ def _fetch_shards(args) -> int:
                         hint=dense.fix_hint(dense.status().get("reason", "")))
     commits = rag._tap_commits()
     by_name = {t.name: commits.get(t.safe_name, "") for t in registry.list_taps()}
-    results = shards.sync(list(by_name), by_name, manifest=manifest,
-                          on_event=_shard_event)
+    results = shards.sync(
+        list(by_name), by_name, manifest=manifest,
+        # Progress goes to stdout, and so does the JSON: emitting both left
+        # `--json` printing "fetching ..." lines ahead of the document, which
+        # no parser can read past.
+        on_event=None if args.as_json else _shard_event)
     if args.as_json:
         print(json.dumps({"shards": results}, indent=2))
         return 0
@@ -335,6 +372,12 @@ def _fetch_shards(args) -> int:
         out.info(out.role("%d tap(s) without usable vectors: %s"
                           % (len(missing), ", ".join(missing[:5])
                              + (" …" if len(missing) > 5 else "")), "muted"))
+        if any(r["status"] == "refused" for r in results):
+            # A refusal here is almost always "the tap has moved past the
+            # commit these vectors describe", which local embedding is the
+            # expensive answer to and `--shards` is the cheap one: it moves the
+            # tap back onto a published commit instead.
+            out.info("taps that moved past their vectors: `boost update --shards`")
         out.info("embed those locally with `boost reindex --dense`")
     return 0
 

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/boost_cli/commands/pkg.py

@@ -16,7 +16,7 @@ from datetime import UTC, datetime
 from itertools import chain
 from pathlib import Path
 
-from .. import cliparse
+from .. import cliparse, spin
 from ..core import (
     adapters,
     agents,
@@ -878,6 +878,103 @@ def _resync_vectors(moved: list[str]) -> None:
                           "`boost reindex --dense`" % left, "muted"))
 
 
+def _ingest_event(tap: str, status: str, detail: str) -> None:
+    """Progress for one tap, quiet enough to run over four hundred of them."""
+    if status == "downloading":
+        out.info(out.role("fetching %s %s" % (tap, detail), "muted"))
+    elif status == "moving":
+        out.info(out.role("moving %s to %s" % (tap, detail), "muted"))
+    elif status == "failed":
+        out.info(out.role("%s: failed%s"
+                          % (tap, " (%s)" % detail if detail else ""), "muted"))
+
+
+def _ingest_shards(args) -> int:
+    """`boost update --shards`: refresh vectors from the published manifest.
+
+    Its own mode rather than a step of the normal update, because the two move
+    taps toward different targets: a plain `boost update` moves each tap to its
+    branch HEAD, and this moves each tap to the commit the published vectors
+    were built from. Running both in one pass would move every tap twice and
+    leave the second answer standing, so the flag replaces the update rather
+    than extending it.
+
+    This is the ingestion path for the weekly shard run. It is a no-op on a
+    machine that already holds this week's vectors, which is what makes it
+    safe to put in a cron line — see the docs.
+    """
+    from ..core import dense, shards
+    taps = registry.list_taps()
+    if not taps:
+        raise BoostError("no taps configured — nothing to refresh",
+                         hint="`boost quickstart` taps the starters and loads "
+                              "their vectors in one pass")
+    manifest = shards.fetch_manifest()
+    why = shards.incompatible(manifest)
+    if why:
+        raise BoostError("published shards cannot serve this machine — %s" % why,
+                         hint=dense.fix_hint(dense.status().get("reason", "")))
+    commits = rag._tap_commits()
+    stored = dense.tap_commits()
+    # Both maps are keyed by tap name; the two sources are keyed by safe name.
+    by_name = {t.name: commits.get(t.safe_name, "") for t in taps}
+    built = {t.name: stored.get(t.safe_name, "") for t in taps}
+    results = shards.ingest(
+        list(by_name), by_name, built=built, manifest=manifest,
+        # Progress goes to stdout, which is where the JSON goes: under `--json`
+        # the two would interleave into something no parser can read.
+        on_event=None if args.as_json else _ingest_event)
+
+    imported = [r for r in results if r["status"] == "imported"]
+    current = [r for r in results if r["status"] == "current"]
+    failed = [r for r in results if r["status"] == "failed"]
+    moved = [r["tap"] for r in results if r.get("moved")]
+    # Before the output branch, never inside it: a tap that moved is describing
+    # a different tree, so its catalog cache and the keyword index both name
+    # entries that may no longer exist. Vectors are not the only thing a commit
+    # is load-bearing for, and a `--json` caller is owed the same repair.
+    for name in moved:
+        catalog.rebuild_tap(registry.get(name))
+    if moved:
+        # Spinners write to stderr, so this is safe under `--json`.
+        with spin.Spinner("rebuilding the keyword index"):
+            rag.build()
+        complete.refresh_names()
+    journal.log("update", "--shards")
+    # Nothing landed and nothing was already current: the manifest and this
+    # machine have nothing to say to each other, which a cron line should
+    # notice rather than read as a quiet success.
+    rc = 1 if failed and not imported and not current else 0
+    if args.as_json:
+        print(json.dumps({"shards": results}, indent=2))
+        return rc
+
+    if imported:
+        total = sum(int(r.get("chunks") or 0) for r in imported)
+        out.ok("imported %s (%s chunk%s)%s"
+               % (_plural(len(imported), "shard"), format(total, ","),
+                  "" if total == 1 else "s",
+                  ", %d moved to a newer commit" % len(moved) if moved else ""))
+    if current:
+        out.info(out.role("%s already at the published commit"
+                          % _plural(len(current), "tap"), "muted"))
+    if not imported and not current:
+        # Never a tick. Nothing landed, and "imported 0" with a tick reads as a
+        # job well done to the one user who most needs to know otherwise.
+        out.warn("no published vectors matched your taps")
+    unpublished = [r["tap"] for r in results if r["status"] == "unpublished"]
+    if unpublished:
+        out.info(out.role(
+            "%s not in the manifest, left where they are: %s"
+            % (_plural(len(unpublished), "tap"), ", ".join(unpublished[:5])
+               + (" …" if len(unpublished) > 5 else "")), "muted"))
+    for r in failed:
+        out.warn("%s: %s" % (r["tap"], r.get("detail") or "failed"))
+    if failed:
+        out.info("embed those locally with `boost reindex --dense`")
+    return rc
+
+
 def cmd_update(argv: list[str]) -> int:
     ap = cliparse.parser(prog="boost update",
                                  description="Sync taps or update installed skills")
@@ -894,7 +991,16 @@ def cmd_update(argv: list[str]) -> int:
                     help="skip the confirmation prompt")
     ap.add_argument("--force", action="store_true",
                     help="move pinned taps too, clearing their pin")
+    ap.add_argument("--shards", action="store_true",
+                    help="refresh prebuilt vectors from the published "
+                         "manifest, moving taps to the commits it names")
+    ap.add_argument("--json", dest="as_json", action="store_true",
+                    help="with --shards: print the per-tap result as JSON")
     args = ap.parse_args(argv)
+    if args.shards:
+        if args.taps_only:
+            ap.error("--shards and --taps-only move taps to different commits")
+        return _ingest_shards(args)
     results, failures = registry.update(args.tap or None, force=args.force)
     if not results and not failures:
         out.info("no taps configured — start with `boost tap --defaults`")

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/boost_cli/commands/quality.py

@@ -24,6 +24,7 @@ from ..core import (
     agents,
     ai,
     catalog,
+    claude_settings,
     complete,
     frontmatter,
     gitutil,
@@ -549,6 +550,20 @@ def cmd_doctor(argv):
                  "left alone; yours to remove or repair"
                  % (len(foreign), _s(len(foreign))))
 
+    others = claude_settings.foreign_hooks("global")
+    if others:
+        # `out.info`, not `bad`, for the same reason as the foreign symlinks
+        # above: boost did not write these and will never remove them, so
+        # counting them would leave doctor permanently red on something no
+        # boost command can clear. Naming them is still worth a line — at
+        # 130k stars gstack is now a likely second writer of this exact file,
+        # and a user debugging a hook needs to know boost is not the only one
+        # in it.
+        events = sorted({h["event"] for h in others})
+        out.info("%d hook%s in ~/.claude/settings.json not managed by boost "
+                 "(%s) — left alone; `boost hooks` only touches its own"
+                 % (len(others), _s(len(others)), ", ".join(events)), wrap=True)
+
     for dup in store.duplicate_discovery():
         # An agent that reads the canonical store natively, holding its own
         # entry for a skill that store already carries. Boost did not put it

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/boost_cli/core/claude_settings.py

@@ -200,6 +200,42 @@ def has_hook(scope: str, event: str, name: str,
     return False
 
 
+def foreign_hooks(scope: str | None = None,
+                  project_dir: Path | None = None,
+                  host: str = hookhost.CLAUDE) -> list[dict]:
+    """Hooks in this host's settings that boost does not own.
+
+    The complement of :func:`list_hooks`, which skips every entry without the
+    `# boost:` marker — so boost could write this file for years and never be
+    able to say who else was writing it. That matters now that a settings.json
+    routinely has more than one writer: `garrytan/gstack`'s `./setup` registers
+    its own Stop hooks here and prunes "dead gstack entries" on every run, and
+    boost prunes its own by marker. The two namespaces are disjoint and
+    `tests/unit/test_gstack_coexistence.py` pins that they stay that way.
+
+    This exists so `boost doctor` can *report* the other tenant rather than
+    discover it by deleting something. Nothing here writes: a foreign hook is
+    not a boost problem to fix, it is context for a user reading a health
+    check — which is why doctor counts it with `out.info` rather than raising
+    the issue count.
+    """
+    scopes = (scope,) if scope else SCOPES
+    rows: list[dict] = []
+    for sc in scopes:
+        data = load(sc, project_dir, host)
+        for event, blocks in (data.get("hooks") or {}).items():
+            for block in blocks or []:
+                if not isinstance(block, dict):
+                    continue
+                for h in block.get("hooks") or []:
+                    raw = str(h.get("command", ""))
+                    if _hook_name(raw) is not None:
+                        continue        # ours
+                    rows.append({"scope": sc, "event": event, "command": raw,
+                                 "matcher": block.get("matcher", "")})
+    return rows
+
+
 def list_hooks(scope: str | None = None,
                project_dir: Path | None = None,
                host: str = hookhost.CLAUDE) -> list[dict]:

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/boost_cli/core/config.py

@@ -131,6 +131,31 @@ def load_registry_catalog() -> list:
     return data.get("registries", [])
 
 
+def self_installing_command(tap: str) -> str | None:
+    """The repo's own install command, when boost must not copy its items.
+
+    Some registries are real catalogues of Markdown and some are programs that
+    happen to ship Markdown entry points. For the second kind boost's install —
+    copy the item's directory into the canonical store, symlink it out — yields
+    a skill that *looks* installed and cannot run, because the step that makes
+    it work is the repo's own build, not a fetch. Returns the upstream command
+    so the caller can name it instead of pretending; None for every other tap.
+
+    The tap may be addressed by full ``owner/repo`` or by the bare repo name a
+    clone directory carries, so both resolve.
+    """
+    if not tap:
+        return None
+    for row in load_registry_catalog():
+        cmd = row.get("self_installing")
+        if not cmd:
+            continue
+        name = row.get("name") or ""
+        if tap in (name, name.split("/")[-1]):
+            return cmd
+    return None
+
+
 def _merge(base: dict, override: dict) -> dict:
     out = deepcopy(base)
     # `or {}`: the only caller feeds this json.loads() of config.json, so a file

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/boost_cli/core/dense.py

@@ -289,6 +289,25 @@ def _recorded_meta(*, count: bool = False) -> dict:
         con.close()
 
 
+def tap_commits() -> dict[str, str]:
+    """Which registry commit this store holds vectors for, per tap safe-name.
+
+    The store already records this — ``build`` writes it and ``import_shard``
+    updates it — but only as a private meta field, so every caller that wanted
+    to ask "are these vectors for the commit I have?" had to re-open the
+    database. That question is the whole basis of skipping work: a weekly shard
+    refresh is a no-op exactly when the answer is yes, and without an accessor
+    the refresh would download and re-import a store's own rows every week.
+
+    Read without sqlite-vec (see :func:`_recorded_meta`) so a machine that lost
+    the extra still gets a truthful answer rather than an empty one.
+    """
+    commits = _recorded_meta().get("commits")
+    if not isinstance(commits, dict):
+        return {}
+    return {str(k): str(v) for k, v in commits.items() if v}
+
+
 # Why dense retrieval isn't serving, keyed by the `reason` status() returns.
 # Each names the ONE next action; the reason order in status() guarantees only
 # the first missing link is ever reported, so these never chain.

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/boost_cli/core/paths.py

@@ -113,6 +113,18 @@ def tap_refresh_marker() -> Path:
     return state_dir() / "last-tap-refresh"
 
 
+def shard_sync_marker() -> Path:
+    """File whose mtime records when published vectors were last ingested.
+
+    Deliberately beside the tap marker and NOT under ``cache/``: `boost clean`
+    sweeps `cache/*.json` whose stem is not a tap, and a marker there would be
+    deleted on every clean — after which search would nag about vectors that
+    were refreshed this morning. Same one-`stat` contract as the tap marker,
+    for the same reason: search reads it, and search does no network.
+    """
+    return state_dir() / "last-shard-sync"
+
+
 def snapshots_dir() -> Path:
     """Return the directory for ``snap-*`` store snapshot tarballs."""
     return state_dir() / "snapshots"

{boost_skill_cli-1.2.58 → boost_skill_cli-1.2.60}/boost_cli/core/registry.py

@@ -419,6 +419,27 @@ def unpin(name: str) -> Tap:
     return tap
 
 
+def retarget(name: str, commit: str) -> Tap:
+    """Move an existing tap's clone to `commit` and pin it there.
+
+    The operation a published-vector refresh needs and no other entry point
+    offers. :func:`add` refuses a registry that is already tapped — deliberately
+    — so its ``at=`` pin only ever serves a first tap; :func:`update` moves a tap
+    to its branch HEAD and ``--force`` moves it and drops the pin. None of the
+    three can land on the commit a manifest names, and the chance that HEAD
+    happens to be that commit falls with every push upstream, which is why a
+    week-old install could see its vectors go stale with no way to act on it
+    but re-embedding locally.
+
+    Checkout first, pin second, and never the reverse: a pin recorded for a
+    tree that was not checked out is a lie :func:`update` would then honour by
+    skipping the tap forever.
+    """
+    tap = get(name)
+    gitutil.checkout_commit(tap.path, commit)
+    return pin(name, commit)
+
+
 def remove(name: str) -> Tap:
     """Deregister a tap and delete its clone and cache file.