{"record":{"id":"c07d0a24c2bed1d6","repo":"usestrix/strix","slug":"unable-to-resolve-a-base-ref-for-diff-scope-pass","errorCode":null,"errorMessage":"Unable to resolve a base ref for diff-scope. Pass --diff-base explicitly (for example: --diff-base origin/main).","messagePattern":"Unable to resolve a base ref for diff-scope\\. Pass --diff-base explicitly \\(for example: --diff-base origin/main\\)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"strix/interface/utils.py","lineNumber":724,"sourceCode":"        github_candidate = f\"refs/remotes/origin/{github_base_ref}\"\n        if _git_ref_exists(repo_path, github_candidate):\n            return github_candidate\n\n    github_base_sha = _extract_github_base_sha(env)\n    if github_base_sha and _git_ref_exists(repo_path, github_base_sha):\n        return github_base_sha\n\n    origin_head = _resolve_origin_head_ref(repo_path)\n    if origin_head and _git_ref_exists(repo_path, origin_head):\n        return origin_head\n\n    if _git_ref_exists(repo_path, \"refs/remotes/origin/main\"):\n        return \"refs/remotes/origin/main\"\n\n    if _git_ref_exists(repo_path, \"refs/remotes/origin/master\"):\n        return \"refs/remotes/origin/master\"\n\n    raise ValueError(\n        \"Unable to resolve a base ref for diff-scope. Pass --diff-base explicitly \"\n        \"(for example: --diff-base origin/main).\"\n    )\n\n\ndef _get_current_branch_name(repo_path: Path) -> str | None:\n    result = _run_git_command(repo_path, [\"rev-parse\", \"--abbrev-ref\", \"HEAD\"], check=False)\n    if result.returncode != 0:\n        return None\n    branch_name = result.stdout.strip()\n    if not branch_name or branch_name == \"HEAD\":\n        return None\n    return branch_name\n\n\ndef _parse_name_status_z(raw_output: bytes) -> list[DiffEntry]:\n    if not raw_output:\n        return []","sourceCodeStart":706,"sourceCodeEnd":742,"githubUrl":"https://github.com/usestrix/strix/blob/85513391305171ecc6faffe03da4a8bda5e3febb/strix/interface/utils.py#L706-L742","documentation":"Raised by _resolve_base_ref (utils.py:724) when diff-scope mode needs a comparison base but none can be resolved: the caller did not pass --diff-base, no GitHub base SHA was derivable, the origin HEAD ref is missing, and neither refs/remotes/origin/main nor refs/remotes/origin/master exists in the repository. Strix refuses to guess a base silently, so it demands an explicit one.","triggerScenarios":"Enabling diff-scope on a repo whose default branch is neither main nor master (e.g. 'develop', 'trunk') with no --diff-base given; a shallow/partial clone lacking remote refs; a repo with no 'origin' remote; CI checkouts that fetch only the PR ref without base branch refs.","commonSituations":"GitHub Actions default checkout (fetch-depth 1, no other branches); GitLab 'trunk'-default projects; forks where origin points at the fork with unrelated branches; repos using non-standard default branch names.","solutions":["Pass --diff-base explicitly, e.g. --diff-base origin/develop","Fetch the base branch first: git fetch origin develop, then use --diff-base origin/develop","In CI, configure the checkout to fetch the default branch (fetch-depth: 0 or refs spec)","Rename/align to main or master, or create refs/remotes/origin/main by fetching the default branch"],"exampleFix":"# before\nstrix -t . --diff-scope  # default branch is 'develop'\n# ValueError: Unable to resolve a base ref ...\n\n# after\ngit fetch origin develop\nstrix -t . --diff-scope --diff-base origin/develop","handlingStrategy":"validation","validationCode":"if not diff_base:\n    if not (_git_ref_exists(repo, \"refs/remotes/origin/main\") or _git_ref_exists(repo, \"refs/remotes/origin/master\")):\n        raise SystemExit(\"default branch is not main/master; pass --diff-base origin/<branch>\")","typeGuard":"def has_resolvable_base(repo_path) -> bool:\n    return any(_git_ref_exists(repo_path, r) for r in (\"refs/remotes/origin/main\", \"refs/remotes/origin/master\"))","tryCatchPattern":"try:\n    run_diff_scope_scan()\nexcept ValueError as e:\n    if \"Unable to resolve a base ref\" in str(e):\n        fetch_and_retry_with_explicit_base()  # git fetch origin <default>; --diff-base origin/<default>\n    else:\n        raise","preventionTips":["Always pass --diff-base in CI where default branches are non-standard","Fetch the default branch ref before diff-scope runs","Prefer refs/remotes/origin/<name> spelling over bare branch names"],"tags":["git","diff-scope","configuration","ci"],"backgroundTag":null,"analyzedSha":"85513391305171ecc6faffe03da4a8bda5e3febb","analyzedAt":"2026-08-15T05:03:57.275Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}