pypa/pip · error · ValueError

unexpected show-ref line: {line!r}

Error message

unexpected show-ref line: {line!r}

What it means

ValueError raised by Git.resolve_revision while parsing `git show-ref` output when a line cannot be split into exactly sha + ref name. Each line should look like '<40-hex-sha> refs/...'. If split(' ', maxsplit=2) yields a different arity, the offending line is included verbatim for diagnosis. This is a defensive guard against unexpected git output (or malicious unicode separators — note pip deliberately does NOT use splitlines for that reason).

Source

Thrown at src/pip/_internal/vcs/git.py:173

            cwd=dest,
            show_stdout=False,
            stdout_only=True,
            on_returncode="ignore",
        )
        refs = {}
        # NOTE: We do not use splitlines here since that would split on other
        #       unicode separators, which can be maliciously used to install a
        #       different revision.
        for line in output.strip().split("\n"):
            line = line.rstrip("\r")
            if not line:
                continue
            try:
                ref_sha, ref_name = line.split(" ", maxsplit=2)
            except ValueError:
                # Include the offending line to simplify troubleshooting if
                # this error ever occurs.
                raise ValueError(f"unexpected show-ref line: {line!r}")

            refs[ref_name] = ref_sha

        branch_ref = f"refs/remotes/origin/{rev}"
        tag_ref = f"refs/tags/{rev}"

        sha = refs.get(branch_ref)
        if sha is not None:
            return (sha, True)

        sha = refs.get(tag_ref)

        return (sha, False)

    @classmethod
    def _should_fetch(cls, dest: str, rev: str) -> bool:
        """
        Return true if rev is a ref or is a commit that we don't have locally.

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Reproduce manually: `git show-ref <rev>` in the checkout and inspect non-standard lines.
2. Remove any git wrapper/alias that prints extra output to stdout (move it to stderr).
3. Upgrade git to a standard release; avoid patched distributions.
4. Ensure GIT_EXECUTABLE points at the real git binary.

Example fix

// before
# ~/.gitconfig aliases or a wrapper printed a banner to stdout
pip install git+https://example.com/repo.git@v1

// after
# remove stdout noise; rerun:
git config --global --unset core.gitproxy
pip install -v git+https://example.com/repo.git@v1

import subprocess, re
LINE_RE = re.compile(r'^[0-9a-f]{40} \S+$')
def show_ref_clean(repo: str, rev: str) -> bool:
    out = subprocess.run(['git','show-ref',rev], cwd=repo,
                         capture_output=True, text=True).stdout
    return all(LINE_RE.match(l) for l in out.splitlines() if l.strip())

null

null

When it happens

Trigger: Calling pip's VCS git support to resolve a revision when `git show-ref <rev>` emits a line that isn't the standard '<sha> <ref>' format. Possible if a hooked-in git wrapper, an alias, or a tampered git binary emits extra output, or if a unicode separator sneaks through despite the splitlines guard.

Common situations: Custom GIT_EXECUTABLE or wrapper script that prints banners/logs to stdout; git alias output; corrupted/old git version; very unusual ref names; security probe trying to inject a ref via unicode separators.

Related errors

• Key does not contain dot separated section and key. Perhaps
• Got invalid value for load_only - should be one of {}
• No such key - {orig_key}
• Fatal Internal error [id=1]. Please report as a bug.
• An error occurred while writing to the configuration file {f

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/a7902a199e75dad0.json. Report an issue: GitHub.