Neovim sync module#

python/src/dotfiles/nvim.py computes sync plans and applies runtime Neovim state into home/dot_config/nvim.

High-level structure#

nvim.py
|-- snapshot models
|   |-- NvimPathPair
|   |-- NvimLuaSubdirManifest
|   |-- NvimSubdirManifest
|   `-- NvimSyncPlan / NvimSyncInfoCounts
|-- abstractions
|   |-- ShellOp (writes)
|   `-- DiskAccessor (reads)
|-- request models
|   |-- NvimSyncWithMimicArgs
|   `-- NvimInfoArgs
|-- plan and diff helpers
|   `-- managed-surface totals helpers
|       |-- _nvim_count_existing_top_level_files
|       `-- _nvim_collect_managed_surface_totals
 `-- orchestration
     |-- _nvim_sync
     |-- nvim_sync_with_mimic
     `-- nvim_info

  • Builds a snapshot plan from runtime and local manifests.

  • Splits file changes into add, update, unchanged buckets.

  • Removes missing runtime entries and copies changed runtime entries.

  • Computes managed-surface totals through dedicated helpers before sync-change counts.

  • Resolves runtime/local paths and branch/worktree prechecks in one place.

Sync flow#

  1. nvim_sync_with_mimic resolves runtime/local paths from request args.

  2. It validates runtime git cleanliness and branch policy.

  3. _nvim_sync resolves ShellOp from dry_run and builds sync plan.

  4. Removes explicit top-level targets except lua.

  5. Prunes missing runtime files/directories from local lua.

  6. Copies non-lua base targets and changed top-level files.

  7. Copies changed lua files while preserving protected templates.

Info flow#

  • nvim_collect_sync_info_counts computes totals and add/update/remove counts from the same plan model used by sync.

  • nvim_info logs those counts and returns the structured summary.

Mimic flow#

  • nvim_sync_with_mimic can run sync against a temporary copy of local nvim.

  • It then runs nvim_info against the mimicked directory to verify no pending managed-surface changes remain.