feat(config,cli) Numeric clone depth, sync keys under options: (#554)

vcspull can now keep a small window of git history per repository via a
numeric `options.depth: N`, instead of the all-or-nothing `shallow:
true`. The per-repository sync-tuning keys (`rev`, `shallow`, `depth`)
move into an `options:` block alongside the existing mutation policy,
and a new `vcspull migrate` command rewrites configs from the older
top-level form. Builds on the rev-pinning and shallow-detection work
from v1.61.0. Fixes #552.

- **Numeric depth:** `add` and `discover` accept `--depth N` (clone
  `--depth N` on sync) and auto-detect an existing checkout's depth —
  recording `options.shallow: true` for a depth-1 clone and
  `options.depth: N` for a deeper window. `depth` wins over `shallow`.
- **options: block:** `rev`/`shallow`/`depth` are written under
  `options:` (joining `pin`/`pin_reason`), keeping the entry root to the
  repo URL, remotes, and worktrees.
- **vcspull migrate:** new subcommand (mirrors `fmt`: `-f/--file`,
  `--write`, `--all`) that relocates top-level keys into `options:`;
  previews by default and is idempotent on re-run.
- **Deprecation warning:** `vcspull sync` warns when it reads a config
  still using the top-level form and points at `vcspull migrate`.

Breaking changes:

  The `rev:` and `shallow:` keys that shipped at the repository entry
  root in v1.61.0 are deprecated in favor of the `options:` block. They
  are still read (with a warning), so existing configs keep working;
  run `vcspull migrate --write` to update them.

  # Before
  ~/code/:
    flask:
      repo: git+https://github.com/pallets/flask.git
      shallow: true

  # After
  ~/code/:
    flask:
      repo: git+https://github.com/pallets/flask.git
      options:
        shallow: true

Dependencies:

  Minimum libvcs >= 0.42.0 (was >= 0.41.0) — its GitSync honors an
  arbitrary clone depth, which `options.depth: N` relies on.

Author: tony

CHANGES

@@ -37,6 +37,53 @@ $ uvx --from 'vcspull' --prerelease allow vcspull
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Breaking changes
+
+#### Per-repository sync keys now live under `options:` (#552)
+
+The per-repository `rev`, `shallow`, and new `depth` keys are written under an
+`options:` block instead of the entry root. The top-level form that shipped in
+v1.61.0 is still read, but {ref}`cli-sync` warns when it encounters it. Run
+{ref}`cli-migrate` to rewrite existing configs:
+
+```yaml
+# Before
+~/code/:
+  flask:
+    repo: git+https://github.com/pallets/flask.git
+    shallow: true
+
+# After
+~/code/:
+  flask:
+    repo: git+https://github.com/pallets/flask.git
+    options:
+      shallow: true
+```
+
+### Dependencies
+
+#### Minimum `libvcs>=0.42.0` (was `>=0.41.0`)
+
+libvcs 0.42.0 teaches its git backend an arbitrary clone depth, which the new
+`depth: N` key relies on.
+
+### What's new
+
+#### Numeric clone depth (#552)
+
+A repository can keep a small window of history with `options.depth: N` (clone
+with `--depth N`) instead of the all-or-nothing `shallow: true`. {ref}`cli-add`
+and {ref}`cli-discover` accept `--depth N` and detect an existing checkout's
+depth automatically—recording `shallow: true` for a depth-1 checkout and
+`depth: N` for a deeper window. See {ref}`configuration`.
+
+#### Migrate configs to the `options:` form (#552)
+
+{ref}`cli-migrate` rewrites configuration files that still carry top-level
+`rev`/`shallow`/`depth`, moving them under `options:`. It previews changes by
+default and applies them with `--write`.
+
 ## vcspull v1.61.0 (2026-05-30)
 
 vcspull v1.61.0 lets `add` and `discover` capture per-repository git state when

MIGRATION

@@ -21,7 +21,41 @@ well.
 
 ## Next release
 
-_Notes on the upcoming release will be added here_
+### Per-repository sync keys moved under `options:`
+
+_via #552_
+
+The per-repository `rev`, `shallow`, and the new `depth` keys are now written
+under an `options:` block instead of the repository entry root. The top-level
+form still loads, but `vcspull sync` now warns when it reads it and points you
+here. Rewrite your configs in place:
+
+```console
+$ vcspull migrate --write
+```
+
+Before:
+
+```yaml
+~/code/:
+  flask:
+    repo: git+https://github.com/pallets/flask.git
+    shallow: true
+```
+
+After:
+
+```yaml
+~/code/:
+  flask:
+    repo: git+https://github.com/pallets/flask.git
+    options:
+      shallow: true
+```
+
+`depth: N` is new — record a numeric clone depth (`git clone --depth N`) when a
+boolean `shallow` (depth 1) is too little. See {ref}`configuration` and
+{ref}`cli-migrate`.
 
 <!-- Maintainers, insert changes / features for the next release here -->
 

docs/cli/index.md

@@ -49,6 +49,12 @@ Scan directories for existing repos.
 Normalize and format config files.
 :::
 
+:::{grid-item-card} vcspull migrate
+:link: migrate
+:link-type: doc
+Move rev/shallow/depth under options:.
+:::
+
 :::{grid-item-card} vcspull import
 :link: import/index
 :link-type: doc
@@ -82,6 +88,7 @@ search
 status
 worktree/index
 fmt
+migrate
 ```
 
 ```{toctree}
@@ -105,5 +112,5 @@ completion
     :nosubcommands:
 
     subparser_name : @replace
-        See :ref:`cli-sync`, :ref:`cli-add`, :ref:`cli-import`, :ref:`cli-discover`, :ref:`cli-list`, :ref:`cli-search`, :ref:`cli-status`, :ref:`cli-worktree`, :ref:`cli-fmt`
+        See :ref:`cli-sync`, :ref:`cli-add`, :ref:`cli-import`, :ref:`cli-discover`, :ref:`cli-list`, :ref:`cli-search`, :ref:`cli-status`, :ref:`cli-worktree`, :ref:`cli-fmt`, :ref:`cli-migrate`
 ```

docs/cli/migrate.md

@@ -0,0 +1,81 @@
+(cli-migrate)=
+
+# vcspull migrate
+
+`vcspull migrate` rewrites configuration files to the current schema, moving the
+per-repository `rev`, `shallow`, and `depth` keys from the entry root into the
+`options:` block. By default it prints the proposed changes; apply them in place
+with `--write`.
+
+These keys shipped at the entry root in vcspull v1.61.0. They are still read,
+but {ref}`cli-sync` warns when it encounters them. Migrating clears the warning
+and keeps configs on the supported shape.
+
+## Command
+
+```{eval-rst}
+.. argparse::
+    :module: vcspull.cli
+    :func: create_parser
+    :prog: vcspull
+    :path: migrate
+```
+
+## What gets migrated
+
+For each repository entry, a top-level `rev`, `shallow`, or `depth` key is moved
+under `options:`. A value already present under `options:` wins, and `depth`
+takes precedence over `shallow`. Entries already on the `options:` form, string
+shorthands, and unrelated keys are left untouched.
+
+Given:
+
+```yaml
+~/code/:
+  flask:
+    repo: git+https://github.com/pallets/flask.git
+    rev: v3.0.0
+    shallow: true
+```
+
+`vcspull migrate --write` produces:
+
+```yaml
+~/code/:
+  flask:
+    repo: git+https://github.com/pallets/flask.git
+    options:
+      rev: v3.0.0
+      shallow: true
+```
+
+## Writing changes
+
+Preview the rewrite first:
+
+```console
+$ vcspull migrate --file ~/.vcspull.yaml
+```
+
+Then add `--write` to persist it:
+
+```console
+$ vcspull migrate \
+    --file ~/.vcspull.yaml \
+    --write
+```
+
+Use `--all` to iterate over the default search locations: the current working
+directory, `~/.vcspull.*`, and the XDG configuration directory.
+
+```console
+$ vcspull migrate --all --write
+```
+
+Migration is idempotent—running it again on an already-migrated file makes no
+changes.
+
+## See also
+
+- {ref}`configuration` — the `options:` block and its sync-tuning keys.
+- {ref}`migration` — the deprecation note for the top-level form.

docs/configuration/index.md

@@ -119,41 +119,83 @@ Optional fields:
 
 See {ref}`cli-worktree` for full command documentation.
 
-## Revision pinning
+## Sync options
 
-A `rev:` key pins a repository to a commit, tag, or branch, which {ref}`cli-sync`
-checks out. This lets a config capture a reproducible snapshot instead of
-tracking the branch tip. It is distinct from `options.pin` (see
+Per-repository sync behavior lives under an `options:` block alongside the
+`repo` URL. The keys below tune how {ref}`cli-sync` clones and updates a
+checkout. Mutation policy such as `pin` lives in the same block (see
+{ref}`config-pin`).
+
+### Revision pinning
+
+`options.rev` pins a repository to a commit, tag, or branch, which
+{ref}`cli-sync` checks out. This lets a config capture a reproducible snapshot
+instead of tracking the branch tip. It is distinct from `options.pin` (see
 {ref}`config-pin`), which guards the config entry from being overwritten rather
 than pinning a git ref.
 
 ```yaml
 ~/code/:
   flask:
     repo: git+https://github.com/pallets/flask.git
-    rev: v3.0.0
+    options:
+      rev: v3.0.0
 ```
 
 `vcspull add <path> --pin <ref>` and `vcspull discover <dir> --pin <ref>` record
 this key when importing an existing checkout. See {ref}`cli-add` and
 {ref}`cli-discover`.
 
-## Shallow clones
+### Shallow clones
 
-A `shallow: true` key makes {ref}`cli-sync` clone the repository with
+`options.shallow: true` makes {ref}`cli-sync` clone the repository with
 `--depth 1`, trading git history for disk and time—useful for workspaces with
 many repositories.
 
 ```yaml
 ~/code/:
   flask:
     repo: git+https://github.com/pallets/flask.git
-    shallow: true
+    options:
+      shallow: true
+```
+
+`vcspull add` and `vcspull discover` detect an existing depth-1 checkout
+automatically and record `options.shallow: true`; the `--shallow` flag forces it
+on even for a full checkout.
+
+### Clone depth
+
+`options.depth: N` keeps a small window of history by cloning with `--depth N`.
+Reach for it when `shallow: true` (depth 1) is too little—for example, a handful
+of recent commits for `git log` or `git bisect`.
+
+```yaml
+~/code/:
+  django:
+    repo: git+https://github.com/django/django.git
+    options:
+      depth: 50
+```
+
+`vcspull add <path> --depth N` and `vcspull discover <dir> --depth N` record this
+key. When importing an existing shallow checkout, both detect its depth: a
+depth-1 checkout records `options.shallow: true` and a deeper window records
+`options.depth: N`. `depth` takes precedence over `shallow` when both are set.
+
+### Migrating from the top-level form
+
+vcspull v1.61.0 accepted `rev:` and `shallow:` at the repository entry root.
+Those keys still work but are deprecated in favor of the `options:` block, and
+{ref}`cli-sync` warns when it reads them. Run {ref}`cli-migrate` to rewrite
+existing configs in place:
+
+```console
+$ vcspull migrate --write
 ```
 
-`vcspull add` and `vcspull discover` detect an existing shallow checkout
-automatically and record `shallow: true`; the `--shallow` flag forces it on even
-for a full checkout.
+See {ref}`migration` for the deprecation note and {ref}`cli-migrate` for the
+command reference.
 
 (config-pin)=
 

docs/internals/api/cli/index.md

@@ -17,6 +17,7 @@ search
 status
 worktree
 fmt
+migrate
 ```
 
 ## vcspull CLI - `vcspull.cli`

docs/internals/api/cli/migrate.md

@@ -0,0 +1,8 @@
+# vcspull migrate - `vcspull.cli.migrate`
+
+```{eval-rst}
+.. automodule:: vcspull.cli.migrate
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```

pyproject.toml

@@ -53,7 +53,7 @@ keywords = [
 ]
 homepage = "https://vcspull.git-pull.com"
 dependencies = [
-  "libvcs>=0.41.0,<0.42.0",
+  "libvcs>=0.42.0,<0.43.0",
   "colorama>=0.3.9",
   "PyYAML>=6.0"
 ]