fix(config): preserve symlinks when writing config files (#538)

Config files that are symbolic links (e.g. ~/.vcspull.yaml →
~/dotfiles/vcspull.yaml) were silently replaced by regular files on
every write. os.rename() on a symlink path replaces the symlink entry
itself, so each save destroyed the link and left a bare file behind.

The write path now resolves the symlink before creating the temp file,
so the atomic rename targets the real file and the symlink directory
entry is left intact.

A second related fix stops callers from calling .resolve() when
normalising config paths. Dereferencing the symlink there strips the
logical .yaml/.json suffix used for format detection, causing further
corruption downstream. A new normalize_config_file_path() helper
expands ~ and env vars without following symlinks, and all CLI
commands (add, discover, fmt, import) now use it.

- **_atomic_write()**: create temp file next to the resolved target,
  rename into the resolved path — symlink entry preserved
- **normalize_config_file_path()**: new helper — expands paths without
  .resolve() so the logical config name is retained
- **config_format_from_path()**: new helper — inspects the symlink
  target's extension so a .yaml symlink pointing to a .json file
  serialises correctly as JSON
- **CLI commands**: switch from .expanduser().resolve() to
  normalize_config_file_path() throughout

Fixes #537

Author: tony

CHANGES

@@ -37,6 +37,20 @@ $ uvx --from 'vcspull' --prerelease allow vcspull
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Bug fixes
+
+#### `config`: Preserve symlinks when writing config files (#538)
+
+Config files that are symbolic links (e.g. `~/.vcspull.yaml` pointing to a
+dotfiles directory) were being silently replaced by regular files on every
+write, destroying the symlink. The write now goes through the link — a temp
+file is created next to the real target, renamed into place, and the symlink
+directory entry is preserved.
+
+Format detection now also inspects the symlink target's extension, so a
+`.yaml` symlink pointing to a `.json` file serialises correctly as JSON rather
+than overwriting the target with YAML.
+
 ## vcspull v1.58.0 (2026-03-01)
 
 ### New features

src/vcspull/_internal/config_reader.py

@@ -8,6 +8,56 @@
 import yaml
 
 FormatLiteral = t.Literal["json", "yaml"]
+_SUPPORTED_CONFIG_SUFFIXES: dict[str, FormatLiteral] = {
+    ".json": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+}
+
+
+def config_format_from_path(path: pathlib.Path) -> FormatLiteral | None:
+    """Return config format inferred from a path or symlink target.
+
+    The visible path remains the config identity, but symlinks may point
+    at a differently named target. When the target advertises a supported
+    config suffix, prefer that format; otherwise fall back to the visible
+    path suffix.
+
+    Parameters
+    ----------
+    path : pathlib.Path
+        Path to inspect.
+
+    Returns
+    -------
+    FormatLiteral | None
+        ``"json"`` or ``"yaml"`` when a supported suffix is found,
+        otherwise ``None``.
+
+    Examples
+    --------
+    >>> config_format_from_path(pathlib.Path("config.yaml"))
+    'yaml'
+    >>> import tempfile
+    >>> with tempfile.TemporaryDirectory() as tmp:
+    ...     root = pathlib.Path(tmp)
+    ...     target = root / "config.json"
+    ...     _ = target.write_text("{}", encoding="utf-8")
+    ...     link = root / ".vcspull.yaml"
+    ...     link.symlink_to(target)
+    ...     config_format_from_path(link)
+    'json'
+    """
+    path_format = _SUPPORTED_CONFIG_SUFFIXES.get(path.suffix.lower())
+
+    target_format: FormatLiteral | None = None
+    if path.is_symlink():
+        resolved = path.resolve(strict=False)
+        target_format = _SUPPORTED_CONFIG_SUFFIXES.get(resolved.suffix.lower())
+
+    return target_format or path_format
+
+
 RawConfigData: t.TypeAlias = dict[t.Any, t.Any]
 
 
@@ -114,14 +164,12 @@ def _from_file(cls, path: pathlib.Path) -> dict[str, t.Any]:
         #    the formatter helpers directly;
         # 3) Keep this basic loader but add an opt-in path for duplicate-aware
         #    parsing so commands like ``vcspull add`` can avoid data loss.
-        # Revisit once the new ``vcspull add`` flow lands so both commands share
-        # the same duplication safeguards.
+        # ``vcspull add`` now uses ``DuplicateAwareConfigReader`` for reading
+        # (see ``cli/add.py``). This basic loader remains for simpler read
+        # contexts. Option 1 (shared utility) is the cleanest long-term path.
 
-        if path.suffix in {".yaml", ".yml"}:
-            fmt: FormatLiteral = "yaml"
-        elif path.suffix == ".json":
-            fmt = "json"
-        else:
+        fmt = config_format_from_path(path)
+        if fmt is None:
             msg = f"{path.suffix} not supported in {path}"
             raise NotImplementedError(msg)
 
@@ -335,7 +383,7 @@ def _load_from_path(
         cls,
         path: pathlib.Path,
     ) -> tuple[dict[str, t.Any], dict[str, list[t.Any]], list[tuple[str, t.Any]]]:
-        if path.suffix.lower() in {".yaml", ".yml"}:
+        if config_format_from_path(path) == "yaml":
             content = path.read_text(encoding="utf-8")
             return cls._load_yaml_with_duplicates(content)
 

src/vcspull/cli/add.py

@@ -13,7 +13,10 @@
 
 from colorama import Fore, Style
 
-from vcspull._internal.config_reader import DuplicateAwareConfigReader
+from vcspull._internal.config_reader import (
+    DuplicateAwareConfigReader,
+    config_format_from_path,
+)
 from vcspull._internal.private_path import PrivatePath
 from vcspull.config import (
     canonicalize_workspace_path,
@@ -22,6 +25,7 @@
     get_pin_reason,
     is_pinned_for_op,
     merge_duplicate_workspace_roots,
+    normalize_config_file_path,
     save_config,
     save_config_json,
     save_config_yaml_with_items,
@@ -340,7 +344,7 @@ def _save_ordered_items(
     >>> "~/code/" in data
     True
     """
-    if config_file_path.suffix.lower() == ".json":
+    if config_format_from_path(config_file_path) == "json":
         save_config_json(
             config_file_path,
             _collapse_ordered_items_to_dict(ordered_items),
@@ -508,7 +512,9 @@ def add_repo(
     # Determine config file
     config_file_path: pathlib.Path
     if config_file_path_str:
-        config_file_path = pathlib.Path(config_file_path_str).expanduser().resolve()
+        config_file_path = normalize_config_file_path(
+            pathlib.Path(config_file_path_str)
+        )
     else:
         home_configs = find_home_config_files(filetype=["yaml"])
         if not home_configs:

src/vcspull/cli/discover.py

@@ -22,6 +22,7 @@
     get_pin_reason,
     is_pinned_for_op,
     merge_duplicate_workspace_roots,
+    normalize_config_file_path,
     normalize_workspace_roots,
     save_config,
     workspace_root_label,
@@ -327,7 +328,9 @@ def discover_repos(
 
     config_file_path: pathlib.Path
     if config_file_path_str:
-        config_file_path = pathlib.Path(config_file_path_str).expanduser().resolve()
+        config_file_path = normalize_config_file_path(
+            pathlib.Path(config_file_path_str)
+        )
     else:
         home_configs = find_home_config_files(filetype=["yaml"])
         if not home_configs:

src/vcspull/cli/fmt.py

@@ -19,6 +19,7 @@
     find_home_config_files,
     is_pinned_for_op,
     merge_duplicate_workspace_roots,
+    normalize_config_file_path,
     normalize_workspace_roots,
     save_config,
 )
@@ -570,7 +571,9 @@ def format_config_file(
     else:
         # Format single config file
         if config_file_path_str:
-            config_file_path = pathlib.Path(config_file_path_str).expanduser().resolve()
+            config_file_path = normalize_config_file_path(
+                pathlib.Path(config_file_path_str)
+            )
         else:
             home_configs = find_home_config_files(filetype=["yaml"])
             if not home_configs:

src/vcspull/cli/import_cmd/_common.py

@@ -14,7 +14,10 @@
 import sys
 import typing as t
 
-from vcspull._internal.config_reader import DuplicateAwareConfigReader
+from vcspull._internal.config_reader import (
+    DuplicateAwareConfigReader,
+    config_format_from_path,
+)
 from vcspull._internal.private_path import PrivatePath
 from vcspull._internal.remotes import (
     AuthenticationError,
@@ -33,6 +36,7 @@
     get_pin_reason,
     is_pinned_for_op,
     merge_duplicate_workspace_roots,
+    normalize_config_file_path,
     save_config,
     workspace_root_label,
 )
@@ -560,11 +564,11 @@ def _resolve_config_file(config_path_str: str | None) -> pathlib.Path:
     Returns
     -------
     pathlib.Path
-        Resolved config file path
+        Absolute config file path
     """
     if config_path_str:
-        path = pathlib.Path(config_path_str).expanduser().resolve()
-        if path.suffix.lower() not in {".yaml", ".yml", ".json"}:
+        path = normalize_config_file_path(pathlib.Path(config_path_str))
+        if config_format_from_path(path) is None:
             msg = f"Unsupported config file type: {path.suffix}"
             raise ValueError(msg)
         return path