config(feat): Write canonical repository entries

why: Newly written entries must use the same layout as the loader.

what: Write checkout targets and Git settings in their named blocks.
Migrate entries touched by import and fmt while honoring command pins.
Reject invalid writer settings and report migration errors before writes.
Make local Git discovery explicit and isolate the home-config doctest.

Author: tony

CHANGES

@@ -64,6 +64,8 @@ at the repository entry level.
 {ref}`cli-migrate` separates legacy settings into `working_copy`, the
 matching backend block, and entry-level pin policy in one pass. Unknown
 legacy options stop migration before it writes the configuration file.
+`add` and `discover` write the same layout. `import` and `fmt` migrate entries
+they rewrite and preserve entries pinned for that command.
 See {ref}`migration` for an upgrade example.
 
 #### Validate shared checkout targets

MIGRATION

@@ -65,6 +65,10 @@ After:
 Existing canonical values take precedence. Unknown legacy `options` keys
 produce an error before the file is written.
 
+`add` and `discover` write the canonical layout. `import` and `fmt` migrate
+entries they rewrite; entries pinned for that command stay unchanged. Use
+`migrate --write` to upgrade every entry, including pinned entries.
+
 Loading normalizes the same legacy locations in memory and warns once per
 file. Unknown entry or backend fields now fail during loading; metadata
 belongs in `metadata`, not in a libvcs constructor argument. Sync constructs

src/vcspull/cli/add.py

@@ -34,6 +34,7 @@
     save_config_yaml_with_items,
     workspace_root_label,
 )
+from vcspull.exc import VCSPullException
 
 log = logging.getLogger(__name__)
 
@@ -133,7 +134,7 @@ def create_add_subparser(parser: argparse.ArgumentParser) -> None:
         dest="shallow",
         action="store_true",
         help=(
-            "Record 'options.shallow: true' (clone --depth 1 on sync). A "
+            "Record 'git.depth: 1' (clone --depth 1 on sync). A "
             "shallow checkout is detected automatically; this forces it on."
         ),
     )
@@ -143,7 +144,7 @@ def create_add_subparser(parser: argparse.ArgumentParser) -> None:
         type=int,
         metavar="N",
         help=(
-            "Record 'options.depth: N' (clone --depth N on sync). Overrides "
+            "Record 'git.depth: N' (clone --depth N on sync). Overrides "
             "--shallow. An existing shallow checkout's depth is detected "
             "automatically."
         ),
@@ -270,7 +271,7 @@ class ParsedRepoUrl(t.NamedTuple):
     url : str
         The URL without any pip-style ``@rev``, suitable to record as ``repo``.
     rev : str | None
-        Revision from a pip-style ``@rev``, to record as ``options.rev``.
+        Revision from a pip-style ``@rev``, to record as ``working_copy.rev``.
     unparsed_rev : str | None
         Revision trailing a URL libvcs does not parse revisions for, which
         would otherwise stay in the recorded URL and fail to clone.
@@ -1049,11 +1050,11 @@ def add_repo(
     dry_run : bool
         If True, preview changes without writing
     rev : str | None
-        Commit, tag, or branch to record as ``options.rev``.
+        Commit, tag, or branch to record as ``working_copy.rev``.
     shallow : bool
-        If ``True``, record ``options.shallow: true`` for the repository.
+        If ``True``, record ``git.depth: 1`` for the repository.
     depth : int | None
-        If set, record ``options.depth: N`` for the repository.
+        If set, record ``git.depth: N`` for the repository.
     """
     # Determine config file
     resolution = _resolve_config_file(config_file_path_str)
@@ -1123,7 +1124,11 @@ def add_repo(
         preserve_cwd_label=explicit_dot,
     )
 
-    new_repo_entry = build_repo_entry(url, rev=rev, shallow=shallow, depth=depth)
+    try:
+        new_repo_entry = build_repo_entry(url, rev=rev, shallow=shallow, depth=depth)
+    except VCSPullException as error:
+        log.error("%s: %s", name, error)  # noqa: TRY400
+        return
 
     def _ensure_workspace_label_for_merge(
         config_data: dict[str, t.Any],

src/vcspull/cli/discover.py

@@ -29,6 +29,7 @@
     save_config,
     workspace_root_label,
 )
+from vcspull.exc import VCSPullException
 
 log = logging.getLogger(__name__)
 
@@ -53,9 +54,9 @@ class _FoundRepo(t.NamedTuple):
     workspace_path : pathlib.Path
         Workspace root the entry is recorded under.
     shallow : bool
-        Whether to record ``options.shallow: true``.
+        Whether to record ``git.depth: 1``.
     depth : int | None
-        Clone depth to record as ``options.depth``, or ``None`` for none.
+        Clone depth to record as ``git.depth``, or ``None`` for none.
     """
 
     name: str
@@ -220,10 +221,12 @@ def get_git_origin_url(repo_path: pathlib.Path) -> str | None:
             text=True,
             check=True,
         )
-        return result.stdout.strip()
     except (subprocess.CalledProcessError, FileNotFoundError) as e:
         log.debug("Could not get origin URL for %s: %s", repo_path, e)
         return None
+    else:
+        url = result.stdout.strip()
+        return f"git+{url}" if url.startswith("file://") else url
 
 
 def create_discover_subparser(parser: argparse.ArgumentParser) -> None:
@@ -274,7 +277,7 @@ def create_discover_subparser(parser: argparse.ArgumentParser) -> None:
         dest="shallow",
         action="store_true",
         help=(
-            "Record 'options.shallow: true' for discovered repositories. "
+            "Record 'git.depth: 1' for discovered repositories. "
             "Shallow checkouts are detected automatically; this forces it on "
             "for all."
         ),
@@ -285,7 +288,7 @@ def create_discover_subparser(parser: argparse.ArgumentParser) -> None:
         type=int,
         metavar="N",
         help=(
-            "Record 'options.depth: N' for every discovered repository "
+            "Record 'git.depth: N' for every discovered repository "
             "(clone --depth N on sync). Overrides --shallow."
         ),
     )
@@ -382,13 +385,13 @@ def discover_repos(
     dry_run : bool
         If True, preview changes without writing
     rev : str | None
-        Commit, tag, or branch to record as ``options.rev`` for every
+        Commit, tag, or branch to record as ``working_copy.rev`` for every
         discovered repository.
     shallow : bool
-        If ``True``, force ``options.shallow: true`` for every discovered
+        If ``True``, force ``git.depth: 1`` for every discovered
         repository; otherwise clone depth is auto-detected per repository.
     depth : int | None
-        If set, record ``options.depth: N`` for every discovered repository;
+        If set, record ``git.depth: N`` for every discovered repository;
         overrides ``shallow``.
     """
     if depth is not None and depth < 1:
@@ -869,12 +872,16 @@ def discover_repos(
             continue
 
         if repo_name not in raw_config[workspace_label]:
-            raw_config[workspace_label][repo_name] = build_repo_entry(
-                repo_url,
-                rev=rev,
-                shallow=repo_shallow,
-                depth=repo_depth,
-            )
+            try:
+                raw_config[workspace_label][repo_name] = build_repo_entry(
+                    repo_url,
+                    rev=rev,
+                    shallow=repo_shallow,
+                    depth=repo_depth,
+                )
+            except VCSPullException as error:
+                log.error("%s: %s", repo_name, error)  # noqa: TRY400
+                return
             log.info(
                 "%s+%s Importing %s'%s'%s (%s%s%s) under '%s%s%s'.",
                 Fore.GREEN,

src/vcspull/cli/fmt.py

@@ -19,6 +19,7 @@
     find_home_config_files,
     is_pinned_for_op,
     merge_duplicate_workspace_roots,
+    migrate_repo_entry,
     normalize_config_file_path,
     normalize_workspace_roots,
     save_config,
@@ -105,13 +106,11 @@ def normalize_repo_config(repo_data: t.Any) -> dict[str, t.Any]:
         # Convert compact format to verbose format
         return {"repo": repo_data}
     if isinstance(repo_data, dict):
-        # If it has 'url' key but not 'repo', convert to use 'repo'
-        if "url" in repo_data and "repo" not in repo_data:
-            normalized = repo_data.copy()
+        _, normalized = migrate_repo_entry(repo_data)
+        if "url" in normalized and "repo" not in normalized:
+            normalized = normalized.copy()
             normalized["repo"] = normalized.pop("url")
-            return normalized
-        # Already in correct format or has other fields
-        return repo_data
+        return t.cast("dict[str, t.Any]", normalized)
     # Return as-is for other types
     return t.cast("dict[str, t.Any]", repo_data)
 
@@ -208,7 +207,11 @@ def format_config(config_data: dict[str, t.Any]) -> tuple[dict[str, t.Any], int]
 
         for repo_name in sorted(repos.keys()):
             repo_data = repos[repo_name]
-            action, result = _classify_fmt_action(repo_data)
+            try:
+                action, result = _classify_fmt_action(repo_data)
+            except (TypeError, ValueError) as error:
+                msg = f"{directory!r} -> {repo_name!r} -> {error}"
+                raise ValueError(msg) from error
             if action == FmtAction.SKIP_PINNED:
                 formatted_dir[repo_name] = copy.deepcopy(result)
             else:
@@ -342,7 +345,11 @@ def format_single_config(
     for message in duplicate_merge_conflicts:
         log.warning(message)
 
-    formatted_config, change_count = format_config(normalized_config)
+    try:
+        formatted_config, change_count = format_config(normalized_config)
+    except ValueError as error:
+        log.error("%s: %s", display_config_path, error)  # noqa: TRY400
+        return False
     change_count += normalization_changes + duplicate_merge_changes
 
     if change_count == 0:

src/vcspull/cli/import_cmd/_common.py

@@ -36,6 +36,7 @@
     get_pin_reason,
     is_pinned_for_op,
     merge_duplicate_workspace_roots,
+    migrate_repo_entry,
     normalize_config_file_path,
     save_config,
     workspace_root_label,
@@ -456,7 +457,7 @@ def _create_shared_parent() -> argparse.ArgumentParser:
             "Sync config with remote: update URLs for existing entries whose "
             "URL has changed, and remove entries no longer on the remote. "
             "Preserves all metadata (options, remotes, shell_command_after). "
-            "Respects pinned entries (options.pin.import)."
+            "Respects pinned entries (pin.import)."
         ),
     )
     output_group.add_argument(
@@ -666,8 +667,8 @@ def _run_import(
         Exclude repos whose owner path contains any of these group name segments
     sync : bool
         Sync existing config entries whose URL has changed
-        (default: False).  Entries with ``options.pin.import`` or
-        ``options.allow_overwrite: false`` are exempt.
+        (default: False).  Entries with ``pin.import`` or
+        ``allow_overwrite: false`` are exempt.
     prune : bool
         Remove config entries tagged by a previous import that are
         no longer on the remote (default: False).  Does not update
@@ -1060,6 +1061,17 @@ def _run_import(
                     if isinstance(existing_raw, dict)
                     else {}
                 )
+                try:
+                    _, updated = migrate_repo_entry(updated)
+                except (TypeError, ValueError) as error:
+                    log.error(  # noqa: TRY400
+                        "%s: %r -> %r -> %s",
+                        display_config_path,
+                        repo_workspace_label,
+                        repo.name,
+                        error,
+                    )
+                    return 1
                 updated["repo"] = incoming_url
                 updated.pop("url", None)
                 if import_source:
@@ -1085,8 +1097,18 @@ def _run_import(
                     )
                     if needs_tag:
                         if not dry_run:
-                            # None is not safe: setdefault returns existing
-                            # None instead of replacing it, causing TypeError.
+                            try:
+                                _, live = migrate_repo_entry(live)
+                            except (TypeError, ValueError) as error:
+                                log.error(  # noqa: TRY400
+                                    "%s: %r -> %r -> %s",
+                                    display_config_path,
+                                    repo_workspace_label,
+                                    repo.name,
+                                    error,
+                                )
+                                return 1
+                            raw_config[repo_workspace_label][repo.name] = live
                             if not isinstance(existing_meta, dict):
                                 live["metadata"] = {}
                             live.setdefault("metadata", {})["imported_from"] = (

src/vcspull/config.py

@@ -366,7 +366,10 @@ def find_home_config_files(
 
     Examples
     --------
-    >>> find_home_config_files()
+    >>> with tempfile.TemporaryDirectory() as home:
+    ...     with getfixture("monkeypatch").context() as patch:
+    ...         patch.setenv("HOME", home)
+    ...         find_home_config_files()
     []
     """
     if filetype is None:
@@ -1021,19 +1024,19 @@ def build_repo_entry(
     """Build a raw per-repository config entry for ``add``/``discover``.
 
     Centralizes the entry shape written by both subcommands so the recorded
-    keys stay consistent. Sync-tuning keys are nested under ``options:``;
+    keys stay consistent. Targets use ``working_copy`` and clone settings use ``git``;
     ``depth`` wins over ``shallow`` when both are supplied.
 
     Parameters
     ----------
     url : str
         VCS URL in vcspull format, e.g. ``git+https://github.com/u/r.git``.
     rev : str | None
-        Commit, tag, or branch to pin via ``options.rev``. Omitted when falsy.
+        Commit, tag, or branch to pin via ``working_copy.rev``. Omitted when falsy.
     shallow : bool
-        If ``True``, record ``options.shallow: true`` (clone ``--depth 1``).
+        If ``True``, record ``git.depth: 1`` (clone ``--depth 1``).
     depth : int | None
-        If set, record ``options.depth: N`` (clone ``--depth N``).
+        If set, record ``git.depth: N`` (clone ``--depth N``).
 
     Returns
     -------
@@ -1046,35 +1049,33 @@ def build_repo_entry(
     {'repo': 'git+https://github.com/u/r.git'}
 
     >>> build_repo_entry("git+https://github.com/u/r.git", rev="v1.0.0")
-    {'repo': 'git+https://github.com/u/r.git', 'options': {'rev': 'v1.0.0'}}
+    {'repo': 'git+https://github.com/u/r.git', 'working_copy': {'rev': 'v1.0.0'}}
 
     >>> build_repo_entry("git+https://github.com/u/r.git", shallow=True)
-    {'repo': 'git+https://github.com/u/r.git', 'options': {'shallow': True}}
+    {'repo': 'git+https://github.com/u/r.git', 'git': {'depth': 1}}
 
     >>> build_repo_entry("git+https://github.com/u/r.git", depth=50)
-    {'repo': 'git+https://github.com/u/r.git', 'options': {'depth': 50}}
+    {'repo': 'git+https://github.com/u/r.git', 'git': {'depth': 50}}
 
     ``depth`` wins over ``shallow``:
 
     >>> build_repo_entry("git+https://github.com/u/r.git", shallow=True, depth=50)
-    {'repo': 'git+https://github.com/u/r.git', 'options': {'depth': 50}}
+    {'repo': 'git+https://github.com/u/r.git', 'git': {'depth': 50}}
     """
     entry: dict[str, t.Any] = {"repo": url}
-    options: dict[str, t.Any] = {}
     if rev:
-        options["rev"] = rev
-    if depth:
-        options["depth"] = depth
+        entry["working_copy"] = {"rev": rev}
+    if depth is not None:
+        entry["git"] = {"depth": depth}
     elif shallow:
-        options["shallow"] = True
-    if options:
-        entry["options"] = options
+        entry["git"] = {"depth": 1}
+    validate_repo_entry(entry, location="repository")
+    if "working_copy" in entry:
+        validate_working_copy(entry["working_copy"])
     return entry
 
 
-#: Per-repository sync-tuning keys whose canonical home is the ``options:``
-#: block. They were accepted at the entry root in v1.61.0; that form is now
-#: deprecated and migrated by :func:`migrate_repo_entry`.
+#: Legacy flat tuning fields migrated into ``working_copy`` or ``git``.
 LEGACY_REPO_OPTION_KEYS = ("rev", "shallow", "depth")