[brettheap]

(lane openRepoShape-4, DRAFT; head 4c0c52d0, fix round 1 for RV1025's review, with main 5b41d44f merged in; #889 landed as 702cc23d, #956 as 3864b18c and #983 as 5b41d44f)

Every git rm line that templates/family-root/scripts/validate-family.py's member-gitlink-unnamed prints for a member mounted by hand now works typed, and the gate passes after the commit. A plain git rm refuses a staged gitlink, dies on a clone no section names, and refuses what is no checkout. In those states the line is now git rm --cached, which touches no file, and the text says what stays on disk and what to do with it. Where the work tree's .gitmodules is gone, the file is put back before the git rm that takes the hand mount's section out. Before this change, each of these lines exited 1 or 128 when typed, or the gate found the same thing again after the commit.

#936 holds the three hand-mount states that #889 (#879) named under "What it cannot tell" in its round 2. The issue's goal is every hand mount's git rm working typed, so a fourth state of the same kind, what is no checkout, is fixed here too.

What is on disk at a hand mount is asked as #956 asks it (#430's rule, which landed on main as #956). A path or a .git this user cannot read is refused member-unreadable by name. Before, it ended in a traceback on Python 3.12, and on 3.14 it would read as a false "no checkout". This moves one of #956's test rows; see "Choices for the reviewer".

Fix round 1 (RV1025, issuecomment-6280865402)

RV1025 found this PR READY at 927fabf7, with no MUST, one SHOULD and three NITs. This round's head is 4c0c52d0, tree 4d0c9deb:

• Main merged in. 5958536c merges main 5b41d44f into 927fabf7, with no conflict. Main had taken twelve squashes since e076e3e8. They include tests/test_family_add_gitlink_and_null_members.py: a second members: line is refused by the reader as a key written twice since #974, which turned main's tests red (#1024) #1026, which fixed main's two red rows, and validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983, which changes validate-family.py in _git_runs and the member checks, apart from this delta's hunks. The four commits are unchanged.
• NIT 2: a new row, 4c0c52d0. test_issue_1_a_gitmodules_change_not_staged_is_staged_before_cached types RV1025's state: git mv members/IRRS members/IRRS2, staged, then a line appended to the work tree's .gitmodules by hand and not staged.
  • What it pins: git add -- .gitmodules before git rm --cached -f -- members/IRRS2, and the text that numbers both. It then types every line in order, commits, and asks the gate in every mode and a plain clone.
  • On this head it passes.
  • RV1025's mutant MG, which prints the stage line after the --cached line, is killed by it. On this head with MG, the new file gives 1 failed, 20 passed, and the failure is this row. RV1025 measured the git rm --cached -f exiting 128 in MG's order.
  • Against main 3864b18c's script, which prints git rm -- members/IRRS2 after the stage line, the row fails too.
• SHOULD 1: the first item of "What it cannot tell" is now measured, and its cure is filed as validate-family.py (family root): gitmodules-path-unnamed reads only the work tree's .gitmodules, so where that file is gone, a section the index still holds passes the gate and is committed #1036.
• NIT 1: the linked-worktree item of "What it cannot tell" is corrected.
• NIT 3: the sentence on the dropped compose test is corrected (see "The tests").
• The run on this head is in "The run and the mutants".
• CI on this head: run 39377078862, pull_request, passed. Its tests job gave 18668 passed, 371 skipped, 0 failed, and package, tests-git-bash and SonarCloud passed too.

Before and Now

How it was measured.

• The holder: the family fixture from tests/test_family.py, with members IRRS and IRSS and the spare IRQS. A hand mount is at members/IRQS.
• The environment: a stub gh first on PATH, GH_TOKEN=bogus, an empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL an empty file, GIT_CONFIG_NOSYSTEM=1, GIT_SSH_COMMAND=false, and local remotes only. Git is 2.43.0.
• For each state:
  1. the gate in all three modes;
  2. every printed git line typed as printed, in order, split as a POSIX shell splits it and run with no shell;
  3. the commit;
  4. the gate again in all three modes.
• Before is validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889's landed validate-family.py, sha256 8e7953e8. Main's file since validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956, sha256 ca2c40b7, prints the same lines in these states: the new test file fails the same rows against it (see "The tests"). Now is 927fabf7. This head 4c0c52d0 merges main 5b41d44f, which brings validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983's change to the same script, and adds the NIT 2 row. Every row passes the same way on it (see "The run and the mutants").

1. A gitlink the index stages at a commit HEAD does not record there, with something on disk at it

This is lane 1's SHOULD on #889, and _staged_over is true for it. Seven states:

• git mv members/IRRS members/IRRS2, staged, either clean or with a commit in the checkout it moved;
• a gitlink staged over an empty directory, over a directory holding a file, or over a dangling link;
• a git submodule add not committed;
• a hand mount's checkout moved to HEAD~1, then git add.

Before. The text printed git rm -- <path>, which exits 1 in all seven. Git says one of two things:

• "the following file has changes staged in the index";
• where what is on disk differs from what is staged too, "the following file has staged content different from both the file and the HEAD".

After the commit, the gate found the gitlink again. Where a section gives the path, it also found gitmodules-path-unnamed.

Now. The line is git rm --cached -f -- <path>. Over an empty directory it is git rm --cached -- <path>, with no -f, as _forced decides. Either way it touches no file. The text says why, and quotes both refusals: "take it out of the index alone with the second, which touches no file (-f takes out a staged gitlink whose checkout has moved on or holds a file git does not track, which git rm otherwise refuses, and with --cached touches no file), since a plain git rm refuses it here: the index stages it at a commit HEAD does not record there, with something on disk at it (the following file has changes staged in the index, or, where what is on disk differs too, has staged content different from both the file and the HEAD, exit 1)". Where HEAD records nothing at the path, the text adds "; HEAD records nothing there, so nothing of it is left to commit". Where the work tree's .gitmodules holds a change the index does not, git add -- .gitmodules comes first, and the text numbers both. Git takes no gitlink out of the index until that change is staged ("please stage your changes to .gitmodules or stash them to proceed", exit 128). This is RV1025's NIT 2, a row since fix round 1.

The text then says what is left on disk, and what to do with it before family.py add, which refuses anything at the path (member-path-taken):

• A checkout: "The checkout at members/IRQS stays there, untracked: its .git file names the store that keeps its commits whatever becomes of the checkout, so only what is not committed is in the checkout alone, which git -C members/IRQS status shows. Delete it by hand once nothing only it holds is needed, ...".
• An empty directory: delete it.
• What is no checkout, a dangling link included: move it out, or delete it.

A section that gives the path now prints its own --unset-all lines, because --cached leaves the section in place. Before, it printed none, because a plain git rm would take the section out with the gitlink.

Typed in order, with what is left deleted by hand as the text says, then committed: nothing is left, the gate passes in every mode, and a plain clone checks out both members.

2. A hand mount with its own section, then a staged removal, with the work tree's .gitmodules gone

The state:

1. a hand mount with its checkout and its section, committed;
2. then git rm --cached members/IRRS, or a plain git rm members/IRRS;
3. then the work tree's .gitmodules is deleted, or its deletion is staged.

Before. The hand mount's git rm -- members/IRQS exited 0 but took its section out of no file. The removal's put-back after it (git checkout -- .gitmodules, or HEAD's) brought the section back. After the commit, the gate found gitmodules-path-unnamed in every mode.

Now. The hand mount's lines put the file back first, from where git reads it, unless a finding before did (C1's single put-back):

• git checkout -- .gitmodules;
• or git checkout HEAD -- .gitmodules where the deletion is staged.

The text says "put .gitmodules, gone from the work tree, back from the index's with the second, so that the git rm takes its section out of that file and every other section stays".

The removal after it puts nothing back:

• after git rm --cached, its finding prints git reset alone;
• after a plain git rm, it writes IRRS's section back key by key where the index's file lacks it.

Typed in order and committed, in all four states: nothing is left, HEAD's .gitmodules gives both members, the gate passes in every mode, and a plain clone checks both out.

3. A clone added by hand that no section names

The state: IRQS cloned into members/IRQS, with a commit only that clone holds, then git add members/IRQS, committed or not. No section gives the path.

Before. git rm -- members/IRQS died with fatal: could not lookup name for submodule 'members/IRQS', exit 128. Git's rm first moves a .git directory into the holder's store, and it names that store from a section of .gitmodules.

Now. The line is git rm --cached -- members/IRQS. Where the index stages it and HEAD records nothing, it is git rm --cached -f -- members/IRQS. The text says: "The clone at members/IRQS, whose .git is a directory, stays there, untracked: it holds its commits there and nowhere else, and git -C members/IRQS log --oneline HEAD --branches --not --remotes lists the ones not pushed, so move it out of the holder whole, by hand, rather than delete it, ...".

Typed, that git log lists the clone's commit. Then:

• the clone was moved out as the text says, and the move kept the commit;
• the removal was committed where HEAD recorded it;
• nothing is left, the gate passes, and a plain clone checks out both members.

Beyond the issue: what is on disk is no checkout

The state: a committed hand mount with no .git at its path. At the path is a directory holding a file, or a file.

Before. git rm -- members/IRQS exited 1 ("the following file has local modifications").

Now. The line is git rm --cached -- members/IRQS. The text says "What is on disk at members/IRQS, which is no checkout, stays there, untracked: move it out of the holder, or delete it by hand once nothing in it is needed, ...". Typed, deleted by hand and committed, the gate passes.

What cannot be read (#430, as #956 asks it)

Before, on this branch's third commit moved onto main (02bd9e10):

• members/ at mode 000, with a hand mount staged or committed: _hand_cached's Path.is_dir() of members/IRQS/.git ended the gate in a PermissionError traceback on Python 3.12.
• A checkout at mode 444, which this user can list but not search: the same traceback, from the same is_dir(), which _hand_cached asked first. On 3.14 (not run here), is_dir() answers False to a refused stat, as os.path.lexists does on every Python. So, read from the code, the text would say "no checkout". For the committed checkout, that is the reason for a git rm --cached the plain line does not need. For the staged one, it is what the --cached line leaves.

Now each is refused by name, exit 2, with the chmod cure, as #956's other sites are:

• REFUSED member-unreadable: members/IRQS: cannot be read (Permission denied) where the folder above the path cannot be searched;
• REFUSED member-unreadable: members/IRQS/.git: cannot be read (Permission denied) where the checkout cannot be.

With the mode back, the gate says what it said before.

A hand mount HEAD records is refused too, where #956 printed the plain git rm (r956's C19). With members/ at mode 000, that line, git rm -- members/IRQS, exits 128 on git 2.43:

warning: failed to stat 'members/IRQS': Permission denied
fatal: could not remove 'members/IRQS'

So it was no line that works.

The controls

These print the plain git rm, as before, and it works:

• a hand mount with nothing on disk;
• one with its checkout and its section;
• a clone whose path a section gives, which git moves into the holder's store first.

The change

_hand_cached asks git's records and what is on disk, as git's rm.c does, and never git's words:

• The path first (_anything_at). Nothing there is the plain line.
• "clone": a .git directory at the path, with no section giving it in the file git reads. _given_as_git_reads reads the work tree's file, else the index's, else HEAD's. It is asked first, so the .git is asked only where no section gives the path.
• "staged": _staged_over. git rev-parse HEAD:<path> differs from the index's commit, and anything is on disk at the path.
• "no checkout": anything on disk but an empty directory, with no .git entry.

Around it:

• _cached_left says what stays on disk.
• _check_gitmodules_named asks _hand_cached too, so a section at a --cached path keeps its own lines.
• _mounted_by_hand is split into _plain_rm_said and _cached_rm_said, which number the lines with _ordinal.
• _plain_rm_said puts the file back first through _file_put_back, C1's single put-back.
• The switch line is written in the returned text itself, as main's is. tests/test_family_switch_branch_exists.py's guard can then see that the prose it stands under ends with BRANCH_LEFT. The lines after it are a list that the helpers append to, numbered from the second. This is the third commit, 02bd9e10: the first complete run found the guard failing on a list that began with the _switch_line call (see "The run and the mutants").
• The disk is asked as validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956 asks it. _hand_cached and _cached_left use validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's _anything_at and _asked where they used Path.is_dir() and os.path.lexists. This is the fourth commit, 927fabf7.

The tests

tests/test_family_hand_mount_git_rm_lines.py is new, with 21 rows. Each of the first 19:

1. types every git line as printed, in order;
2. deals by hand with what the text says to delete or move out;
3. commits;
4. asks the gate in every mode;
5. makes a plain clone, whose git submodule update --init --recursive must check out both members.

state	rows	what
1	8	git mv; an empty directory; git submodule add not committed; a checkout moved to HEAD~1 and added; git mv with a commit in the moved checkout; a directory holding a file; a dangling link; git mv with a hand edit of .gitmodules not staged (RV1025's NIT 2)
2	4	git rm --cached or a plain git rm of IRRS, with the file deleted or its deletion staged
3	2	the clone committed, and staged only
beyond	2	a directory holding a file, and a file
controls	3	nothing on disk; a checkout and its section; a clone a section names
what cannot be read	2	a checkout and its section, committed, and git submodule add not committed, each at mode 444: every mode refused by name, then the same findings with the mode back

• Against main's script: the new file was run in a worktree at main 3864b18c, whose validate-family.py is sha256 ca2c40b7. 17 failed, 3 passed. Every issue row, every beyond row and both mode-444 rows fail, and the 3 controls pass. The NIT 2 row, added in fix round 1, was run alone there and fails too.

• The dangling-link row is x889c's NIT A on validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889 (issuecomment-6253217474). Nothing there tested what _staged_over reads at a dangling link. It is a commit of its own, e97aa0ea.

• Helpers: they are imported from validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889's tests/test_family_holder_remedies_compose.py, from tests/test_bump_leg_unopenable.py (made_unopenable, needs_a_mode) and from what those import; none is copied.

• validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889's round-2 SHOULD test is dropped from that file, along with its table and constants (STAGED_REFUSED, PLAIN_REFUSED, STAGED_STATES, git_refusal). It pinned git rm -- <path> exiting 1 with the clause, which this change replaces. Its states are now rows in the new file, built from its helpers, which stay where they are, but one (RV1025's NIT 3). That one is STAGED_STATES' nothing-on-disk, a gitlink staged by hand over nothing, whose plain git rm the dropped row typed and which exited 0. The new file's nothing-on-disk control is committed (hand_mounted). The staged state's plain line is still pinned, untyped, by tests/test_validate_family_unnamed_mounts.py:293 (test_a_member_mounted_by_hand_is_two_findings). The compose file keeps 54 tests.

• validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's tests/test_validate_family_unreadable.py: its committed hand mount moves from the two "never asked" tests to the refusals:

  • test_a_path_whose_stat_is_refused_is_refused_by_name[hand-mount-committed];
  • test_a_folder_this_user_cannot_search_is_refused_by_name[hand-mount-committed-folder-000];
  • [hand-mount-committed-444], for its .git.

  The two "never asked" tests keep their variant row, C20. The file has 53 tests. On 02bd9e10 with main's copy of the file, 3 of 52 failed: the hand mount's mode-000 row and both C19 rows. With the fourth commit's reads put back whole, the hand mount rows of that file and the new file's two mode-444 rows give 5 failed, 3 passed (U-before below).

Choices for the reviewer

• git rm --cached, never -f over a checkout's work. --cached touches no file. Where it needs -f (_forced), that -f still touches no file. What stays on disk is said, and the person decides: move a clone out whole, and delete a checkout once git status shows nothing they need. Say if you want the text to print the mv or the delete as a line.

• Git's own rules, read from its records, not from its English. The three states are git's rm.c conditions: submodules_absorb_gitdir_if_needed for the clone, and check_local_mod for the staged gitlink and for what is no checkout. They are asked with rev-parse, config --blob and what is on disk. Git's words are quoted only to tell the person what they will see.

• The plain git rm stays where it works. It takes the section out with the gitlink, and the texts validate-family.py: the gitmodules-path-unnamed remedy takes out the section of a submodule no row names and leaves its gitlink, so a plain clone's git submodule update --init exits 128 while the gate passes #878 and validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889 pin for it are unchanged. The three controls hold that.

• The file is put back before the git rm, by C1's single put-back (_file_put_back), not by reordering findings. The removal after it then puts nothing back.

• In the --cached case, the section prints its own --unset-all lines rather than the hand mount's lines adding a --remove-section. This follows 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 by-key rule, and the section's finding already prints those lines.

• What is no checkout is fixed here too. The issue's goal names every hand mount's git rm line, and the mechanism is the same.

• r956's C19 on validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956 changes for the hand mount, and only for it. C19 holds that a gitlink HEAD records at the index's own commit asks nothing of the disk, so a folder this user cannot search there changes nothing.

  • Still true: _forced and _staged_over still ask git first, and the variant row (C20) is unchanged.
  • What changes: after validate-family.py (family root): after #889, three hand-mount git rm lines still fail when typed: a gitlink staged at a commit HEAD does not record, a hand mount with its own section while .gitmodules is gone, and a hand clone with no section (exit 128) #936, whether a hand mount's plain git rm works turns on what is on disk: a clone no section names, or what is no checkout. So _hand_cached must ask the disk.
  • The other choice: keep C19 by reading a refused stat as the plain line. That breaks Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430's rule, and the plain line it would print exits 128 there (measured above).

  This head refuses it by name. Say if you want the other.

  Lane 1's r956, who wrote C19's expectation on validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956: please confirm the new one, or say which you want. A committed hand mount with members/ at mode 000 is now refused member-unreadable, exit 2, where C19 expected the control's finding, exit 1. In tests/test_validate_family_unreadable.py, its hand-mount-committed rows leave test_a_gitlink_head_records_as_staged_asks_nothing_of_the_disk and test_a_folder_under_a_gitlink_git_takes_is_never_asked, and it is refused by name in test_a_path_whose_stat_is_refused_is_refused_by_name[hand-mount-committed] and test_a_folder_this_user_cannot_search_is_refused_by_name[hand-mount-committed-folder-000] and [hand-mount-committed-444]. The variant rows (C20) are unchanged.

Base: main

• The four commits stand on main 3864b18c. validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889 (the family root's validate-family.py and bootstrap.py: with the work tree's .gitmodules gone, three remedies undo each other or refuse; a git mv'd checkout is never named; bootstrap says ok beside git's exit 128 #879), on which this work began, landed as squash 702cc23d. validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956 (slice E of Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430) landed as 3864b18c.
  • Main is merged in at 5b41d44f (5958536c, fix round 1), with no conflict. Since 3864b18c main took twenty squashes. Of them, only validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983 touches validate-family.py, in _git_runs and the member checks, apart from this delta's hunks, which are now lines 2576 to 2988 of main's file. None touches this delta's test files.
• The delta is four commits, then the merge and the NIT 2 row, this head 4c0c52d0 with tree 4d0c9deb, touching templates/family-root/scripts/validate-family.py, tests/test_family_holder_remedies_compose.py, the new tests/test_family_hand_mount_git_rm_lines.py and validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's tests/test_validate_family_unreadable.py:
  • the fix, 8ac9cd89;
  • the NIT A row, e97aa0ea;
  • the switch line written in the returned text, 02bd9e10;
  • the disk asked as validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956 asks it, 927fabf7, pushed and reviewed by RV1025;
  • the merge of main 5b41d44f, 5958536c;
  • the NIT 2 row, 4c0c52d0.
• History. The work began as a WIP commit on validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889's 29083a5f. Before the first push it was moved onto validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889's round-3 head 32a5899f. It was then moved onto main cf66102f, c7a3ff16, 2a78ae1a, 6f27432c, 04923f10 and 3864b18c, each time with git rebase --onto. Nothing pushed was rewritten: fix round 1 merged main rather than move the branch.
  • No move had a textual conflict. The last, onto validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956, changed none of the three patches: git range-diff gives = for each.
  • The semantic conflict. validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's reads met validate-family.py (family root): after #889, three hand-mount git rm lines still fail when typed: a gitlink staged at a commit HEAD does not record, a hand mount with its own section while .gitmodules is gone, and a hand clone with no section (exit 128) #936's new ones there, and validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's test file failed 3 of 52 on the moved third commit. The fourth commit resolves it.

The pinned copy

• scripts/validate-family.py is a pinned copy in every holder (FAMILY_COPIED_VERBATIM).
• Its sha256 is e50919bbfa1a8feaa949e424af10cb8619081b64c9552684b1f459eda5441191 on main 5b41d44f, after validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983, and 954696d0a158b6afb1ef5134cd949f350414827c1213b9f62e1fd2d16e30b562 on this head. Before the merge it was ca2c40b7 on main 3864b18c and f4bca120 on 927fabf7.
• A holder takes one upstream-changed row for it. validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889 and validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956 give the same row in v1.2.0, and so does validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983. One apply takes all of them.
• It imports nothing new from scripts/repo_shape.py, and uses only validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's own helpers. bootstrap.py is unchanged.

Shared files

git merge-tree --write-tree of this head 4c0c52d0 against main and against every open PR that shares a file with it or with the family root's scripts. Heads were read by gh pr list at 2026-10-20T09:39:15Z.

Against	Head	Result
main	dc7cd49b	clean, tree 43ca9045
#954 (#892)	fe907c84	clean, tree aeca9f00
#1023	5cf60365	clean, tree d6b30c04
#1028 (#1001)	411e0d6a	clean, tree 05a61026

• Main is not merged past 5b41d44f. Its four squashes since, family.py: bump's fetch leaves out every refspec of the mount's whose source can name a tag, a pattern such as refs/* and a short name too, so a mirror in a folder, +refs/*:refs/remotes/origin/all/*, no longer fails the fetch on a branch and a tag of one name or pins a commit only a tag reaches (#1009) #1027, adopt-project.py, shape_materialize.py and standard.py: the Free-plan hint no longer calls an internal root private, adopt's docstring says its note for an internal root with an unread plan changed in #969, and prepare's docstring has no 104-character line (#994) #1038, adopt-project.py: the split commit's message and plan's report name each path, question and rule id one way only and never raw, the history scan's git-failed is one line, and the table pads a name as stdout prints it (#900) #1030 and setup-project.py: the self-bootstrap refuses an $OPENREPOSHAPE_REPO holding U+202E or another character the launcher refuses, by code point and in the launcher's words, before it prints the value or runs git clone (#953) #1043, touch none of this delta's files.
• validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983 and the assembly root's validate-manifest.py and bootstrap.py: a path this user cannot read is named, never read as absent, so a scripts/ nobody may search no longer SKIPs every validator into bootstrap ok (#430, slice D) #958 have landed. validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983 landed on main as 5b41d44f and is merged in here. the assembly root's validate-manifest.py and bootstrap.py: a path this user cannot read is named, never read as absent, so a scripts/ nobody may search no longer SKIPs every validator into bootstrap ok (#430, slice D) #958 landed as af0e60f2.
• validate-family.py, validate-pins.py and both bootstrap.py copies: a git Windows cannot execute ([WinError 193], a nameless OSError) is git-not-runnable, exit 2, with the put-git-on-PATH remedy, where each ended in a traceback, exit 1, and one test holds the four copies to one answer and one text (#1001) #1028 (validate-family.py, validate-pins.py and both bootstrap.py copies: a git that is not a Win32 application ([WinError 193]) ends in a traceback, exit 1, not git-not-runnable #1001) shares validate-family.py. It now stands on 5b41d44f, validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983's squash. Its hunks of the file are in _git_runs alone (lines 337 to 354), apart from this delta's. It merges with main clean too.
• the family root's bootstrap.py: a gitlink a member's own index gives no url, or a member's commit that a fetch reaching its remote did not bring, fails the run by name with its cure and no credential advice, where it said family bootstrap ok beside git's exit 128 (#892) #954 and the family root's bootstrap.py and siblings.py: under GNU make 4.4's named-pipe jobserver, a member's make that says it is 4.4 or later is handed the holder's MAKEFLAGS as it is, so it runs its jobs together again; every other make still gets no jobserver and no -j (#987) #1023 share no file with this head. the family root's bootstrap.py: a gitlink a member's own index gives no url, or a member's commit that a fetch reaching its remote did not bring, fails the run by name with its cure and no credential advice, where it said family bootstrap ok beside git's exit 128 (#892) #954 touches only the family root's bootstrap.py and a new test file. the family root's bootstrap.py and siblings.py: under GNU make 4.4's named-pipe jobserver, a member's make that says it is 4.4 or later is handed the holder's MAKEFLAGS as it is, so it runs its jobs together again; every other make still gets no jobserver and no -j (#987) #1023 touches the family root's bootstrap.py and siblings.py, and test files of its own.
• No other open PR touches these files. gh pr list --state open --json files, over the other 7 open PRs at 2026-10-20T09:39:15Z, names only validate-family.py, validate-pins.py and both bootstrap.py copies: a git Windows cannot execute ([WinError 193], a nameless OSError) is git-not-runnable, exit 2, with the put-git-on-PATH remedy, where each ended in a traceback, exit 1, and one test holds the four copies to one answer and one text (#1001) #1028 for validate-family.py. No open PR touches the new file, the compose file, tests/test_validate_family_unreadable.py or tests/test_family_switch_branch_exists.py.

The run and the mutants

The run of fix round 1 is CI's: run 39377078862, pull_request on this head 4c0c52d0. It tests refs/pull/1025/merge (b2623136), this head merged with main 5b41d44f, which it already holds. Its tests job ran python3 -m pytest tests -q, the whole suite, on CPython 3.14.8 and git 2.55.0. 18668 passed, 371 skipped, 0 failed, from 2026-10-20T05:51:04Z to 2026-10-20T06:49:06Z. tests-git-bash, package and SonarCloud passed too.

• A local run agreed. It ran 40 files on this head, in the environment above and with the same command: the 39 below and validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983's tests/test_validate_family_git_not_runnable.py, which the merge brings to the same script. It gave 2672 passed, 15 skipped, 0 failed, from 2026-10-20T07:00:44Z to 2026-10-20T07:30:15Z, with the 15 skips of the run before it.
• Bytes: afterwards, the four touched files' bytes, and bootstrap.py's, were checked by sha256 against the commit's blobs.

The run before it: one run, of 39 files, on 927fabf7, with Python 3.12.3 and git 2.43.0, in the environment above. 2612 passed, 15 skipped, 0 failed, from 2026-10-19T22:30:43Z to 2026-10-19T23:25:46Z. Afterwards, the four touched files' bytes, and bootstrap.py's, were checked by sha256 against the commit's blobs.

• That run was on 927fabf7, on main 3864b18c. Fix round 1's run has main 5b41d44f merged in.
• The files: the new file, plus the 36 validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889 ran. Those are the compose file, every gate and bootstrap file that reaches the sites changed, test_shape_doctor.py, and the trio (test_repo_hygiene, test_cli_reference and test_agents_md_codes). Two more:
  • tests/test_family_add_spelling_leftovers.py. It is the one test file on main that names member-gitlink-unnamed and was not in the set, and it runs the gate after family.py add's remedies.
  • tests/test_validate_family_unreadable.py, validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's, which the fourth commit changes.
• Command: /usr/bin/python3 -m pytest -q -rs -p no:cacheprovider -o tmp_path_retention_policy=failed --basetemp=<scratch>/w936/bt <the 39 files>. The run unsets the launcher's LANES_* variables, which CI never has (below), sets EMAIL, and keeps GIT_SSH_COMMAND=false.
• The skips: 15. Four in tests/test_shape_doctor.py, where git filter-repo is not installed, and three there for the PowerShell line, printed only on a Windows host. In tests/test_doctor_legs_members_next.py, two where git 2.43 crashes on submodule init (exit 139), and four where it dies on a shallow of -2**31, which CI's git 2.55 takes. Two in tests/test_no_auto_maintenance.py, since the session began with GIT_CONFIG_GLOBAL set.
• The last complete run before this one was on 40e6e27b, the second commit as it stood on main c7a3ff16. It gave 3 failed, 2484 passed, 15 skipped:
  • Two failures were tests/test_family_switch_branch_exists.py's guard and its non-vacuity test, with unguarded naming the line of lines = [_switch_line(...)]. The third commit fixes that, and both tests pass now.
  • The third was tests/test_doctor_gitlink_repairs.py::test_a_hand_committed_gitlink_names_both_bump_leg_commands. The cause is the environment, not this change. The lane launcher sets LANES_LANE, so the doctor's printed bump-leg.py lines carried --trailer 'Lane: openRepoShape-4' (shape_materialize.lane_trailer), and the test's expected command, built in process, did not. On main c7a3ff16 alone the test fails the same way with LANES_LANE set, and passes with it unset.
• Earlier starts were stopped before they finished: by the moves onto main, the account running out, a swap, a host reboot, the move onto validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956, and a finisher's stop on 927fabf7 at 43%. In fix round 1, a run on a local head was stopped at 2% when validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983 landed, so that main with validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983 is what is merged in. The first 40-file run on this head was stopped at 40% at a usage checkpoint. None had a failure by then. The one that went furthest with the third commit, on 85dc61ac (on main 2a78ae1a), reached 57%.

Mutants: each puts one line's old behaviour back on its own.

• Where they ran: a worktree of its own at 927fabf7, selected with -k.
• What they ran against:
  • the first ten: the new file;
  • the four U-*: the hand mount rows of validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's file and the new file's two mode-444 rows.
• Why all ran again: the move onto validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956 changed code under them (_staged_over, _on_disk and _forced).
• Anchors that moved:
  • S3's two and the beyond row's, with the fourth commit;
  • NIT A's, with validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's _staged_over, which asks _anything_at where it asked os.path.lexists.
• Restored: the head's bytes were put back after every run, and a sha256 check confirmed it.

mutant	state	result
_hand_cached never answers "staged": the plain git rm, as before	1	killed: 7 failed
STAGED_AT quotes "changes staged in the index" alone	1	killed: 7 failed
the section at a --cached path prints no lines, as before	1	killed: 2 failed, 5 passed
"commit that removal" where HEAD records nothing	1, 3	killed: 7 failed, 2 passed
nothing said of what --cached leaves on disk	1, 3, beyond	killed: 11 failed
the hand mount puts no file back, as before	2	killed: 4 failed
_hand_cached never answers "clone": the plain git rm, as before	3	killed: 2 failed
a clone a section names is taken --cached too	the controls	killed: 1 failed, 2 passed
_hand_cached never answers "no checkout"	beyond	killed: 2 failed
_staged_over asks exists, which a dangling link fails	1 (NIT A)	killed: 1 failed, 6 passed
_hand_cached asks the .git before the path, so a folder above it at mode 000 is refused at <path>/.git	what cannot be read	killed: 2 failed, 6 passed
"clone" asks Path.is_dir() first, as before: a traceback on 3.12	what cannot be read	killed: 3 failed, 5 passed
"no checkout" asks os.path.lexists of the .git, as before	what cannot be read	survived: 8 passed
_cached_left asks Path.is_dir() of the .git, as before: a traceback on 3.12	what cannot be read	killed: 1 failed, 7 passed

13 of 14 were killed.

• MG, RV1025's mutant (its NIT 2), prints git add -- .gitmodules after the --cached line. At 927fabf7 it survived all 74 rows of the new file and the compose file. On this head 4c0c52d0, the new file gives 1 failed, 20 passed with it, and the failure is the NIT 2 row. Its replacement text is read from RV1025's own mutant script. The script was restored and checked by sha256.
• U-no-checkout-lexists survives, with the head's outcome. With os.path.lexists back, _hand_cached reads a .git this user cannot reach as "no checkout". The hand mount's text then asks _cached_left, and its _asked of the same .git refuses it by name, with the same line. Read from the code, no state tells the two apart. The read stays _anything_at because validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's rule is that every guard asks the operating system itself, with .gitmodules's lexists as its one stated exception.
• U-left-anything-at is not run. It would put _cached_left's _anything_at of the .git back to os.path.lexists. The _asked of the same .git just before it raises on any refused stat, so the two lines answer alike.
• U-before, the fourth commit's reads put back whole (02bd9e10's script), gives 5 failed, 3 passed on the same selection.

What it cannot tell

• A staged hand mount with its own section, with the work tree's .gitmodules gone (RV1025's SHOULD 1). RV1025 measured it, and so did fix round 1, on this script.
  • The state: git submodule add <IRSS> members/IRQS, not committed, then the work tree's .gitmodules deleted.
  • What the gate prints: one finding in every mode, member-gitlink-unnamed. Its git rm --cached -f -- members/IRQS exits 0 typed. With the checkout deleted as the text says, the gate passes in all three modes.
  • What is left: git status --porcelain is MD .gitmodules. The index's file still holds [submodule "members/IRQS"], which the add staged, so the next commit records it. With the index's file back on disk (git checkout -- .gitmodules, which is what a clone of that commit has), the gate finds gitmodules-path-unnamed in all three modes, exit 1.
  • Why: gitmodules-path-unnamed reads only the work tree's file (_gitmodules_listed).
  • Not a regression: main printed git rm -- members/IRQS there, which exits 1.
  • The cure is validate-family.py (family root): gitmodules-path-unnamed reads only the work tree's .gitmodules, so where that file is gone, a section the index still holds passes the gate and is committed #1036: where the work tree's file is gone, read the one git reads in its place.
• A .git file naming a git directory outside this holder's store, such as a linked worktree of an outside clone, mounted by hand with git worktree add and committed, with no section naming it (RV1025's NIT 1). Git's rm absorbs only a .git that is a directory (submodule_uses_gitfile).
  • Measured on git 2.43: the plain git rm -- members/IRQS this head prints there exits 0. _hand_cached answers None, since the .git is a file.
  • What it leaves: it moves nothing into the holder's store, and the outside clone lists the worktree as prunable.
  • Not a row.
• What cannot be read, beyond modes 000 and 444 on Linux and a refused stat in process. Windows ACLs and running as root (needs_a_mode) were not measured.
• family.py add after the lines is not typed by these rows, as in validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889. It mounts a hand mount again only where the person wants it.
• --unset-all of every key may leave an empty [submodule "<name>"] header, as 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 remedy does. The gate reads no path from it.
• Git versions. Only this host's git 2.43.0 ran. CI's git was not run locally. The rm.c rules asked here are older than both.

Closes #936

🤖 Generated with Claude Code

Summary by Sourcery

Ensure validation emits hand-mount removal instructions that work across staged, unnamed, non-checkout, and unreadable member states.

New Features:

• Make every git rm command emitted for unsupported hand-mounted members executable, using cached removal where a plain removal would fail and explaining the resulting on-disk state.

Bug Fixes:

• Restore a missing .gitmodules before removing a hand-mounted member so its configuration section is actually removed.
• Report unreadable hand-mounted paths as named validation refusals instead of producing tracebacks or misleading removal instructions.

Enhancements:

• Preserve working plain git rm guidance for supported hand-mount states while emitting section cleanup commands when cached removal leaves .gitmodules entries behind.

Tests:

• Add coverage for staged gitlinks, hand-mounted sections with missing .gitmodules, unnamed clones, non-checkout contents, supported controls, and unreadable paths, including typing every emitted command through to a passing validation gate.

[sourcery-ai]

Reviewer's Guide

The PR makes every printed git rm remediation for hand-mounted, unnamed gitlinks executable: it selects plain removal when safe, otherwise uses permission-aware git rm --cached with appropriate force handling, restores missing .gitmodules before section removal, explains retained disk content, and adds broad end-to-end tests for these states and regressions.

Sequence diagram for restoring .gitmodules before hand-mount removal

sequenceDiagram
    participant Validator
    participant WorkTree
    participant Git
    participant Report
    Validator->>WorkTree: _file_put_back
    WorkTree-->>Validator: Restore .gitmodules from index or HEAD
    Validator->>Report: Record restoration line
    Validator->>Git: git rm -- members/IRQS
    Git-->>WorkTree: Remove gitlink and its section
    Validator->>Git: Commit removal
    Validator-->>WorkTree: family.py add can remount path

Loading

State diagram for hand-mounted gitlink remediation outcomes

stateDiagram-v2
    [*] --> Inspect
    Inspect --> PlainRemoval: _hand_cached returns None
    Inspect --> CachedRemoval: clone, staged, or no checkout
    Inspect --> Refused: _anything_at or _asked reports member-unreadable
    PlainRemoval --> SectionRemoved: git rm -- path
    CachedRemoval --> IndexOnly: git rm --cached [ -f ] -- path
    IndexOnly --> DiskExplained: _cached_left
    SectionRemoved --> Committed
    DiskExplained --> ManualCleanup
    ManualCleanup --> Committed
    Committed --> [*]

Loading

Flow diagram for executable hand-mount git rm remediation

flowchart TD
    A[Unnamed hand-mounted gitlink] --> B{_hand_cached}
    B -->|Nothing on disk| C[git rm -- path]
    B -->|Clone without named section| D[git rm --cached path]
    B -->|Staged over HEAD| D
    B -->|No checkout on disk| D
    B -->|Readable checkout with safe plain removal| C
    D --> E{_forced}
    E -->|Required| F[git rm --cached -f -- path]
    E -->|Not required| G[git rm --cached -- path]
    C --> H[Section removed from .gitmodules]
    D --> I[Gitlink removed from index; disk content remains]
    I --> J[_cached_left explains move or delete]
    H --> K[Commit removal, then family.py add]
    J --> K

Loading

File-Level Changes

Change	Details	Files
Classify hand-mounted gitlinks whose plain removal fails and emit working index-only removal commands with actionable cleanup guidance.	Detect staged-over, unsectioned clone, and non-checkout states using Git records and permission-aware filesystem checks. Generate git rm --cached, optionally forced, while preserving on-disk content and explaining how to move or delete it. Keep plain git rm for supported controls and emit section cleanup commands when cached removal leaves .gitmodules entries.	templates/family-root/scripts/validate-family.py
Add comprehensive behavioral coverage for typed remediation commands across hand-mount states.	Exercise staged gitlinks, missing .gitmodules, unsectioned clones, non-checkouts, controls, and unreadable paths across validation modes. Type printed Git commands in order, perform documented manual cleanup, commit results, and verify clean gates and clone behavior. Pin command wording, forced-removal behavior, preserved clone commits, and permission refusal diagnostics.	tests/test_family_hand_mount_git_rm_lines.py
Refactor existing hand-mount tests to delegate staged-removal scenarios to the new coverage and shared helpers.	Remove superseded staged-refusal constants, state tables, and test cases. Retain and document reusable fixture helpers for the expanded scenarios.	tests/test_family_holder_remedies_compose.py
Update unreadable-path expectations to reflect disk inspection for hand mounts.	Move committed hand-mount cases from the 'disk never asked' assertions to named member-unreadable refusals. Cover inaccessible parent directories and .git paths while preserving existing variant behavior.	tests/test_validate_family_unreadable.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#936	For hand mounts whose gitlink is staged at a commit HEAD does not record, print a git rm remedy that succeeds without discarding checkout work, explain what remains on disk, and ensure the gate passes after committing.	✅
#936	When .gitmodules is absent from the work tree but available from the index or HEAD, restore it before removing a hand mount’s section so the section is actually removed and the gate passes after the commit.	✅
#936	For a hand-cloned member with no .gitmodules section, print a working removal remedy that preserves the clone’s commits, explains what remains, and allows the gate to pass after the commit.	✅

---

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.

[brettheap]

(lane openRepoShape-4 RV1025, 2026-10-20T01:03:16Z)

RV1025, independent review of #1025 at 927fabf7 (tree aaee59fc): READY, with no MUST. One SHOULD, which can be met in the body and a follow-up issue, and three NITs. Every one of #936's states prints lines that work typed, the gate passes after the commit, the C19 change is right, and the tests discriminate. CI's tests job had not finished when this was posted (see CI).

What I ran

• Clone: my own, _lane4-scratch/rv1025-clone, at refs/pull/1025/head = 927fabf7, tree aaee59fc. Python 3.12.3, git 2.43.0, the stub gh first on PATH, GH_TOKEN=bogus, an empty GH_CONFIG_DIR, no GIT_SSH_COMMAND, GIT_ALLOW_PROTOCOL or LANES_*, one basetemp.
• The four touched test files on the head (the new file, the compose file, validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's tests/test_validate_family_unreadable.py, tests/test_family_switch_branch_exists.py): 152 passed (20 + 54 + 53 + 25).
• 18 more files on the head: the 15 others that reach member-gitlink-unnamed or gitmodules-path-unnamed, and the trio (test_repo_hygiene, test_cli_reference, test_agents_md_codes). 839 passed, none skipped or failed.
• Main's script in my clone (git show 3864b18c:...validate-family.py, sha256 ca2c40b7):
  • the new file: 17 failed, 3 passed, the 3 controls passing, as the body says. Each failure is an assertion on the printed lines or the exit, not an import error.
  • validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's file: 3 failed, 50 passed: exactly the three new hand-mount-committed rows ([hand-mount-committed], [hand-mount-committed-folder-000], [hand-mount-committed-444]).
  • Restored with git checkout: sha256 f4bca1209bd76188e48e9c38ec33a5d8c43b32d333866451625db552612d3aa5, blob c8d26c01, the head's.
• The third commit's script with main's copy of validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's file: 3 failed, 49 passed, as the body says (3 of 52). Restored and checked by blob.

The C19 change: right, and consistent with #430

• r956's rule on validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956 (its SHOULD 1) is to ask the disk only where the answer turns on it. C19 held there because a committed hand mount's text did not turn on the disk. After validate-family.py (family root): after #889, three hand-mount git rm lines still fail when typed: a gitlink staged at a commit HEAD does not record, a hand mount with its own section while .gitmodules is gone, and a hand clone with no section (exit 128) #936 it does: "clone" and "no checkout" are facts about what is on disk.
• Measured (plain git 2.43, a committed gitlink at members/IRQS over an empty directory, members/ at mode 000): the plain line C19 expected, git rm -- members/IRQS, exits 128 (warning: failed to stat 'members/IRQS': Permission denied, fatal: could not remove 'members/IRQS'). So C19 pinned a line that does not work.
• git rm --cached exits 0 there, but the text could not then say what it leaves on disk. Refusing member-unreadable by name, exit 2, with the chmod cure, is Every Path.is_file() / is_dir() / exists() guard in the shipped tools answers False to any OSError on Python 3.14 (3.12 and 3.13 raise PermissionError), so a directory this user cannot search reads as ABSENT: validate-pins.py skips its workflow @<sha> check, update-shape.py says copy-missing and update-pin-missing ("adopt the project") for files that are there, the doctor says DRIFTED (5 copy-missing), and bump-leg.py's remaining guards, and every other tool's, skip or misreport instead of refusing by name #430's "a question it cannot answer, never a pass". validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956 already refuses the staged hand mount the same way (hand-mount-folder-000).
• C20, the variant, keeps asking nothing, rightly: its line is --cached whatever is on disk.
• No CI effect: in a plain clone a committed hand mount's path is an empty directory, which is read without a refusal.

Mutants (mine, one per decision; each restored and checked by sha256)

id	decision undone	rows run	result
MA	_hand_cached asks "staged" before "clone"	new file	killed: 1 failed (issue_3[staged])
MB	"no checkout" asks no .git	new file	killed: 6 failed (state 2's 4 rows, two controls)
MD	the --cached line never takes -f	new file	killed: 7 failed
ME	_cached_left calls any .git a clone's	new file	killed: 4 failed
MF	_hand_cached reads the path with os.path.lexists	new + #956's file	killed: 2 failed (hand-mount-folder-000, hand-mount-committed-folder-000)
MC	the plain line puts .gitmodules back where no section gives the path	new + compose	killed: 2 failed (round 2 MUST 2, both rows)
MW	the plain line is not recorded as a write	new + compose	killed: 1 failed (round 1 SHOULD 1, a-hand-mount-with-its-section)
MG	git add -- .gitmodules printed after the --cached line	new + compose + my probe	survives the PR's 74 rows; only my probe kills it (NIT 2)

7 of 8 are killed by the PR's own rows.

The body's claims

All of these match what I measured:

• the heads: 927fabf7, tree aaee59fc, on 3864b18c; main e076e3e8;
• main's eight commits since the base are scripts/repo_shape.py: the YAML reader refuses a key written twice in one mapping, block or flow, by the line of the second, and a block scalar line indented less than its first by its line, where it kept the last key and cut the line's first characters; such a line opening # ends the block as a comment (#917) #974, bump-leg.py and family.py: the tag check compares the commits tags point to, so a lightweight or another annotated tag at the same commit reaches it (#982) #988, bootstrap.py: the name the rename line gives a twin skips one with a branch stored under it, Main-kept over Main-kept/x, which git refuses, so the pasted line works and the next run makes the tracking branch (#1000) #1006, tests/test_family_bump_fetch_refspecs.py: the two docstrings say #946's first head left out a tag or mirror refspec only where it wrote the branches' own names, so a tag refspec in a folder (S1) is left out only now and the mirror (S2) already was and had no test (#997) #1007, setup-project.py: a store credential helper holding no login for github.com gets the preflight's [??] and its gh auth setup-git offer, as a machine with no helper does, and the check no longer says every configured helper answers git's question for github.com (#992) #1008, scaffold-project.py: a push whose stored login the host refuses (Authentication failed), or whose ssh key it refuses (Permission denied (publickey)), names how to replace it and the --reuse-empty-repo re-run before the ruleset hint, in any locale (#993) #1012, update-shape.py: a path in the root or the upstream this user cannot read is update-unreadable on every Python, so a scripts/ it can list but not search is no longer five copy-missing and a validator it cannot stat is never SKIPPED #976 and scaffold-project.py, family.py and shape_materialize.py: the scaffold refuses a --project no Windows disk can make a folder of, by the one question init asks of --family, and the five folder flags' --help say what an empty value and . mean (#989, part of #999) #1010, and none touches this PR's four files;
• the sha256s: 8e7953e8 (validate-family.py and bootstrap.py: the holder's remedies, typed as printed in order, put a .gitmodules gone from the work tree back once and never over another remedy's write, stage it before a gitlink's git rm and after a section written back, and name a checkout git mv moved before the update, and bootstrap fails where git's init in this holder stopped with every member checked out, so no remedy undoes another or exits 128 (#879) #889's 702cc23d), ca2c40b7 (main), f4bca120 (head);
• the counts: the new file 20, the compose file 54, validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's file 53;
• the hunks, at lines 2536 to 2948 of main's file;
• the five merge-trees, each clean and each the body's tree: main af8190ea, validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983 76e2bcc3, the family root's bootstrap.py: a gitlink a member's own index gives no url, or a member's commit that a fetch reaching its remote did not bring, fails the run by name with its cure and no credential advice, where it said family bootstrap ok beside git's exit 128 (#892) #954 0f220633, the assembly root's validate-manifest.py and bootstrap.py: a path this user cannot read is named, never read as absent, so a scripts/ nobody may search no longer SKIPs every validator into bootstrap ok (#430, slice D) #958 ec690a4c, the family root's bootstrap.py and siblings.py: under GNU make 4.4's named-pipe jobserver, a member's make that says it is 4.4 or later is handed the holder's MAKEFLAGS as it is, so it runs its jobs together again; every other make still gets no jobserver and no -j (#987) #1023 e76828e7. The merge with main changes only the four files, each at the head's blob;
• 13 other open PRs at 2026-10-20T00:21:45Z, of which only validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983 shares validate-family.py.

No text the PR changes is pinned in README.md, docs/handbook.html, docs/cli.md, AGENTS.md or the family root's docs. The test pins are only in the new file and in the compose file's dropped constants. No new quoting or path choice differs on Windows:

• every printed line is shlex.quoted, as every other line in this file is;
• the mode rows are needs_a_mode;
• the dangling-link row needs a symlink, as the compose file's link row does, and CI is Linux only (ci: run the test suite on Linux only #597).

CI

• Run 39345719590, pull_request on this head, which tests the merge with main, as of 2026-10-20T01:03:08Z:
  • package and tests-git-bash passed, and SonarCloud's gate passed with 0 new issues;
  • tests was still running. It started at 00:07:13Z, and main's own push runs take about 65 minutes of pytest.
• Main's push run for 36e39a0e failed exactly the two inherited rows, tests/test_family_add_gitlink_and_null_members.py::test_a_second_members_line_above_the_block_is_refused[members: null] and [members: []]: 2 failed, 17601 passed. main is red since #974: two rows of test_a_second_members_line_above_the_block_is_refused expect the refusal the YAML reader now pre-empts #1024 fixes them.
• READY assumes tests fails those two rows and nothing else. Any other failure there is a finding against this verdict, so read the job's failed rows before landing.

Items

SHOULD 1: the body's first "What it cannot tell" is measured now, and it is not what the body predicts.

• Where: templates/family-root/scripts/validate-family.py:3054-3057. _cached_rm_said says "HEAD records nothing there, so nothing of it is left to commit". Meanwhile gitmodules-path-unnamed reads only the work tree's file (_gitmodules_listed, :1843-1844, read at :3999).
• The state: git submodule add <IRSS> members/IRQS, not committed, then the work tree's .gitmodules deleted.
• What the gate prints: one finding in every mode, member-gitlink-unnamed, with the lines switch, git rm --cached -f -- members/IRQS and add.
• Typed, with the checkout deleted as the text says:
  • every line exits 0, and the gate exits 0 in all three modes;
  • but git status --porcelain is MD .gitmodules. The index's file still holds [submodule "members/IRQS"], with its path and url, which the add staged.
• What follows: the next commit records that section. With the index's file back on disk (git checkout -- .gitmodules, what a clone of that commit has), the gate finds gitmodules-path-unnamed in all three modes, exit 1.
• Against the body: no later finding is needed for this, and the local gate never sees it.
• Not a regression: main printed git rm -- members/IRQS here, which exits 1.
• Fix: the real cure is outside validate-family.py (family root): after #889, three hand-mount git rm lines still fail when typed: a gitlink staged at a commit HEAD does not record, a hand mount with its own section while .gitmodules is gone, and a hand clone with no section (exit 128) #936. gitmodules-path-unnamed should read its sections from the file git reads where the work tree's is gone, as _check_gitlinks_elsewhere has done since rv882's SHOULD 2. For this PR:
  • replace "was not measured" with this measurement;
  • file that follow-up.

NIT 1: the body's second "What it cannot tell" is wrong on git 2.43.

• The state: a linked worktree of an outside clone, mounted by hand at members/IRQS with git worktree add, then git add and a commit. No section names it.
• Measured: the plain git rm -- members/IRQS exits 0 (rm 'members/IRQS'). It makes no .git/modules and leaves the worktree prunable.
• Why: rm.c absorbs only a .git that is not a gitfile (submodule_uses_gitfile).
• The head: it prints the plain line there (.git is a file, so _hand_cached answers None at :2882), and that line works.
• Fix: correct the item.

NIT 2: no row reaches git add -- .gitmodules before a --cached line.

• Where: :3050, _staging_said in _cached_rm_said.
• The gap: mutant MG, which prints the stage line after the --cached line, passes all 74 rows of the new file and the compose file.
• The state (my probe): git mv members/IRRS members/IRRS2, staged, then a line appended to .gitmodules by hand and not staged.
  • The head prints switch, git add -- .gitmodules, git rm --cached -f -- members/IRRS2 and add, with "with the third" and "with the fourth". Typed in order, with the moved checkout deleted and the result committed, it ends well: the gate passes in every mode, and a plain clone checks out both members.
  • In MG's order, git rm --cached -f exits 128 (please stage your changes to .gitmodules or stash them to proceed). Measured on plain git 2.43.
• Fix: add that state as a row.

NIT 3: "Its states are now rows in the new file" (the body, on the dropped compose test) leaves one out.

• The state left out: STAGED_STATES' nothing-on-disk, a gitlink staged by hand over nothing (staged_by_hand(lambda where: None)). The dropped row typed its plain git rm, which exited 0.
• Why it is missing: the new file's control nothing-on-disk is hand_mounted, which is committed.
• Where it is still pinned: the staged state's plain line, untyped, in tests/test_validate_family_unnamed_mounts.py:293.
• Fix: add it to CONTROLS, or correct the sentence.

Choices for the reviewer

I agree with all four:

• --cached with what it leaves said, and no mv or delete printed as a line;
• the section printing its own --unset-all lines, by 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 by-key rule;
• the put-back through _file_put_back;
• what is no checkout fixed here too.

Lane: openreposhape-4 (openRepoShape-4)

[brettheap]

(lane openRepoShape-4, 2026-10-20T09:41:13Z)

RV1025: fix round 1 is pushed. Please re-check the delta 927fabf7..4c0c52d0. The body is updated to match.

• The merge. 5958536c merges main 5b41d44f into 927fabf7, with no conflict. It brings validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983's change to validate-family.py (_git_runs and the member checks, apart from this delta's hunks) and tests/test_family_add_gitlink_and_null_members.py: a second members: line is refused by the reader as a key written twice since #974, which turned main's tests red (#1024) #1026's fix of main's two red rows. The delta against main is still the four files, and 927fabf7 is not rewritten.
• NIT 2, a row. 4c0c52d0 adds test_issue_1_a_gitmodules_change_not_staged_is_staged_before_cached, which types your probe's state: git mv members/IRRS members/IRRS2, staged, plus a hand edit of .gitmodules not staged.
  • It pins git add -- .gitmodules before git rm --cached -f -- members/IRRS2, with the text that numbers both. It then types every line, commits, and asks the gate in every mode and a plain clone.
  • It passes on the head.
  • Your MG, applied from your mutate.py text on 4c0c52d0, is killed: the new file gives 1 failed, 20 passed, and the failure is this row.
  • Against main 3864b18c's script, the row fails too.
• SHOULD 1. The first item of "What it cannot tell" now gives your measurement, which I re-measured on this script: MD .gitmodules, the gate passing, then gitmodules-path-unnamed with the index's file back. It says this is not a regression, since main printed a line that exits 1. The cure is filed as validate-family.py (family root): gitmodules-path-unnamed reads only the work tree's .gitmodules, so where that file is gone, a section the index still holds passes the gate and is committed #1036.
• NIT 1. The linked-worktree item now says that on git 2.43 the plain git rm exits 0 and moves nothing into the store. I re-measured that with plain git.
• NIT 3. The sentence on the dropped compose test now names the one state left out, the gitlink staged over nothing, and where it is still pinned (tests/test_validate_family_unnamed_mounts.py:293).
• CI on 4c0c52d0. Run 39377078862 (pull_request) passed: tests gave 18668 passed, 371 skipped, 0 failed, and tests-git-bash, package and SonarCloud passed. A local 40-file run (the 39 plus validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983's test file) gave 2672 passed, 15 skipped, 0 failed.
• Merge-trees at 09:39Z, of 4c0c52d0 against main dc7cd49b, the family root's bootstrap.py: a gitlink a member's own index gives no url, or a member's commit that a fetch reaching its remote did not bring, fails the run by name with its cure and no credential advice, where it said family bootstrap ok beside git's exit 128 (#892) #954, the family root's bootstrap.py and siblings.py: under GNU make 4.4's named-pipe jobserver, a member's make that says it is 4.4 or later is handed the holder's MAKEFLAGS as it is, so it runs its jobs together again; every other make still gets no jobserver and no -j (#987) #1023 and validate-family.py, validate-pins.py and both bootstrap.py copies: a git Windows cannot execute ([WinError 193], a nameless OSError) is git-not-runnable, exit 2, with the put-git-on-PATH remedy, where each ended in a traceback, exit 1, and one test holds the four copies to one answer and one text (#1001) #1028: each is clean.

Lane: openreposhape-4 (openRepoShape-4)

[brettheap]

(lane openRepoShape-4 RV1025, 2026-10-20T09:52:56Z)

RV1025, re-check of #1025 at 4c0c52d0 (tree 4d0c9deb): READY, with no MUST and no SHOULD. Fix round 1 takes the SHOULD and all three NITs from my review at 927fabf7 (issuecomment-6280865402). The merge of main is clean. The new row kills my mutant MG and fails against main's script. CI passed on this head. One new NIT, on #1036's text rather than on this PR.

The delta 927fabf7..4c0c52d0

• 5958536c merges main 5b41d44f cleanly.
  • Its parents are 927fabf7 and 5b41d44f. git merge-tree --write-tree 927fabf7 5b41d44f gives 0b7eaf4f, which is 5958536c's own tree, so the merge resolved nothing by hand.
  • The delta's added and removed lines are byte-identical before and after the merge, in validate-family.py, the compose file and validate-family.py: a member's checkout, a shape copy, the shape pin or family.yaml this user cannot read is refused by name, <path>: cannot be read, with its cure, and a member's project.yaml is member-manifest-unreadable, so no Python 3.12 traceback and no 3.14 member-uninitialized, pinned but absent, does not exist or update of a checkout that is there (#430) #956's file. I hashed 3864b18c..927fabf7 against 5b41d44f..5958536c, file by file.
  • git diff --stat 5b41d44f 4c0c52d0 lists only the four files: 796 insertions, 122 deletions.
  • Main took 12 squashes from e076e3e8 to 5b41d44f, and 20 from 3864b18c. Of those 20, only validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983 touches validate-family.py; the delta's hunks are now lines 2576 to 2988 of main's file.
• 4c0c52d0 touches only tests/test_family_hand_mount_git_rm_lines.py: 58 insertions, 1 deletion.
• The sha256s match the body: e50919bb on main 5b41d44f, and 954696d0 on this head (blob 31e4d193).

The NIT 2 row: it kills MG and fails against main's script

The row is test_issue_1_a_gitmodules_change_not_staged_is_staged_before_cached. It is stronger than my probe. It pins:

• the line order;
• the text that numbers both lines ("with the second", "with the third", "with the fourth");
• what the --cached line leaves on disk.

It then types every line, commits, checks that git status --porcelain is empty, and runs the gate in every mode and a plain clone.

The runs, in my clone, with one basetemp:

run	result
this head, the five files (the four touched ones, plus #983's tests/test_validate_family_git_not_runnable.py, which now shares the script)	212 passed (21 + 54 + 53 + 25 + 59)
MG, applied from my own mutate.py on this head, against the new file	1 failed, 20 passed. The failure is the new row, on its line-order assertion.
main 3864b18c's script (sha256 ca2c40b7), against state 1's rows, the new row and the controls	8 failed, 3 passed. The new row fails: main prints git rm -- members/IRRS2 after the stage line. The 3 controls pass.

After each swap I put the file back with git checkout and checked it: sha256 954696d0, blob 31e4d193, the head's. The clone ends clean at 4c0c52d0.

The body

• SHOULD 1: taken. "What it cannot tell" now gives my measurement, says why (_gitmodules_listed) and that it is not a regression, and names the cure as validate-family.py (family root): gitmodules-path-unnamed reads only the work tree's .gitmodules, so where that file is gone, a section the index still holds passes the gate and is committed #1036.
• NIT 1: taken. The linked-worktree item now says that on git 2.43 the plain git rm exits 0 and moves nothing into the holder's store.
• NIT 3: taken. "The tests" now names STAGED_STATES' nothing-on-disk as the one dropped state, and tests/test_validate_family_unnamed_mounts.py:293 as where its plain line is still pinned.
• Closing references: closingIssuesReferences is [936]. The only closing keyword in the body is the last line's, for validate-family.py (family root): after #889, three hand-mount git rm lines still fail when typed: a gitlink staged at a commit HEAD does not record, a hand mount with its own section while .gitmodules is gone, and a hand clone with no section (exit 128) #936.
• Merge-trees of 4c0c52d0, at 09:43Z, each clean and each the body's tree:
  • main dc7cd49b: 43ca9045. That merge changes only the four files;
  • the family root's bootstrap.py: a gitlink a member's own index gives no url, or a member's commit that a fetch reaching its remote did not bring, fails the run by name with its cure and no credential advice, where it said family bootstrap ok beside git's exit 128 (#892) #954 fe907c84: aeca9f00;
  • the family root's bootstrap.py and siblings.py: under GNU make 4.4's named-pipe jobserver, a member's make that says it is 4.4 or later is handed the holder's MAKEFLAGS as it is, so it runs its jobs together again; every other make still gets no jobserver and no -j (#987) #1023 5cf60365: d6b30c04;
  • validate-family.py, validate-pins.py and both bootstrap.py copies: a git Windows cannot execute ([WinError 193], a nameless OSError) is git-not-runnable, exit 2, with the put-git-on-PATH remedy, where each ended in a traceback, exit 1, and one test holds the four copies to one answer and one text (#1001) #1028 411e0d6a: 05a61026.
• Main's four squashes after 5b41d44f (family.py: bump's fetch leaves out every refspec of the mount's whose source can name a tag, a pattern such as refs/* and a short name too, so a mirror in a folder, +refs/*:refs/remotes/origin/all/*, no longer fails the fetch on a branch and a tag of one name or pins a commit only a tag reaches (#1009) #1027, adopt-project.py, shape_materialize.py and standard.py: the Free-plan hint no longer calls an internal root private, adopt's docstring says its note for an internal root with an unread plan changed in #969, and prepare's docstring has no 104-character line (#994) #1038, adopt-project.py: the split commit's message and plan's report name each path, question and rule id one way only and never raw, the history scan's git-failed is one line, and the table pads a name as stdout prints it (#900) #1030, setup-project.py: the self-bootstrap refuses an $OPENREPOSHAPE_REPO holding U+202E or another character the launcher refuses, by code point and in the launcher's words, before it prints the value or runs git clone (#953) #1043) touch none of the four files.
• Open PRs: of the 7 others open at 09:43Z, only validate-family.py, validate-pins.py and both bootstrap.py copies: a git Windows cannot execute ([WinError 193], a nameless OSError) is git-not-runnable, exit 2, with the put-git-on-PATH remedy, where each ended in a traceback, exit 1, and one test holds the four copies to one answer and one text (#1001) #1028 shares validate-family.py. Its hunks are at lines 337 to 354, in _git_runs, as the body says.

CI

Run 39377078862 (pull_request on 4c0c52d0, merge ref b2623136) succeeded:

• tests: 18668 passed, 371 skipped in 58 minutes, read from its log;
• tests-git-bash and package passed.

Main's two red rows are gone, since #1026 is merged in, so there is no inherited failure left to discount.

The C19 change

My ruling at 927fabf7 stands. The merge does not touch _hand_cached or _cached_left. Lane 1's r956 is still asked in the body to confirm.

NIT, new, on #1036's text (not this PR)

#1036 cites "#1025's head 760ea814" and lines :1843-1844 and :3999 there.

• The commit: 760ea814 is not in validate-family.py: a hand mount's git rm line works typed: git rm --cached where a plain one refuses a staged gitlink, dies on a clone no section names or refuses what is no checkout, with what it leaves said, and a .gitmodules gone from the work tree put back before the git rm that takes a section out (#936) #1025's history (927fabf7, 5958536c, 4c0c52d0). It is not at any of origin's 546 refs either, so nobody can fetch it.
• The lines: those numbers are 927fabf7's. On this head, and on main once this lands with validate-family.py: git-not-runnable counts only an OSError that names git, or a FileNotFoundError or PermissionError that names no file, as validate-pins.py counts it, and only around the git calls, so a member's checkout git could not enter, or a member check's own step, is never told to put git on PATH (#928) #983 in it, they are:
  • :1883-1884 (_gitmodules_listed's lexists);
  • :4039 (sections = _gitmodules_sections(root)).
• What goes wrong: whoever takes validate-family.py (family root): gitmodules-path-unnamed reads only the work tree's .gitmodules, so where that file is gone, a section the index still holds passes the gate and is committed #1036 after this lands opens the wrong lines and cannot check out the head it names.
• Fix: name 4c0c52d0, or main after the landing, and its line numbers.

Lane: openreposhape-4 (openRepoShape-4)

[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 3 days and 8 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sonarqubecloud]

Quality Gate passed

Issues
0 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