[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #685 (comment)

Stacked on #670 (fix/646-add-member-variant-remedy, a837a023); retarget to main once #670 lands. Once #670 squash-lands, this branch conflicts with main in scripts/family.py, tests/test_family_add_member_variant.py and tests/test_family_members_case_variants.py, as any stacked PR does. Resolve it by the stacked-PR procedure: merge #670's final head, then main, taking this head's side for #670's files. Predicted at bbb961f: #670's squash onto main bf1f099 (scratch commit e8938e8c) conflicts with this head in those three files, and merge-tree -X ours resolves it to tree 760eeb70, the tree of this head merged with main.

Goal (#685): every command an add refusal prints can be typed as printed, with the arguments it needs, in the state it describes, on the git the estate supports. The issue's three #574 lines are all in _spellings_refusal, which #670 rewrote. Line 1 changes the remedy, line 3 changes two sentences, and line 2 is closed by a test, with no change to its remedy.

Line 1: git mv members Members, staged or committed

What was wrong

git mv members Members renames each member's checkout, its gitlink and its section of .gitmodules (path = Members/IRRS). It also points each gitdir's core.worktree at Members/IRRS. Measured on git 2.43.

The issue saw #574's generic git mv -- Members/IRRS <new name> on main. On #670's base, both gitlinks are members' own gitlinks (the index holds nothing at members/IRRS or members/IRSS), so add prints #646's move back instead. That move puts each gitlink back at members/<P> in the index alone, and leaves each section naming Members/<P>. Typed as printed ($Q/v114/w685/probes/line1.out, at a837a02):

• staged: git submodule update --init --recursive fails, fatal: No url found for submodule path 'members/IRRS' in .gitmodules; the gate refuses member-uninitialized, exit 2;
• committed: the same failure; the gate exits 1 with gitmodules-path-unnamed in every mode;
• a fresh recursive clone of the committed state: git submodule update checks nothing out at members/IRRS, and the gate exits 1 with gitmodules-path-unnamed.

This is #670's checklist candidate (e), for a whole members/ renamed with git.

What changed (scripts/family.py)

• A new remedy, RENAME_BACK, placed in REMEDY_ORDER after the index's own remedies and before the move back. It renames the spelling back in two steps through a free name:

  git mv -- Members members.renaming
  git mv -- members.renaming members
  

  and commits, where a commit is left to make.

• The free name (_free_name) is members.renaming, or the first of members.renaming-2, -3 and on, that no index entry is at or under (asked in any case) and that the disk does not hold (asked as the disk resolves a name).

• _renamed_with_git says when it applies. Every one of these must hold:

  • the index holds nothing at or under members itself (a file members included);
  • everything the index holds under another spelling is under ONE spelling;
  • none of it is a case variant of the mount path;
  • some of it is a member's own gitlink (family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's test);
  • HEAD holds no member's gitlink under another spelling that the index no longer does;
  • no members/ is on this disk, or the one there is that spelling's own directory (samefile), as on macOS and Windows;
  • neither that spelling nor members is a link, which is never members/ itself (_members_dir_on_disk's own rule; rv685's MUST-B and SHOULD-A);
  • every entry under the spelling is at stage 0, and none is kept off disk by a sparse checkout;
  • every entry under the spelling is on disk as the index holds it (a gitlink as a directory, anything else not), as the disk resolves the name, or can be put back first.

• Putting back what the disk lacks (rv685's MUST-2, direction (b)). git mv of a directory says bad source for any entry under it that is not on disk. So before the two steps the text says to put each such entry back:

  • a file: git checkout -- <file>;
  • a gitlink: git submodule update --init --recursive -- <path>, where a section of .gitmodules with a url gives that path. After git mv members Members the sections name Members/<P>, so this types clean.
  • Where a missing gitlink has no such section, or the disk holds a path in a form the index does not (a file where a checkout was, a directory where a file is), nothing is renamed back. The move back is printed, as before (direction (a)).

• The work tree's .gitmodules comes first (rv685's SHOULD-1, then MUST-A). Wherever the index holds a gitlink the refusal names, _checked_mount_path asks _gitmodules_beside, which tells the copy apart as gitmodules-unstaged tells it:

  • modified (the index holds it at stage 0, the work tree has a copy, and git ls-files -m lists it): the text says first to stage it, or set it aside (git add -- .gitmodules). git mv and git rm of a gitlink refuse to run beside such a change (Please stage your changes to .gitmodules or stash them to proceed), and family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's move back died there too.
  • missing (stage 0, no work-tree copy): the text says first to put back the index's copy (git checkout -- .gitmodules). git mv rewrites a moved member's section only in the work tree's copy, and a git add would stage the deletion, which the printed commit would then take out of HEAD with every section.
  • unmerged (any stage other than 0): gitmodules-unstaged is raised first, with its own restore ("resolve the conflict in it and stage the result, git add .gitmodules"), since a git add would stage the conflict markers and git mv then says bad config line. Only this state moves a refusal, and only beside a gitlink.
  • nothing: no copy in the index, one a sparse checkout keeps off disk (gitmodules-sparse's), or one as the index holds it.

• What the disk holds under the spelling goes back with it, so it is not named as untracked.

The refusal's text for the staged state:

REFUSED family-members-dir-variant: the family root holds a path at or under another spelling of members/, which a case-insensitive disk takes for members/ itself — in the index: `Members/IRRS` (a submodule), `Members/IRSS` (a submodule)
Remediation: every member is mounted under members/, and a holder keeps that directory in one spelling on every disk. Rename `Members` back to members/, since it holds the gitlinks of members whose rows place them under members/, in two steps through a name nothing holds, as macOS and Windows take `Members` for members/ itself: `git mv` takes each checkout, and each section of .gitmodules that names it, with it (`git mv -- Members members.renaming`, then `git mv -- members.renaming members`); then re-run.

With one checkout gone, the part begins: "Put back what the index holds under Members and the disk does not, git submodule update --init --recursive -- Members/IRSS, then rename …".

The code stays family-members-dir-variant. Only the remedy changes.

Why two steps, and not git mv -- Members members or mkdir members with a git mv per member

All three were probed on Linux, staged and committed, and the first two in a fresh recursive clone too. Each typed clean, and left .gitmodules and core.worktree at members/, the gate passing in every mode, and add going through (probes/test_w685_line1.py; rv685's two-step.txt).

• On a disk that folds case, only the two steps can work. From reading git v2.43.0's builtin/mv.c (not run: this host is case-sensitive):
  • git mv -- Members members takes members for an existing directory, makes the destination members/Members, and asks the disk to rename a directory into itself, which it refuses.
  • git mv -- Members/IRRS members/IRRS makes the destination members/IRRS/IRRS, and mkdir members fails with File exists.
  • In the two steps, neither destination exists when its step runs.
• So one text serves every disk for the renamed state, and the folding disk no longer gets family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's move back with its section gap. That closes the first head's checklist candidate (e′) wherever this text is printed. family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's own state is not one text: with every member's gitlink moved in the index alone and the checkouts at members/, Linux gets the move back (Members is not on its disk), and the folding emulation gets the two steps, where git mv warns Could not find section in .gitmodules and ends right (from reading the source; rv685's NIT 1). test_every_disk_gets_the_same_rename_back asks the same layout of both disks in process (disk_as). test_a_folding_disk_that_received_it_renames_it_back asks the state a pull leaves there: the index at Members/, the directory spelled members. A folding disk gets the two steps; Linux gets the move back, since Members is not on its disk at all.
• The per-member moves are the git mv to the row's path that family.py: add's refusal of a member's own gitlink held only under another spelling of its row's path moves it back to that path in the index alone, so the printed remedy no longer takes the member's gitlink away from its row (#646) #670 set aside. They also left an empty Members/ in each probe, where the directory's rename takes untracked files with it.
• The cost is one more line, and a name that must be free, which _free_name finds.

Line 2: a folding disk that pulled Members/README (closed by a test)

On a disk that folds case, holding members/, a pulled commit that adds Members/README puts the file at members/README. The remedy is git rm -r --cached -- Members/README, and commit the removal, because nothing is on disk in that spelling. The issue called it benign and asked for the remedy to be worded for that disk or verified there.

Verified on the emulated disk. The remedy is not changed. test_a_folding_disk_that_pulled_members_readme_takes_it_out (DISKS: core.ignorecase false and true):

• the file is written at members/README as bytes, and the index and HEAD hold Members/README;
• the dry run and the real run refuse alike, and each disk, asked in process (disk_as), gives the subprocess's text;
• typed as printed: the file stays on disk byte for byte at members/README, untracked; the gate passes in every mode; add goes through; the gate passes again;
• committing members/README afterwards still gives family ok.

Why the remedy was not worded as a committed git mv for that disk: git mv -- Members/README <new name> works only where the disk folds case. No test or CI job here can type it: this host is case-sensitive, and CI runs Linux alone (#597). Wording it would also need a lookup that follows the disk's folding in _on_disk_as_named, which #574's review (B1) made exact on purpose. The printed line types clean, touches no file, and leaves add and the gate passing. rv685 agreed the emulation is enough to close the line.

Line 3: each --sparse says the git it needs

• git mv --sparse (family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574) says "which needs git 2.38 or later" (SPARSE_MV_GIT). git took git mv --sparse in 2.34, but up to 2.37 a single source that a sparse checkout keeps off disk still fails bad source before --sparse is read. The remedy names exactly one such entry.
  • builtin/mv.c is byte-identical from v2.34.0 to v2.37.7 (sha256 30d476b9…, checked here for v2.34.0 and v2.37.7; rv685 checked seven tags).
  • In that file, if (lstat(src, &st) < 0) { if (modes[i] != SPARSE) bad = _("bad source");, and nothing marks a single skip-worktree source SPARSE.
  • v2.38.0 adds that lookup, and its t7002 first has can move out-of-cone file with --sparse.
  • Read from source, not run: only git 2.43 is here. (rv685's MUST-1. The first head said 2.34.)
• The move back's git rm --sparse (family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's S1) says "which needs git 2.34 or later" (SPARSE_RM_GIT). v2.33.0's builtin/rm.c has no --sparse, and v2.34.0's does.
• family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's sparse test asserts its text on every git, and types git mv --sparse only on git 2.38 or later.

No older way is named, from a probe on git 2.43 alone (probes/sparse-probe.log, sparse-probe-rm.log; rv685's sparse.log agrees). git update-index --no-skip-worktree -- Members/README, then git mv, fails bad source (exit 128), both for an entry marked by hand and in a real cone-mode sparse checkout. With git checkout -- between them, it works for the entry marked by hand, and git mv still refuses in the real checkout (exit 1). For the move back's removal, git rm --cached after --no-skip-worktree exits 0 and removes nothing in the real checkout. Those refusals are 2.34's sparse-checkout checks. On an older git the older way may well work: v2.33.0's mv.c has no sparse code at all, and its rm.c skips only skip-worktree entries. No older git was run.

The second sentence goes past the issue's text. The issue names git mv --sparse. #670 added git rm --sparse to its move back after #685 was filed, and its body lists the same limit under "Left out". rv685 agreed to keep the phrase there.

The estate states no minimum git, and none is set here.

No pinned file changes: templates/family-root/scripts/validate-family.py is untouched. No --help text changes. render-cli-reference.py --check passes. A git grep of README.md, AGENTS.md, docs/ and templates/ finds no sentence about these remedies, so none became false.

Tests

All runs used $Q/v110/run9.sh: a gh stub that exits 97 first on PATH, GH_TOKEN=bogus-l5, an empty GH_CONFIG_DIR, /usr/bin/python3 -m pytest, and local bare remotes only. Git 2.43.0.

tests/test_family_add_spellings_remedies.py is new, with 45 tests. Every printed command is typed as printed (typed_as_printed, #646's; type_remedy, #574's). Then the gate passes in every mode (assert_passes_in_every_mode), the same add goes through, and the gate passes again.

• test_members_renamed_with_git_mv_is_renamed_back_as_printed, 12 states:

  • staged; committed; staged with core.ignorecase=true;
  • committed with a file of its own under Members/;
  • after a pending change in HEAD, where the first commit takes the rename with it;
  • with the free name taken (a tracked members.renaming), through members.renaming-2;
  • one checkout gone; an empty Members/; nothing of it on disk (git submodule update … -- puts back the gitlinks first);
  • a committed file deleted from disk (git checkout -- puts it back first);
  • a change to .gitmodules nobody staged (git add -- .gitmodules first);
  • a .gitmodules deleted from disk (git checkout -- .gitmodules first, never git add).

  Each checks every member at its row's path and commit, and HEAD's family.yaml and .gitmodules bytes as the holder began. A git submodule update --recursive is typed with protocol.file.allow=always, since it clones a member's legs from the fixture's local paths.

• test_an_untracked_file_in_it_goes_back_with_it.

• test_a_fresh_clone_of_it_is_renamed_back_as_printed, now with the gate after add (rv685's NIT 2).

• test_every_disk_gets_the_same_rename_back (Linux and folding, in process).

• test_a_folding_disk_that_received_it_renames_it_back (Linux and folding, in process).

• test_only_members_renamed_whole_is_renamed_back, 13 states where it is not printed:

  • a members/ on disk beside it;
  • an entry the index holds under members/;
  • a file members in the index (rv685's NIT 1, mutant R8);
  • another spelling in the index too;
  • a case variant of the mount path under it;
  • an entry under it kept off disk;
  • a member's gitlink HEAD alone holds;
  • an entry under it unmerged (SHOULD-1);
  • a checkout gone that no section names there (MUST-2's fallback);
  • a file where a checkout was;
  • a directory where a file is;
  • a link members -> Members (MUST-B);
  • Members a link to a directory outside the holder (SHOULD-A).

• test_nothing_in_it_a_members_own_keeps_its_own_remedy.

• test_the_free_name_is_one_nothing_holds (4 states).

• test_what_gitmodules_needs_first_is_said_beside_a_gitlink (3): a change beside family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's move back (staged first); a change beside a file alone (nothing said); a copy a sparse checkout keeps off disk (nothing said).

• test_no_gitmodules_in_the_index_adds_nothing_first.

• test_a_missing_gitmodules_is_put_back_before_the_move_back: family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's state with .gitmodules deleted, typed through; HEAD keeps every section, the gate passes in every mode, and add goes through with every member registered.

• test_an_unmerged_gitmodules_is_named_first: the rename committed and .gitmodules unmerged with conflict markers. add refuses gitmodules-unstaged first, with the index left as it was. Resolved to this side and staged as printed, the rename back is printed and typed through, to the gate in every mode and add.

• test_a_folding_disk_that_pulled_members_readme_takes_it_out (DISKS, 2).

• test_the_move_backs_sparse_says_the_git_it_needs.

Two existing files change:

• tests/test_family_members_case_variants.py:
  • index_part(sparse=…) says 2.38 (NEEDS_GIT_2_38);
  • family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's sparse test asserts the text on every git and types it only on git 2.38 or later;
  • the eleven-field Spelled its non-UTF-8 test compares gains "", False, for the two new fields through and put_back.
• tests/test_family_add_member_variant.py: moved_back(sparse=True) says 2.34 (NEEDS_GIT_2_34).

The states that need git mv members Members skip on a disk that folds case, where that command fails. No test makes two directories that differ only in case.

Results at the head, bbb961f ($Q/v114/w685/fix/). Every run used its tree, uncommitted then and committed unchanged.

Run	Result
the new file	45 passed in 38.99s (new3.log)
the new file, test_family_members_case_variants.py, test_family_add_member_variant.py, test_family_add_refusals.py	207 passed in 142.83s (mod2.log)
rv685's v2 probe file (test_rv685_v2.py, 22 probes that log and assert nothing), in a scratch clone with this head's family.py	1 failed, 21 passed: the one is the unmerged .gitmodules probe, whose helper expects the spelling refusal and now meets gitmodules-unstaged, as intended (rv685-v2-probes.txt)

At 215e810 (fix round 1, family.py changed since only in the .gitmodules question and the link check): every tests/test_family*.py, 24 files, 961 passed, 19 skipped in 627.44s (batchA.log), and the four files above on its merge with main e313701, 200 passed in 167.47s (merge-main.log). Not re-run at this head. At the first head: tests/test_validate_family*.py (5), test_repo_hygiene.py, test_agents_md_codes.py, test_cli_reference.py and eleven more, 1085 passed in 398.99s ($Q/v114/w685/batchB.log). render-cli-reference.py --check passes on this head ([ok] docs/cli.md is what the generator produces).

From rv685's v2 probes at this head: the deleted .gitmodules, in the renamed state and in #646's, now types through with HEAD keeping every section, the gate passing in all three modes, and add going through. Both link states get the move back, as at 70307d2 (see "Left out").

Fails on base

The three test files at this head, over a837a02's scripts/family.py ($Q/v114/w685/fix/base3.log): 30 failed, 112 passed in 80.55s.

• Line 1: the 12 typed states, the untracked file, the fresh clone, both disks of test_every_disk_gets_the_same_rename_back, the folding disk of test_a_folding_disk_that_received_it_renames_it_back, the 4 free-name cases, the change beside a gitlink, the missing .gitmodules before the move back, and the unmerged .gitmodules.
• Line 3: test_the_move_backs_sparse_says_the_git_it_needs, family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's sparse test, the two disks of test_each_disk_answers_for_the_directory_it_holds[and every remedy the index takes], and family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's test_with_the_other_remedies_each_runs_in_its_order[kept off disk by a sparse checkout].
• The two new Spelled fields: test_a_name_head_holds_that_is_not_utf8_is_shown_replaced.

These pass on base by design: line 2's two tests; the Linux disk of the received state; the 13 states of test_only_members_renamed_whole_is_renamed_back; test_nothing_in_it_a_members_own_keeps_its_own_remedy; the change beside a file alone; the copy a sparse checkout keeps off disk; and the holder with no .gitmodules in its index.

The five tests this round adds, over 215e810's family.py (prev215.log): 5 failed, 40 passed in 37.27s. They are the deleted .gitmodules state, both link states, the missing .gitmodules before the move back, and the unmerged .gitmodules.

Mutation probes

$Q/v114/w685/fix/mutate2.py, in a throwaway clone at a837a02 with this head's three test files. Each probe changes one hunk or condition of this head's scripts/family.py, then runs the named file with -x (mutants.log). All 36 of fix round 1 are caught at 215e810: the first head's 18 (M8 replaced by the stage check, M2 split three ways, M14b added), rv685's R4, R7 (here M2c) and R8, and one or more per new hunk (N1 to N13).

Probe	What it undoes	Result	First failing test
M1	_renamed_with_git never asked	1 failed	…renamed_back_as_printed[staged]
M2	the members/ on disk not asked	1 failed, 15 passed	test_a_folding_disk_that_received_it_renames_it_back[linux]
M2b	samefile taken as true	1 failed, 17 passed	test_only_members_renamed_whole…[a members/ on disk beside it]
M2c (rv685's R7)	only canon's exact spelling	1 failed, 16 passed	test_a_folding_disk_that_received_it_renames_it_back[folding]
M3	the index under members/ not asked	1 failed, 18 passed	…[an entry the index holds under members/]
R8	a file members not asked	1 failed, 19 passed	…[a file at members in the index]
M4	one spelling not asked	1 failed, 20 passed	…[another spelling in the index too]
M4b	only the last entry's spelling read	1 failed, 20 passed	the same
M5	a member's own gitlink not asked	1 failed, 28 passed	test_nothing_in_it_a_members_own_keeps_its_own_remedy
R4	every entry must be a member's own	1 failed, 3 passed	…renamed_back_as_printed[committed, with a file of its own]
M6	a variant of the mount path not asked	1 failed, 21 passed	…[a case variant of the mount path under it]
M7	a gitlink HEAD alone holds not asked	1 failed, 23 passed	…[a member's gitlink HEAD alone holds]
M8	stages not asked	1 failed, 24 passed	…[an entry under it unmerged]
M9	skip-worktree under it not asked	1 failed, 22 passed	…[an entry under it a sparse checkout keeps off disk]
M10	the remedy not replaced	1 failed	…renamed_back_as_printed[staged]
M11	the disk under the spelling still named	1 failed, 11 passed	test_an_untracked_file_in_it_goes_back_with_it
M12	no commit after a pending change	1 failed, 4 passed	…[after a pending change in HEAD]
M13	the commit always printed	1 failed	…renamed_back_as_printed[staged]
M14	git mv --sparse without the git it needs	1 failed, 13 passed	test_an_entry_a_sparse_checkout_keeps_off_disk_takes_git_mv_sparse
M14b	git mv --sparse said to need 2.34	1 failed, 13 passed	the same
M15	the move back's --sparse without it	1 failed, 37 passed	test_the_move_backs_sparse_says_the_git_it_needs
M16	the git it needs said without --sparse	1 failed	#646's test_each_layout…[nothing on disk in that spelling]
M17	RENAME_BACK not in REMEDY_ORDER	1 failed	…renamed_back_as_printed[staged]
N1	the free name: the index not asked	1 failed, 33 passed	test_the_free_name…[an entry in the index, in another case]
N2	the free name: the disk not asked	1 failed, 32 passed	test_the_free_name…[a file on disk]
N3	the free name: the index asked in one case	1 failed, 33 passed	…[an entry in the index, in another case]
N4	nothing put back	1 failed, 6 passed	…renamed_back_as_printed[one checkout gone]
N5	a gitlink no section names put back	1 failed, 25 passed	…[a checkout gone that no section names there]
N6	a path held in another form put back	1 failed, 26 passed	…[a file where a checkout was]
N7	a gitlink: anything there counts	1 failed, 26 passed	the same
N8	a file: anything there counts	1 failed, 27 passed	…[a directory where a file is]
N9	files not put back	1 failed, 9 passed	…[a committed file deleted from disk]
N10	the stage-first part never said	1 failed, 10 passed	…[a change to .gitmodules nobody staged]
N11	the stage-first part beside any entry	1 failed, 30 passed	test_a_change_to_gitmodules…[beside a file alone]
N12	the caller never asks .gitmodules	1 failed, 10 passed	…[a change to .gitmodules nobody staged]
N13	one step, not two	1 failed	…renamed_back_as_printed[staged]

Fix round 2 (mutate3.py, mutants3.log), at this head, one per new hunk or branch, each -x on the new file. All 11 are caught.

Probe	What it undoes	Result	First failing test
G1	an unmerged copy not told apart	1 failed, 37 passed	test_an_unmerged_gitmodules_is_named_first
G2	a missing copy not told apart (so ls-files -m calls it modified)	1 failed, 11 passed	…renamed_back_as_printed[a .gitmodules deleted from disk]
G3	a modified copy not told apart	1 failed, 10 passed	…[a change to .gitmodules nobody staged]
G4	no copy in the index not asked	1 failed, 35 passed	test_no_gitmodules_in_the_index_adds_nothing_first
G5	a copy kept off disk not asked	1 failed, 34 passed	test_what_gitmodules_needs_first…[a copy a sparse checkout keeps off disk]
G6	asked beside any entry, not a gitlink alone	1 failed, 33 passed	…[a change beside a file alone]
G7	an unmerged copy not named first	1 failed, 37 passed	test_an_unmerged_gitmodules_is_named_first
G8	the restore part never said	1 failed, 11 passed	…[a .gitmodules deleted from disk]
G9	the stage part never said	1 failed, 10 passed	…[a change to .gitmodules nobody staged]
L1	a link spelling not asked	1 failed, 30 passed	test_only_members_renamed_whole…[Members a link to a directory outside]
L2	a link members not asked	1 failed, 29 passed	…[a link members to Members]

The _replace also resets recorded and sparse to their empty values, as Spelled's docstring gives them for every remedy but the move back. Nothing reads them for RENAME_BACK, so leaving them is not observable.

Merge checks

git merge-tree --write-tree of the head bbb961f, after a fetch at about 01:35Z on 2026-10-17. Every one is clean.

• origin/main bf1f099 (tree 760eeb70). Since e313701 it landed one shape-doctor.py change.
• family.py: add's refusal of a member's own gitlink held only under another spelling of its row's path moves it back to that path in the index alone, so the printed remedy no longer takes the member's gitlink away from its row (#646) #670 itself, fix/646-add-member-variant-remedy a837a02.
• Lane 4's branches that change scripts/family.py: fix/684-family-holder-states 7015386, fix/686-bump-reachability 7567e60, fix/688-family-init-values aa95b6b, fix/689-next-push-refspec fa51384 and fix/693-local-remote-dir 96ebe45.
• Lane 5's fix/692-raw-folder-paths ab55c29 and fix/681-validate-family-remedies 58d6c50.

After #670 squash-lands, the conflict and its resolution are as the first paragraph says, predicted again at this head after the fetch at 01:39Z: the three files conflict, and -X ours gives 760eeb70, the same tree as this head merged with main.

Left out, and why

• The same state after a hand mv Members members on Linux (the index still at Members/). Members is not on that disk, and members/ is a second spelling git mv cannot reach, so the rule does not apply. family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's move back is printed, with candidate (e)'s section gap.
• A member's gitlink staged for removal beside a staged git mv members Members (rv685's candidate 1). HEAD holds members/<P> and the index none, so _members_spellings never sees it. The rename back leaves that member's section at Members/<P>. add then goes through and commits that .gitmodules, and the gate refuses. Not changed here.
• family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's plain git mv in a cone-mode sparse checkout (rv685's candidate 2). Where an entry under Members/ is on disk with its skip-worktree bit cleared, git mv refuses it as outside the sparse definition (exit 1, as the 3-step in sparse.log shows). Not run through add.
• An untracked case variant of the mount path under the renamed directory (Members/irqs) goes back with it, to members/irqs. The next add names it there, with family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's mv. Not run.
• A file staged under Members/ that HEAD does not hold goes back with the rest, to members/<file>, still staged. No commit is printed for it, since it is the holder's own change, not the remedy's. Not run.
• A gitlink put back from a section whose gitdir is not in .git/modules. git submodule update then clones it from its url, which may need the network and a credential. Every state tested here has the gitdir.
• The two link states get family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's move back, which has its own gaps there (as at 70307d2 and on the base). With a link members -> Members, the move back leaves candidate (e)'s section gap, and add then refuses member-path-unaddable for the link itself, which names it. With Members a link to a directory outside, the move back's git rm --cached fails through the link (not a git repository: Members/IRRS/../../.git/modules/members/IRRS). rv685's v2 probes show both.
• An unmerged .gitmodules the work tree lacks. gitmodules-unstaged leaves a missing copy to git submodule add for add, so it raises nothing there, and the spelling refusal says nothing of the file. Not run.
• A deletion of .gitmodules the holder already staged is committed by any printed commit, as on the base. Nothing here stages it.
• Git older than 2.38 (or 2.34 for git rm): the sentences say what is needed. No such git is here to run them on.

Fix rounds

• Round 1 (215e810, rv685 on 70307d2). git mv --sparse says 2.38 (MUST-1). What the disk lacks under the spelling is put back first (MUST-2). Unmerged entries keep the move back, and a change to .gitmodules nobody staged is staged first (SHOULD-1). The older-way comment says what was measured (SHOULD-2). The rename back is two steps through a free name, one text on every disk for the renamed state (SHOULD-3). Plus the NITs.
• Round 2 (bbb961f, rv685 on 215e810).
  • MUST-A: _gitmodules_beside tells the work tree's .gitmodules apart as gitmodules-unstaged does. A missing copy is put back, not staged; an unmerged one is gitmodules-unstaged's to name first.
  • MUST-B and SHOULD-A: no rename back where the spelling or members is a link.
  • NITs: "one text serves every disk" now says it holds for the renamed state, with family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's own state named. The free name following the disk's case needs no change.

Checklist candidates

• family.py add: a file under a third spelling in the index blocks the rename back (rv685's NIT 5). With MEMBERS/notes in the index beside a Members/ renamed with git, the rule asks for one spelling, so family.py add: where another member's own gitlink sits at a case variant (Members/<P> for its row members/<P>), the refusal's remedy prints git rm -r --cached or git mv, which takes that member's gitlink away from its row #646's move back is printed, with candidate (e)'s section gap. git mv of Members alone would still type clean, after family.py: add refuses, before the member is read and on every disk, any path under another spelling of members/, in its index, in HEAD or on disk, and names a remedy per entry that never moves the members' checkouts (#362, #363, #364) #574's remedy for MEMBERS/notes. This is outside family.py add: #574's spelling remedy gives a generic <new name> after git mv members Members, git rm --cached for a pulled Members/README, and a git mv --sparse that needs git 2.34 or later #685's states.
• (e), what is left of it. The move back of a member's own gitlink, printed by add and by the pinned validator, still leaves a section naming the variant after a git mv of the gitlink itself (family.py: add's refusal of a member's own gitlink held only under another spelling of its row's path moves it back to that path in the index alone, so the printed remedy no longer takes the member's gitlink away from its row (#646) #670's candidate (e)). Under "Left out" above, the hand mv Members members state and rv685's candidate 1 leave the same gap.

Review. rv685 reviewed three times: CHANGES REQUESTED at 70307d20 and at 215e8102, then APPROVE at bbb961f8. Its last round typed every named row through: a deleted .gitmodules keeps every member registered, an unmerged one is refused first by gitmodules-unstaged, the two link states get the move back as on the base, and the four files give 207 passed. It judged the refusal-order change sound.

Closes #685

🤖 Generated with Claude Code

Summary by Sourcery

Make family.py add print executable, cross-platform remedies for alternate members/ spellings, including Git renames and sparse-checkout requirements.

New Features:

• Make family.py add repair whole members/ directories renamed with Git by restoring missing contents and renaming them back through a free intermediate name.
• Report the minimum Git versions required by printed sparse-checkout remedies.

Bug Fixes:

• Ensure printed remedies for Git-renamed member directories preserve .gitmodules, submodule checkouts, and the gate's valid state across case-sensitive and case-folding disks.
• Handle modified, missing, and unmerged work-tree .gitmodules files before applying remedies so every printed command can be executed as stated.

Enhancements:

• Add comprehensive coverage for renamed-directory recovery, free-name selection, disk variations, missing work-tree content, symlinks, sparse checkouts, and remedy typing.

Tests:

• Add 45 tests covering all three affected refusal/remedy scenarios and validating that typed remedies restore a passing family state.

[brettheap]

(lane openRepoShape-5, 2026-10-17T00:11Z) @codex review

[sourcery-ai]

Reviewer's Guide

Adds a narrowly gated git mv -- Members members remedy for whole-directory renames, improves sparse-remedy version guidance for Git 2.34+, and backs both behaviors with end-to-end tests that type the printed commands and verify the family gate and subsequent add succeed.

Sequence diagram for whole members/ rename-back remedy

sequenceDiagram
    participant Add as family.py add
    participant Index as Git index
    participant Disk as Working tree
    participant Output as Refusal output
    Add->>Index: _index_entries()
    Add->>Disk: _members_dir_on_disk()
    Add->>Add: _renamed_with_git()
    Add->>Output: Print git mv -- Members members
    Output->>Disk: git mv -- Members members
    Disk->>Index: Update member gitlinks
    Disk->>Disk: Move checkouts and .gitmodules sections
    Add->>Output: Re-run add and family gate

Loading

State diagram for sparse remedy Git version guidance

stateDiagram-v2
    [*] --> SparseRefusal: Entry kept off disk
    SparseRefusal --> VersionCheck: Print git mv --sparse or git rm --cached --sparse
    VersionCheck --> Supported: Git 2.34 or later
    VersionCheck --> Unsupported: Git older than 2.34
    Supported --> TypedRemedy: Command can be typed
    Unsupported --> UpgradeGit: Upgrade Git before running remedy
    TypedRemedy --> [*]
    UpgradeGit --> [*]

Loading

Flow diagram for family add refusal remedies

flowchart TD
    A[family.py add detects refusal] --> B{Whole members/ renamed with git mv?}
    B -- Yes --> C[Print git mv -- Members members]
    C --> D[Checkout and .gitmodules paths return to members/]
    D --> E[Re-run add and family gate]
    B -- No --> F{Sparse entry is off disk?}
    F -- Yes --> G[Print git mv --sparse or git rm --cached --sparse]
    G --> H[State Git 2.34 or later]
    H --> E
    F -- No --> I[Use existing member or disk remedy]
    I --> E

Loading

File-Level Changes

Change	Details	Files
Adds a dedicated remedy for repositories whose entire members directory was renamed with Git, while preserving existing remedies for unsafe layouts.	Detects the narrow state where all member gitlinks and their on-disk checkouts share one alternate directory spelling. Introduces ordered RENAME_BACK handling that emits git mv -- Members members, carries untracked contents back, and conditionally requests commits. Excludes case-folding disks, sparse contents, conflicting index/HEAD spellings, and non-member contents so their existing remedies remain applicable. Updates spelling documentation and disk-path suppression to account for the directory-level rename.	scripts/family.py
Makes sparse-checkout refusal text declare the minimum Git version required by the printed sparse commands.	Adds the shared which needs git 2.34 or later qualifier to sparse git mv and member-gitlink move-back remedies. Keeps the refusal text available on older Git versions while only executing --sparse commands where supported.	scripts/family.py tests/test_family_members_case_variants.py tests/test_family_add_member_variant.py
Adds comprehensive behavioral coverage proving printed add remedies are executable across directory-rename, case-folding, sparse, staged, committed, clone, and pending-change states.	Verifies the new whole-directory rename remedy, commit sequencing, preservation of gitlinks and .gitmodules, and movement of untracked files. Verifies conditions where the new remedy must not be selected and confirms the existing remedies remain in force. Exercises the folding-disk Members/README case and sparse Git-version messaging, including typed remedies and post-remediation gate/add success.	tests/test_family_add_spellings_remedies.py tests/test_family_members_case_variants.py tests/test_family_add_member_variant.py

---

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.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-17T00:14:00.759138Z	70307d2	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 70307d200d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Exclude unmerged entries from the whole-directory rename

When a renamed Members/ contains an unmerged member gitlink, such as after a conflicted stash pop, indexed collapses its multiple stages and the stage-2 gitlink makes this predicate classify the directory as safe to rename back. The emitted git mv -- Members members is not executable in that state: Git 2.43 exits 128 with fatal: source directory is empty, source=Members/<member>, destination=members/<member>. Check the original index records for non-stage-0 entries and retain the conflict-safe per-entry remedy (or explicitly require resolving the conflict) instead of returning this spelling.

Useful? React with 👍 / 👎.

[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 12 hours and 58 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud