What causes "baseline ref {ref!r} is unavailable: {commit.stderr.strip()}" in Hmbown/CodeWhale?

Run git fetch --all (or git fetch origin ) so the baseline ref exists locally

Hmbown/CodeWhale · error · ValueError

baseline ref is unavailable

Error message

baseline ref {ref!r} is unavailable: {commit.stderr.strip()}

What it means

load_topology_at_ref verifies a baseline git ref (branch, tag, or commit) exists by running git rev-parse before reading the topology file at that ref. When the rev-parse exits nonzero it raises ValueError embedding git's stderr, because the checker cannot compare the current manifest against a baseline that does not resolve in this repository.

Solutions

Run git fetch --all (or git fetch origin <ref>) so the baseline ref exists locally
Fix the ref spelling passed to the checker
Use a ref that exists in a shallow checkout, or unshallow the clone (git fetch --unshallow)
Verify with git rev-parse <ref> manually before re-running the checker

Example fix

# before
python scripts/check-command-migration-manifest.py --baseline origin/main
# after
git fetch origin main
python scripts/check-command-migration-manifest.py --baseline origin/main

Defensive patterns

Strategy: validation

Validate before calling

import subprocess
r = subprocess.run(["git", "rev-parse", "--verify", ref], capture_output=True, text=True)
assert r.returncode == 0, f"baseline ref {ref} missing: run git fetch origin {ref}"

Try / catch

try:
    topology = load_topology_at_ref(root, ref)
except ValueError as exc:
    print(exc)  # includes git stderr
    sys.exit(2)

Prevention

Fetch the baseline branch explicitly in CI before running the checker
Avoid shallow clones (or use --unshallow) for jobs that compare against a baseline
Keep the baseline branch name in one config constant, not inline strings
Verify refs with git rev-parse after any branch rename

When it happens

Trigger: Running the migration-manifest checker with a baseline ref that is missing locally: a typo'd branch/tag, a ref that exists only on the remote (not fetched), a shallow clone lacking history, or a commit that was garbage-collected.

Common situations: CI checkout with depth=1 or single-branch so the baseline branch is absent; renamed/deleted baseline branch; running in a fresh worktree without fetching tags; passing main when the repo uses master (or vice versa).

Understand the failure class

Background: "git command failed": what it means when a tool shells out to git and git exits non-zero — this error's family across 21 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/c018cdf65f6d10ae. Report an issue: GitHub.

Appendix: source

Thrown at scripts/check-command-migration-manifest.py:501

        return [ManifestViolation(
            "frontier-projection",
            "PENDING_GROUPS",
            f"TUI projection {pending!r} does not equal JSON frontier {doc.get('frontier')!r}",
        )]
    return []


def load_topology_at_ref(ref: str, root: Path = REPO_ROOT) -> dict | None:
    """Load the topology from a Git revision; return None before its introduction."""
    commit = subprocess.run(
        ["git", "rev-parse", "--verify", f"{ref}^{{commit}}"],
        cwd=root,
        capture_output=True,
        text=True,
        check=False,
    )
    if commit.returncode != 0:
        raise ValueError(f"baseline ref {ref!r} is unavailable: {commit.stderr.strip()}")
    shown = subprocess.run(
        ["git", "show", f"{ref}:{TOPOLOGY_REPO_PATH}"],
        cwd=root,
        capture_output=True,
        text=True,
        check=False,
    )
    if shown.returncode != 0:
        return None
    return json.loads(shown.stdout)


def validate_baseline_transition(current: dict, previous: dict | None) -> list[ManifestViolation]:
    """Enforce immutable topology and shrink-or-declared-split across revisions."""
    if validate_topology_document(current):
        return [ManifestViolation(
            "current",
            "topology",

View on GitHub (pinned to 433685b202)