[brettheap]

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

What

family.py add takes --dry-run. This is the second and last part of #326. Part 1, #345 (3ae0109), gave bump and remove their dry runs and left add out until the changes to cmd_add then in flight had landed. With this PR, every subcommand has the dry run the module's EXIT CODES line promises.

add also takes --trailer, the same repeatable flag bump has. Ruling 4 asks --trailer with --dry-run to print the trailers it would write, and add had no --trailer at all. The flag goes into the real commit too, through _commit_one, as bump's does. Without it, add's commit is byte for byte the one it has always written.

Why

Until now the only way to see what add would pin was to run it: clone the member, git submodule add it, rewrite family.yaml and commit.

The rulings, as implemented

1. Every refusal before the first write, in the same order, with the same codes, exit 2. cmd_add leaves for _add_dry_run after the probe and before MountRollback is taken or git submodule add runs. So every refusal before that point is the real run's own code, in the real run's order:

   • the holder's: member-malformed, member-already-present, member-path-taken, member-path-unaddable, member-name-taken, member-path-registered, member-git-dir-cached, family-members-unrecognised, member-at-not-a-commit;
   • the member's, asked of the probe's throwaway clone: member-no-tip, member-at-unknown, member-not-a-project, the manifest's own refusals, and an unreadable member (REFUSED reading ... plus the hint).

2. It reads the member, outside the holder.

   • A real add reads the member twice: the probe's clone, then the mount, whose reading the row records. The dry run has no mount. Its second reading is a second bare clone, made as the probe makes its own: in a temporary directory outside the holder, and deleted whatever the answer, a refusal included.
   • It reads that clone at the commit the probe resolved. The id: comes from _member_id_at, which reads project.yaml with the function the mount's checkout is read with. The digest comes from tree_digest, which reads objects and never a checkout.
   • It never runs git submodule add. It never writes .gitmodules, family.yaml, the index, the work tree, .git/config or .git/modules.
   • The help and the module docstring say it reads the member.

3. What it prints, in bump --dry-run's layout, exit 0:

   • commit none -> <sha> and the digest, which is the real run's, from the same tree;
   • the gitlink;
   • the .gitmodules section git submodule add writes: its name (the path), its path and its url, and in a new .gitmodules for a family's first member;
   • the registration it writes in .git/config, or the one there whose url it rewrites;
   • the directory and the object store the mount makes, where git keeps the store;
   • the row as family.yaml would carry it, built by _member_row, as the real run's is;
   • the trailers.

   Without --at, a note says the real run pins the tip it finds when it mounts, and prints the --at <sha> that pins the commit shown.

4. --trailer with --dry-run prints trailers N to append, in order: and the lines, after the row, as part 1 does. With no --trailer it prints trailers none.

5. The module docstring and the help. EXIT CODES now says every subcommand takes --dry-run. The dry-run paragraph says what add's dry run asks and that it reads the member, and add's --help says so too. docs/cli.md was regenerated in this worktree under GIT_ALLOW_PROTOCOL=file, and render-cli-reference.py --check passes. AGENTS.md is not changed.

6. Closes #326.

What it names and does not ask:

• A linked project.yaml. The objects hold only the link's text, and the real run's mount reads through it. The dry run says so in a note and prints id: (read through the link by the real run); it does not guess an id. The real run then writes the rest of the row as printed (test, POSIX only).
• A .gitmodules the index or HEAD has and the work tree does not. Git 2.43 refuses this case in git submodule add before it writes anything (please make sure that the .gitmodules file is in the working tree). The real run exits 2 there with the holder unchanged. Only git can say that sentence, so the dry run says in a note that the real run will exit 2, and how to put the file back, then exits 0. It never claims a new .gitmodules. Part 1 treats the checkout's own refusal the same way, and the module docstring says so.

Composes with

Each row is git merge-tree --write-tree origin/<branch> e792bd3, at the branch's head after a fetch at 2026-10-12T16:20Z, over the same tree as de628fe. Every one exits 0.

branch	PR	head	files shared with this PR	merge
main		1f90a0f	none	clean
fix/family-add-member-id	#381	8c14f79	scripts/family.py (cmd_add)	clean
fix/family-member-re	#399	37e8f1e	scripts/family.py	clean
fix/family-init-values	#397	abb27e6	scripts/family.py, docs/cli.md	clean
fix/trailer-non-ascii-old-git	#376	d079893	scripts/family.py	clean
fix/ruleset-hint-tracking-branch	#373	741cbf2	scripts/family.py	clean
fix/scaffold-tracking-branch-ref-format	#355	a03abcf	scripts/family.py	clean
fix/template-quoted-placeholders	#395	3894aa8	scripts/family.py	clean
fix/adopt-plan-leg-path-help	#401	6124cb4	docs/cli.md	clean
fix/scaffold-manifest-values	#314	a5438a5	docs/cli.md	clean

#381 adds member-duplicate-id right after the probe. The dry-run return sits after that point, separated from #381's insertion by the blank line that follows the probe's except. So the merge is textually clean, and the id check comes before the return.

I probed the merged tree offline: a holder pinning IRQS, then add --member InkRouter/IRQS2 (a bare copy with the same id). Real and --dry-run both exit 2 with REFUSED member-duplicate-id: ..., their stdout and stderr byte-identical. The index is unchanged and no temporary clone is left.

Tests

The tests are appended to tests/test_family_dry_run.py; part 1's tests are untouched. They use the same local-bare-remote family, with a gh shim that exits 97 and git's automatic maintenance off. Every "changes nothing" claim is checked as bytes, compared in the order a mount would change them: index, .gitmodules, the .git/modules listing, .git/config, family.yaml, status --porcelain=v1 -z, the work tree, the holder's objects, HEAD. A file that is not there is compared as absent.

• A real add previewed, for a holder with members and for a family's first member (no .gitmodules: absent stays absent, and the section says in a new .gitmodules). Nothing moved, no gh call, and no temporary clone left. The real add then writes exactly what was printed:

  • the printed row;
  • the printed digest;
  • the gitlink;
  • the section (path and url, read back with git config -f .gitmodules);
  • the registration, the directory and the store;
  • no trailers.

  The holder then validates.

• 13 refusals before the first write, each run real and --dry-run over the same holder. Both give exit 2 with the same stdout and the same stderr, normalized only for the throwaway clone's random directory name in a failed clone's command line. The holder is unchanged and nothing is left behind. The cases:

  • member-malformed ×2 (no owner, <org>/..);
  • a duplicate row ×2 (member-already-present, exact and in another case);
  • member-path-taken;
  • member-name-taken;
  • member-path-registered (family.py: add never reads .gitmodules, so a section under ANOTHER name whose path is already members/<P> (a "ghost" section) does not stop it: it exits 0 and commits two sections for one path, validate-family.py says family ok, and a recursive clone takes the LATER section, so with the ghost second it dies fetching the ghost's URL #300's ghost, an unstaged hand edit);
  • member-git-dir-cached;
  • family-members-unrecognised;
  • member-at-not-a-commit;
  • member-at-unknown;
  • member-not-a-project (a leg);
  • an unreadable member.

• --trailer with --dry-run prints them, in order, after the row, and the real commit ends with exactly those lines.

• --at previews that commit, with no without --at note, and the real add pins it.

• A registration the mount rewrites is named as rewritten, and the real add leaves the url that was printed.

• The .gitmodules note, for an unstaged and a staged deletion: the dry run exits 0 with the note, and the real add exits 2 on git's line. The holder is unchanged after both.

• A linked manifest (POSIX only), as above.

• In process, every program recorded:

  • both clones are under the run's TEMP, and none is in the holder;
  • the holder's git status, asked while the dry run's own clone still exists (at the moment its digest is computed), is the status before the run;
  • no git command run in the holder writes. Git's own add --dry-run, the real run's check of the mount path, is the one exception;
  • no git submodule runs.

• An id that is not the name lowercased (fix round, S1). Member IRDI records id: routing-core. The dry run prints id: routing-core, and the real add writes exactly the printed row.

• The dry run's own clone, removed when it fails (fix round, N3). In process, the member's remote is moved away between the probe's clone and the dry run's own, so the second clone fails in git, for real. The dry run gives exit 2 with REFUSED reading, the exact command and the hint. Its clone's directory is gone, TEMP is empty, and the holder is unchanged. The test does not stub _probe_member, whose return family.py: add refuses member-duplicate-id before it mounts anything when the member's project.yaml records an id a row already pins, so adding a repository renamed at the forge no longer commits a second row the holder's own validate-family.py refuses (#330) #381 changes.

• A holder that is a linked worktree (fix round, N3). The object store the dry run names, under .git/worktrees/<name>/modules/, does not exist before the real add and is the one the real add makes.

Targeted set (Linux, git 2.43.0, CI's git-filter-repo pin): tests/test_family_dry_run.py, test_family.py, test_family_add_refusals.py, test_family_member_path.py and test_cli_reference.py.

• On head 8bcc57c: 269 passed in 433.53s (0:07:13), 0 skipped.
• On head de628fe (e792bd3 before its message took these results; the tree is the same, 1ef88b7): 272 passed in 192.45s (0:03:12), 0 skipped.

test_family_add_refusals.py also gains one docstring sentence. It said add had no --dry-run; it now points here.

Mutants

Each mutant was run in a scratch worktree at the head against the test the ruling names (mutants.py, restored after each):

mutant	test	fails on
the dry-run return moved after git submodule add	test_add_dry_run_prints_what_a_real_add_writes_and_changes_nothing[two-members]	AssertionError: index changed
same	test_add_dry_run_reads_the_member_outside_the_holder_and_writes_nothing	AssertionError: the holder's status moved while the member was being read (M .gitmodules ...)
the dry run's temporary clone made inside the holder (mkdtemp(dir=family.root))	test_add_dry_run_reads_the_member_outside_the_holder_and_writes_nothing	AssertionError: the holder's status moved while the member was being read (?? openreposhape-member-…/)
the dry run's temporary directory not removed	test_add_dry_run_prints_what_a_real_add_writes_and_changes_nothing[two-members]	offline.assert_left_nothing(): […/temp/openreposhape-member-yc8fysxa] == []

The second mutant survives the end-state test, and the table shows why it must. A clone made inside the holder and deleted at the end leaves no trace in any end state. That is why the in-process test asks git status while the clone exists.

The fix round's mutants are the reviewer's own M4, M10 and M11, applied by the reviewer's mutants.py in a scratch worktree at e792bd3 (the same tree as de628fe). Each was run over the same selection the review used (pytest tests/test_family_dry_run.py -k add, now 25 tests). All three survived at 8bcc57c:

mutant	result at e792bd3	killed by	fails on
M4: the id made from the name, project.lower(), for any non-linked manifest	1 failed, 24 passed	test_add_dry_run_prints_the_id_the_members_manifest_records	At index 1 diff: ' id: irdi' != ' id: routing-core'
M10: the dry run's own clone leaked on its failure path (finally turned into else)	1 failed, 24 passed	test_add_dry_run_removes_its_own_clone_when_reading_the_member_fails	AssertionError: the dry run's clone was left
M11: the store assumed to be .git/modules/<path>	1 failed, 24 passed	test_add_dry_run_names_the_store_git_keeps_for_a_linked_worktree	AssertionError: the store printed, …/lane/.git/modules/members/IRQS, is not the one git made

Fix round (review of 8bcc57c)

The review's verdict was MERGEABLE WITH NITS: 0 MUST, 1 SHOULD, 6 NIT. I added one commit, de628fe, on top of 8bcc57c, pushed plainly; nothing on origin was amended or rebased. It changes tests only: scripts/family.py is byte-identical to 8bcc57c's.

• S1 (fixed): the id test above. It kills M4, which printed project.lower() as the id.
• N3 (fixed): the own-clone and linked-worktree tests above. They kill M10 (the clone leaked on its failure path) and M11 (the store assumed to be .git/modules/<path>). add_state now reads .git/objects and .git/modules as absent where .git is a file.
• N5 (fixed): the "Composes with" table is refreshed at today's heads, with family.py: add refuses a --member whose owner or project does not begin with a letter or a digit as member-malformed before the member is read, so testorg/_Zed, testorg/.Zed, testorg/-Zed, _org/Zed and .org/Zed no longer exit 0 with a commit that the holder's own validate-family.py fails as member-repository (#366) #399, adopt-project.py: plan --help says what --spec-path and --code-path are, the default and key each records, and the two refusals plan makes on them, so docs/cli.md no longer lists the two flags that choose where a leg is mounted as bare lines (#340) #401 and scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314 added.
• N1 (follow-up, below): git's mount refusal is certain, yet the dry run exits 0 with a note. The fix belongs in the real add: a named refusal both runs would ask.
• N2 (noted): a force-push between the two readings makes the dry run print REFUSED reading with the access hint, while the real run would pin the new tip. The window is seconds wide, and reading the member once (N4) removes it.
• N4 (follow-up, below): two copies of the throwaway-clone block, and one remediation sentence spelled twice.
• N6 (noted): on a merge with family.py: add refuses member-duplicate-id before it mounts anything when the member's project.yaml records an id a row already pins, so adding a repository renamed at the forge no longer commits a second row the holder's own validate-family.py refuses (#330) #381, a linked project.yaml whose target records an id a row already pins gets exit 0 from the dry run. The real run refuses member-duplicate-id after the mount and unwinds. This is inside the module docstring's stated limit. Whichever of family.py: add refuses member-duplicate-id before it mounts anything when the member's project.yaml records an id a row already pins, so adding a repository renamed at the forge no longer commits a second row the holder's own validate-family.py refuses (#330) #381 and family.py: add --dry-run makes every refusal add makes before it mounts, reads the member from throwaway clones outside the holder for the row's id and digest, and prints the row, gitlink, .gitmodules section and trailers without mounting, writing or committing anything, and add takes --trailer as bump does, so every subcommand has the dry run the module's EXIT CODES line promises (#326) #400 lands second should add a member-duplicate-id row to ADD_REFUSALS, and may make the linked note name that refusal.

Fix round 2 (stacked on #399, main merged, member-duplicate-id parity)

Added on top of de628fe, pushed plainly; nothing on origin was amended or rebased: two merge commits, then one commit of tests/test_family_dry_run.py and a docstring in scripts/family.py.

• Stacked on family.py: add refuses a --member whose owner or project does not begin with a letter or a digit as member-malformed before the member is read, so testorg/_Zed, testorg/.Zed, testorg/-Zed, _org/Zed and .org/Zed no longer exit 0 with a commit that the holder's own validate-family.py fails as member-repository (#366) #399. family.py: add refuses a --member whose owner or project does not begin with a letter or a digit as member-malformed before the member is read, so testorg/_Zed, testorg/.Zed, testorg/-Zed, _org/Zed and .org/Zed no longer exit 0 with a commit that the holder's own validate-family.py fails as member-repository (#366) #399 (fix/family-member-re, family.py _checked_member's MEMBER_RE admits an owner or a project that begins with ., _ or - (testorg/_Zed, testorg/.Zed, testorg/-Zed, _org/Zed, .org/Zed), which the holder's own validate-family.py refuses with its QUALIFIED_RE, so add exits 0 with a commit whose new row its gate then reports as member-repository #366: MEMBER_RE and _checked_member) lands before this PR and also edits scripts/family.py, and a Windows CI run now takes about 55 minutes. So origin/fix/family-member-re (1f86188) is merged here, then origin/main (45e01f4, tests/test_agents_md_codes.py: every backticked code-shaped name in AGENTS.md must be an exact string constant in a shipped tool, so a misspelt scaffold-pin-collides, or the code renamed in scaffold-project.py while AGENTS.md keeps its old spelling, fails naming the token and the document instead of leaving an assistant to relay a code no tool prints (#348) #396's tests/test_agents_md_codes.py). CI tests main, family.py: add refuses a --member whose owner or project does not begin with a letter or a digit as member-malformed before the member is read, so testorg/_Zed, testorg/.Zed, testorg/-Zed, _org/Zed and .org/Zed no longer exit 0 with a commit that the holder's own validate-family.py fails as member-repository (#366) #399 and family.py: add --dry-run makes every refusal add makes before it mounts, reads the member from throwaway clones outside the holder for the row's id and digest, and prints the row, gitlink, .gitmodules section and trailers without mounting, writing or committing anything, and add takes --trailer as bump does, so every subcommand has the dry run the module's EXIT CODES line promises (#326) #400 together, and this PR can land right after family.py: add refuses a --member whose owner or project does not begin with a letter or a digit as member-malformed before the member is read, so testorg/_Zed, testorg/.Zed, testorg/-Zed, _org/Zed and .org/Zed no longer exit 0 with a commit that the holder's own validate-family.py fails as member-repository (#366) #399 without a second cycle. Both merges were clean: no conflict, nothing to resolve. The "Composes with" table above predates this: family.py: add refuses member-duplicate-id before it mounts anything when the member's project.yaml records an id a row already pins, so adding a repository renamed at the forge no longer commits a second row the holder's own validate-family.py refuses (#330) #381 has landed (f0a8bf6) and family.py: add refuses a --member whose owner or project does not begin with a letter or a digit as member-malformed before the member is read, so testorg/_Zed, testorg/.Zed, testorg/-Zed, _org/Zed and .org/Zed no longer exit 0 with a commit that the holder's own validate-family.py fails as member-repository (#366) #399 is now underneath this branch.
• member-duplicate-id under --dry-run. Lane 3's family.py: add refuses member-duplicate-id before it mounts anything when the member's project.yaml records an id a row already pins, so adding a repository renamed at the forge no longer commits a second row the holder's own validate-family.py refuses (#330) #381 landed as f0a8bf6 before this PR, and add refuses a member whose project.yaml records an id a row already pins, before it mounts anything. The merge placed _checked_member_id in cmd_add after the probe and before the dry-run return, so the dry run reaches the check through the same function as the real run, with the id the probe read. No code change was needed: the dry run already refuses it with member-duplicate-id, the same stdout and stderr and exit 2, the holder unchanged and no clone left. Only the _add_dry_run docstring now names the check. ADD_REFUSALS gains the row, last, in add's own order: the member is IRRS2, a bare copy of the pinned IRRS made beside the holder (never in the module's shared remotes), as f0a8bf6's own tests build it.
• family.py: add refuses a --member whose owner or project does not begin with a letter or a digit as member-malformed before the member is read, so testorg/_Zed, testorg/.Zed, testorg/-Zed, _org/Zed and .org/Zed no longer exit 0 with a commit that the holder's own validate-family.py fails as member-repository (#366) #399's member-malformed cases under --dry-run. The table had malformed and malformed-dot, and neither is family.py: add refuses a --member whose owner or project does not begin with a letter or a digit as member-malformed before the member is read, so testorg/_Zed, testorg/.Zed, testorg/-Zed, _org/Zed and .org/Zed no longer exit 0 with a commit that the holder's own validate-family.py fails as member-repository (#366) #399's rule: <org>/.. is refused by the directory-reference clause, which predates it. Five rows are added after malformed-dot: a project beginning with _, - and ., and an owner beginning with _ and ., each refused identically by the real run and the dry run. An owner beginning with - cannot be said as --member <owner>/<project> (argparse reads it as an option), so that spelling stays with the real run's test in test_family_member_name.py.

Tests: ADD_REFUSALS grows from 13 rows to 19. A set-up may return the directory of remotes the add is to read from; the others return None.

Mutants, each run on the parametrized refusal test over the malformed and duplicate-id rows (8 cases):

mutant	result	fails on
the dry run skips _checked_member_id (if probed_id is not None and not args.dry_run)	1 failed, 7 passed	[duplicate-id]: the dry run exits 0 and prints the row for IRRS2, the real run exits 2
the dry run takes --member without _checked_member	7 failed, 1 passed	every malformed* row, the five new ones included; [duplicate-id] passes
MEMBER_RE loosened to the pre-#399 class	5 failed, 3 passed	exactly the five new rows; malformed, malformed-dot and [duplicate-id] pass

Targeted set: tests/test_family_dry_run.py, test_family_add_refusals.py, test_family_add_member_id.py, test_family_member_name.py, test_family_member_path.py, test_family.py, test_cli_reference.py and test_agents_md_codes.py, on the bytes of head 1d82455 (sha256 of each file recorded first and re-checked): 352 passed in 331.72s (0:05:31), 0 failed, 0 skipped (Linux, git 2.43.0, CI's git-filter-repo pin).

Still open (N6, unchanged by this round): a linked project.yaml whose target records an id a row pins gets exit 0 from the dry run, and the real run refuses member-duplicate-id after the mount and unwinds. That is inside the module docstring's stated limit (what fails only once the mount is made is never reached by the dry run), and the linked note does not yet name this refusal.

Follow-ups (not in this PR)

• AGENTS.md: the family section should name add --dry-run, add --trailer, and part 1's two dry runs. This is held back by the line cap, as part 1 said.
• N4, one throwaway-clone helper: _add_dry_run's clone-and-delete repeats _probe_member's. _probe_member is left untouched because family.py: add refuses member-duplicate-id before it mounts anything when the member's project.yaml records an id a row already pins, so adding a repository renamed at the forge no longer commits a second row the holder's own validate-family.py refuses (#330) #381 changes its return and body.
  • Converge the two once family.py: add refuses member-duplicate-id before it mounts anything when the member's project.yaml records an id a row already pins, so adding a repository renamed at the forge no longer commits a second row the holder's own validate-family.py refuses (#330) #381 lands: the probe could return the id (as family.py: add refuses member-duplicate-id before it mounts anything when the member's project.yaml records an id a row already pins, so adding a repository renamed at the forge no longer commits a second row the holder's own validate-family.py refuses (#330) #381 makes it) and the digest, and the dry run could then read the member once. That also ends N2's race.
  • Share the sentence "Put back the copy git read first: git checkout -- .gitmodules (the index's), or git checkout HEAD -- .gitmodules". It is spelled in member-path-registered's remediation and again in the dry run's note.
• N1, add asks .gitmodules-off-the-work-tree itself: a named refusal in _checked_mount_path, asked by both runs before the probe's clone. At present the real run clones the member, prints mounting, and is then refused by git.

Closes #326

🤖 Generated with Claude Code

Summary by Sourcery

Enable family.py add to preview its complete pinning operation safely while adding commit trailer support and aligning member-name validation with holder checks.

New Features:

• Add family.py add --dry-run to preview the member pin, gitlink, .gitmodules entry, registration, storage location, row, and commit trailers without modifying the holder.
• Add repeatable --trailer support to family.py add and include trailers in dry-run previews and real commits.

Bug Fixes:

• Reject member names beginning with punctuation that the holder's own validation rules would reject, preventing invalid repository rows from being committed.

Enhancements:

• Ensure add dry runs preserve pre-mount refusal behavior and read members from temporary clones outside the holder.
• Document the expanded add command behavior and regenerate the CLI reference.
• Expand coverage for add previews, refusal parity, trailer handling, linked manifests, temporary-clone cleanup, and linked-worktree storage paths.

Documentation:

• Update the family CLI and module documentation to describe add dry runs, trailer support, and their limitations.

Tests:

• Add comprehensive tests covering add dry-run output, no-change guarantees, refusal parity, trailers, pinned commits, linked manifests, cleanup, and storage locations.
• Add tests enforcing consistent member-name validation across add and the repository validators.

[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 1 hour by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

Adds a fully read-only family.py add --dry-run that performs the same pre-write validation, reads the member from disposable external clones, and prints the exact prospective pin, manifest, gitlink, Git configuration, and trailers. It also adds repeatable --trailer support to real and dry-run adds, with extensive regression coverage and updated CLI documentation.

Sequence diagram for family add dry-run preview

sequenceDiagram
    participant User
    participant Add as family.py add
    participant Holder
    participant Probe as Probe clone
    participant Preview as Preview clone

    User->>Add: add --dry-run [--at] [--trailer]
    Add->>Holder: Validate add target
    Add->>Probe: Clone member and probe refusals
    Probe-->>Add: Resolved commit
    Add->>Preview: Clone member outside holder
    Preview-->>Add: Read project id and tree digest
    Add->>Holder: Check prospective git state
    Add-->>User: Print commit, digest, gitlink, .gitmodules, row, trailers
    Add-->>User: Exit 0 without mounting or writing

Loading

Sequence diagram for family add commit with trailers

sequenceDiagram
    participant User
    participant Add as family.py add
    participant Git
    participant Member
    participant Holder

    User->>Add: add [--at] [--trailer]
    Add->>Git: git submodule add
    Git->>Member: Clone and checkout member
    Member-->>Git: Mounted working tree
    Add->>Holder: Read member id and tree digest
    Add->>Git: _commit_one with row and trailers
    Git-->>Holder: Commit gitlink, .gitmodules, family.yaml
    Add-->>User: Exit 0

Loading

Flow diagram for add dry-run refusal boundary

flowchart TD
    A[family.py add --dry-run] --> B[Validate holder target]
    B --> C[Probe member clone]
    C --> D{Pre-write refusal?}
    D -->|Yes| E[Return same refusal and exit 2]
    D -->|No| F[Second disposable clone outside holder]
    F --> G[Read member id and tree digest]
    G --> H[Print prospective files, git state, row, and trailers]
    H --> I[Exit 0 with holder unchanged]

Loading

File-Level Changes

Change	Details	Files
Implemented a side-effect-free family.py add --dry-run that mirrors pre-mount validation and previews the member pin and all holder changes.	Routes execution to the dry-run path after holder and probe refusals, preserving refusal codes, ordering, and output. Reads the resolved member from a second bare clone in a temporary directory outside the holder, computes its ID and tree digest, and always cleans up. Prints the prospective commit, digest, gitlink, .gitmodules section, registration, module directory/store, manifest row, trailers, and notes for mount-only cases. Adds coverage for successful previews, first-member mounts, all pre-write refusals, --at, registrations, missing work-tree .gitmodules, linked manifests, cleanup, and no-write guarantees.	scripts/family.py tests/test_family_dry_run.py
Added repeatable commit trailer support to add and propagated trailers through the real mount-and-commit path and dry-run output.	Adds --trailer to the add parser using the same validation and ordering behavior as bump. Passes trailers into _mount_and_pin and verifies the real commit ends with the requested lines. Documents trailer behavior in generated CLI help.	scripts/family.py docs/cli.md tests/test_family_dry_run.py
Updated family command documentation to state that every subcommand supports dry runs and explain add's read-only behavior and mount-only refusals.	Updates the module exit-code and dry-run documentation, including linked manifests and .gitmodules caveats. Regenerates family.py add CLI reference with --trailer and --dry-run details. Updates refusal-test documentation to point to the new add dry-run coverage.	scripts/family.py docs/cli.md tests/test_family_add_refusals.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#326	Add a bump --dry-run that resolves --to, previews the row and digest it would write, and exits without checking out the member or modifying the holder.	✅
#326	Provide --dry-run for add and remove as well, so those operations can be previewed without modifying the holder.	✅

---

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
1.1% Duplication on New Code

See analysis details on SonarQube Cloud

[brettheap]

(lane openRepoShape-3, 2026-10-12T19:54:30Z) A v1.0.0 scope notice. Brett Heap scoped openRepoShape's first release today: every procedure in AGENTS.md works end to end for ordinary repositories on Linux, macOS and Windows. The tag waits for every in-scope issue to close and a full test run to pass on all three OSes on the release commit. This PR closes #326 (P2, parent #459): in scope, in the v1.0.0 milestone. Nothing changes in how it lands. Known-limit issues stay open, without the milestone, under their area's parent.