What causes "error: could not read {ref}: {result.stderr.strip()}" in Graphify-Labs/graphify?

Fetch the ref: `git fetch origin v8:refs/remotes/origin/v8` (or `git fetch --unshallow` in a shallow clone)

Graphify-Labs/graphify · error · SystemExit

error: could not read {ref}: {result.stderr.strip()}

Error message

error: could not read {ref}: {result.stderr.strip()}

What it means

skillgen's _git_show() helper reads file blobs out of git history (git show <ref>) to power validators such as audit-coverage, monolith-roundtrip, and always-on-roundtrip, which compare rendered output against origin/v8 sources. If the git subprocess exits non-zero — bad ref, missing object, unreachable remote ref — the helper aborts with SystemExit embedding git's own stderr. The companion _v8_available() probe exists precisely because shallow CI checkouts often lack origin/v8.

Source

Thrown at tools/skillgen/gen.py:751

        # An ATX heading is 1-6 '#' then a space then text.
        if stripped.startswith("#"):
            hashes = len(stripped) - len(stripped.lstrip("#"))
            if 1 <= hashes <= 6 and stripped[hashes:hashes + 1] == " ":
                out.append(stripped.strip())
    return out


def _git_show(ref: str) -> str:
    """Read a blob from git, normalised to LF."""
    result = subprocess.run(
        ["git", "show", ref],
        cwd=REPO_ROOT,
        capture_output=True,
        text=True,
        encoding="utf-8",
    )
    if result.returncode != 0:
        raise SystemExit(f"error: could not read {ref}: {result.stderr.strip()}")
    return result.stdout


def _v8_available() -> bool:
    """Whether origin/v8 is fetchable in this checkout.

    The git-show validators (audit-coverage, monolith-roundtrip,
    always-on-roundtrip) read blobs from origin/v8. CI's default shallow checkout
    does not fetch that ref, so the validators set fetch-depth: 0 to fetch it.
    This probe lets the CLI skip with a clear, actionable message (rather than
    crash with a cryptic git error) when the ref is genuinely unreachable.
    """
    result = subprocess.run(
        ["git", "rev-parse", "--verify", "--quiet", "origin/v8"],
        cwd=REPO_ROOT,
        capture_output=True,
        text=True,
    )

View on GitHub (pinned to 7fe58b0b0f)

Solutions

Fetch the ref: `git fetch origin v8:refs/remotes/origin/v8` (or `git fetch --unshallow` in a shallow clone)
On GitHub Actions, set `fetch-depth: 0` on the actions/checkout step for the validator job
Run `git show <ref> --` manually with the failing ref to see git's underlying error and confirm the ref/path exists
If you cannot fetch the ref, rely on the CLI's skip path (_v8_available probe) instead of forcing the validator to run

Example fix

# before
# .github/workflows/ci.yml
- uses: actions/checkout@v4        # default fetch-depth: 1 → validators fail

# after
- uses: actions/checkout@v4
  with:
    fetch-depth: 0                 # origin/v8 fetchable → git-show validators run

Defensive patterns

Strategy: validation

Validate before calling

import subprocess

def ref_readable(ref: str) -> bool:
    return subprocess.run(
        ['git', 'show', ref], capture_output=True
    ).returncode == 0

if not ref_readable('origin/v8:path/to/file'):
    raise SystemExit('skip git-show validators: origin/v8 not fetched (use fetch-depth: 0 on CI)')

Try / catch

from tools.skillgen.gen import _git_show
try:
    blob = _git_show('origin/v8:skills/graphify/SKILL.md')
except SystemExit as e:
    raise SystemExit(f'validator input unavailable: {e}') from e

Prevention

Set fetch-depth: 0 on CI jobs that run the git-show validators
Run `git fetch origin v8` after creating or unshallowing a clone before invoking validators
Reuse the generator's _v8_available() probe to skip (not crash) when the ref is absent

When it happens

Trigger: Invoking any git-show-based validator (audit-coverage, monolith-roundtrip, always-on-roundtrip) in a checkout where origin/v8 (or the referenced blob path) cannot be resolved: shallow clone with fetch-depth != 0, a clone where origin/v8 was never fetched, a ref typo, or a path that does not exist in that ref.

Common situations: GitHub Actions default shallow checkout (fetch-depth: 1) missing origin/v8; running validators in a worktree or partial clone without the ref; a local clone whose remote refs are stale after the v8 branch was force-pushed.

Related errors

AI-assisted analysis of Graphify-Labs/graphify@7fe58b0b0f (2026-08-14). Data as JSON: /api/errors/49401da5c286dd6f. Report an issue: GitHub.