inspect_mount
Report what syncing a mount would change, without changing anything. Distinguish job-produced artifacts from stale files to prevent data loss.
Instructions
Report what syncing a mount would change, without changing anything.
Read-only: this never transfers, deletes, or creates anything on the
cluster. Call it freely, including before a sync you are unsure about.
Its main job is answering a question ``sync_files`` cannot: **what is on the
cluster that no longer exists locally?** A sync is additive, so those files
stay — including code deleted in a local refactor, which a job on the
cluster can still import and run. They are listed here as
``mirror_delete_candidate_paths``.
Those candidates mix two kinds of thing:
* **produced by jobs** — checkpoints, logs, outputs. Must NOT be deleted.
* **left over locally** — stale modules, renamed files. Usually should be.
``stale_upload_paths`` is the second group on its own: paths srunx recorded
uploading that are no longer present locally. Job output was never uploaded,
so it does not appear there — which holds even when the mount's exclude list
misses an output directory, the case that otherwise buries a few stale
scripts among dozens of artifacts.
One exception: output pulled into the local tree with ``srunx ssh sync
--pull`` becomes a file the next push manages, so it is recorded like any
other and can be reported as stale once its local copy is removed. Excluding
the output directories on the mount avoids that, and is worth doing anyway.
**Check ``stale_uploads_known`` first.** When it is false the record could
not answer (nothing uploaded with tracking yet, an unreadable record, or a
changed exclude filter), and ``stale_uploads: 0`` means "could not tell",
not "nothing is stale" — ``stale_uploads_unknown_reason`` says which. Fall
back to reading the full candidate list yourself in that case.
Args:
transport: SSH profile name to inspect. Required — there is no local
inspection, and (unlike the CLI) no implicit current-profile
fallback. Call ``list_ssh_profiles`` for the available profiles and
the mounts each defines.
mount: Mount name from that SSH profile.
max_paths: Cap on how many paths to list. Counts stay exact regardless;
past the cap the list is omitted rather than shortened, and
``mirror_delete_candidate_paths_omitted`` says so.
Returns:
``files_would_transfer``, ``mirror_delete_candidates`` (a count),
``mirror_delete_candidate_paths``, whether that list was omitted,
``effective_exclude_patterns``, and the stale-upload fields described
above (``stale_uploads_known`` / ``stale_uploads`` /
``stale_upload_paths`` / ``stale_uploads_unknown_reason``).
The exclude list matters for reading the result: excluded paths are
invisible to this inspection *and* protected from a mirror's deletions,
so something absent from the candidates may simply be excluded rather
than in sync.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mount | Yes | ||
| max_paths | No | ||
| transport | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||