Document parity gate and fix fetch refspecs

Author: blhsing

README.md

@@ -116,11 +116,18 @@ pygit convert-object-format --object-format=sha1 ./sha256-copy ./sha1-copy
 
 ## Supported commands
 
-The command surface covers git built-ins plus aliases and pythongit-specific
-helpers. CLI parity is tracked against C Git 2.54.0 from the upstream
-implementation source: `tools/git_cli_manifest.py` generates
-`tests/git_parity/manifest/git-2.54.0.json`. A dedicated CI job builds a
-`git version 2.54.0` oracle and runs:
+The command surface covers the 147 built-ins from C Git 2.54.0 plus
+pythongit-specific helpers. Runtime registration is checked against the
+source-derived manifest in
+`tests/git_parity/manifest/git-2.54.0.json`, so upstream built-in names such as
+`stage`, `pickaxe`, `fsck-objects`, `checkout--worker`,
+`credential-cache--daemon`, and `submodule--helper` remain available under the
+same spellings as C Git. Pythongit-only helpers are kept separate from the
+compatibility surface.
+
+CLI parity is tracked against C Git 2.54.0 from the upstream implementation
+source: `tools/git_cli_manifest.py` regenerates the manifest, and a dedicated
+CI job builds a `git version 2.54.0` oracle and runs:
 
 ```bash
 PYGIT_PARITY_GIT=/path/to/git-2.54.0 \
@@ -350,8 +357,8 @@ bodies.
 ## Testing
 
 ```bash
-pip install pythongit[test]
-pytest
+pip install -e ".[test]"
+python -m pytest
 ```
 
 The suite passes:
@@ -366,9 +373,24 @@ The suite passes:
 | `unit_integration.py`   | end-to-end CLI flows incl. ort-backed conflicts, rename-aware merge, rerere replay, SHA-256 translation, loose cache, streaming upload-pack, recursive tree diff |
 | `test_ort_parity.py`    | byte-for-byte `ort` parity vs `git merge-tree --write-tree` across every conflict type (content, modify/delete, add/add, rename/rename, rename/delete, directory rename, distinct-types, exec-bit) |
 | `unit_phase_scripts.py` | wraps the script-style phase tests |
+| `tests/git_parity`      | C Git 2.54.0 manifest coverage, exact built-in registry coverage, and oracle behavior comparisons |
 
 Tests that require the real `git` binary are silently skipped when it's not on
-PATH, so the suite runs cleanly in containers without one.
+PATH, so the normal suite runs cleanly in containers without one. The dedicated
+`git-254-parity` CI job is stricter: it builds C Git 2.54.0 from the pinned
+upstream tarball, verifies the archive SHA-256, sets `PYGIT_PARITY_GIT`, and
+runs the parity tests with `--require-git-254-oracle`.
+
+To run the same required parity gate locally, build or install a `git version
+2.54.0` binary and run:
+
+```bash
+PYGIT_PARITY_GIT=/path/to/git-2.54.0 \
+  python -m pytest tests/git_parity --require-git-254-oracle
+```
+
+Without `--require-git-254-oracle`, the behavior-comparison tests skip when the
+oracle is unavailable, while manifest and registry coverage still run.
 
 The pure-Python `ort` engine is additionally cross-checked against C Git with
 the differential fuzzers in `tests/diff_xdiff_harness.py` (blob-level 3-way
@@ -411,16 +433,20 @@ randomized cases.
 ## Contributing
 
 The project tries to follow git's published wire and on-disk format specs
-(`Documentation/gitformat-*.adoc`, `Documentation/technical/*.adoc`). When
-adding a feature:
-
-1. Find the matching `builtin/<name>.c` and read its argument parser to figure
-   out the flag set people actually use.
-2. Implement the behavior, but only the common flags first. Less-common flags
-   should `argparse.error` rather than silently misbehave.
-3. Add a unit test in `tests/unit_*.py`. If real `git` can verify the output,
-   also add an interop check.
-4. Run `pytest` — must remain green.
+(`Documentation/gitformat-*.adoc`, `Documentation/technical/*.adoc`) and C Git
+2.54.0's implementation behavior. When adding or changing CLI behavior:
+
+1. Find the matching C implementation in the Git 2.54.0 source and compare its
+   parser, setup flags, output, exit codes, and repository mutations.
+2. Regenerate or inspect `tests/git_parity/manifest/git-2.54.0.json` with
+   `tools/git_cli_manifest.py` when the upstream source target changes.
+3. Keep every C Git built-in registered under its exact 2.54.0 name; classify
+   any pythongit-only command in `_PYGIT_EXTENSION_COMMANDS`.
+4. Add focused unit/integration tests plus a `tests/git_parity` oracle case for
+   user-visible CLI behavior whenever the command can be exercised
+   deterministically.
+5. Run `python -m pytest`; when a Git 2.54.0 binary is available, also run the
+   required parity gate shown above.
 
 ## License
 

pythongit/cli.py

@@ -1310,10 +1310,11 @@ def cmd_stash(argv: list[str]) -> int:
 def cmd_fetch(argv: list[str]) -> int:
     ap = argparse.ArgumentParser(prog="pygit fetch")
     ap.add_argument("remote", nargs="?", default="origin")
+    ap.add_argument("refspecs", nargs="*")
     args = ap.parse_args(argv)
     repo = _repo()
     from . import protocol
-    updated = protocol.fetch(repo, args.remote)
+    updated = protocol.fetch(repo, args.remote, args.refspecs or None)
     for ref, sha in updated.items():
         _print(f" * {ref} -> {sha[:7]}")
     if not updated:

pythongit/protocol.py

@@ -371,10 +371,46 @@ def clone(url: str, target_dir: str, object_format: str | None = None) -> Reposi
 
 
 # ---------------------------------------------------------------------------
-# fetch — like clone, but updates remote-tracking refs only.
+# fetch — like clone; default fetch updates remote-tracking refs, while
+# explicit branch refspecs are fetched to FETCH_HEAD unless a destination is
+# given.
 
 
-def fetch(repo: Repository, remote: str = "origin") -> dict[str, str]:
+def _resolve_remote_fetch_ref(remote_refs: dict[str, str], source: str) -> tuple[str, str]:
+    candidates = [source]
+    if not source.startswith("refs/"):
+        candidates.extend((f"refs/heads/{source}", f"refs/tags/{source}"))
+    for name in candidates:
+        sha = remote_refs.get(name)
+        if sha:
+            return name, sha
+    raise RuntimeError(f"couldn't find remote ref {source}")
+
+
+def _normalize_fetch_destination(remote_name: str, destination: str) -> str:
+    if destination.startswith("refs/"):
+        return destination
+    if remote_name.startswith("refs/tags/"):
+        return f"refs/tags/{destination}"
+    return f"refs/heads/{destination}"
+
+
+def _fetch_head_note(remote_name: str, url: str) -> str:
+    if remote_name == "HEAD":
+        return f"'{remote_name}' of {url}"
+    if remote_name.startswith("refs/heads/"):
+        return f"branch '{remote_name[len('refs/heads/'):]}' of {url}"
+    if remote_name.startswith("refs/tags/"):
+        return f"tag '{remote_name[len('refs/tags/'):]}' of {url}"
+    return f"'{remote_name}' of {url}"
+
+
+def _write_fetch_head(repo: Repository, entries: list[tuple[str, str]], url: str) -> None:
+    lines = [f"{sha}\t\t{_fetch_head_note(name, url)}\n" for name, sha in entries]
+    (repo.gitdir / "FETCH_HEAD").write_text("".join(lines), encoding="utf-8")
+
+
+def fetch(repo: Repository, remote: str = "origin", refspecs: list[str] | None = None) -> dict[str, str]:
     from . import pack as pack_mod
     from . import refs as refs_mod
     cp = repo.config()
@@ -389,7 +425,19 @@ def fetch(repo: Repository, remote: str = "origin") -> dict[str, str]:
         s = refs_mod.read_ref(repo, f"refs/heads/{b}")
         if s:
             haves.append(s)
-    wants = sorted(set(remote_refs.values()) - set(haves))
+    explicit: list[tuple[str, str, str | None]] = []
+    if refspecs:
+        for raw in refspecs:
+            spec = raw[1:] if raw.startswith("+") else raw
+            source, has_destination, destination = spec.partition(":")
+            if not source:
+                continue
+            remote_name, sha = _resolve_remote_fetch_ref(remote_refs, source)
+            dst_ref = _normalize_fetch_destination(remote_name, destination) if has_destination and destination else None
+            explicit.append((remote_name, sha, dst_ref))
+        wants = sorted({sha for _name, sha, _dst in explicit} - set(haves))
+    else:
+        wants = sorted(set(remote_refs.values()) - set(haves))
     updated: dict[str, str] = {}
     if wants:
         tmp_pack = None
@@ -409,15 +457,28 @@ def fetch(repo: Repository, remote: str = "origin") -> dict[str, str]:
                     os.unlink(str(Path(tmp_pack).with_suffix(".idx")))
                 except OSError:
                     pass
+    if explicit:
+        fetch_head_entries = []
+        for name, sha, dst_ref in explicit:
+            if dst_ref:
+                cur = refs_mod.read_ref(repo, dst_ref)
+                if cur != sha:
+                    refs_mod.update_ref(repo, dst_ref, sha, message=f"fetch {remote}")
+                    updated[dst_ref] = sha
+            else:
+                fetch_head_entries.append((name, sha))
+                updated["FETCH_HEAD"] = sha
+        if fetch_head_entries:
+            _write_fetch_head(repo, fetch_head_entries, url)
+        return updated
     for name, sha in remote_refs.items():
-        if not name.startswith("refs/heads/"):
-            continue
-        branch = name[len("refs/heads/"):]
-        ref = f"refs/remotes/{remote}/{branch}"
-        cur = refs_mod.read_ref(repo, ref)
-        if cur != sha:
-            refs_mod.update_ref(repo, ref, sha, message=f"fetch {remote}")
-            updated[ref] = sha
+        if name.startswith("refs/heads/"):
+            branch = name[len("refs/heads/"):]
+            ref = f"refs/remotes/{remote}/{branch}"
+            cur = refs_mod.read_ref(repo, ref)
+            if cur != sha:
+                refs_mod.update_ref(repo, ref, sha, message=f"fetch {remote}")
+                updated[ref] = sha
     return updated
 
 

tests/unit_integration.py

@@ -369,6 +369,27 @@ def test_remote_verbose_option(tmprepo, capsys):
     assert "origin\thttps://example.com/repo.git (push)" in out
 
 
+def test_fetch_accepts_explicit_refspec(tmprepo, monkeypatch, capsys):
+    from pythongit import protocol
+
+    repo, _ = tmprepo
+    captured = {}
+
+    def fake_fetch(fetch_repo, remote="origin", refspecs=None):
+        captured["repo"] = fetch_repo
+        captured["remote"] = remote
+        captured["refspecs"] = refspecs
+        return {"FETCH_HEAD": "a" * repo.hex_len}
+
+    monkeypatch.setattr(protocol, "fetch", fake_fetch)
+
+    assert cli_run("fetch", "origin", "main") == 0
+    assert captured["repo"].path == repo.path
+    assert captured["remote"] == "origin"
+    assert captured["refspecs"] == ["main"]
+    assert "FETCH_HEAD" in capsys.readouterr().out
+
+
 def test_global_options_before_command(tmprepo, capsys):
     repo, path = tmprepo
     cwd = os.getcwd()

tests/unit_modules.py

@@ -205,6 +205,44 @@ def test_protocol_auth_header_uses_github_token_env(tmp_path, monkeypatch):
     assert header == "Basic eC1hY2Nlc3MtdG9rZW46c2VjcmV0LXRva2Vu"
 
 
+def test_protocol_fetch_explicit_branch_writes_fetch_head(tmprepo, monkeypatch):
+    from pythongit import refs
+    from pythongit import pack as pack_mod
+
+    repo, _ = tmprepo
+    cfg = repo.gitdir / "config"
+    cfg.write_text(
+        cfg.read_text(encoding="utf-8")
+        + '[remote "origin"]\n'
+        + "\turl = https://example.com/repo.git\n"
+        + "\tfetch = +refs/heads/*:refs/remotes/origin/*\n",
+        encoding="utf-8",
+    )
+    main_sha = "a" * repo.hex_len
+    other_sha = "b" * repo.hex_len
+    wanted = []
+
+    monkeypatch.setattr(
+        protocol_mod,
+        "discover_refs",
+        lambda _url: {"refs/heads/main": main_sha, "refs/heads/other": other_sha},
+    )
+
+    def fake_fetch_pack_to_file(_url, wants, _path, haves=None):
+        wanted.extend(wants)
+        return 0
+
+    monkeypatch.setattr(protocol_mod, "fetch_pack_to_file", fake_fetch_pack_to_file)
+    monkeypatch.setattr(pack_mod, "install_pack_file", lambda _repo, _path: None)
+
+    updated = protocol_mod.fetch(repo, "origin", ["main"])
+
+    assert updated == {"FETCH_HEAD": main_sha}
+    assert wanted == [main_sha]
+    assert refs.read_ref(repo, "refs/remotes/origin/main") is None
+    assert "branch 'main' of https://example.com/repo.git" in (repo.gitdir / "FETCH_HEAD").read_text()
+
+
 # --- rerere ---------------------------------------------------------------