tests: e2e: add tests for network-only & local-only syncs

Cover `repo sync -n` & `-l` on existing checkouts (interleaved &
phased), projects that were never fetched, and two-phase syncs with a
superproject.  `-l` must not touch the network, which the tests check by
taking the server offline.  Also cover tags (`--no-tags` & `sync-tags`),
`--prune`, `--force-sync`, `--force-remove-dirty` & `-d`.

Teach the harness to simulate outages (`GitHost.offline`) and to collect
the requests made during a block (`GitHost.watch_requests`), and add a
few `RepoClient` helpers.

Bug: 566270944
Change-Id: I96b4729a7d4e5b58bc57fb46a060beda35549979
Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/648545
Tested-by: Brian Gan <brgan@google.com>
Commit-Queue: Brian Gan <brgan@google.com>
Reviewed-by: Gavin Mak <gavinmak@google.com>

4 files changed, 442 insertions, 6 deletions

diff --git a/tests/e2e/README.md b/tests/e2e/README.md
index 201a05a3b..0f53d2c2c 100644
--- a/tests/e2e/README.md
+++ b/tests/e2e/README.md
@@ -28,5 +28,6 @@ superproject support), or when not run from a git checkout.
 
 * `harness.py`: the git server, server-side repos & the repo client.
 * `test_init_sync.py`: core `repo init` & `repo sync` options.
+* `test_sync_modes.py`: `sync -n`/`-l` & the other sync flags.
 * `test_workflows.py`: multi-step workflows.
 * `test_manifest_regressions.py`: manifests that broke users in the past.
diff --git a/tests/e2e/harness.py b/tests/e2e/harness.py
index 29a162a57..07252ad0d 100644
--- a/tests/e2e/harness.py
+++ b/tests/e2e/harness.py
@@ -17,7 +17,8 @@
 The harness has three parts:
 
 * `GitHttpServer`: a local smart HTTP git server built on `git http-backend`.
-  It also serves static `clone.bundle` files like Gerrit/GoB do.
+  It also serves static `clone.bundle` files like Gerrit/GoB do, and can
+  simulate outages.
 * `ServerRepo`/`GitHost`: bare repositories hosted by the server, with helpers
   to create commits (including gitlinks for superprojects), branches, tags &
   bundles without needing a worktree.
@@ -299,6 +300,8 @@ class GitHttpServer:
         self.root = root
         self.requests: List[Request] = []
         self._lock = threading.Lock()
+        # Path prefixes for which every request fails; see offline().
+        self._offline: Set[str] = set()
         self._httpd: Optional[_ThreadingHTTPServer] = None
         self._thread: Optional[threading.Thread] = None
         self._env = dict(
@@ -344,10 +347,43 @@ class GitHttpServer:
         with self._lock:
             self.requests.append(Request(method, path, status))
 
-    def requests_for(self, prefix: str) -> List[Request]:
-        """Return the requests whose path starts with `prefix`."""
+    def request_count(self) -> int:
+        """Return the number of requests received so far."""
         with self._lock:
-            return [r for r in self.requests if r.path.startswith(prefix)]
+            return len(self.requests)
+
+    def requests_for(self, prefix: str, start: int = 0) -> List[Request]:
+        """Return the requests whose path starts with `prefix`.
+
+        Args:
+            prefix: The request path prefix to match.
+            start: Skip the first `start` requests (see `request_count`).
+        """
+        with self._lock:
+            return [
+                r for r in self.requests[start:] if r.path.startswith(prefix)
+            ]
+
+    @contextlib.contextmanager
+    def offline(self, prefix: str) -> Iterator[None]:
+        """Fail all requests under the path `prefix` (like an outage).
+
+        Requests are still recorded (with a 503 status) so tests can tell
+        whether a command needed the network.
+        """
+        with self._lock:
+            assert prefix not in self._offline, f"{prefix} is already offline"
+            self._offline.add(prefix)
+        try:
+            yield
+        finally:
+            with self._lock:
+                self._offline.discard(prefix)
+
+    def is_offline(self, path: str) -> bool:
+        """Whether requests for `path` should fail; see offline()."""
+        with self._lock:
+            return any(path.startswith(x) for x in self._offline)
 
     def run_backend(
         self,
@@ -453,6 +489,11 @@ class _GitHttpHandler(http.server.BaseHTTPRequestHandler):
     def _handle(self) -> None:
         path = self._request_path
         query = self.path.partition("?")[2]
+        if self.git_server.is_offline(path):
+            # Drain any request body so the client sees the response.
+            self._read_body()
+            self._send(503, {"Content-Type": "text/plain"}, b"offline\n")
+            return
         if path.endswith("/clone.bundle"):
             self._serve_bundle(path)
             return
@@ -740,6 +781,32 @@ class GitHost:
         """All requests received for this namespace."""
         return self.server.requests_for(f"/{self.prefix}/")
 
+    @contextlib.contextmanager
+    def watch_requests(self) -> Iterator[List[Request]]:
+        """Collect the requests this namespace receives inside the block.
+
+        The yielded list is filled in when the block exits, e.g.:
+
+            with host.watch_requests() as requests:
+                client.sync("-l")
+            assert requests == []
+        """
+        start = self.server.request_count()
+        requests: List[Request] = []
+        try:
+            yield requests
+        finally:
+            requests.extend(self.server.requests_for(f"/{self.prefix}/", start))
+
+    @contextlib.contextmanager
+    def offline(self) -> Iterator[None]:
+        """Fail all requests for this namespace during the context.
+
+        This emulates the server (or network) being unavailable.
+        """
+        with self.server.offline(f"/{self.prefix}/"):
+            yield
+
 
 def manifest_xml(*elements: str, default: Optional[str] = None) -> str:
     """Build a manifest with an `origin` remote & a default element.
@@ -923,9 +990,9 @@ class RepoClient:
             *args,
         )
 
-    def sync(self, *args: str) -> RepoResult:
+    def sync(self, *args: str, check: bool = True) -> RepoResult:
         """Run `repo sync`."""
-        return self.run("sync", *args)
+        return self.run("sync", *args, check=check)
 
     def git(self, path: str, *args: str) -> str:
         """Run git in a checkout dir (relative to the client top)."""
@@ -935,6 +1002,10 @@ class RepoClient:
         """Return the commit checked out in `path`."""
         return self.git(path, "rev-parse", "HEAD")
 
+    def is_detached(self, path: str) -> bool:
+        """Whether HEAD in `path` is detached (not on a local branch)."""
+        return self.git(path, "rev-parse", "--abbrev-ref", "HEAD") == "HEAD"
+
     def remote_branches(self, path: str) -> Set[str]:
         """Return the names of the `origin` remote-tracking branches."""
         out = self.git(
@@ -945,6 +1016,10 @@ class RepoClient:
         )
         return set(out.split())
 
+    def tags(self, path: str) -> Set[str]:
+        """Return the names of the tags in `path`."""
+        return set(self.git(path, "tag", "--list").split())
+
     def checkouts(self) -> Set[str]:
         """Return the names of the top-level dirs, except `.repo`."""
         return {
diff --git a/tests/e2e/test_harness.py b/tests/e2e/test_harness.py
index 689ab4f73..b25dc6763 100644
--- a/tests/e2e/test_harness.py
+++ b/tests/e2e/test_harness.py
@@ -114,3 +114,24 @@ def test_http_post_body(
         assert f"{commit} refs/heads/main".encode() in resp.read()
     finally:
         conn.close()
+
+
+def test_offline(git_server: harness.GitHttpServer) -> None:
+    """Requests fail while a namespace is offline, and work again after."""
+    host = harness.GitHost(git_server, "offline")
+    repo = host.create_repo("platform/repo", {"f": "x"})
+    other = harness.GitHost(git_server, "online")
+    other_repo = other.create_repo("repo", {"f": "x"})
+
+    with host.offline():
+        with pytest.raises(AssertionError, match="503"):
+            harness.run_git("ls-remote", repo.url)
+        # Other namespaces are unaffected.
+        assert "refs/heads/main" in harness.run_git("ls-remote", other_repo.url)
+    assert {r.status for r in host.requests()} == {503}
+
+    # The outage ends even if the context exits with an exception.
+    with pytest.raises(RuntimeError):
+        with host.offline():
+            raise RuntimeError("boom")
+    assert "refs/heads/main" in harness.run_git("ls-remote", repo.url)
diff --git a/tests/e2e/test_sync_modes.py b/tests/e2e/test_sync_modes.py
new file mode 100644
index 000000000..531db257e
--- /dev/null
+++ b/tests/e2e/test_sync_modes.py
@@ -0,0 +1,339 @@
+# Copyright (C) 2026 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""E2E tests for `repo sync` modes (`-n`, `-l`) & sync flags."""
+
+from typing import List
+
+from harness import GIT_DEFAULTS_PARAMS
+from harness import GitHost
+from harness import Gitlink
+from harness import manifest_xml
+from harness import RepoClient
+import pytest
+
+
+# Interleaved (the default) & phased syncs implement `-n` & `-l` separately.
+SYNC_MODES = [[], ["--no-interleaved"]]
+
+
+@pytest.mark.parametrize("mode_args", SYNC_MODES, ids=["interleaved", "phased"])
+def test_network_only_then_local_only(
+    host: GitHost, client: RepoClient, mode_args: List[str]
+) -> None:
+    """`sync -n` on an existing checkout updates objects & remote refs only.
+
+    The worktree, HEAD & local branches don't change until `sync -l`, which
+    checks out what `-n` fetched without touching the network.
+    """
+    foo = host.create_repo("platform/foo", {"f": "1"})
+    bar = host.create_repo("platform/bar", {"f": "1"})
+    host.create_manifest(
+        manifest_xml(
+            '<project name="platform/foo" path="foo" />',
+            '<project name="platform/bar" path="bar" />',
+        )
+    )
+    client.init(host.manifest_url)
+    client.sync(*mode_args)
+    old_foo = foo.rev_parse("main")
+    # Local work on a topic branch in bar.
+    client.run("start", "topic", "bar")
+    (client.top / "bar/local").write_text("local")
+    client.git("bar", "add", "local")
+    client.git("bar", "commit", "-q", "-m", "local change")
+    local_commit = client.head("bar")
+    fetched = {"foo": foo.commit({"f": "2"}), "bar": bar.commit({"f": "2"})}
+
+    assert client.sync("-n", *mode_args).stderr == ""
+
+    assert client.head("foo") == old_foo
+    assert (client.top / "foo/f").read_text() == "1"
+    assert client.head("bar") == local_commit
+    assert client.git("bar", "symbolic-ref", "--short", "HEAD") == "topic"
+    for path, commit in fetched.items():
+        assert client.has_object(path, commit)
+        assert client.git(path, "rev-parse", "refs/remotes/origin/main") == (
+            commit
+        )
+        assert client.git(path, "status", "--porcelain") == ""
+
+    # The server moves on, but `-l` must only use what `-n` fetched.
+    foo.commit({"f": "3"})
+    with host.watch_requests() as requests, host.offline():
+        client.sync("-l", *mode_args)
+
+    assert requests == []
+    assert client.head("foo") == fetched["foo"]
+    assert (client.top / "foo/f").read_text() == "2"
+    # The local commit on `bar` was rebased onto what `-n` fetched.
+    assert client.git("bar", "symbolic-ref", "--short", "HEAD") == "topic"
+    assert client.git("bar", "rev-parse", "HEAD~1") == fetched["bar"]
+    assert (client.top / "bar/local").read_text() == "local"
+
+
+def test_local_only_unfetched_project(
+    host: GitHost, client: RepoClient
+) -> None:
+    """`sync -l` fails clearly for a project that was never fetched.
+
+    The other projects are still checked out, no network requests are made,
+    and the error says how to fix it.
+    """
+    foo = host.create_repo("platform/foo", {"f": "1"})
+    host.create_repo("platform/bar", {"f": "bar"})
+    host.create_manifest(
+        manifest_xml('<project name="platform/foo" path="foo" />')
+    )
+    client.init(host.manifest_url)
+    client.sync()
+    v2 = foo.commit({"f": "2"})
+    host.update_manifest(
+        manifest_xml(
+            '<project name="platform/foo" path="foo" />',
+            '<project name="platform/bar" path="bar" />',
+        )
+    )
+    # Update the manifest & fetch foo, but not the new project.
+    client.sync("-n", "platform/foo")
+    assert not (client.repodir / "projects/bar.git").exists()
+
+    with host.watch_requests() as requests, host.offline():
+        result = client.sync("-l", check=False)
+
+    assert requests == []
+    assert result.returncode != 0
+    assert (
+        "Cannot checkout platform/bar due to missing network sync; Run "
+        "`repo sync -n platform/bar` first." in result.stderr
+    )
+    assert not (client.top / "bar").exists()
+    # The already-fetched project still got checked out.
+    assert client.head("foo") == v2
+    assert (client.top / "foo/f").read_text() == "2"
+
+    # Fetching the missing project fixes it.
+    client.sync("-n", "platform/bar")
+    with host.watch_requests() as requests, host.offline():
+        client.sync("-l")
+    assert requests == []
+    assert (client.top / "bar/f").read_text() == "bar"
+    assert client.list_projects() == {
+        "bar": "platform/bar",
+        "foo": "platform/foo",
+    }
+
+
+@pytest.mark.parametrize("git_defaults", GIT_DEFAULTS_PARAMS)
+def test_two_phase_sync_superproject(host: GitHost, client: RepoClient) -> None:
+    """`sync -n` pins projects via the superproject; `sync -l` reuses the pins.
+
+    The local phase must not hit the network, even to re-read the
+    superproject after the server's superproject moved on.
+    """
+    foo = host.create_repo("platform/foo", {"f": "v1"})
+    pinned = foo.rev_parse("main")
+    superproject = host.create_repo("superproject", {"foo": Gitlink(pinned)})
+    foo.commit({"f": "v2"})
+    host.create_manifest(
+        manifest_xml(
+            '<superproject name="superproject" />',
+            '<project name="platform/foo" path="foo" />',
+        )
+    )
+    client.init(host.manifest_url, "--use-superproject")
+
+    assert client.sync("-n").stderr == ""
+    assert not (client.top / "foo").exists()
+    assert (
+        client.repodir / "exp-superproject/superproject_override.xml"
+    ).exists()
+
+    # Advance the superproject on the server before running `sync -l`.
+    new_pin = foo.commit({"f": "v3"})
+    superproject.commit({"foo": Gitlink(new_pin)})
+
+    with host.watch_requests() as requests, host.offline():
+        client.sync("-l")
+
+    assert requests == []
+    assert client.head("foo") == pinned
+    assert (client.top / "foo/f").read_text() == "v1"
+
+    # The next two-phase sync picks up the new superproject pin.
+    client.sync("-n")
+    assert client.head("foo") == pinned
+    with host.watch_requests() as requests, host.offline():
+        client.sync("-l")
+    assert requests == []
+    assert client.head("foo") == new_pin
+    assert (client.top / "foo/f").read_text() == "v3"
+
+
+@pytest.mark.parametrize(
+    "sync_args,project_attrs,expect_tags",
+    [
+        # Despite `repo sync --help` calling `--no-tags` the default.
+        ([], "", True),
+        # `-c` only limits branches: tags on other branches are still fetched
+        # unless `--no-tags` is passed.
+        (["-c"], "", True),
+        (["--tags"], "", True),
+        (["-c", "--no-tags"], "", False),
+        (["-c"], 'sync-tags="false"', False),
+        (["-c", "--tags"], 'sync-tags="false"', True),
+    ],
+)
+def test_tags(
+    host: GitHost,
+    client: RepoClient,
+    sync_args: List[str],
+    project_attrs: str,
+    expect_tags: bool,
+) -> None:
+    """Tags are fetched unless `--no-tags` or the manifest says `sync-tags`."""
+    foo = host.create_repo("platform/foo", {"f": "1"})
+    foo.tag("v1", "main")
+    # A tag that isn't on the synced branch, like release tags usually are.
+    foo.commit({"f": "release"}, branch="release")
+    foo.tag("v2", "release")
+    host.create_manifest(
+        manifest_xml(f'<project name="platform/foo" {project_attrs} />')
+    )
+
+    client.init(host.manifest_url)
+    client.sync(*sync_args)
+
+    assert client.tags("platform/foo") == (
+        {"v1", "v2"} if expect_tags else set()
+    )
+    expected_branches = {"main"} if "-c" in sync_args else {"main", "release"}
+    assert client.remote_branches("platform/foo") == expected_branches
+
+
+def test_prune(host: GitHost, client: RepoClient) -> None:
+    """Remote-tracking branches deleted on the server are pruned by default.
+
+    `--no-prune` keeps them.
+    """
+    foo = host.create_repo("platform/foo", {"f": "1"})
+    foo.commit({"f": "stale"}, branch="stale")
+    host.create_manifest(manifest_xml('<project name="platform/foo" />'))
+    client.init(host.manifest_url)
+    client.sync()
+    path = "platform/foo"
+    assert client.remote_branches(path) == {"main", "stale"}
+
+    foo.git("update-ref", "-d", "refs/heads/stale")
+    client.sync("--no-prune")
+    assert client.remote_branches(path) == {"main", "stale"}
+
+    client.sync()
+    assert client.remote_branches(path) == {"main"}
+
+
+def test_force_sync(host: GitHost, client: RepoClient) -> None:
+    """`--force-sync` re-creates a path whose project changed in the manifest.
+
+    The old gitdir points at another project's object dir, which sync refuses
+    to overwrite unless forced.
+    """
+    host.create_repo("platform/foo", {"f": "foo"})
+    foo_v2 = host.create_repo("platform/foo-v2", {"f": "foo-v2"})
+    host.create_manifest(
+        manifest_xml('<project name="platform/foo" path="foo" />')
+    )
+    client.init(host.manifest_url)
+    client.sync()
+    host.update_manifest(
+        manifest_xml('<project name="platform/foo-v2" path="foo" />')
+    )
+
+    result = client.sync(check=False)
+
+    assert result.returncode != 0
+    assert "--force-sync not enabled" in result.stderr
+    assert "`repo sync --force-sync foo`" in result.stderr
+    assert (client.top / "foo/f").read_text() == "foo"
+
+    client.sync("--force-sync")
+
+    assert client.head("foo") == foo_v2.rev_parse("main")
+    assert (client.top / "foo/f").read_text() == "foo-v2"
+    assert client.list_projects() == {"foo": "platform/foo-v2"}
+    assert client.git("foo", "status", "--porcelain") == ""
+
+
+def test_force_remove_dirty(host: GitHost, client: RepoClient) -> None:
+    """Removed projects with uncommitted changes need `--force-remove-dirty`."""
+    host.create_repo("platform/foo", {"f": "foo"})
+    host.create_repo("platform/bar", {"f": "bar"})
+    host.create_manifest(
+        manifest_xml(
+            '<project name="platform/foo" path="foo" />',
+            '<project name="platform/bar" path="bar" />',
+        )
+    )
+    client.init(host.manifest_url)
+    client.sync()
+    (client.top / "bar/f").write_text("dirty")
+    host.update_manifest(
+        manifest_xml('<project name="platform/foo" path="foo" />')
+    )
+
+    # Repeat to check that the project stays tracked in project.list (rather
+    # than forgotten & left behind) after the first failure.
+    for _ in range(2):
+        result = client.sync(check=False)
+        assert result.returncode != 0
+        assert (
+            "bar: Cannot remove project: uncommitted changes are present"
+            in result.stderr
+        )
+        assert (client.top / "bar/f").read_text() == "dirty"
+
+    result = client.sync("--force-remove-dirty")
+    assert "bar: Removing dirty project" in result.stderr
+    assert not (client.top / "bar").exists()
+    assert client.list_projects() == {"foo": "platform/foo"}
+
+
+def test_detach(host: GitHost, client: RepoClient) -> None:
+    """`sync -d` detaches projects on a topic branch at the manifest revision.
+
+    The topic branch & its local commit are left alone.
+    """
+    foo = host.create_repo("platform/foo", {"f": "1"})
+    host.create_manifest(
+        manifest_xml('<project name="platform/foo" path="foo" />')
+    )
+    client.init(host.manifest_url)
+    client.sync()
+    client.run("start", "topic", "--all")
+    (client.top / "foo/local").write_text("local")
+    client.git("foo", "add", "local")
+    client.git("foo", "commit", "-q", "-m", "local change")
+    local = client.head("foo")
+    latest = foo.commit({"f": "2"})
+
+    client.sync("-d")
+
+    assert client.is_detached("foo")
+    assert client.head("foo") == latest
+    assert (client.top / "foo/f").read_text() == "2"
+    assert not (client.top / "foo/local").exists()
+    assert client.git("foo", "rev-parse", "topic") == local
+    # A regular sync afterwards stays detached.
+    client.sync()
+    assert client.is_detached("foo")