[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #413 (comment)
Claim: #414 (comment)

What changed and why

Since #276 (PR #354) the doctor's legs and members rows hand over git -C <root> submodule update --init --recursive --checkout -- <paths> where a checkout cures the row, and the lockstep gate where none does. Since #277 (PR #402) the row's why says what the line does. This PR fixes the two follow-ups this lane's review of #354 filed, in the same functions. Both issues' repro scripts split the NEXT on #. Since #277 that split finds an empty sentence on main, and the sentence is the row's why ("why" in --json).

#413: every detached commit the line would move is named

The keep sentence ("A commit made in a leg on no branch is left only in its reflog by this line. To keep one, run first git -C branch NAME") was printed only for a populated mount detached off its pin. The line moves more HEADs than that, each able to hold the only copy of a commit:

• (a) An emptied mount whose repository git kept. git submodule deinit -f keeps .git/modules/<name>. The update links the mount to it again and checks the gitlink out over the commit. The row now finds that repository by the submodule's name (.gitmodules, read where git reads it) and git rev-parse --git-path modules/<name>. It reads that repository's HEAD through --git-dir, never in the empty mount, where git walks up to the root. When the HEAD is detached at a commit that is not the gitlink (left_in_reflog, the rule the populated mounts use too), the row names the commit with git --git-dir=<repository> branch NAME <commit>. Run in the empty mount, git -C <mount> branch NAME would branch the ROOT. If the mount directory is gone too, git refuses every command in that repository (cannot chdir, exit 128, measured), so that keep line then carries a --work-tree.
• (b) The holder's own scripts/bootstrap.py. Its update names no path, so it moves every member, including one the row hands to the family gate. Its why now carries the same keep sentence, built by the same function (checkout_notes, factored out of submodule_update_next), for every member it would move off a detached commit.
• (c) --recursive. It checks out the submodules a mount carries of its own, at the commits that mount records: each member's legs, and anything a leg mounts. The row does not walk into them. A line that names a mount carrying some (a .gitmodules in it, or a kept repository that keeps their modules/) says so in general words, with a placeholder keep line to run first: git -C LEG branch NAME for a member's leg, git -C LEG/SUB branch NAME for a leg's own submodule. --recursive stays, for parity with the holder's bootstrap (fetch_members).

#414: four states, each sent to a line that cures it or to none

state	on main	now
(1) files in the mount, no .git of its own	the gate, under "no submodule update cures", and the reason quoted the ROOT's HEAD as the leg's	No HEAD is read there. If git kept the repository, the NEXT is the git line, whose why says it links the two again; pasted, the row is ok. If not, the NEXT is the gate, whose why says git kept none: the update tries a clone into a directory that is not empty and exits 1 (measured).
(2) an unborn HEAD	the gate, which says pins ok while the row stays red	NEXT None. The reason names the branch, and the why says nothing here chooses a commit.
(3) git finds no url: no .gitmodules section gives the path, or the section has no url and the root's own config has none either	the git line, which exits 128 (No url found)	NEXT None. The why says a person restores the entry from the repository's history. The gates were measured: pin-submodule-uninitialized, and member-uninitialized for a member, name no .gitmodules entry and hand back the same git line. No command is printed, so none can discard an uncommitted .gitmodules.
(4) a leg the line checks out, with its own lockstep fact	"run the doctor again" only when ANOTHER leg was lockstep	Asked per leg too: a pin that is not 40 hex, or not the gitlink.

For (3), the url is asked for every mount the line would name, populated ones too: --init exits 128 on a populated one as well (measured). .gitmodules is read where git reads it, so a copy deleted from the working tree alone is read from the index, and the line stands (pasted, it exits 0). A section that keeps its path but lost its url key is not url-less while the root's own config still holds the url submodule init copied there: --init reads that first, and the line exits 0 and cures the row (measured, populated past its pin and emptied by rm; deinit removes the configured url).

The members row takes the same rules through one function, checkout_reach, and a member reaches all four states. A holder adds one case. Git stops the holder's bootstrap at a member it finds no url for: the bootstrap's update names no path, git exits 128 before any member is fetched, and the bootstrap still exits 0 with the row as red as before. So the NEXT is then the git line over the members a checkout cures, and its why says why it is not the bootstrap.

Where the lockstep gate is the NEXT, an unborn HEAD or a mount with no url beside it is named in the gate's why, in the same sentence it gets when no line is printed. That sentence ends by saying to run the doctor again.

Review round 1 (R559, at 83b3865)

• M1: the url check asked .gitmodules alone, a regression from main for an initialized mount whose section lost only its url key. It now also asks git config --get submodule.<name>.url in the root (configured_url), so such a mount, populated or emptied by rm, keeps the curing git line, as on main. The holder's bootstrap does the same for a member.
• S1: a leg's own submodules get the general --recursive sentence, as a member's legs do.
• N1, N2: tests now pin detached()'s None, and every member the holder's bootstrap moves.
• N3: the docstrings no longer apply the old # tail rule to the why.
• N4: the gate's why now carries the states no line cures.
• N5: pre-existing, and left as it is.

Tests

The new tests go at the end of tests/test_doctor_legs_members_next.py: 13 for #413, 21 for #414, and 15 from review round 1. Each runs for the legs row and the members row where the state applies. One existing test there changes. It asserted no reflog in a branched member's why, which now carries the nested sentence, so it asserts instead that the member gets no keep line of its own.

• shape-doctor.py's legs and members NEXT after #354 moves a detached HEAD that holds the only copy of a commit, with no reflog note, in three states: an emptied leg mount whose kept gitdir holds the commit, a holder whose own scripts/bootstrap.py is the NEXT (any commit made in the pinned members/<P>), and a commit in a member's own leg that --recursive moves, so after the paste the commit is held by a reflog entry alone #413 (a), (b) and (c): each has the shape of test_the_keep_line_in_the_explanation_keeps_a_detached_commit.
  • The commit is named before the paste: by its sha in (a), and by its mount's keep line in (b). In (c) it is named in general words, for a member's leg and for a leg's own submodule.
  • The named keep line, run first (placeholders filled in for (c)), leaves the commit on a branch after the paste.
  • Without that line, no ref holds the commit afterwards.
  • (a) is also tested with the mount directory gone, and with a kept HEAD on a branch or at the gitlink, which is not named. (b) is also tested with a second member the row hands to the gate, which the bootstrap moves and names.
• shape-doctor.py's legs NEXT after #354 does not fit four edge states: a populated mount with no .git but its gitdir kept is sent to validate-pins.py under a sentence saying no update cures it, though the git line does; an unborn HEAD gets the gate, which says pins ok while the row stays red; an empty mount with no .gitmodules section gets a git line that exits 128; and an empty mount whose pin is not 40 hex gets no "run the doctor again" #414 (1) to (4): each NEXT, pasted, turns the row ok, or the NEXT is None and the why or the reason names the state.
  • (1) never quotes the root's HEAD.
  • (3) never prints a line that exits 128. One test pins what the git line (128, No url found) and the gate (pin-submodule-uninitialized, no .gitmodules in its output) do there.
  • (3) also keeps the line, which pasted cures the row, for a url the root's config still holds: a leg past its pin, a leg emptied by rm, and a member.
  • (4) says to run the doctor again.
• Also: detached() answers None where symbolic-ref fails (a member whose gitdir is gone is not called detached in --json), and an unborn leg beside a lockstep one is named in the gate's why.
• The paste tests are WINDOWS_SKIP, as the file's others are: 7 for shape-doctor.py's legs and members NEXT after #354 moves a detached HEAD that holds the only copy of a commit, with no reflog note, in three states: an emptied leg mount whose kept gitdir holds the commit, a holder whose own scripts/bootstrap.py is the NEXT (any commit made in the pinned members/<P>), and a commit in a member's own leg that --recursive moves, so after the paste the commit is held by a reflog entry alone #413, 6 for shape-doctor.py's legs NEXT after #354 does not fit four edge states: a populated mount with no .git but its gitdir kept is sent to validate-pins.py under a sentence saying no update cures it, though the git line does; an unborn HEAD gets the gate, which says pins ok while the row stays red; an empty mount with no .gitmodules section gets a git line that exits 128; and an empty mount whose pin is not 40 hex gets no "run the doctor again" #414 and 7 from round 1. Every text-level assertion runs on all three OSes.

Run on Linux (py-bench) at this head's bytes (shape-doctor.py sha256 d85e92ac…, the test file 7b765cae…), with git-filter-repo on PATH:

• tests/test_doctor_legs_members_next.py tests/test_doctor_unfinished_merge.py tests/test_doctor_next_is_a_command.py tests/test_shape_doctor.py tests/test_repo_hygiene.py tests/test_cli_reference.py tests/test_agents_md_codes.py: 654 passed, 3 skipped (10 min 38 s).
• The three other tests that read these rows: tests/test_family.py::test_the_doctor_reports_a_project_pinned_twice and tests/test_doctor_validator_rows.py's two test_a_colon_standard_withholds_the_{legs,members}_rows_lockstep_line*. 3 passed.
• This head merged in turn with shape-doctor.py: manifest kinds prints one command for its NEXT, the git rm, git clean or git status its files need as git has them, where it printed prose joined by ; whose backticks ran family.py in zsh, and counts a manifest validated only at a path its gate reads, so a contracts/<x>-pin.yaml no leg or product names is a FINDING (#548, #439) #555, tests: every test that clones a just-pushed local remote by its plain path now clones it with clone_just_pushed, so the macOS failed to copy file race of #440 cannot reach it; load_without_bytecode keeps the doctor's and the Windows-path tests' loads of the family root's scripts from writing .pyc into the templates; the not-a-list doctor cases hold INVALID, exit 1; and GOOD_KEYS holds th #554 and shape-doctor.py: a validator's verdict is a printed FINDING or REFUSED and any other non-zero exit is a crash, so a gate killed by a signal, ended by os._exit(1), holding conflict markers or failing argparse no longer "reports a finding", a crash of the standard's own naming script is CANNOT ANSWER instead of INVALID (naming), and a pass that printed WARNING or note lines is a note quoting them while a red row quotes its finding and never a warning (#410, #448) #557, tests/test_doctor_legs_members_next.py: 111 passed.

No tests/test_family.py test reads the doctor's members row. Its only doctor test reads the family row, and runs above.

Mutants, each run against its own tests, then reverted (sha256 checked):

mutant	tests	result
drop the kept-repository read (kept_head answers nothing)	-k 413a	4 failed: (a)'s text test, both paste tests that use its keep line, and the members (a) test
drop the holder bootstrap's keep sentence	-k 413b	4 failed: (b)'s text tests and keep-line pastes, for the checkout member and for the member the gate gets
compute rerun from other legs only	-k 414_4	2 failed: both legs cases of (4)
R559's R1: detached() reads any failure as detached, as main did	-k detached	2 failed: the detached test and the member --json test
R559's R3: the bootstrap names off_pin only	-k 413b	2 failed: the second-member text test and its keep-line paste
the url asked of .gitmodules alone	-k 414_3	6 failed: the url-in-config text and paste tests, for both legs cases and the member
no nested sentence on the legs line	-k submodule	2 failed: the leg-submodule text test and its keep-line paste
the gate's why without the states no line cures	-k gate_is_the_line	1 failed

macOS and Windows were not run here; this PR's CI is their first run.

Shared files

shape-doctor.py is also changed by other open PRs, on other lines. Each is named by the functions its hunks sit in, and the functions it adds:

• lane 4's shape-doctor.py: a validator's verdict is a printed FINDING or REFUSED and any other non-zero exit is a crash, so a gate killed by a signal, ended by os._exit(1), holding conflict markers or failing argparse no longer "reports a finding", a crash of the standard's own naming script is CANNOT ANSWER instead of INVALID (naming), and a pass that printed WARNING or note lines is a note quoting them while a red row quotes its finding and never a warning (#410, #448) #557 (P2, fix/doctor-validator-verdicts, shape-doctor.py's two naming rows read only the naming script's exit code, so a crash of the STANDARD's own validate-repository-naming.py is a FINDING about the project (INVALID (naming), exit 1, where #357 makes a crashed template CANNOT ANSWER), and a directory whose name is not UTF-8 gets naming FINDING Atl?as: UnicodeEncodeError: ..., the script's traceback quoted as a fact about the name #410/shape-doctor.py's manifest row says ok ... passes when the project's own validate-manifest.py exits 0 after printing WARNING naming-referent-chain: ... not reachable here, and the warning appears nowhere in the text or --json report, so a referent chain nothing on this disk could check reads as checked under COMPLIANT: the class of the skip #357 makes a note, in the form #357 still drops #448): run_validator, validator_row, report, offline, check_naming and check_not_a_root_naming; it adds signal_name, reported, skipped, passed_but and naming_crashed_row;
• lane 3's shape-doctor.py: manifest kinds prints one command for its NEXT, the git rm, git clean or git status its files need as git has them, where it printed prose joined by ; whose backticks ran family.py in zsh, and counts a manifest validated only at a path its gate reads, so a contracts/<x>-pin.yaml no leg or product names is a FINDING (#548, #439) #555 (l3-548-manifest-kinds): the module docstring, ManifestKind, check_manifest_kinds, registered_elsewhere, linked_record_row, git_states, family_beside_project, placement_policy, refusal_line and run_checks; it adds own_pins, pins_read_here, read_by_a_gate, remedy_as_why, listed, register_way, read_nowhere, read_here, removal_next and taking_out;
• lane 3's shape-doctor.py: a git repository is told of both ways in, the adoption and the scaffold, and the adoption line ends --org <your-org> where its origin names no organisation plan can read, so pasting it is no longer refused adopt-no-org (#545) #553 (l3-545-doctor-way-in): the module docstring, CHECKS, check_the_way_in, python_command, repo_local_origin_name and scaffold_command; it adds origin_org, way_in_project and check_the_other_way_in;
• lane 3's shape-doctor.py: the machine row of a machine that is not ready names the preflight checks that failed, in the [!!] lines the preflight printed, so its reason no longer ends on this machine is not ready yet (see above). with nothing above it (#549) #552 (l3-549-doctor-machine-row): check_what_is_here and check_machine; it adds preflight_failures, is_preflight_verdict and first_sentence.

This PR touches submodule_update_next, check_legs, detached, member_state, member_problem and members_verdict, and adds its helpers between lockstep_next and submodule_update_next. None of the four adds a function under a name this PR adds.

tests/test_doctor_legs_members_next.py is also changed by lane 3's #554 (l3-544-test-hygiene): its import line and test_a_plain_clones_empty_mounts_are_cured_by_the_pasted_line. This PR changes the module docstring and one other test, test_the_members_reflog_note_is_printed_for_a_detached_member_only, and appends its tests at the end.

git merge-tree --write-tree of this head with origin/main and with each of them exits 0 with a tree, so none conflicts. The heads were main b8b7062, #557 430c13f, #554 4619757, #555 abbce43, #553 e64f47e and #552 9362501. Main's commit since this branch's base, 5ed3e5d (#518), changes none of this PR's files.

The two stale #533 docstrings in shape-doctor.py (submodule_update_next, check_legs), and the test file's own, are corrected here: since #475 and #490 bootstrap does move a branch whose tip is not the pin, where that loses nothing.

v1.1.0: lands only after the v1.0.0 tag.

Closes #413
Closes #414

🤖 Generated with Claude Code

Summary by Sourcery

Make shape-doctor accurately route legs and members repairs while warning about every detached commit and nested checkout that a proposed update may move.

Bug Fixes:

• Correct NEXT routing for legs and members with missing repositories, unborn HEADs, missing submodule URLs, and nested lockstep problems so commands are only offered when they can cure the reported state.
• Ensure checkout and bootstrap explanations identify every detached commit that may be displaced, including commits in retained submodule repositories and recursively updated nested submodules.

Enhancements:

• Unify submodule checkout analysis, URL resolution, retained repository detection, detached/unborn HEAD handling, and explanatory notes across the legs and members checks.
• Read submodule metadata and configured URLs consistently with Git and distinguish mounts that can be relinked from those requiring the lockstep gate or manual intervention.

Tests:

• Expand legs and members coverage for detached commit preservation, missing repositories, unborn HEADs, missing URLs, recursive submodules, retained configuration URLs, nested repositories, and per-leg rerun guidance.

[sourcery-ai]

Reviewer's Guide

Updates the doctor’s legs and members NEXT routing to avoid unsafe or ineffective commands, accurately account for every detached commit a checkout or bootstrap may move, and provide shared, tested explanations for retained repositories, recursive updates, unborn HEADs, missing submodule URLs, and follow-up lockstep facts.

Sequence diagram for safe submodule checkout routing

sequenceDiagram
    participant Doctor
    participant Gitmodules
    participant KeptRepo
    participant Git
    Doctor->>Gitmodules: gitmodules_entry(root, rel)
    alt URL is missing
        Gitmodules-->>Doctor: no-url
        Doctor-->>Doctor: NEXT None
    else URL exists
        Doctor->>KeptRepo: kept_gitdir(root, name)
        alt Repository was kept
            Doctor->>KeptRepo: kept_head(root, git_dir)
            KeptRepo-->>Doctor: detached state and commit
        else No kept repository
            KeptRepo-->>Doctor: None
        end
        Doctor->>Doctor: checkout_reach(...)
        alt checkout or relink
            Doctor->>Git: submodule_update_next(...)
            Git-->>Doctor: checkout command and keep notes
        else gone
            Doctor-->>Doctor: lockstep_next(...)
        end
    end

Loading

Flow diagram for legs and members NEXT routing

flowchart TD
    A[Inspect leg or member state] --> B{Checkout can cure it?}
    B -->|No| C{Unborn HEAD or missing URL?}
    C -->|Yes| D[NEXT: None; explain manual repair]
    C -->|No| E[NEXT: lockstep gate]
    B -->|Yes| F[checkout_reach]
    F --> G{Route}
    G -->|checkout or relink| H[git submodule update --init --recursive --checkout]
    G -->|gone| E
    G -->|no-url| D
    H --> I[Add keep and rerun guidance]

Loading

File-Level Changes

Change	Details	Files
Centralize checkout safety and detached-commit preservation so every command emitted for legs and members accounts for kept repositories, recursive updates, and shell-safe keep instructions.	Read .gitmodules using Git’s working-tree/index/HEAD precedence and reject git lines that would fail due to a missing URL. Detect repositories retained under .git/modules, inspect their HEAD through --git-dir, and generate branch commands that preserve detached commits, including missing-mount work-tree handling. Factor shared checkout explanation generation for direct mounts, holder bootstrap behavior, recursive member legs, and relinked mounts. Expand submodule update command metadata and rerun guidance to describe all potentially moved commits and remaining lockstep facts.	shape-doctor.py
Refine legs and members verdict routing so NEXT commands cure the reported state or are withheld when no safe automated repair exists.	Stop reading the root HEAD for populated mounts without their own .git and route them based on whether Git retained a submodule repository. Handle unborn HEADs and missing .gitmodules URLs with no NEXT command and explanatory reasons. Route retained no-.git mounts to checkout, mounts with no retained repository to the lockstep gate, and member URL failures away from the holder bootstrap. Apply per-mount rerun detection when checkout leaves invalid pins or gitlinks, while preserving recursive and bootstrap semantics.	shape-doctor.py
Add comprehensive regression coverage for detached-commit naming and all four checkout-routing edge cases across legs and members.	Test kept repositories, missing mount directories, bootstrap-moved members, recursive member legs, and preservation of commits via pasted keep commands. Test no-.git mounts, unborn HEADs, missing URLs, Git’s .gitmodules source precedence, and gate-versus-git-line behavior. Verify shell quoting, command exit behavior, row status transitions, and rerun guidance.	tests/test_doctor_legs_members_next.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#413	For every detached commit that a legs or members NEXT can move, explain the risk and provide an appropriate keep instruction, including kept gitdirs for emptied mounts, the holder’s bootstrap path, and recursive member legs.	✅
#414	Route a populated mount with no .git of its own according to whether Git retained its submodule repository, without reading or reporting the root's HEAD as the mount's.	✅
#414	For an unborn HEAD or a mount with no .gitmodules URL, avoid handing over a command that does not cure the state; give no NEXT and explain what must happen instead.	✅
#414	When a checkout NEXT leaves a lockstep problem in the same leg, say that the doctor must be run again.	✅

Possibly linked issues

• shape-doctor.py's legs NEXT after #354 does not fit four edge states: a populated mount with no .git but its gitdir kept is sent to validate-pins.py under a sentence saying no update cures it, though the git line does; an unborn HEAD gets the gate, which says pins ok while the row stays red; an empty mount with no .gitmodules section gets a git line that exits 128; and an empty mount whose pin is not 40 hex gets no "run the doctor again" #414: The PR directly fixes all four reported routing defects: relinks kept gitdirs, withholds commands for unborn HEADs or missing URLs, and requests reruns for hidden lockstep facts.
• shape-doctor.py's legs and members NEXT after #354 moves a detached HEAD that holds the only copy of a commit, with no reflog note, in three states: an emptied leg mount whose kept gitdir holds the commit, a holder whose own scripts/bootstrap.py is the NEXT (any commit made in the pinned members/<P>), and a commit in a member's own leg that --recursive moves, so after the paste the commit is held by a reflog entry alone #413: The PR fixes the issue’s three unreported reflog-only commit cases: emptied mounts, the holder bootstrap, and recursive member legs.

---

Tips and commands

Interacting with Sourcery

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

Customizing Your Experience

Access your dashboard to:

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

Getting Help

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

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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

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