[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #326 (comment)

What

family.py bump and family.py remove take --dry-run. Each dry run makes every refusal its verb makes before its first write, prints what the real run would write or remove, and changes nothing in the holder.

Why

bump, add and remove had no --dry-run. The module docstring said 1 nothing (a dry run prints and exits 0), which was true only of init and siblings, and bump-leg.py already had one. To see what a bump would pin you had to run it: fetch the member, check it out at --to, rewrite family.yaml and stage. Even the nothing to do answer from #210 cost the fetch and the checkout.

The rulings, as implemented

• bump --dry-run leaves after the fetch and before the checkout, which is the real run's first write. The refusals before that point are the real run's own code, so they come out byte for byte the same, exit 2: the row (member-unknown, member-ambiguous), --to's form (member-to-not-a-commit), family.py: bump and remove refuse member-path when a row's path: is not members/<project> or its project: is not a directory name, and hand git every path literally, so a hand-edited path: members/* or project: . no longer makes remove unmount every member in one commit while dropping one row (#299) #315's member-path, and member-uninitialized.

  • It fetches, as the real run does. The fetch writes into the member's object store, which nothing in the holder records. The help and the docstring both say so. When the fetch fails, the closing line says --to was resolved from what the member's object store already held.

  • It resolves --to the way the checkout accepts it, with rev-parse --verify <to>^{commit}. A commit the member does not have after the fetch exits 2, where the real run's checkout would fail.

  • The digest is real. tree_digest reads objects and never a checkout, so the dry run prints the digest the real run computes. The "digest computed by the real run" fallback was never needed.

  • What the real run asks after its checkout is also asked, with nothing written:

    • the member's project.yaml at --to, read from its objects by the same _read_member_project. member-not-a-project, member-manifest-unreadable and member-bad-id come out word for word. load_yaml's own refusals come out word for word except the file's name: <repository> @ <commit>:project.yaml, not the member's path;
    • family.rewritten (family-members-unrecognised).

  • What it does not ask: what only the write itself can answer. A member whose local changes git checkout would refuse to overwrite gets exit 0 and a row from the dry run, and exit 2 from the real run's checkout. The module docstring says so.

  • Output. It prints:

    • commit <old> -> <new> and tree <digest>, in bump-leg.py --dry-run's layout;
    • the gitlink old -> new;
    • the whole row as family.yaml would carry it.

    The real run builds its rows with the same _bumped_rows, so the row printed is the row written by construction.

  • Exit 1 for nothing to do uses the real run's own family.py bump to the commit already pinned exits 2 as "REFUSED a git or gh command failed" around git's "nothing to commit", where family.py documents exit 1 for nothing and bump-leg.py answers the same re-run with "nothing to do", exit 1 #210 rule, checked without writing anything: HEAD's gitlink is already --to AND the rewritten manifest hashes (git hash-object --path, no -w) to the blob HEAD already has. A row that names --to over a digest that does not recompute, or over a gitlink that moved alone, is still a move under --dry-run, as it is in the real run.

  • It never runs checkout, add, commit or submodule, never runs hash-object -w, and never writes family.yaml.

• remove --dry-run leaves after member-path and before git submodule deinit.
  • It runs ls-files --error-unmatch over the same literal pathspec, and otherwise lists what git rm -r unstages. Where the index holds nothing at the path, this fails with the same line from git as the real run's deinit (did not match any file(s) known to git). It is printed the same way, the exact command and git's own words, exit 2, with no remediation for a leg.
  • It asks family-members-unrecognised.
  • It prints the row, the gitlink, the .gitmodules section, the holder's .git/config registration and the directory.
    • The section is the one a real git rm drops. Git looks the path up the way it reads the work-tree .gitmodules (overwrite on), and drops every section of the name it finds:
      • a name keeps the last path it is given;
      • a name that moves to another path takes the old path out of git's map;
      • a suspicious name (../ghost) is ignored.
    • Where that lookup finds no name, the dry run says none is removed. It names the other sections that still say the path and stay.
    • The registration is printed only when the holder's config holds one under that same name, the one deinit drops.
  • The index, .gitmodules, family.yaml, the work tree, .git/config and the holder's own object store stay byte-identical. It does not ask what only git rm answers: an unmerged .gitmodules.
• --trailer with --dry-run prints trailers N to append, in order: and the lines, worded as bump-leg.py words them, after the row. It prints nothing of the kind for nothing to do.
• The module docstring's EXIT CODES paragraph now says which subcommands have a dry run. A new paragraph says what each dry run asks, that bump's fetches, and what neither asks. bump's and remove's --help gained --dry-run, and docs/cli.md was regenerated with scripts/render-cli-reference.py.

Why add is not in it

This PR is ruling 1. add's dry run comes after the three changes to cmd_add now in flight have landed: this lane's #317 and #318, and lane 3's #330. This PR does not touch cmd_add or any function only it calls. remove's dry run reads .gitmodules and the index with readers of its own, not with add's _submodule_paths/_index_entries, because #317 and #318 change those two. AGENTS.md is not changed here because of its line cap; a line in its family section naming the two dry runs is a follow-up.

Tests

tests/test_family_dry_run.py is new, written in tests/test_family.py's style over the same local-bare-remote family, with a gh shim that exits 97. Every "changes nothing" claim is checked as bytes: ls-files -s -z, status --porcelain=v1 -z, family.yaml, .gitmodules, .git/config, the member's HEAD, the whole work tree and the holder's .git/objects. The comparison runs in an order that names the first fact that moved.

• A bump previewed, nothing changed, no gh call, the temporary manifest copy gone. A real bump then writes exactly the printed row, digest included.
• --to the pin: exit 1, nothing changed (plain, and with trailers).
• The two family.py bump to the commit already pinned exits 2 as "REFUSED a git or gh command failed" around git's "nothing to commit", where family.py documents exit 1 for nothing and bump-leg.py answers the same re-run with "nothing to do", exit 1 #210 repairs (a digest, a gitlink that moved alone): the dry run says move, and the real run agrees.
• --trailer with --dry-run prints the trailers, and the real commit ends with them.
• Each refusal before the first write is the same refusal under --dry-run: bump × unknown, not-a-commit, family.py: bump and remove refuse member-path when a row's path: is not members/<project> or its project: is not a directory name, and hand git every path literally, so a hand-edited path: members/* or project: . no longer makes remove unmount every member in one commit while dropping one row (#299) #315 member-path (hand-edited path:) and uninitialized; remove × unknown and member-path. Same exit, same stderr, nothing changed.
• A --to the member does not have: exit 2.
• A failed fetch: the note, and a closing line that says what --to was resolved from.
• member-not-a-project at --to: same stderr as the real run, with the member's checkout left unmoved.
• A symlinked project.yaml is left to the real run (POSIX only).
• remove previewed, nothing changed, then a real remove takes out exactly the printed row, gitlink, section, registration and directory, and leaves the neighbour.
• A row whose gitlink the index no longer holds: dry and real both exit 2 on git's same line, nothing moves, and neither names validate-pins.py or a leg pin.
• A second section for the member's path, in four hand edits, each compared with a real remove: two names; one name given another path then the member's (last path wins); the reverse (git drops nothing); a suspicious ../ghost. The real remove takes out exactly the sections, and the registration, the dry run named.
• family-members-unrecognised is asked by both dry runs.
• In process, with every subprocess recorded, for a move, a nothing to do and a remove: no git command that writes (hash-object -w and a non-listing config included), and only bump's fetches.

Mutants

Each mutant was run against the test the ruling names, and each was killed by the assertion the ruling names:

mutant	test	fails on
the dry-run return moved after the checkout	test_bump_dry_run_prints_the_move_and_a_real_bump_writes_exactly_that	AssertionError: member HEAD changed
write_members before the return	same	AssertionError: family.yaml changed
remove's return moved after git rm	test_remove_dry_run_prints_what_a_real_remove_takes_and_changes_nothing	AssertionError: index changed

Fix round (review of 875d802)

One commit on top of 875d802; nothing rebased.

• S1: the index listing in remove --dry-run now goes through _git_bytes, so a failure is a CommandFailed. It is printed as _bump_dry_run prints its own (REFUSED listing members/<P> in the index, where a real remove unmounts it. THE EXACT COMMAND WAS: ..., with git's own did not match any file(s) known to git), exit 2, and never with repo_shape's leg remediation. Every git call the dry runs make whose failure would reach the human now goes through _git_bytes: the manifest read, the .gitmodules and config listings, and hash-object. New test: a row whose gitlink was git rm --cached and committed. Dry and real both exit 2 on git's same line, nothing moves, and neither prints validate-pins or a leg pin.

• S2: _gitmodules_names now models git's own lookup over git config -z --file .gitmodules --list:

  • a name keeps its LAST path;
  • a name moving away takes the old path out of git's path map, whoever held it;
  • suspicious names (check_submodule_name) and option-like paths are skipped.

  It returns the name whose sections git rm drops (every section of that name), or none. The other names with a path = <P> line are printed as left in place. New parametrized test: the review's three probes plus the common two-names case. Each runs the dry run, then a real remove, which must take out exactly the sections of the name printed: last-path-wins drops both ghost sections; path-left-behind drops nothing; suspicious-name drops members/IRRS and keeps ../ghost.

• N1: the module docstring and _bump_dry_run's now say "every refusal made before its first write", and name what is not asked: a member's local changes the checkout would refuse, and an unmerged .gitmodules.

• N2: after a failed fetch the closing line says --to was resolved from what the object store already held. New test, with the member's origin pointed at a missing path.

• N5: the state the tests compare now includes the holder's own .git/objects. The in-process test treats hash-object -w and any non-listing config as writes, and gained a nothing to do case, which is the run that asks hash-object.

• N7: this body: refusals word for word except load_yaml's file name; the trailers header's 5 spaces; S1's and S2's wording; "before its first write".

• N8: remove --dry-run prints registration [submodule "<name>"] in the holder's .git/config, dropped by \git submodule deinit`. It does so only when the holder's config holds one under the name git rm drops (deinit` looks the name up the same way). The remove and ghost tests check that the real remove drops exactly that registration.

• N3, N4, N6: follow-ups, listed below.

Fix-round mutants, each against the test that must catch it:

mutant	killed by
MJ: remove --dry-run without --error-unmatch	test_remove_dry_run_of_a_member_the_index_does_not_hold_fails_as_remove (assert 0 == 2)
MI: hash-object -w	test_a_dry_run_runs_no_git_command_that_writes[bump-nothing] (['git', 'hash-object', '-w', ...])
MS2: a name keeps its FIRST path (the old rule)	test_remove_dry_run_names_the_sections_a_real_remove_drops[last-path-wins] and [path-left-behind]
MS3: suspicious names read like any other	test_remove_dry_run_names_the_sections_a_real_remove_drops[suspicious-name]

Follow-ups (not in this PR)

• N3, one definition: _print_trailers is a second copy of scripts/bump-leg.py's. Its home is shape_materialize.py, beside commit_trailers, once the open PRs on those two files have landed.
• N4, second readers: _gitmodules_names and _remove_dry_run read .gitmodules and the index beside add's _submodule_paths and _index_entries, which family.py: add refuses member-path-registered when a .gitmodules section under another name already gives the mount path, and validate-family.py finds gitmodules-path-twice, so add no longer commits two sections for one path that a recursive clone resolves to the later one, and a holder that already has such a ghost section fails its own gate (#300) #317 and family.py: add asks the holder's index for the mount path in any case, so an entry Members/Atlas/README is refused as member-path-taken before anything is cloned instead of leaving the member's 19 files staged under it, and a refused add says the holder is exactly as it was only when the whole index is as it was (#302) #318 are changing. Converge them once both have landed. Likewise _git_bytes beside add's _git_input, and _member_id_at beside _probe_manifest.
• N6, three-OS reading of the manifest: under Windows core.symlinks=false a symlinked project.yaml checks out as the link text, which the real run refuses while the dry run says the real run reads through the link. On a case-insensitive disk a Project.yaml is read by the real run and refused by the dry run. Both are rare and neither is probed on CI.
• AGENTS.md: a line in the family section naming the two dry runs (the line cap).
• Real-run defects the review confirmed on main:
  • remove asks family-members-unrecognised only after the unmount;
  • bump leaves the member checked out at --to when it refuses after the checkout;
  • remove over a ghost section keeps the member's own section;
  • bump --to a 40-hex annotated tag id pins the tag oid while the gitlink records the commit;
  • remove with an uncommitted deletion of .gitmodules commits that deletion;
  • repo_shape.REMEDIATION, a leg's, is what family.py's real-run git_out and load_yaml refusals print.

Part of #326

🤖 Generated with Claude Code

Summary by Sourcery

Add non-mutating previews for family member bumps and removals while preserving the real commands' validation and exit-code semantics.

New Features:

• Add --dry-run support to family.py bump, including realistic commit resolution, tree digest calculation, manifest validation, row and trailer previewing, and correct exit behavior.
• Add --dry-run support to family.py remove, previewing the affected family row, gitlink, .gitmodules sections, configuration registration, and directory without modifying the holder.

Bug Fixes:

• Ensure dry-run refusal handling matches the corresponding real operation for pre-write validation failures and preserves the documented exit-code behavior.

Enhancements:

• Model Git's .gitmodules section lookup when determining which sections a real removal would delete, including duplicate, moved, and suspicious names.
• Share row generation and no-op detection between real and dry-run bump operations.

Documentation:

• Update the CLI reference and module documentation to describe dry-run support, fetch behavior, no-op handling, and refusal boundaries.

Tests:

• Add comprehensive coverage verifying dry-run output, exit codes, refusal parity, trailer previews, no-change guarantees, Git metadata handling, and equivalence with subsequent real operations.

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 13 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

Adds fully validated dry-run support to family.py bump and remove: bump fetches and resolves object data but stops before checkout or holder writes, while remove reports the exact row, gitlink, .gitmodules section, and directory it would delete; extensive tests verify output parity, refusal parity, exit codes, and that no prohibited state changes occur.

Sequence diagram for family bump dry run

sequenceDiagram
    participant CLI
    participant Holder
    participant Member

    CLI->>Holder: cmd_bump
    Holder->>Member: git fetch
    Holder->>Member: rev-parse --verify <to>^{commit}
    Holder->>Member: _member_id_at
    Holder->>Member: tree_digest
    Holder->>Holder: _bumped_rows
    Holder->>Holder: family.rewritten
    alt nothing to do
        Holder-->>CLI: nothing to do, exit 1
    else move to preview
        Holder-->>CLI: print gitlink, row, and trailers
        Holder-->>CLI: exit 0
    end
    Note over Member,Holder: No checkout, family.yaml write, staging, or commit

Loading

Sequence diagram for family remove dry run

sequenceDiagram
    participant CLI
    participant Holder
    participant Member

    CLI->>Holder: cmd_remove
    Holder->>Holder: ls-files --error-unmatch
    Holder->>Holder: family.rewritten
    Holder->>Holder: _gitmodules_names
    Holder->>Member: inspect directory
    Holder-->>CLI: print row, gitlink, .gitmodules section, and directory
    Holder-->>CLI: exit 0
    Note over Member,Holder: No git submodule deinit, git rm, index, manifest, or config writes

Loading

File-Level Changes

Change	Details	Files
Add a non-mutating preview path for family.py bump, preserving real-run validation while stopping before checkout and holder writes.	Fetch the member before previewing, resolve --to with commit verification, and compute the real tree digest from objects. Read project.yaml at the target commit without checkout and reuse row-building logic shared with the real bump. Detect the existing nothing to do condition using HEAD gitlink and an unstored manifest blob hash. Print the commit transition, digest, gitlink, rewritten row, trailers, and explicit fetch/no-write status. Expose --dry-run in the parser and CLI documentation.	scripts/family.py docs/cli.md
Add a non-mutating preview path for family.py remove that describes the exact removal effects.	Validate the literal index path with ls-files --error-unmatch before previewing. Inspect index entries and .gitmodules sections, including duplicate-path behavior matching the section removed by git. Run manifest validation and print the row, gitlink/index entries, removed section, directory, and unchanged-state notice without deinit, rm, or other writes. Expose --dry-run in the parser and CLI documentation.	scripts/family.py docs/cli.md
Provide comprehensive regression coverage for dry-run semantics, output, refusals, and write isolation.	Verify byte-for-byte holder and member state preservation, including index, work tree, configuration, manifests, and member HEAD. Compare preview output with the subsequent real bump/remove results, including digests, rows, trailers, duplicate .gitmodules sections, and repair cases. Cover matching refusal behavior, missing commits, manifest errors, symlink handling, nothing to do, and manifest-recognition validation. Record subprocesses to ensure dry runs execute no writing git commands while confirming bump fetches.	tests/test_family_dry_run.py

Possibly linked issues

• family.py bump (and add, remove) take no --dry-run, though the file's exit-code paragraph says a dry run prints and exits 0 and bump-leg.py has one, so the only way to see what a bump would pin is to run it: fetch, check the member out at --to and rewrite family.yaml #326: PR family.py bump (and add, remove) take no --dry-run, though the file's exit-code paragraph says a dry run prints and exits 0 and bump-leg.py has one, so the only way to see what a bump would pin is to run it: fetch, check the member out at --to and rewrite family.yaml #326 directly resolves the issue by adding bump --dry-run, preserving holder state and previewing the intended pin change.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud