Support numeric depth: N and move per-repo sync keys under options:

[tony]

Summary

• Add a numeric options.depth: N per-repository key (and --depth N on add/discover) so workspaces can keep a small window of history instead of the all-or-nothing shallow: true. Resolves add/discover: support numeric depth: N (follow-up to #550) #552.
• Add automatic clone-depth detection on import: a depth-1 checkout records options.shallow: true, a deeper window records options.depth: N.
• Relocate the per-repository sync keys rev, shallow, and depth under an options: block (joining the existing pin/pin_reason), so VCS-sync tuning and mutation policy share one namespace.
• Add a vcspull migrate subcommand that rewrites configs from the deprecated top-level form into options:.
• Deprecate the top-level rev:/shallow: keys that shipped in v1.61.0 — they are still read, and vcspull sync warns and points at vcspull migrate.
• Require libvcs>=0.42.0, which honors an arbitrary GitSync(depth=N).

Changes by area

Dependencies

• pyproject.toml / uv.lock: bump the floor to libvcs>=0.42.0,<0.43.0.

Schema & config (src/vcspull/types.py, src/vcspull/config.py)

• RepoOptionsDict: now carries rev/shallow/depth alongside pin/pin_reason; RepoEntryDict marks the top-level rev/shallow as deprecated; ConfigDict gains depth.
• extract_repos: lifts options.{rev,shallow,depth} onto the flat internal config; an options: value wins over a legacy top-level key, so the sync path is unchanged apart from depth.
• detect_git_depth: reports a shallow checkout's commit count.
• resolve_clone_depth: the shared hybrid precedence used by add and discover (explicit --depth → explicit --shallow → auto-detect).
• migrate_repo_entry / detect_legacy_repo_options: relocate top-level keys under options: (depth wins over shallow) and scan a raw config for entries still using the old form.

CLI (add, discover, sync)

• add / discover: add --depth N (validated >= 1); record sync keys under options: via a shared build_repo_entry; log the recorded depth/shallow.
• sync: applies options.depth as GitSync.depth (git-only, depth wins over shallow), and warns when it loads a config still using top-level keys.

Migrate command (src/vcspull/cli/migrate.py)

• vcspull migrate: mirrors fmt (-f/--file, --write, --all). Previews by default, rewrites with --write, and is idempotent.

Docs

• docs/configuration/: an options: "Sync options" section (rev/shallow/depth), a clone-depth section, and a migration note.
• docs/cli/migrate.md (+ index/grid/API page): the new command's reference.

Design decisions

• options: is the home for sync tuning, not the entry root: rev/shallow/depth join pin under one per-repository namespace rather than scattering VCS keys across the root. This keeps "how to clone" and "may vcspull edit this entry" co-located and the entry root limited to repo/remotes/worktrees.
• Deprecate-and-migrate over hard break: the top-level keys that shipped in v1.61.0 are still read (with a sync warning) and rewritten by a dedicated vcspull migrate command, so existing configs keep working through a grace period.
• Hybrid auto-detection: an auto-detected depth-1 checkout records the boolean shallow: true (the common case, unchanged from v1.61.0); only a genuine window (depth > 1) records depth: N.
• Precedence delegated to libvcs: GitSync.obtain() already resolves "explicit depth wins, else shallow→depth 1, else full," so vcspull records and forwards rather than re-implementing precedence at sync time.

Verification

--depth is wired into both importers:

$ rg -n '"--depth"' src/vcspull/cli/add.py src/vcspull/cli/discover.py

The reader and migrator share one canonical key list:

$ rg -n 'LEGACY_REPO_OPTION_KEYS' src/vcspull

The migrate subcommand is registered and dispatched:

$ rg -n 'migrate' src/vcspull/cli/__init__.py

End-to-end migrate (preview → write → idempotent):

$ vcspull migrate -f ~/.vcspull.yaml
$ vcspull migrate -f ~/.vcspull.yaml --write
$ vcspull migrate -f ~/.vcspull.yaml

Before / After

Config written by vcspull add/discover and read by sync:

# Before (v1.61.0)
~/code/:
  flask:
    repo: git+https://github.com/pallets/flask.git
    shallow: true
    rev: v3.0.0

# After
~/code/:
  flask:
    repo: git+https://github.com/pallets/flask.git
    options:
      rev: v3.0.0
      shallow: true   # or `depth: 50` for a history window

Test plan

• uv run ruff format . — formatting clean
• uv run ruff check . --fix --show-fixes — lint clean
• uv run mypy . — types clean
• uv run py.test --reruns 0 — full suite green
• just build-docs — docs build; new cli-migrate / config references resolve
• test_detect_git_depth, test_resolve_clone_depth_explicit, test_resolve_clone_depth_autodetect — depth detection and hybrid precedence
• test_extract_repos_lifts_options_sync_keys — reader surfaces options: and legacy forms, options: wins
• test_migrate_repo_entry, test_migrate_config, test_migrate_idempotent, test_migrate_cli_end_to_end — relocation, depth-wins, idempotency, CLI
• test_update_repo_git_depth — options.depth clones at --depth N on sync
• test_load_configs_warns_on_legacy_options — sync warns on the deprecated top-level form
• test_discover_detects_numeric_depth, test_discover_detects_shallow_clone — auto-detection records the right key
• add/discover fixtures assert the options: output shape with --depth cases

Closes #552

[codecov]

Codecov Report

❌ Patch coverage is 66.82243% with 71 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.82%. Comparing base (37b2c53) to head (597104f).

Files with missing lines	Patch %	Lines
src/vcspull/cli/migrate.py	46.66%	50 Missing and 6 partials ⚠️
src/vcspull/cli/add.py	40.00%	3 Missing and 3 partials ⚠️
src/vcspull/config.py	91.17%	5 Missing and 1 partial ⚠️
src/vcspull/cli/discover.py	76.92%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #554      +/-   ##
==========================================
- Coverage   83.69%   82.82%   -0.88%     
==========================================
  Files          29       30       +1     
  Lines        4159     4354     +195     
  Branches      820      873      +53     
==========================================
+ Hits         3481     3606     +125     
- Misses        442      502      +60     
- Partials      236      246      +10     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.