sync: Return SyncResult from update_repo(), fix other bugs (#514)

update_repo() across Git, Hg, and SVN sync classes now returns
a SyncResult instead of None. Callers can distinguish successful
syncs from failures and inspect structured error details, instead
of errors being silently swallowed or raising uncaught exceptions.

New dataclasses in sync/base.py:
- SyncResult: tracks ok status and a list of SyncError entries
- SyncError: records step name, message, and original exception

GitSync.update_repo() changes:
- All 13 except-CommandError-return paths now record errors in
  SyncResult with labeled steps (obtain, set-remotes, fetch,
  rebase, checkout, stash-save, stash-pop, status, etc.)
- Original early-return vs continue-on-error control flow is
  preserved per step
- Best-effort cleanup uses contextlib.suppress(CommandError)
  for rebase abort, stash pop, and reset operations

HgSync and SvnSync updated for API consistency, wrapping
obtain and pull/update failures in SyncResult.

Additional fixes:
- cmd/git: Fix rev_list() _all parameter shadowed by builtin
- sync/git: Disambiguate rev-list with refs/heads/ for local
  branch names that collide with filesystem paths
- sync/git: Return early on invalid-upstream rebase instead of
  falling through to stash-pop
- sync/git: Add __str__() to GitRemoteRefNotFound to avoid
  AttributeError from parent CommandError.__str__()
- sync/git: Add explicit _message type annotation on
  GitRemoteRefNotFound
- libvcs/__init__: Export SyncResult and SyncError from
  top-level package
- tests/sync: Fix hg test isolation by using factory fixture
  instead of deleting session-scoped remote
- ruff: Move A002 suppression to per-file-ignores in
  pyproject.toml

Test coverage:
- All 13 GitSync.update_repo() error steps now have dedicated
  tests covering obtain, set-remotes, symbolic-ref, rev-list,
  remote-name, remote-ref-not-found, fetch, status, stash-save,
  checkout, rebase (invalid upstream + conflict), stash-pop,
  and submodule-update
- SyncResult multi-error accumulation test
- Hg and SVN obtain/pull/update failure tests
- Git rev_list _all parameter test

See also: vcs-python/vcspull#512

Author: tony

CHANGES

@@ -20,6 +20,43 @@ $ uv add libvcs --prerelease allow
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### New features
+
+#### sync: Return {class}`~libvcs.sync.base.SyncResult` from `update_repo()` (#514)
+
+`update_repo()` across {class}`~libvcs.sync.git.GitSync`,
+{class}`~libvcs.sync.hg.HgSync`, and {class}`~libvcs.sync.svn.SvnSync`
+now returns a {class}`~libvcs.sync.base.SyncResult` instead of `None`.
+Callers can inspect `result.ok` and `result.errors` to distinguish
+successful syncs from failures.
+
+- New dataclasses: {class}`~libvcs.sync.base.SyncResult` and
+  {class}`~libvcs.sync.base.SyncError`
+- Git: 10+ silent `except CommandError: return` paths now record
+  structured errors with labeled steps (`fetch`, `rebase`, `checkout`,
+  `stash-save`, etc.)
+- Hg and SVN: Wrap `obtain` and `pull`/`update` failures for API
+  consistency
+
+Companion change: [vcspull#512](https://github.com/vcs-python/vcspull/pull/512)
+
+### Bug Fixes
+
+- cmd: Fix `Git.rev_list()` referencing builtin `all` instead of `_all`
+  parameter (#514)
+
+- sync: Disambiguate `rev-list` when a local branch name collides with a
+  filesystem path by using fully-qualified `refs/heads/` refs (#514)
+
+- sync: Return early with error on invalid-upstream rebase instead of
+  falling through to stash-pop (#514)
+
+### Tests
+
+- sync: Fix `test_update_repo_pull_failure_returns_sync_result` (hg)
+  destroying the session-scoped `hg_remote_repo` fixture, which broke
+  downstream tests like `test_hg_url` (#514)
+
 ## libvcs 0.38.6 (2026-01-27)
 
 ### Bug Fixes

README.md

@@ -70,9 +70,13 @@ repo = GitSync(
 )
 
 # Clone (if not exists) or fetch & update (if exists)
-repo.update_repo()
+result = repo.update_repo()
 
-print(f"Current revision: {repo.get_revision()}")
+if result.ok:
+    print(f"Current revision: {repo.get_revision()}")
+else:
+    for error in result.errors:
+        print(f"Sync failed at {error.step}: {error.message}")
 ```
 
 ### 2. Command Abstraction

pyproject.toml

@@ -211,6 +211,7 @@ convention = "numpy"
 
 [tool.ruff.lint.per-file-ignores]
 "*/__init__.py" = ["F401"]
+"src/libvcs/_internal/subprocess.py" = ["A002"]
 
 [tool.pytest.ini_options]
 addopts = [

src/libvcs/__init__.py

@@ -5,7 +5,7 @@
 import logging
 
 from ._internal.run import CmdLoggingAdapter
-from .sync.base import BaseSync
+from .sync.base import BaseSync, SyncError, SyncResult
 from .sync.git import GitSync
 from .sync.hg import HgSync
 from .sync.svn import SvnSync
@@ -16,6 +16,8 @@
     "GitSync",
     "HgSync",
     "SvnSync",
+    "SyncError",
+    "SyncResult",
 ]
 
 logger = logging.getLogger(__name__)

src/libvcs/_internal/subprocess.py

@@ -1,4 +1,3 @@
-# ruff: NOQA: A002
 r"""Invocable :mod:`subprocess` wrapper.
 
 Defer running a subprocess, such as by handing to an executor.

src/libvcs/cmd/git.py

@@ -2193,7 +2193,7 @@ def rev_list(
 
         for flag, shell_flag in [
             # Limiting output
-            (all, "--all"),
+            (_all, "--all"),
             (author, "--author"),
             (committer, "--committer"),
             (grep, "--grep"),
@@ -2212,7 +2212,7 @@ def rev_list(
             (first_parent, "--first-parent"),
             (exclude_first_parent_only, "--exclude-first-parent-only"),
             (_not, "--not"),
-            (all, "--all"),
+            (_all, "--all"),
             (exclude, "--exclude"),
             (reflog, "--reflog"),
             (alternative_refs, "--alternative-refs"),

src/libvcs/sync/base.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import dataclasses
 import logging
 import pathlib
 import typing as t
@@ -14,6 +15,82 @@
 logger = logging.getLogger(__name__)
 
 
+@dataclasses.dataclass
+class SyncError:
+    """An error encountered during a sync step.
+
+    Examples
+    --------
+    >>> error = SyncError(step="fetch", message="remote not found")
+    >>> error.step
+    'fetch'
+    >>> error.message
+    'remote not found'
+    >>> error.exception is None
+    True
+    """
+
+    step: str
+    message: str
+    exception: Exception | None = None
+
+
+@dataclasses.dataclass
+class SyncResult:
+    """Result of a repository synchronization.
+
+    Examples
+    --------
+    >>> result = SyncResult()
+    >>> result.ok
+    True
+    >>> bool(result)
+    True
+
+    >>> result = SyncResult()
+    >>> result.add_error(step="fetch", message="remote not found")
+    >>> result.ok
+    False
+    >>> bool(result)
+    False
+    >>> result.errors[0].step
+    'fetch'
+    """
+
+    ok: bool = True
+    errors: list[SyncError] = dataclasses.field(default_factory=list)
+
+    def __bool__(self) -> bool:
+        """Return True if the sync succeeded without errors.
+
+        Returns
+        -------
+        bool
+            True if no errors were recorded, False otherwise.
+        """
+        return self.ok
+
+    def add_error(
+        self,
+        step: str,
+        message: str,
+        exception: Exception | None = None,
+    ) -> None:
+        """Record an error and mark the result as failed.
+
+        Parameters
+        ----------
+        step : str
+            Name of the sync step that failed (e.g. ``"fetch"``, ``"checkout"``).
+        message : str
+            Human-readable description of the error.
+        exception : Exception or None, optional
+            The underlying exception, if available.
+        """
+        self.ok = False
+        self.errors.append(SyncError(step=step, message=message, exception=exception))
+
+
 class VCSLocation(t.NamedTuple):
     """Generic VCS Location (URL and optional revision)."""
 
@@ -200,8 +277,14 @@ def ensure_dir(self, *args: t.Any, **kwargs: t.Any) -> bool:
 
         return True
 
-    def update_repo(self, *args: t.Any, **kwargs: t.Any) -> None:
-        """Pull latest changes to here from remote repository."""
+    def update_repo(self, *args: t.Any, **kwargs: t.Any) -> SyncResult:
+        """Pull latest changes to here from remote repository.
+
+        Returns
+        -------
+        SyncResult
+            Result of the sync operation, with any errors recorded.
+        """
         raise NotImplementedError
 
     def obtain(self, *args: t.Any, **kwargs: t.Any) -> None: